@yildizpay/http-adapter

🔗

Fluent Request Builder

Construct complex HTTP requests with an intuitive, chainable API. Immutable by design to prevent side effects in concurrent environments.

🛡️

Structured Exception Hierarchy

Every HTTP status code and network failure maps to a dedicated exception class with rich metadata, isRetryable() signals, and toJSON() serialization.

✅

Response Validation

Attach schema validators (Zod, Joi, or custom) directly to requests. Invalid responses throw before reaching your business logic.

🔄

Resilience & Retries

Exponential backoff, fixed delay, linear backoff, full jitter, and decorrelated jitter policies. Circuit Breaker with a full CLOSED/OPEN/HALF_OPEN state machine.

📊

Observability

Read-only observer hooks for metrics and distributed tracing. Deep integration with structured loggers like Pino and Winston via toJSON().

🧪

First-class Testing Utilities

MockHttpAdapter with endpoint-scoped mocking, strict mode, FIFO queues, and rich assertion helpers. SpyInterceptor and SpyObserver included.

See It in Action

Create an AdapterBuild a RequestHandle Errors PreciselyTest Without HTTP

typescript

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

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

typescript

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

const request = new RequestBuilder('https://api.payment.com')
  .setEndpoint('/v1/charges')
  .setMethod(HttpMethod.POST)
  .setBody({ amount: 1000, currency: 'USD' })
  .build();

typescript

import {
  TooManyRequestsException,
  CircuitBreakerOpenException,
  NetworkException,
} from '@yildizpay/http-adapter';

try {
  const response = await adapter.send<ChargeResponse>(request);
  console.log('Charge ID:', response.data.id);
} catch (error) {
  if (error instanceof TooManyRequestsException) {
    console.warn(`Rate limited. Retry after ${error.getRetryAfterMs()}ms`);
  } else if (error instanceof CircuitBreakerOpenException) {
    console.error('Payment service unavailable. Failing fast.');
  } else if (error instanceof NetworkException) {
    console.error('Network failure:', error.toJSON());
  }
}

typescript

import { MockHttpAdapter } from '@yildizpay/http-adapter/testing';

const adapter = new MockHttpAdapter();

adapter
  .onEndpoint('/v1/charges')
  .mockResolvedValue({ id: 'ch_123', status: 'succeeded' });

await chargeService.process(order);

adapter.assertCalledWith('/v1/charges', { method: HttpMethod.POST });
adapter.assertCalledTimes(1);

Why @yildizpay/http-adapter?

Built around the real challenges of service-to-service communication in production Node.js applications — not just wrapping fetch.

	Raw Fetch	axios	@yildizpay/http-adapter
Typed exception per HTTP status code	—	—	✅
Built-in Circuit Breaker	—	—	✅
Per-request retry/circuit override	—	—	✅
Response validation hooks	—	—	✅
`isRetryable()` signal on errors	—	—	✅
Structured `toJSON()` on all errors	—	—	✅
First-class testing utilities	—	—	✅
Zero production dependencies	✅	—	✅
Runs on Node.js Native Fetch	✅	—	✅

Raw Fetch

axios

@yildizpay/http-adapter

Typed exception per HTTP status code

—

✅

Built-in Circuit Breaker

—

✅

Per-request retry/circuit override

—

✅

Response validation hooks

—

✅

isRetryable() signal on errors

—

✅

Structured toJSON() on all errors

—

✅

First-class testing utilities

—

✅

Zero production dependencies

✅

—

✅

Runs on Node.js Native Fetch

✅

—

✅

@yildizpay/http-adapterEnterprise-grade HTTP client for Node.js

Fluent Request Builder

Structured Exception Hierarchy

Response Validation

Resilience & Retries

Observability

First-class Testing Utilities

See It in Action ​

Why @yildizpay/http-adapter? ​

See It in Action

Why @yildizpay/http-adapter?