@molecule/api-http-axios

Axios HTTP client provider for molecule.dev.

Implements the @molecule/api-http HttpClient contract with axios, adding the optional capabilities the core's built-in fetch client lacks: request/response/error interceptors, create(defaults) for derived clients, and pre-configured instances via createClient({ baseURL, timeout, headers }) (or a custom axios instance). Errors are normalized to HttpError — axios internals never leak to callers.

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

import { setClient } from '@molecule/api-http'
import { createClient } from '@molecule/api-http-axios'

const client = createClient({ baseURL: 'https://api.example.com', timeout: 5000 })
client.addRequestInterceptor?.((req) => ({
  ...req,
  headers: { ...req.headers, 'X-Request-Id': crypto.randomUUID() },
}))
setClient(client)

Type

provider

Installation

npm install @molecule/api-http-axios @molecule/api-http axios

API

Interfaces

AxiosClientOptions

Options for creating an Axios client.

interface AxiosClientOptions extends HttpRequestOptions {
  /**
   * Axios instance to use (if not provided, a new one is created).
   */
  instance?: AxiosInstance
}

HttpRequestOptions

HTTP request options.

interface HttpRequestOptions {
  /**
   * HTTP method.
   */
  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS'
  /**
   * Request headers.
   */
  headers?: Record<string, string>
  /**
   * Request body (will be JSON-stringified if object).
   */
  body?: unknown
  /**
   * Query parameters.
   */
  params?: Record<string, string | number | boolean | undefined>
  /**
   * Request timeout in milliseconds.
   */
  timeout?: number
  /**
   * Base URL to prepend to the request URL.
   */
  baseURL?: string
  /**
   * Whether to include credentials (cookies) in the request.
   */
  credentials?: 'omit' | 'same-origin' | 'include'
  /**
   * Response type.
   */
  responseType?: 'json' | 'text' | 'blob' | 'arraybuffer'
  /**
   * Signal for aborting the request.
   */
  signal?: AbortSignal
  /**
   * Custom options passed to the underlying client.
   */
  [key: string]: unknown
}

HttpResponse

HTTP response.

interface HttpResponse<T = unknown> {
  /**
   * Response status code.
   */
  status: number
  /**
   * Response status text.
   */
  statusText: string
  /**
   * Response headers.
   */
  headers: Record<string, string>
  /**
   * Response body.
   */
  data: T
  /**
   * Original request options.
   */
  request: HttpRequestOptions & {
    url: string
  }
}

HttpError

HTTP error.

interface HttpError extends Error {
  /**
   * Response (if available).
   */
  response?: HttpResponse
  /**
   * Request options.
   */
  request: HttpRequestOptions & {
    url: string
  }
  /**
   * Error code (e.g., 'ECONNREFUSED', 'ETIMEDOUT').
   */
  code?: string
  /**
   * Whether the request was aborted.
   */
  isAborted?: boolean
  /**
   * Whether the request timed out.
   */
  isTimeout?: boolean
}

HttpClient

HTTP client interface that all HTTP bond packages must implement.

Provides methods for each HTTP verb plus optional interceptors and client factory support.

interface HttpClient {
  /**
   * Makes an HTTP request.
   */
  request<T = unknown>(url: string, options?: HttpRequestOptions): Promise<HttpResponse<T>>
  /**
   * Makes a GET request.
   */
  get<T = unknown>(
    url: string,
    options?: Omit<HttpRequestOptions, 'method' | 'body'>,
  ): Promise<HttpResponse<T>>
  /**
   * Makes a POST request.
   */
  post<T = unknown>(
    url: string,
    body?: unknown,
    options?: Omit<HttpRequestOptions, 'method' | 'body'>,
  ): Promise<HttpResponse<T>>
  /**
   * Makes a PUT request.
   */
  put<T = unknown>(
    url: string,
    body?: unknown,
    options?: Omit<HttpRequestOptions, 'method' | 'body'>,
  ): Promise<HttpResponse<T>>
  /**
   * Makes a PATCH request.
   */
  patch<T = unknown>(
    url: string,
    body?: unknown,
    options?: Omit<HttpRequestOptions, 'method' | 'body'>,
  ): Promise<HttpResponse<T>>
  /**
   * Makes a DELETE request.
   */
  delete<T = unknown>(
    url: string,
    options?: Omit<HttpRequestOptions, 'method'>,
  ): Promise<HttpResponse<T>>
  /**
   * Creates a new client with the given defaults.
   */
  create?(defaults: HttpRequestOptions): HttpClient
  /**
   * Adds a request interceptor.
   */
  addRequestInterceptor?(interceptor: RequestInterceptor): () => void
  /**
   * Adds a response interceptor.
   */
  addResponseInterceptor?(interceptor: ResponseInterceptor): () => void
  /**
   * Adds an error interceptor.
   */
  addErrorInterceptor?(interceptor: ErrorInterceptor): () => void
}

