@tech-arelius/api-client/src/builder/ApiClientBuilder.ts

Configurable HTTP client with builder pattern for Node.js/TypeScript

import { ApiClient } from '../client/ApiClient';
import { authorizationInterceptor } from '../interceptor/AuthorizationInterceptor';
import { Interceptor } from '../interceptor/Interceptor';
import { SessionProvider } from '../session/SessionProvider';


/**
 * Builder class for creating configured API clients
 */
export class ApiClientBuilder {
  private _baseUrl?: string;
  private timeout?: number;
  private sessionProvider?: SessionProvider;
  private defaultHeaders: Record<string, string> = {};
  private interceptors: Interceptor[] = [];

  /**
   * Sets the connection timeout in milliseconds
   * @param ms - Timeout in milliseconds
   * @returns This builder instance for chaining
   */
  connectTimeout(ms: number): ApiClientBuilder {
    this.timeout = ms;
    return this;
  }

  /**
   * Sets the base URL for all requests
   * @param url - Base URL
   * @returns This builder instance for chaining
   */
  baseUrl(url: string): ApiClientBuilder {
    this._baseUrl = url;
    return this;
  }

  /**
   * Adds a default header for all requests
   * @param key - Header key
   * @param value - Header value
   * @returns This builder instance for chaining
   */
  addHeader(key: string, value: string): ApiClientBuilder {
    this.defaultHeaders[key] = value;
    return this;
  }

  /**
   * Sets multiple default headers at once
   * @param headers - Object containing header key-value pairs
   * @returns This builder instance for chaining
   */
  addHeaders(headers: Record<string, string>): ApiClientBuilder {
    this.defaultHeaders = { ...this.defaultHeaders, ...headers };
    return this;
  }

  /**
   * Configures authentication with a session provider
   * Automatically adds an authorization interceptor that adds the Authorization header
   * @param provider - Session provider implementation
   * @returns This builder instance for chaining
   */
  withSessionProvider(provider: SessionProvider): ApiClientBuilder {
    this.sessionProvider = provider;
    // Automatically add authorization interceptor
    const authInterceptor = authorizationInterceptor(provider);
    this.interceptors.push(authInterceptor);
    return this;
  }

  /**
   * Adds a custom interceptor for request/response/error handling
   * @param interceptor - Interceptor implementation
   * @returns This builder instance for chaining
   */
  addInterceptor(interceptor: Interceptor): ApiClientBuilder {
    this.interceptors.push(interceptor);
    return this;
  }

  /**
   * Adds multiple interceptors at once
   * @param interceptors - Array of interceptor implementations
   * @returns This builder instance for chaining
   */
  addInterceptors(interceptors: Interceptor[]): ApiClientBuilder {
    this.interceptors.push(...interceptors);
    return this;
  }

  /**
   * Sets the content type header
   * @param contentType - Content type value
   * @returns This builder instance for chaining
   */
  contentType(contentType: string): ApiClientBuilder {
    return this.addHeader('Content-Type', contentType);
  }

  /**
   * Sets the accept header
   * @param accept - Accept value
   * @returns This builder instance for chaining
   */
  accept(accept: string): ApiClientBuilder {
    return this.addHeader('Accept', accept);
  }

  /**
   * Sets user agent header
   * @param userAgent - User agent string
   * @returns This builder instance for chaining
   */
  userAgent(userAgent: string): ApiClientBuilder {
    return this.addHeader('User-Agent', userAgent);
  }

  /**
   * Adds a custom request ID header
   * @param requestId - Request ID value
   * @returns This builder instance for chaining
   */
  requestId(requestId: string): ApiClientBuilder {
    return this.addHeader('X-Request-ID', requestId);
  }

  /**
   * Builds and returns a configured ApiClient instance
   * @returns Configured ApiClient instance
   */
  build(): ApiClient {
    return new ApiClient(
      this._baseUrl,
      this.timeout,
      this.defaultHeaders,
      this.interceptors.length > 0 ? this.interceptors : undefined
    );
  }

}