@zerotal/arch 1.7.0

package/docs/client/errors.md

@@ -0,0 +1,139 @@
+---
+title: Client Error Handling
+description: What a failed request throws, and how to tell the failure modes apart.
+---
+
+# Error handling
+
+Non-2xx responses throw `ApiClientError`:
+
+```ts
+// in any frontend module
+import { ApiClientError } from "@zerotal/client";
+
+try {
+  await api.post("/api/users", { name: "", email: "bad" });
+} catch (err) {
+  if (err instanceof ApiClientError) {
+    console.log(err.status); // 422
+    console.log(err.statusText); // 'Unprocessable Entity'
+    console.log(err.body); // raw response text (the error message truncates it to 200 chars)
+  }
+}
+```
+
+## Telling the failure modes apart
+
+Two very different things can go wrong, and only one of them produces an
+`ApiClientError`:
+
+| What happened                    | What is thrown                      |
+| -------------------------------- | ----------------------------------- |
+| The server answered with non-2xx | `ApiClientError`                    |
+| A 422 in the validator's shape   | `ValidationError`                   |
+| The circuit breaker is open      | `CircuitBreakerOpenError`           |
+| No answer at all                 | The platform's own error, unwrapped |
+
+That last row is the one worth internalising. A DNS failure, a dropped connection,
+a CORS rejection, or an aborted request never reaches the point where a status
+exists, so `fetch` rejects with its own error and the client passes it through
+untouched. An `instanceof ApiClientError` check therefore does _not_ catch an
+offline user — and a `catch` block that assumes `err.status` exists throws a second
+error while handling the first.
+
+```ts
+try {
+  await api.get("/api/users");
+} catch (err) {
+  if (err instanceof ValidationError) showFieldErrors(err.errors);
+  else if (err instanceof ApiClientError) showStatus(err.status);
+  else showOffline(); // no response: network, CORS, timeout, or abort
+}
+```
+
+Timeouts and cancellations land in that final branch too, since both abort the
+request rather than producing a response.
+
+## Reading response headers
+
+`ApiClientError` carries the response headers when there were any, which is where
+rate limiters and throttles put the information you need to react well:
+
+```ts
+// in any frontend module
+if (err instanceof ApiClientError && err.status === 429) {
+  const waitMs = err.retryAfterMs; // parsed Retry-After, or null
+  if (waitMs !== null) scheduleRetry(waitMs);
+  console.log(err.headers?.get("X-RateLimit-Remaining"));
+}
+```
+
+`retryAfterMs` handles both forms the header takes — a delta in seconds and an
+HTTP-date — and returns milliseconds, or `null` when the header is absent or
+cannot be parsed.
+
+## Global handlers
+
+The `onError` callback fires for every non-2xx response before the error is thrown.
+Use it for global side-effects (toasts, logging) without needing try/catch at every
+call site:
+
+```ts
+// app/api/client.ts
+const api = createApiClient<Routes>({
+  baseUrl: "https://api.example.com",
+  onError: (err) => {
+    toast.error(`${err.status}: ${err.statusText}`);
+    logger.error("api_error", { status: err.status, body: err.body });
+  },
+});
+```
+
+> **Warning** — `onError` fires for every non-2xx error including 401, even when `onUnauthorized` is also configured. To suppress the global error callback for 401 during token refresh, guard by status inside `onError`.
+
+Because `onError` only ever sees responses, it does not report the network failures
+described above. Reporting that should also cover "the request never arrived"
+belongs in the caller, or in a wrapper around it.
+
+### Typed validation errors
+
+A `422` response whose body matches the framework's validation shape (`{ message, errors }`,
+as produced by [`@zerotal/validator`](/docs/validator)) throws a `ValidationError` — an
+`ApiClientError` subclass with the field errors already parsed:
+
+```ts
+// in any frontend module
+import { ValidationError } from "@zerotal/client";
+
+try {
+  await api.post("/api/users", form);
+} catch (err) {
+  if (err instanceof ValidationError) {
+    setFieldErrors(err.errors); // { email: ["…"], password: ["…"] }
+    err.has("email"); // boolean
+    err.first("email"); // first message, or undefined
+    err.fields(); // ["email", "password"]
+    err.validationMessage; // "The given data was invalid."
+  }
+}
+```
+
+Check for `ValidationError` before `ApiClientError`. It is a subclass, so the
+broader check also matches it and would swallow the parsed field errors.
+
+A 422 whose body does not match that shape stays a plain `ApiClientError`, so an
+endpoint returning its own error format still surfaces as an ordinary failure
+rather than quietly producing an empty `errors` object.
+
+`onForbidden` is the 403 counterpart of `onUnauthorized`:
+
+```ts
+// app/api/client.ts
+createApiClient<Routes>({ onForbidden: () => router.push("/403") });
+```
+
+## Next steps
+
+- [Client overview](/docs/client) — the guide's front page and the rest of the sections.
+- [Resilience](/docs/client/resilience) — retries, timeouts, and the circuit breaker.
+- [Authentication](/docs/client/auth) — the 401 refresh hook.