Types

RequestInterceptor

Function that transforms an outgoing HTTP request before it is sent (e.g. add auth headers).

type RequestInterceptor = (
  options: HttpRequestOptions & {
    url: string
  },
) =>
  | (HttpRequestOptions & {
      url: string
    })
  | Promise<
      HttpRequestOptions & {
        url: string
      }
    >

ResponseInterceptor

Function that transforms an incoming HTTP response before it is returned (e.g. unwrap data).

type ResponseInterceptor<T = unknown> = (
  response: HttpResponse<T>,
) => HttpResponse<T> | Promise<HttpResponse<T>>

• response — The response object.

ErrorInterceptor

Callback invoked when an HTTP request fails, allowing error transformation or logging before re-throwing.

type ErrorInterceptor = (error: HttpError) => HttpError | Promise<HttpError>

Functions

createClient(options)

Creates an Axios-backed HTTP client that implements the HttpClient interface. Supports request/response/error interceptors and per-request configuration.

function createClient(options?: AxiosClientOptions): HttpClient

• options — Axios client options (baseURL, timeout, headers, or a pre-configured instance).

Returns: An HttpClient backed by Axios.

toHttpResponse(response, requestOptions)

Converts axios response to HttpResponse.

function toHttpResponse(
  response: AxiosResponse<T, any, {}, any>,
  requestOptions: HttpRequestOptions & { url: string },
): HttpResponse<T>

• response — The response object.
• requestOptions — The request options.

Returns: The transformed result.

sanitizeRequestOptions(requestOptions)

Returns a shallow copy of request options with secret-bearing fields redacted. The request body (which for an OAuth token exchange contains client_secret/code/refresh_token) is replaced with a placeholder, and any authorization header (Basic client_secret or Bearer access token) is masked. This is applied before attaching the request to an HttpError so a caught/logged error can never emit a credential to logs (CWE-532). The success path (toHttpResponse from client.request) is unaffected, so legitimate consumers of response.request still see the full options.

function sanitizeRequestOptions(
  requestOptions: HttpRequestOptions & { url: string },
): HttpRequestOptions & { url: string }

• requestOptions — The original request options.

Returns: A redacted copy safe to attach to an error destined for logs.

toHttpError(error, requestOptions)

Converts axios error to HttpError.

function toHttpError(
  error: AxiosError,
  requestOptions: HttpRequestOptions & { url: string },
): HttpError

• error — The error.
• requestOptions — The request options.

Returns: The transformed result.

Constants

client

The default Axios HTTP client instance with default configuration.

const client: HttpClient

provider

Alias for the client (for consistency with other providers).

const provider: HttpClient

Namespaces

axios

Core Interface

Implements @molecule/api-http interface.

Bond Wiring

Setup function to register this provider with the core interface:

import { setClient } from '@molecule/api-http'
import { provider } from '@molecule/api-http-axios'

export function setupHttpAxios(): void {
  setClient(provider)
}

Injection Notes

Requirements

Peer dependencies:

• @molecule/api-http ^1.0.1

Runtime Dependencies

• @molecule/api-http

• axios

• This category wires via setClient() from @molecule/api-http — NOT setProvider. Without any bond the core already falls back to a built-in fetch client; bond this package only when you need interceptors, create(), or per-instance defaults.

• The exported provider (alias client) is a shared default instance created with no options — interceptors added to it apply process-wide. Prefer createClient() for scoped/per-service instances.