@zerotal/arch 1.7.2 → 1.7.4

package/docs/client/auth.md

@@ -1,113 +0,0 @@
----
-title: Client Authentication
-description: Bearer tokens, CSRF, and refreshing credentials on a 401.
----
-
-# Authentication & CSRF
-
-The client supports the two ways a browser app proves who it is, and the choice is
-usually made for you by where the API lives:
-
-- **Bearer tokens** suit APIs on another origin, mobile clients, and anything where
-  the caller holds a credential it can attach itself.
-- **Session cookies** suit an API served from your own domain, where the browser
-  already carries the session and CSRF protection is the concern instead.
-
-## Bearer tokens
-
-Attach a bearer token (string or a resolver, sync or async) without writing an interceptor —
-update it at runtime with `setToken()`:
-
-```ts
-// app/api/client.ts
-const api = createApiClient<Routes>({
-  token: () => authStore.accessToken, // re-read on every request
-});
-api.setToken(freshToken); // or update imperatively
-```
-
-Prefer the resolver form. A plain string is captured once at construction, so a
-token refreshed later never reaches the client; a function is consulted on every
-request and always sees the current value.
-
-Calling `setToken()` with no argument clears the token, which is what a logout
-should do — otherwise the next request still carries the credential of the user who
-just signed out.
-
-> **Note** — The `token` is only applied when no `Authorization` header is already
-> present on the request, so a per-request override always wins.
-
-## Session cookies and CSRF
-
-For session/cookie (SPA) auth, set `withCredentials` to send cookies, which also turns on CSRF:
-the client reads the `XSRF-TOKEN` cookie and sends it as `X-XSRF-TOKEN` on mutating requests
-(matching the session/CSRF middleware). Customize the names with `csrf`:
-
-```ts
-// app/api/client.ts
-createApiClient<Routes>({
-  withCredentials: true, // credentials: 'include' + CSRF on
-  csrf: { cookie: "XSRF-TOKEN", header: "X-XSRF-TOKEN" }, // defaults shown
-});
-```
-
-Enabling `withCredentials` turns CSRF on by default, so the two travel together and
-neither needs configuring in the common case. Set `csrf: false` to opt out, or pass
-an object to rename the cookie and header to match a server that uses different
-ones.
-
-The token is attached only to mutating requests — `POST`, `PUT`, `PATCH`, `DELETE`.
-A `GET` is exempt because it should not change state, so it needs no protection
-from being triggered cross-site. If a `GET` in your API does change something, that
-is the thing to fix; adding a CSRF header to it would only hide the problem.
-
-The header is skipped when the request already carries one, so a caller that sets
-its own value keeps it.
-
-## 401 / token refresh
-
-`onUnauthorized` is called when any request receives a 401 response. It receives
-the error and a `retry` function. Call `retry()` — optionally with header overrides
-— to re-execute the failed request. The retry is limited to **one attempt**.
-
-```ts
-// app/api/client.ts
-const api = createApiClient<Routes>({
-  baseUrl: "https://api.example.com",
-
-  onUnauthorized: async (err, retry) => {
-    const newToken = await authStore.refresh();
-    return retry({ Authorization: `Bearer ${newToken}` });
-  },
-});
-```
-
-If `onUnauthorized` is not provided or does not call `retry`, the 401 error is
-thrown normally.
-
-The single-attempt limit is deliberate: a refresh that itself returns 401 would
-otherwise retry forever, turning an expired session into an endless loop of
-requests. When the retry also fails, the error is thrown and the app can send the
-user to the login screen.
-
-One case the hook does not solve on its own is a page that fires several requests
-at once. Each 401 calls `onUnauthorized` separately, so a naive handler triggers
-several concurrent refreshes and the losers of that race may invalidate the winner's
-token. Have the refresh itself de-duplicate — cache the in-flight promise in your
-auth store and hand the same one to every caller until it settles:
-
-```ts
-// app/api/authStore.ts
-let inflight: Promise<string> | null = null;
-
-export function refresh(): Promise<string> {
-  inflight ??= requestNewToken().finally(() => (inflight = null));
-  return inflight;
-}
-```
-
-## Next steps
-
-- [Client overview](/docs/client) — the guide's front page and the rest of the sections.
-- [Error handling](/docs/client/errors) — the errors a rejected request throws.
-- [CSRF protection](/docs/csrf) — the server side of the cookie and header pair.

package/docs/client/errors.md

@@ -1,139 +0,0 @@
----
-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

@@ -1,118 +0,0 @@
----
-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/references.md

@@ -1,58 +0,0 @@
----
-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

@@ -1,131 +0,0 @@
----
-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.