package/docs/client/files.md

@@ -0,0 +1,118 @@
+---
+title: Client File Transfers
+description: Uploading and downloading binary payloads.
+---
+
+# File uploads & downloads
+
+The client encodes plain objects as JSON, which is the right default until the
+payload is binary. Recognising the difference is the whole of file handling here:
+on the way out, a body the platform already knows how to encode is passed through
+untouched; on the way back, you name the shape you expect.
+
+## Uploading
+
+A body that is `FormData`, `Blob`, `File`, `URLSearchParams`, `ArrayBuffer`, or a
+string is sent as-is with no JSON encoding, which lets `fetch` set the correct
+`Content-Type` — including the multipart boundary, a value that cannot be written
+by hand:
+
+```ts
+// in any frontend module
+const form = new FormData();
+form.append("avatar", file);
+await api.post("/api/avatars", form);
+```
+
+| Body              | Sent as                                     |
+| ----------------- | ------------------------------------------- |
+| Plain object      | JSON, with `Content-Type: application/json` |
+| `FormData`        | Multipart, boundary set by the platform     |
+| `File` / `Blob`   | Raw bytes                                   |
+| `URLSearchParams` | Form-encoded                                |
+| `ArrayBuffer`     | Raw bytes                                   |
+| String            | Sent verbatim                               |
+
+Do not set `Content-Type` yourself for a `FormData` upload. A hand-written header
+has no boundary parameter, and the server then fails to parse a body that is
+otherwise perfectly formed — a confusing failure worth avoiding by simply leaving
+the header alone.
+
+To send a file alongside ordinary fields, put everything in the `FormData`;
+mixing a JSON body and a file in one request is not possible:
+
+```ts
+const form = new FormData();
+form.append("title", "Quarterly report");
+form.append("document", file);
+await api.post("/api/reports", form);
+```
+
+## Downloading
+
+Responses are parsed as JSON unless you say otherwise. `responseType` names the
+shape you want:
+
+| `responseType`  | Returns              | Reach for it when                    |
+| --------------- | -------------------- | ------------------------------------ |
+| `"auto"`        | Parsed JSON, or text | The default — JSON with a safety net |
+| `"json"`        | Parsed JSON, or text | The body is known to be JSON         |
+| `"text"`        | `string`             | CSV, XML, plain text                 |
+| `"blob"`        | `Blob`               | Saving or displaying a file          |
+| `"arrayBuffer"` | `ArrayBuffer`        | Reading bytes directly               |
+
+```ts
+// in any frontend module
+const pdf = await api.get("/api/report", undefined, { responseType: "blob" });
+```
+
+`"auto"` and `"json"` fall back to the raw text when the body will not parse, so a
+misconfigured endpoint returning an HTML error page surfaces that page rather than
+a parse exception.
+
+A `204 No Content` response — or any response with `Content-Length: 0` — resolves
+to `undefined` rather than throwing, so a `DELETE` needs no special handling:
+
+```ts
+await api.delete("/api/avatars/1"); // → undefined
+```
+
+Handing a downloaded blob to the browser takes one more step, since the client
+returns the data rather than saving it:
+
+```ts
+const blob = await api.get("/api/report", undefined, { responseType: "blob" });
+
+const url = URL.createObjectURL(blob);
+const a = Object.assign(document.createElement("a"), { href: url, download: "report.pdf" });
+a.click();
+URL.revokeObjectURL(url);
+```
+
+## Reading response metadata
+
+Binary endpoints often carry the interesting information in headers. A per-request
+`meta` callback reads them without installing a global interceptor:
+
+```ts
+// in any frontend module
+let total: string | null = null;
+const users = await api.get("/api/users", undefined, {
+  meta: (m) => (total = m.headers.get("X-Total")),
+});
+```
+
+This is the way to reach pagination totals, rate-limit counters, and `ETag` values
+while still receiving the parsed body as the return value.
+
+## Query serialization
+
+Query objects serialize arrays and nested objects with bracket notation:
+`{ ids: [1, 2], filter: { status: "open" } }` becomes
+`?ids[]=1&ids[]=2&filter[status]=open`.
+
+## Next steps
+
+- [Client overview](/docs/client) — the guide's front page and the rest of the sections.
+- [Making requests](/docs/client/requests) — the full request surface.
+- [Error handling](/docs/client/errors) — what a failed transfer throws.

