Interceptors

Interceptors let you hook into the request/response lifecycle to implement cross-cutting concerns like authentication, logging, error handling, and data transformation — without modifying individual request call sites.

Interface Segregation

Thanks to the Interface Segregation Principle (ISP), you implement only the hooks you actually need. Three focused interfaces are available:

Interface	Hook	When it fires
HttpRequestInterceptor	onRequest(request)	Before the HTTP call, after all request interceptors
HttpResponseInterceptor	onResponse(response)	After a successful HTTP response
HttpErrorInterceptor	onError(error, request)	When an error is thrown

A single class can implement any combination of these interfaces.

Lifecycle

onRequest → HTTP call → onResponse → validators → onResponseValidated → caller
                                          ↓ (on failure)
                                       onError

onResponse always fires on a successful HTTP call. onResponseValidated only fires when all attached validators pass — ideal for caching or side effects that require a business-valid response.

Request Interceptor

Use for adding common headers like auth tokens before requests leave.

import { HttpRequestInterceptor, Request } from '@yildizpay/http-adapter';

export class AuthInterceptor implements HttpRequestInterceptor {
  constructor(private readonly tokenService: TokenService) {}

  async onRequest(request: Request): Promise<Request> {
    const token = await this.tokenService.getAccessToken();
    request.addHeader('Authorization', `Bearer ${token}`);
    return request;
  }
}

Response Interceptor

Use for inspecting or transforming payloads uniformly across all responses.

import { HttpResponseInterceptor, Response } from '@yildizpay/http-adapter';

export class LoggingInterceptor implements HttpResponseInterceptor {
  async onResponse(response: Response): Promise<Response> {
    console.log(`[HTTP] ${response.status} — ${response.request?.url}`);
    return response;
  }
}

Error Interceptor

Use for centralized error handling — token refresh, alerting, or transforming errors.

import {
  HttpErrorInterceptor,
  Request,
  BaseAdapterException,
  UnauthorizedException,
} from '@yildizpay/http-adapter';

export class GlobalErrorInterceptor implements HttpErrorInterceptor {
  constructor(private readonly tokenService: TokenService) {}

  async onError(error: BaseAdapterException, request: Request): Promise<never> {
    if (error instanceof UnauthorizedException) {
      await this.tokenService.refresh();
    }
    // Always re-throw — the interceptor cannot suppress errors silently
    throw error;
  }
}

Registering Interceptors

Pass interceptors to the adapter builder. They are executed in the order registered.

const adapter = HttpAdapter.builder()
  .withInterceptor(
    new AuthInterceptor(tokenService),
    new LoggingInterceptor(),
    new GlobalErrorInterceptor(tokenService),
  )
  .build();

Excluding Interceptors per Request

If a specific request should skip one or more interceptors (e.g., a sensitive endpoint that should not be logged), use per-request exclusions. See Request-Level Overrides.