@zerotal/client 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog — @zerotal/client
+
+All notable changes to this package are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/); this package
+follows the Zerotal monorepo's unified versioning.
+
+**Maturity: `stable`**
+
+## [Unreleased]
+
+## [1.0.0] — 2026-08-05
+
+_First public release._
+
+### Changed
+
+- Moved service provider to `src/provider/`.
+- Provider now declares `static provides`/`environments`; config factory takes `Partial<>`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zerotal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# @zerotal/client
+
+> Type-safe HTTP API client bound to a route map, with a built-in circuit breaker.
+
+A fetch-based HTTP client that infers request bodies, path params, query params, and response shapes directly from a TypeScript route map — no casting. Includes request/response interceptors, 401 token-refresh handling, and a circuit breaker that fails fast when an upstream service is struggling.
+
+> **`@zerotal/client` vs core's `Http` facade** — they solve different problems, despite both speaking HTTP:
+>
+> - Use **`@zerotal/client`** (`ApiClient`) for the **frontend/SPA** consuming _your own_ typed API — it's route-map-typed and ships a familiar realtime `Socket`.
+> - Use core's **`Http`** facade (`@zerotal/core`) for **server-to-server** outgoing requests — fluent, with test fakes.
+
+Part of the [Zerotal](../../README.md) framework. Requires **Bun ≥ 1.3.14**.
+
+## Installation
+
+```bash
+bun add @zerotal/client
+```
+
+## Setup
+
+Register the provider in `bootstrap/providers.ts`:
+
+```ts
+import { ClientProvider } from "@zerotal/client";
+```
+
+## Usage
+
+Define your API surface as a route map, then create a client bound to it:
+
+```ts
+// api-types.ts
+export interface Routes {
+  "GET /api/users": {
+    query: { page?: number; search?: string };
+    response: { data: UserResource[]; total: number };
+  };
+  "GET /api/users/{id}": { params: { id: number }; response: UserResource };
+  "POST /api/users": { body: { name: string; email: string }; response: UserResource };
+}
+```
+
+```ts
+import { createApiClient } from "@zerotal/client";
+import type { Routes } from "./api-types.ts";
+
+export const api = createApiClient<Routes>({
+  baseUrl: "https://api.example.com",
+  headers: { Accept: "application/json" },
+});
+```
+
+Request methods are fully typed against the route map:
+
+```ts
+const user = await api.get("/api/users/{id}", { id: 42 }); // -> UserResource
+const list = await api.get("/api/users", undefined, { query: { page: 2, search: "alice" } });
+const created = await api.post("/api/users", { name: "Alice", email: "alice@example.com" });
+```
+
+Attach interceptors and 401 refresh handling at construction:
+
+```ts
+const api = createApiClient<Routes>({
+  baseUrl: "https://api.example.com",
+  onRequest: async (config) => ({
+    ...config,
+    headers: { ...config.headers, Authorization: `Bearer ${await tokenStore.get()}` },
+  }),
+  onUnauthorized: async (err, retry) => {
+    const newToken = await authStore.refresh();
+    return retry({ Authorization: `Bearer ${newToken}` }); // limited to one attempt
+  },
+});
+```
+
+Add a circuit breaker to fail fast against an unhealthy upstream:
+
+```ts
+import { CircuitBreaker, CircuitBreakerOpenError } from "@zerotal/client";
+
+const api = createApiClient<Routes>({
+  baseUrl: "https://api.example.com",
+  circuitBreaker: { threshold: 5, resetTimeout: 30_000 },
+});
+
+// CircuitBreaker also wraps any async operation directly:
+const breaker = new CircuitBreaker({ threshold: 3, resetTimeout: 15_000 });
+const rates = await breaker.call(() =>
+  fetch("https://pricing.internal/rates").then((r) => r.json()),
+);
+```
+
+Non-2xx responses throw `ApiClientError` (with `status`, `statusText`, `body`); a `422` throws a typed `ValidationError` (`.errors`, `.has()`, `.first()`); an open circuit throws `CircuitBreakerOpenError`.
+
+The client also handles **auth & CSRF** (`token`/`setToken`, `withCredentials`, `XSRF-TOKEN` → `X-XSRF-TOKEN`), **timeouts & retries** (`timeout`, `retry` with backoff + `Retry-After`), **file uploads/downloads** (`FormData`/`Blob` bodies, `responseType: "blob"`), nested query serialization (`ids[]=`, `filter[x]=`), and a per-request `meta` callback for response headers. See [the docs](../../docs/client/index.md).
+
+### Realtime: `Socket`
+
+A small, dependency-free WebSocket client for [`@zerotal/broadcasting`](../broadcasting)'s native
+`ws` / `redis` drivers, with a familiar realtime-client API (and a drop-in for `window.Echo`). No
+external realtime client required.
+
+```typescript
+import { Socket } from "@zerotal/client";
+
+const socket = new Socket(); // ws(s)://<host>/app/ws
+
+socket.channel("posts").listen("PostPublished", (e) => render(e));
+socket.private(`orders.${id}`).listen("OrderUpdated", (e) => update(e.order));
+socket
+  .presence(`chat.${roomId}`)
+  .here((members) => setOnline(members))
+  .joining((m) => addOnline(m))
+  .leaving((m) => removeOnline(m))
+  .listen("Message", (e) => append(e));
+```
+
+Private/presence channels are authorized with a per-subscription HMAC signature (Pusher-style):
+the client fetches it from `authEndpoint` (default `/broadcasting/auth`, signed server-side with
+`APP_KEY`) and re-fetches on reconnect. Pass `auth.headers` for CSRF, or `authEndpoint: false` for
+connection-level auth. Auto-reconnects and re-subscribes; observe state with
+`socket.on("connected"|"disconnected"|…, cb)`; use `socket.socketId()` as the `X-Socket-ID` header
+so server `toOthers()` broadcasts skip this client. See
+[Broadcasting › Client-side](../../docs/broadcasting/client.md).
+
+## Exports
+
+- `createApiClient<Routes>(config)` — factory returning a type-safe `ApiClient`.
+- `ApiClient` — the client class (`get`, `post`, `put`, `patch`, `delete`, `setToken`).
+- `ApiClientError` — thrown on non-2xx responses (`status`, `statusText`, `body`, `retryAfterMs`).
+- `ValidationError` — thrown on `422`; exposes `.errors`, `.has()`, `.first()`, `.fields()`, `.validationMessage`.
+- `CircuitBreaker` — standalone breaker with `.call()`, `.state`, `.failures`, `.reset()`.
+- `CircuitBreakerOpenError` — thrown immediately while the circuit is open.
+- `Socket` — realtime broadcasting client (`channel`, `private`, `presence`/`join`, `leave`, `socketId`, `on`).
+- `Channel` / `PresenceChannel` — channel objects (`listen`, `stopListening`, `subscribed`, `error`; presence adds `here`/`joining`/`leaving`).
+- `ClientProvider` / `Client` — service provider and facade.
+- `ClientConfig` — config factory.
+- Types: `ApiRouteMap`, `RouteShape`, `HttpMethod`, `PathParams`, `ParamRecord`, `PathsFor`, `ResponseOf`, `BodyOf`, `QueryOf`, `ApiClientConfig`, `RequestConfig`, `RequestInterceptor`, `ResponseContext`, `ResponseInterceptor`, `ResponseMeta`, `RequestOptions`, `GetOptions`, `MutationOptions`, `TokenSource`, `RetryOptions`, `CircuitBreakerOptions`, `CircuitState`, `ClientConfigShape`, `SocketOptions`, `SocketState`, `SocketLike`, `PresenceMember`.
+
+## Documentation
+
+- [API Client](../../docs/client/index.md)

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@zerotal/client",
+  "version": "1.0.0",
+  "license": "MIT",
+  "maturity": "stable",
+  "private": false,
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./Socket": "./src/Socket.ts"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.spec.ts",
+    "!src/**/__fixtures__/**"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@zerotal/core": "1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0"
+  },
+  "description": "Typed HTTP client helpers for Zerotal applications.",
+  "keywords": [
+    "zerotal",
+    "bun",
+    "typescript",
+    "framework"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zerotaldev/zerotal.git",
+    "directory": "packages/client"
+  },
+  "homepage": "https://github.com/zerotaldev/zerotal/tree/main/packages/client#readme",
+  "bugs": "https://github.com/zerotaldev/zerotal/issues"
+}