package/docs/client/index.md

@@ -0,0 +1,128 @@
+---
+title: API Client
+description: Call your HTTP API with full TypeScript inference of params, body, query, and response shapes.
+---
+
+# API Client
+
+A type-safe HTTP client bound to a route map. The TypeScript compiler infers
+request body types, path parameters, query parameters, and response shapes directly
+from the map — no casting required.
+
+This is the **frontend/SPA** client for calling _your own_ typed API. For
+**server-to-server** outgoing HTTP from inside your app, reach for core's `Http`
+facade ([HTTP Client helpers](/docs/context)) instead — it's the fluent,
+fakeable, server-side HTTP client. Same protocol, different jobs.
+
+## Getting Started
+
+```bash
+# in your project root
+bun add @zerotal/client
+```
+
+You can use the client two ways: create instances yourself with `createApiClient()`
+(typical for the browser/frontend), or register `ClientProvider` to resolve a shared,
+config-driven client from the container (typical for server-side and console code).
+
+## Register the provider
+
+Registering the provider is optional — it gives you one container-bound `client`
+built from `config/client.ts`. Add `ClientProvider` to the providers array in
+`bootstrap/providers.ts`:
+
+```ts
+// bootstrap/providers.ts
+import { ClientProvider } from "@zerotal/client";
+
+const providers = [
+  // …your other providers
+  ClientProvider,
+];
+
+export default providers;
+```
+
+Registering the provider switches on the following:
+
+- `onRegister` — binds an `ApiClient` as a lazy singleton under the `client` key, built from the `client` config namespace.
+- `onBooted` — pre-resolves that async singleton so the `Client` facade can be accessed synchronously after boot.
+
+The provider is active in the `web`, `console`, `worker`, `test`, and `repl`
+environments. Resolve the shared client via the container or the `Client` facade:
+
+```ts
+// in a controller or service
+import { Client } from "@zerotal/client";
+
+const users = await Client.get("/api/users");
+```
+
+## Configuration
+
+Create `config/client.ts` with the `ClientConfig()` helper (or `satisfies
+ClientConfigShape`) so every field stays type-checked. The shape extends
+[`ApiClientConfig`](/docs/client/references) — every client option below is valid here:
+
+```ts
+// config/client.ts
+import { ClientConfig } from "@zerotal/client";
+import { env } from "zerotal";
+
+export default ClientConfig({
+  baseUrl: env("API_BASE_URL", "https://api.example.com"),
+  headers: { Accept: "application/json" },
+});
+```
+
+| Field             | Required | Default | Description                                                    |
+| ----------------- | -------- | ------- | -------------------------------------------------------------- |
+| `baseUrl`         | no       | `""`    | Base URL prepended to every request path.                      |
+| `headers`         | no       | `{}`    | Default headers sent with every request.                       |
+| `token`           | no       | —       | Bearer token (string or resolver) attached as `Authorization`. |
+| `withCredentials` | no       | `false` | Send cookies (`credentials: 'include'`); also turns CSRF on.   |
+| `csrf`            | no       | —       | CSRF cookie/header names, or a boolean to force on/off.        |
+| `timeout`         | no       | —       | Default per-request timeout in ms (`0`/omitted = none).        |
+| `retry`           | no       | —       | Default retry policy (number of attempts or `RetryOptions`).   |
+
+> **Note** — The provider carries no framework-level defaults of its own; `ApiClient`
+> applies its own internal defaults. The config file is just typed input.
+
+## Create a client directly
+
+In the browser (or anywhere you want a standalone instance), build a client with
+`createApiClient<Routes>()`:
+
+```ts
+// app/api/client.ts
+import { createApiClient } from "@zerotal/client";
+import { env } from "zerotal";
+import type { Routes } from "./api-types.ts";
+
+export const api = createApiClient<Routes>({
+  baseUrl: env("API_BASE_URL", "https://api.example.com"),
+  headers: { Accept: "application/json" },
+});
+```
+
+> **Tip** — Don't instantiate `ApiClient` directly; `createApiClient<Routes>(config)`
+> binds the route map type for you.
+
+## The rest of the guide
+
+| Page                                       | What it covers                                                                 |
+| ------------------------------------------ | ------------------------------------------------------------------------------ |
+| [Requests](/docs/client/requests)          | The typed route map, making requests, and shaping them with interceptors.      |
+| [Authentication](/docs/client/auth)        | Bearer tokens, CSRF, and refreshing credentials on a 401.                      |
+| [Error Handling](/docs/client/errors)      | What a failed request throws, and how to tell the failure modes apart.         |
+| [Resilience](/docs/client/resilience)      | Timeouts, retries, and the circuit breaker that spares a failing upstream.     |
+| [File Transfers](/docs/client/files)       | Uploading and downloading binary payloads.                                     |
+| [Testing the Client](/docs/client/testing) | Stub the global fetch, cover the failure paths, and drive the circuit breaker. |
+| [References](/docs/client/references)      | Every ApiClient method, config key, and error type in one table.               |
+
+## Next steps
+
+- [Rate Limiting](/docs/rate-limiting) — throttle outbound and inbound traffic.
+- [Authentication](/docs/authentication) — issue the tokens your interceptors attach.
+- [Validator](/docs/validator) — the server side that produces the `ValidationError` body.
+- [Telemetry](/docs/telemetry) — observe request failures and circuit state.

