@molecule/api-http | Molecule.dev

HTTP client core interface for molecule.dev — outbound server-to-server requests.

Defines the HttpClient contract plus convenience functions (request, get, post, put, patch, del) that delegate to the bonded client. Works with ZERO wiring: when no bond is configured, a built-in fetch-based client is used. Bond @molecule/api-http-axios (or another client) only when you need its extras (interceptors, per-instance defaults via create).

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 { get, post } from '@molecule/api-http'
import type { HttpError } from '@molecule/api-http'

try {
  const res = await get<{ id: string }>('https://api.example.com/items/1', {
    headers: { Authorization: `Bearer ${apiToken}` },
    params: { expand: 'owner' },
    timeout: 5000,
  })
  use(res.data) // body is on `.data`, already JSON-parsed
} catch (error) {
  const status = (error as HttpError).response?.status // 404, 500, … — errors THROW
}

Type

core

Installation

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

API

Interfaces

`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

`setClient(client)`

Registers an HTTP client as the active singleton. Called by bond packages during application startup.

function setClient(client: HttpClient): void

client — The HTTP client implementation to bond.

`getClient()`

Retrieves the bonded HTTP client. Falls back to the built-in fetch-based client if no bond has been configured.

function getClient(): HttpClient

Returns: The bonded HTTP client, or the default fetch-based client.

`hasClient()`

Checks whether a custom HTTP client is currently bonded.

function hasClient(): boolean

Returns: true if a custom HTTP client is bonded.