package/src/ApiClient.ts

@@ -0,0 +1,423 @@
+import type { ApiRouteMap, ParamRecord, PathsFor, ResponseOf, BodyOf, QueryOf } from "./types.ts";
+import { ApiClientError, makeApiError } from "./errors.ts";
+import {
+  interpolatePath,
+  buildUrl,
+  serializeBody,
+  timeoutSignal,
+  readCookie,
+  resolveRetry,
+  withRetry,
+  type RetryOptions,
+} from "./http.ts";
+import { CircuitBreaker } from "./CircuitBreaker.ts";
+import type { CircuitBreakerOptions } from "./CircuitBreaker.ts";
+
+// Re-export the error vocabulary so existing `from "./ApiClient.ts"` imports keep working.
+export { ApiClientError, ValidationError } from "./errors.ts";
+export type { RetryOptions } from "./http.ts";
+
+// ── Interceptor types ─────────────────────────────────────────────────────────
+
+/**
+ * The mutable request configuration passed through `onRequest` interceptors.
+ * Modify and return the object (or a new one) to alter the outgoing request.
+ */
+export interface RequestConfig {
+  method: string;
+  url: string;
+  /** Merged headers — modify here to add/override per-request headers. */
+  headers: Record<string, string>;
+  /** The request body (serialized): JSON string, `FormData`, `Blob`, … or `undefined`. */
+  body: BodyInit | undefined;
+}
+
+/**
+ * Called before every outgoing request. Must return the (possibly mutated) `RequestConfig`.
+ *
+ * @example
+ * onRequest: async (cfg) => ({
+ *   ...cfg,
+ *   headers: { ...cfg.headers, Authorization: `Bearer ${await tokenStore.get()}` },
+ * })
+ */
+export type RequestInterceptor = (config: RequestConfig) => RequestConfig | Promise<RequestConfig>;
+
+/** The context passed to `onResponse` interceptors after a successful (2xx) response. */
+export interface ResponseContext {
+  /** HTTP status code of the response. */
+  status: number;
+  /** Response headers. */
+  headers: Headers;
+  /** Parsed response body (JSON-decoded, text, blob/arrayBuffer per `responseType`, or `undefined`). */
+  data: unknown;
+  /** The request config after all `onRequest` interceptors have run. */
+  request: RequestConfig;
+}
+
+/**
+ * Called after every successful (2xx) response, before the parsed body is returned. Must return
+ * the (possibly mutated) `ResponseContext`. Useful for unwrapping API envelopes, logging, etc.
+ */
+export type ResponseInterceptor = (
+  ctx: ResponseContext,
+) => ResponseContext | Promise<ResponseContext>;
+
+/** Lightweight response metadata handed to a per-request `meta` callback. */
+export interface ResponseMeta {
+  status: number;
+  headers: Headers;
+}
+
+// ── Request options ───────────────────────────────────────────────────────────
+
+export interface RequestOptions {
+  /** Extra headers merged on top of the client's default headers. */
+  headers?: Record<string, string>;
+  /** Additional `RequestInit` fields (e.g. `credentials`, `mode`, `cache`). */
+  init?: Omit<RequestInit, "method" | "headers" | "body">;
+  /** Abort signal for cancellation (combined with any `timeout`). */
+  signal?: AbortSignal;
+  /** Per-request timeout in ms (overrides the client default; `0` disables). */
+  timeout?: number;
+  /** Per-request retry policy (overrides the client default; `false` disables). */
+  retry?: number | RetryOptions | false;
+  /** How to read the response body. Default `"auto"` (JSON with text fallback). */
+  responseType?: "auto" | "json" | "text" | "blob" | "arrayBuffer";
+  /** Read response metadata (status, headers) without a global interceptor. */
+  meta?: (meta: ResponseMeta) => void;
+}
+
+export interface GetOptions<Q> extends RequestOptions {
+  /** Query-string parameters (nested arrays/objects are serialized with bracket notation). */
+  query?: Q;
+}
+
+export interface MutationOptions<Q> extends RequestOptions {
+  /** URL path parameters for routes like `/api/users/{id}/action`. */
+  params?: Record<string, string | number>;
+  /** Query-string parameters. */
+  query?: Q;
+}
+
+// ── Client config ─────────────────────────────────────────────────────────────
+
+/** A bearer token, or a (possibly async) function resolving one per request. */
+export type TokenSource =
+  string | (() => string | null | undefined | Promise<string | null | undefined>);
+
+export interface ApiClientConfig {
+  /** Base URL prepended to every request path, e.g. `'https://api.example.com'`. */
+  baseUrl?: string;
+  /** Default headers sent with every request (e.g. `Authorization`). */
+  headers?: Record<string, string>;
+  /**
+   * Bearer token attached as `Authorization: Bearer <token>` when no `Authorization` header is
+   * already present. May be a string or a (possibly async) resolver. Update at runtime with
+   * {@link ApiClient.setToken}.
+   */
+  token?: TokenSource;
+  /** Send credentials (cookies) with every request — sets `credentials: 'include'`. */
+  withCredentials?: boolean;
+  /**
+   * Attach the CSRF/XSRF token to mutating requests: reads the `XSRF-TOKEN` cookie and sends it as
+   * `X-XSRF-TOKEN` (the SPA/session flow). Defaults to `true` when `withCredentials` is set.
+   * Customize the cookie/header names with an object.
+   */
+  csrf?: boolean | { cookie?: string; header?: string };
+  /** Default per-request timeout in ms (`0`/omitted = no timeout). */
+  timeout?: number;
+  /**
+   * Default retry policy. `2` retries idempotent requests on network errors / 5xx / 429 with
+   * exponential backoff (honoring `Retry-After`); pass {@link RetryOptions} to tune, or omit to
+   * disable. Per-request `retry` overrides this.
+   */
+  retry?: number | RetryOptions;
+  /** Called for every non-2xx response before the error is thrown. */
+  onError?: (error: ApiClientError) => void | Promise<void>;
+  /** Called when a request receives `403 Forbidden`. */
+  onForbidden?: (error: ApiClientError) => void | Promise<void>;
+  /** One or more request interceptors executed in order before every fetch. */
+  onRequest?: RequestInterceptor | RequestInterceptor[];
+  /** One or more response interceptors executed in order after every successful (2xx) response. */
+  onResponse?: ResponseInterceptor | ResponseInterceptor[];
+  /**
+   * Called when a request receives `401 Unauthorized`. Receives the error and a `retry` function
+   * (optionally with header overrides) to re-execute the request once.
+   *
+   * @example
+   * onUnauthorized: async (err, retry) => retry({ Authorization: `Bearer ${await refresh()}` }),
+   */
+  onUnauthorized?: (
+    error: ApiClientError,
+    retry: (headerOverrides?: Record<string, string>) => Promise<unknown>,
+  ) => Promise<unknown> | void;
+  /** Attach a circuit breaker (instance to share, or options to create a dedicated one). */
+  circuitBreaker?: CircuitBreaker | CircuitBreakerOptions;
+}
+
+// ── ApiClient<Routes> ───────────────────────────────────────────────────────────
+
+/**
+ * Type-safe HTTP client bound to a route map.
+ *
+ * Do not instantiate directly — use `createApiClient<Routes>(config)`.
+ */
+export class ApiClient<Routes extends ApiRouteMap> {
+  private readonly _baseUrl: string;
+  private readonly _headers: Record<string, string>;
+  private _token: TokenSource | undefined;
+  private readonly _withCredentials: boolean;
+  private readonly _csrf: { cookie: string; header: string } | undefined;
+  private readonly _timeout: number | undefined;
+  private readonly _retry: number | RetryOptions | undefined;
+  private readonly _onError: ((e: ApiClientError) => void | Promise<void>) | undefined;
+  private readonly _onForbidden: ((e: ApiClientError) => void | Promise<void>) | undefined;
+  private readonly _interceptors: RequestInterceptor[];
+  private readonly _responseInterceptors: ResponseInterceptor[];
+  private readonly _onUnauthorized: ApiClientConfig["onUnauthorized"];
+  private readonly _breaker: CircuitBreaker | undefined;
+
+  constructor(config: ApiClientConfig = {}) {
+    this._baseUrl = config.baseUrl ?? "";
+    this._headers = config.headers ?? {};
+    this._token = config.token;
+    this._withCredentials = config.withCredentials ?? false;
+    this._timeout = config.timeout;
+    this._retry = config.retry;
+    this._onError = config.onError;
+    this._onForbidden = config.onForbidden;
+    this._onUnauthorized = config.onUnauthorized;
+    this._interceptors = _asArray(config.onRequest);
+    this._responseInterceptors = _asArray(config.onResponse);
+
+    const csrf = config.csrf ?? (this._withCredentials ? true : false);
+    this._csrf = csrf
+      ? {
+          cookie: (typeof csrf === "object" && csrf.cookie) || "XSRF-TOKEN",
+          header: (typeof csrf === "object" && csrf.header) || "X-XSRF-TOKEN",
+        }
+      : undefined;
+
+    this._breaker =
+      config.circuitBreaker instanceof CircuitBreaker
+        ? config.circuitBreaker
+        : config.circuitBreaker
+          ? new CircuitBreaker(config.circuitBreaker as CircuitBreakerOptions)
+          : undefined;
+  }
+
+  /** Update (or clear) the bearer token used for subsequent requests. */
+  setToken(token: TokenSource | null): void {
+    this._token = token ?? undefined;
+  }
+
+  // ── GET ─────────────────────────────────────────────────────────────────────
+
+  /**
+   * Send a typed GET request.
+   *
+   * @example
+   * const user = await api.get('/api/users/{id}', { id: 1 });   // ^? UserResource
+   * const list = await api.get('/api/users', undefined, { query: { page: 2 } });
+   */
+  async get<Path extends PathsFor<Routes, "GET">>(
+    path: Path,
+    params?: ParamRecord<Path & string>,
+    options?: GetOptions<QueryOf<Routes, "GET", Path & string>>,
+  ): Promise<ResponseOf<Routes, "GET", Path & string>> {
+    const url = buildUrl(
+      this._baseUrl,
+      interpolatePath(path as string, params as Record<string, string | number> | undefined),
+      options?.query as Record<string, unknown> | undefined,
+    );
+    return this._send("GET", url, undefined, options);
+  }
+
+  // ── POST ────────────────────────────────────────────────────────────────────
+
+  /**
+   * Send a typed POST request. The body may be a plain object (JSON), `FormData`, `Blob`,
+   * `URLSearchParams`, or a string.
+   *
+   * @example
+   * await api.post('/api/users', { name: 'Alice', email: 'alice@example.com' });
+   * await api.post('/api/avatars', formData);   // multipart upload
+   */
+  async post<Path extends PathsFor<Routes, "POST">>(
+    path: Path,
+    body?: BodyOf<Routes, "POST", Path & string>,
+    options?: MutationOptions<QueryOf<Routes, "POST", Path & string>>,
+  ): Promise<ResponseOf<Routes, "POST", Path & string>> {
+    return this._send("POST", this._mutationUrl(path, options), body, options);
+  }
+
+  // ── PUT ─────────────────────────────────────────────────────────────────────
+
+  async put<Path extends PathsFor<Routes, "PUT">>(
+    path: Path,
+    body?: BodyOf<Routes, "PUT", Path & string>,
+    options?: MutationOptions<QueryOf<Routes, "PUT", Path & string>>,
+  ): Promise<ResponseOf<Routes, "PUT", Path & string>> {
+    return this._send("PUT", this._mutationUrl(path, options), body, options);
+  }
+
+  // ── PATCH ───────────────────────────────────────────────────────────────────
+
+  async patch<Path extends PathsFor<Routes, "PATCH">>(
+    path: Path,
+    body?: BodyOf<Routes, "PATCH", Path & string>,
+    options?: MutationOptions<QueryOf<Routes, "PATCH", Path & string>>,
+  ): Promise<ResponseOf<Routes, "PATCH", Path & string>> {
+    return this._send("PATCH", this._mutationUrl(path, options), body, options);
+  }
+
+  // ── DELETE ──────────────────────────────────────────────────────────────────
+
+  async delete<Path extends PathsFor<Routes, "DELETE">>(
+    path: Path,
+    params?: ParamRecord<Path & string>,
+    options?: RequestOptions,
+  ): Promise<ResponseOf<Routes, "DELETE", Path & string>> {
+    const url = buildUrl(
+      this._baseUrl,
+      interpolatePath(path as string, params as Record<string, string | number> | undefined),
+    );
+    return this._send("DELETE", url, undefined, options);
+  }
+
+  // ── Internals ─────────────────────────────────────────────────────────────────
+
+  private _mutationUrl(path: string, options?: MutationOptions<unknown>): string {
+    return buildUrl(
+      this._baseUrl,
+      interpolatePath(path, options?.params),
+      options?.query as Record<string, unknown> | undefined,
+    );
+  }
+
+  /** Merge default + token + CSRF + per-request headers. */
+  private async _buildHeaders(
+    method: string,
+    perRequest: Record<string, string> | undefined,
+  ): Promise<Record<string, string>> {
+    const headers: Record<string, string> = { ...this._headers, ...perRequest };
+
+    if (this._token !== undefined && !_hasHeader(headers, "authorization")) {
+      const tok = typeof this._token === "function" ? await this._token() : this._token;
+      if (tok) headers["Authorization"] = `Bearer ${tok}`;
+    }
+
+    if (this._csrf && _isMutating(method) && !_hasHeader(headers, this._csrf.header)) {
+      const value = readCookie(this._csrf.cookie);
+      if (value) headers[this._csrf.header] = value;
+    }
+
+    return headers;
+  }
+
+  private async _parseResponse(
+    res: Response,
+    type: RequestOptions["responseType"],
+  ): Promise<unknown> {
+    if (type === "blob") return res.blob();
+    if (type === "arrayBuffer") return res.arrayBuffer();
+    if (res.status === 204 || res.headers.get("content-length") === "0") return undefined;
+    if (type === "text") return res.text();
+    const text = await res.text();
+    if (!text) return undefined;
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text; // "auto" / "json": fall back to raw text for non-JSON bodies
+    }
+  }
+
+  private async _send<T>(
+    method: string,
+    url: string,
+    body: unknown,
+    options?: RequestOptions,
+    _isRetry = false,
+  ): Promise<T> {
+    const headers = await this._buildHeaders(method, options?.headers);
+    const { body: serialized, contentType } = serializeBody(body);
+    if (contentType && !_hasHeader(headers, "content-type")) headers["Content-Type"] = contentType;
+
+    let config: RequestConfig = { method, url, headers, body: serialized };
+    for (const interceptor of this._interceptors) config = await interceptor(config);
+
+    const timeout = options?.timeout ?? this._timeout;
+    const policy = resolveRetry(options?.retry ?? this._retry, method);
+    const userSignal = options?.signal ?? options?.init?.signal ?? undefined;
+    const credentials =
+      options?.init?.credentials ?? (this._withCredentials ? "include" : undefined);
+
+    const attempt = async (): Promise<Response> => {
+      const signal = timeoutSignal(timeout, userSignal);
+      const init: RequestInit = { method: config.method, headers: config.headers };
+      if (config.body !== undefined) init.body = config.body;
+      Object.assign(init, options?.init);
+      if (signal) init.signal = signal;
+      if (credentials) init.credentials = credentials;
+
+      const raw = await fetch(config.url, init);
+      if (!raw.ok) {
+        const text = await raw.text().catch(() => "");
+        throw makeApiError(raw.status, raw.statusText, text, raw.headers);
+      }
+      return raw;
+    };
+    const runOnce = (): Promise<Response> =>
+      this._breaker ? this._breaker.call(attempt) : attempt();
+
+    let res: Response;
+    try {
+      res = await withRetry(runOnce, policy);
+    } catch (err) {
+      if (err instanceof ApiClientError) {
+        // 401 → optional one-shot refresh + retry.
+        if (err.status === 401 && !_isRetry && this._onUnauthorized) {
+          const retry = (headerOverrides?: Record<string, string>): Promise<unknown> =>
+            this._send<unknown>(
+              method,
+              url,
+              body,
+              { ...options, headers: { ...options?.headers, ...headerOverrides } },
+              true,
+            );
+          const result = await this._onUnauthorized(err, retry);
+          if (result !== undefined) return result as T;
+        }
+        if (err.status === 403) await this._onForbidden?.(err);
+        await this._onError?.(err);
+      }
+      throw err;
+    }
+
+    const data = await this._parseResponse(res, options?.responseType);
+
+    let ctx: ResponseContext = { status: res.status, headers: res.headers, data, request: config };
+    for (const interceptor of this._responseInterceptors) ctx = await interceptor(ctx);
+
+    options?.meta?.({ status: res.status, headers: res.headers });
+
+    return ctx.data as T;
+  }
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────────
+
+function _asArray<T>(v: T | T[] | undefined): T[] {
+  return v ? (Array.isArray(v) ? v : [v]) : [];
+}
+
+function _hasHeader(headers: Record<string, string>, name: string): boolean {
+  const lower = name.toLowerCase();
+  return Object.keys(headers).some((k) => k.toLowerCase() === lower);
+}
+
+function _isMutating(method: string): boolean {
+  const m = method.toUpperCase();
+  return m === "POST" || m === "PUT" || m === "PATCH" || m === "DELETE";
+}