package/docs/client/references.md

@@ -0,0 +1,58 @@
+---
+title: Client References
+description: Every ApiClient method, config key, and error type in one table.
+---
+
+# References
+
+## `createApiClient<Routes>(config)`
+
+Returns an `ApiClient<Routes>` bound to your route map. The `config` is an
+`ApiClientConfig` (see the [Configuration](/docs/client#configuration) table for the common
+fields, plus `onError`, `onResponse`, `onRequest`, `onUnauthorized`, `onForbidden`,
+and `circuitBreaker`).
+
+## ApiClient methods
+
+| Method     | Signature                                                            | Description                        |
+| ---------- | -------------------------------------------------------------------- | ---------------------------------- |
+| `get`      | `get(path, params?, options?: GetOptions): Promise<Response>`        | Typed GET; path params then query. |
+| `post`     | `post(path, body?, options?: MutationOptions): Promise<Response>`    | Typed POST with body.              |
+| `put`      | `put(path, body?, options?: MutationOptions): Promise<Response>`     | Typed PUT with body.               |
+| `patch`    | `patch(path, body?, options?: MutationOptions): Promise<Response>`   | Typed PATCH with body.             |
+| `delete`   | `delete(path, params?, options?: RequestOptions): Promise<Response>` | Typed DELETE; path params only.    |
+| `setToken` | `setToken(token: TokenSource \| null): void`                         | Update or clear the bearer token.  |
+
+## ApiClientError
+
+| Member         | Signature               | Description                            |
+| -------------- | ----------------------- | -------------------------------------- |
+| `status`       | `number`                | HTTP status code.                      |
+| `statusText`   | `string`                | HTTP status text.                      |
+| `body`         | `string`                | Raw response text.                     |
+| `headers`      | `Headers \| undefined`  | Response headers, when available.      |
+| `retryAfterMs` | `get(): number \| null` | Parsed `Retry-After` in ms, or `null`. |
+
+## ValidationError extends ApiClientError
+
+| Member              | Signature                                   | Description                        |
+| ------------------- | ------------------------------------------- | ---------------------------------- |
+| `errors`            | `Record<string, string[]>`                  | Field → messages map.              |
+| `validationMessage` | `string`                                    | Top-level `message` from the body. |
+| `has`               | `has(field: string): boolean`               | Whether a field has any error.     |
+| `first`             | `first(field: string): string \| undefined` | First message for a field.         |
+| `all`               | `all(): Record<string, string[]>`           | The full field-error map.          |
+| `fields`            | `fields(): string[]`                        | Names of every failed field.       |
+
+## CircuitBreaker
+
+| Member     | Signature                                   | Description                             |
+| ---------- | ------------------------------------------- | --------------------------------------- |
+| `call`     | `call<T>(fn: () => Promise<T>): Promise<T>` | Run `fn` under the breaker.             |
+| `state`    | `get(): CircuitState`                       | `'closed'`, `'open'`, or `'half-open'`. |
+| `failures` | `get(): number`                             | Current consecutive failure count.      |
+| `reset`    | `reset(): void`                             | Manually return to the closed state.    |
+
+## Next steps
+
+- [Client overview](/docs/client) — the guide's front page and the rest of the sections.

package/docs/client/requests.md

@@ -0,0 +1,131 @@
+---
+title: Client Requests
+description: The typed route map, making requests, and shaping them with interceptors.
+---
+
+# Route map
+
+Define your API surface once. Keys are `'METHOD /path'` strings — path params are
+`{braces}` style. All fields are optional.
+
+```ts
+// app/api/api-types.ts
+export interface Routes {
+  "GET /api/users": {
+    query: { page?: number; perPage?: 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; password: string };
+    response: UserResource;
+  };
+  "PUT /api/users/{id}": {
+    params: { id: number };
+    body: { name?: string; email?: string };
+    response: UserResource;
+  };
+  "DELETE /api/users/{id}": {
+    params: { id: number };
+    response: void;
+  };
+}
+```
+
+## Making requests
+
+```ts
+// in any frontend module
+// GET with path params
+const user = await api.get("/api/users/{id}", { id: 42 });
+//    ^? UserResource — inferred from the route map
+
+// GET with query string
+const list = await api.get("/api/users", undefined, {
+  query: { page: 2, perPage: 25, search: "alice" },
+});
+//    ^? { data: UserResource[]; total: number }
+
+// POST with body
+const created = await api.post("/api/users", {
+  name: "Alice",
+  email: "alice@example.com",
+  password: "hunter2",
+});
+//    ^? UserResource
+
+// PUT
+await api.put("/api/users/{id}", { name: "Alice Smith" }, { params: { id: 42 } });
+
+// PATCH
+await api.patch("/api/users/{id}", { email: "new@example.com" }, { params: { id: 42 } });
+
+// DELETE
+await api.delete("/api/users/{id}", { id: 42 });
+```
+
+All methods accept an optional `options` argument for per-request headers and
+extra `fetch` init fields (`signal`, `credentials`, etc.):
+
+```ts
+// in any frontend module
+const ctrl = new AbortController();
+
+await api.get("/api/users", undefined, {
+  headers: { "X-Trace-Id": requestId },
+  init: { signal: ctrl.signal },
+});
+```
+
+## Request interceptors
+
+Run one or more async functions before every outgoing request. Each interceptor
+receives the current `RequestConfig` and must return it (or a new one). Useful for
+attaching authorization headers from a reactive store without coupling the store
+to the client's constructor.
+
+```ts
+// app/api/client.ts
+const api = createApiClient<Routes>({
+  baseUrl: "https://api.example.com",
+
+  // Single interceptor
+  onRequest: async (config) => ({
+    ...config,
+    headers: {
+      ...config.headers,
+      Authorization: `Bearer ${await tokenStore.get()}`,
+    },
+  }),
+});
+```
+
+Multiple interceptors execute in declaration order:
+
+```ts
+// app/api/client.ts
+const api = createApiClient<Routes>({
+  baseUrl: "https://api.example.com",
+  onRequest: [addAuthHeader, addRequestId, logOutgoing],
+});
+```
+
+A symmetric `onResponse` runs after every successful (2xx) response — receiving a
+`ResponseContext` of `{ status, headers, data, request }` — to unwrap envelopes or log.
+
+### RequestConfig shape
+
+| Field     | Type                     | Description                                                  |
+| --------- | ------------------------ | ------------------------------------------------------------ |
+| `method`  | `string`                 | HTTP verb — `'GET'`, `'POST'`, …                             |
+| `url`     | `string`                 | Full resolved URL (base + path + query string)               |
+| `headers` | `Record<string, string>` | Merged headers — add/override here                           |
+| `body`    | `BodyInit \| undefined`  | Serialised body (JSON string, `FormData`, …), or `undefined` |
+
+## Next steps
+
+- [Client overview](/docs/client) — the guide's front page and the rest of the sections.
+- [Reference](/docs/client/references) — the full API surface in one table.