Getting Started

Prerequisites

• Node.js 18+ — The library is built on top of the Node.js Native Fetch API. No polyfills required.
• TypeScript 4.7+ — Recommended for full type safety with generics. The library ships its own .d.ts declarations.

Installation

npm

npm install @yildizpay/http-adapter

yarn

yarn add @yildizpay/http-adapter

pnpm

pnpm add @yildizpay/http-adapter

Quick Start

Create an adapter, build a request, send it:

import { HttpAdapter, RequestBuilder, HttpMethod } from '@yildizpay/http-adapter';

// 1. Create the adapter
const adapter = HttpAdapter.builder().build();

// 2. Build the request
const request = new RequestBuilder('https://jsonplaceholder.typicode.com')
  .setEndpoint('/users/1')
  .setMethod(HttpMethod.GET)
  .build();

// 3. Send and receive a typed response
interface User {
  id: number;
  name: string;
  email: string;
}

const response = await adapter.send<User>(request);
console.log(response.data.name); // "Leanne Graham"

Realistic Setup

In production you'll typically add interceptors, a retry policy, and a circuit breaker:

import {
  HttpAdapter,
  RetryPolicies,
  CircuitBreaker,
} from '@yildizpay/http-adapter';

export const apiAdapter = HttpAdapter.builder()
  .withInterceptor(new AuthInterceptor(), new LoggingInterceptor())
  .withRetryPolicy(RetryPolicies.exponential(3))
  .withCircuitBreaker({
    failureThreshold: 5,
    resetTimeoutMs: 30_000,
    successThreshold: 1,
  })
  .withCorrelationId()
  .build();

Create the adapter once (e.g., as a singleton in a service module) and reuse it across requests. Adapter instances are stateless with respect to individual requests.

Using the Builder vs. create()

There are two ways to instantiate an HttpAdapter:

// Builder API — recommended, readable, and discoverable
const adapter = HttpAdapter.builder()
  .withRetryPolicy(RetryPolicies.exponential(3))
  .build();

// Factory function — useful when all options come from a config object
const adapter = HttpAdapter.create(
  [new AuthInterceptor()],
  RetryPolicies.exponential(3),
  undefined,            // optional custom HTTP client
  new CircuitBreaker({ failureThreshold: 5, resetTimeoutMs: 60_000 }),
);

Prefer the builder API — it's more explicit and easier to extend.

What's Next

• Request Builder — All the ways to construct requests
• Interceptors — Auth, logging, and data transformation hooks
• Error Handling — Typed exceptions for every failure scenario
• Resilience — Retry policies and Circuit Breaker