arthron 0.0.1 → 1.0.0

package/README.md

@@ -1,10 +1,22 @@
 # arthron
 
-**Middleware owns the flow — it can call `next` again to retry the whole request. Interceptors only transform values and can never change the flow. arthron keeps the two apart at the type level.**
+A `fetch` client you assemble from plugins.
 
-A composable `fetch` client. Create one from config, plug in interceptors and middleware, get a plain `Response` back. Zero dependencies, TypeScript first, Node 18+ and browsers.
+```ts
+import { arthron, logging, retry, timeout } from "arthron";
+
+const api = arthron({
+  baseURL: "https://api.example.com",
+  use: [logging(), timeout(10_000), retry()],
+});
+
+const user = await api.get("/me").json<User>();
+```
 
-> *arthron* (ἄρθρον) — Greek for "joint": the place where two parts meet and work as one.
+- **Plain `Response` in, plain `Response` out.** No wrapper type to learn. `.json<T>()` and friends are there when you want the body.
+- **Two kinds of plugin, kept apart by the types.** Middleware wraps the request and controls the flow — it can call `next` again to retry. Interceptors transform one value and return it; they cannot retry, skip, or swallow. Auth refresh, retry, timeouts, logging, and anything that reacts to how a call ended (error pages, domain errors) are middleware. Headers, trace ids and per-attempt error details are interceptors.
+- **One error type, two causes.** `ArthronError` means the server said no (`!response.ok`) or the network failed (`status: 0`). Everything else — cancellation, a bug in a plugin — is rethrown as-is.
+- Zero dependencies. ESM and CJS. TypeScript types included. Node 22+ and browsers.
 
 ## Install
 
@@ -12,231 +24,346 @@ A composable `fetch` client. Create one from config, plug in interceptors and mi
 npm i arthron
 ```
 
-## Quick start
+## Usage
 
-```ts
-import { arthron, logging, retry } from "arthron";
-
-const base = arthron({
-  baseURL: "https://api.example.com",
-  use: [logging(), retry({ retries: 3 })],
-});
+### Create a client
 
-const api = base.extend({
-  use: [auth({ getToken, refresh })], // your own plugin — see "Writing your own plugin"
+```ts
+const api = arthron({
+  baseURL: "https://api.example.com", // prefix for relative paths
+  headers: { accept: "application/json" }, // defaults; per-call headers win
+  credentials: "include", // only if you need cookies cross-origin
+  cache: "no-store", // any fetch option works as a default; per-call values win
+  use: [retry()], // plugins, outermost first
 });
-
-const res = await api.get("/me");                             // Response
-const user = await api.get("/me").json<User>();               // parsed body
-const blob = await api.get("/export").blob();
-const stream = (await api.post("/chat", { prompt })).body;    // ReadableStream
 ```
 
-## Concepts
+Every field is optional. Without `baseURL`, only absolute URLs are accepted. With one, an absolute URL must stay on `baseURL`'s origin unless you set `allowAbsoluteUrls: true` — and even then config `headers` are only sent to that origin.
 
-One request runs like this:
+### Make requests
 
-```
-middleware[0] (
-  middleware[1] (
-    ...
-      attempt: request interceptors → fetch → ok ? response interceptors : error interceptors → throw
-  )
-)
+```ts
+await api.get("/users", { params: { page: 2 } }); // → Response
+await api.post("/users", { name: "kim" }); // object body → JSON
+await api.post("/upload", formData); // FormData/Blob/string/stream → sent as-is
+await api.put("/users/1", { name: "lee" });
+await api.patch("/users/1", { name: "lee" });
+await api.query("/search", { filter: { tag: "x" } }); // RFC 10008 QUERY: GET semantics, body carries the query
+await api.delete("/users/1");
+await api.head("/users/1");
+await api.request("/users", { method: "OPTIONS" });
 ```
 
-- **Middleware** wraps the whole call, outermost first in registration order. `next(ctx)` runs everything beneath it; calling `next` again re-runs the whole attempt — that is how retry, auth refresh and timeouts are built.
-- **Interceptors** run inside each attempt. They receive a value (`RequestContext`, `Response`, or `ArthronError`) and return one. They cannot skip, retry, or swallow — an error interceptor's return value is always thrown.
-- Every attempt starts from a **copy** of the context, so headers an interceptor set on attempt one do not leak into attempt two.
-
-A plugin is just an object bundling any of the four:
+Each call returns `Promise<Response>` with body helpers attached:
 
 ```ts
-type Plugin = {
-  name?: string;
-  middleware?: (ctx, next) => Promise<Response>;
-  request?:    (ctx) => RequestContext | Promise<RequestContext>;
-  response?:   (res, ctx) => Response | Promise<Response>;
-  error?:      (err, ctx) => ArthronError | Promise<ArthronError>;
-};
+const res = await api.get("/me"); // Response — status, headers, body untouched
+const user = await api.get("/me").json<User>(); // body parsed; T is a cast, not validation
+const safe = await api.get("/me").json(UserSchema); // validated by any Standard Schema (Zod, Valibot, ArkType); typed from it
+const text = await api.get("/robots.txt").text();
+const blob = await api.get("/export").blob();
+const stream = (await api.post("/chat", prompt)).body; // ReadableStream
+for await (const e of api.post("/chat", prompt).sse()) {} // see "Stream responses"
 ```
 
-## API
+`init` accepts everything `fetch` does (`signal`, `cache`, `headers`, …) plus `params`: an object whose `null`/`undefined` values are dropped and whose arrays become repeated keys (`{ ids: [1, 2] }` → `ids=1&ids=2`), or a `URLSearchParams`. Other object values (a `Date`, a nested object) are rejected rather than sent as `[object Object]`. Put ids into the path with `path`, not string interpolation: `api.get("/users/{id}", { path: { id } })` encodes each value into its own segment, so an id like `../admin` or `x?role=admin` cannot change which endpoint you call (`encodeURIComponent` alone lets `..` through). A `null` (or `undefined`) header value drops a client default for that call: `api.get("/public", { headers: { authorization: null } })`.
+
+`query` sends the [RFC 10008](https://www.rfc-editor.org/rfc/rfc10008) QUERY method: safe and idempotent like GET, so `retry()` repeats it by default, but the query travels in the body. Any `fetch` sends it; the server has to understand it (Node's own `http` server does from v20).
 
-### `arthron(config?)`
+### Stream responses
 
 ```ts
-type ArthronConfig = {
-  baseURL?: string;                 // prefix for relative paths; without it only absolute URLs are accepted
-  headers?: HeadersInit;            // defaults; per-call headers win, compared case-insensitively
-  credentials?: RequestCredentials; // forwarded as-is; NOT set unless you set it
-  fetch?: typeof fetch;             // injection point for tests / polyfills
-  use?: Plugin[];
-  errorMessage?: (data: unknown, res: Response) => string | undefined;
-};
+// Server-sent events — one event per `for await` step
+for await (const { event, data } of api.post("/v1/chat/completions", body).sse()) {
+  if (data === "[DONE]") break; // provider sentinel; arthron does not interpret it
+  process.stdout.write(JSON.parse(data).choices[0].delta.content ?? "");
+}
+
+// Newline-delimited JSON (Ollama, many log endpoints)
+for await (const row of api.get("/logs").ndjson<LogRow>()) console.log(row);
 ```
 
-### Instance
+`.sse()` parses `text/event-stream` the way the EventSource spec does: multi-line `data:` joined with `\n`, comments ignored, dispatch on a blank line, an event the stream ends inside dropped, `lastEventId` carried across events, `retry` accepted as digits only and carried on. It does not reconnect — to resume, send `headers: { "last-event-id": e.lastEventId }` on a new request. Both helpers honour `signal` and `timeout` while the body is being read, and leaving the loop early (`break`, `return`, a throw) closes the connection.
+
+A stream is untrusted input, so both helpers have limits: a line longer than `maxLineLength` (default 8 Mi characters), or an SSE event whose `data` outgrows `maxEventSize` (default 8 Mi), rejects the loop with a `RangeError` and closes the connection. Raise them per call if you expect bigger payloads: `.sse({ maxEventSize: 32 * 1024 * 1024 })`.
+
+### Handle errors
 
 ```ts
-api.get(path, init?)            api.delete(path, init?)        api.head(path, init?)
-api.post(path, body?, init?)    api.put(path, body?, init?)    api.patch(path, body?, init?)
-api.request(path, { method, body?, ...init })
+import { isArthronError } from "arthron";
 
-api.use(...plugins)   // new client with plugins appended
-api.extend(config)    // new client: config shallow-merged, headers merged, plugins appended
+try {
+  await api.get("/users/404");
+} catch (e) {
+  if (isArthronError(e)) {
+    e.status; // 404, or 0 when the network failed
+    e.data; // parsed body: JSON, else text, else undefined
+    e.detail; // the server's explanation (`message` → `error` → `error.message` → `detail`), or undefined — show this to users
+    e.message; // arthron's own: "GET https://api.example.com/users/404 failed with 404 Not Found" — for logs
+    e.response; // the failed Response, still readable (up to 64 KiB of its body)
+    e.request; // what was sent (url, init) — read it directly; it is left out of logs
+  }
+}
 ```
 
-`init` is `RequestInit` minus `method`/`body`, plus `params` (query object; `null`/`undefined` skipped, appended with `&` if the path already has a query).
+`isArthronError(e)` and `e instanceof ArthronError` work across copies of the package — the ESM and CJS builds loaded side by side, a CJS dependency's client caught by your ESM code. `request`, `response` and `headers` are not enumerable, and `toJSON()` returns only name, message, detail, status, method, a URL without query or userinfo, and `data`. So `JSON.stringify(e)`, `console.error(e)` and error trackers never print your tokens.
 
-Clients are **immutable**. `use` and `extend` return new clients; the receiver — and anything previously derived from it — is untouched.
+`message` and `detail` are kept apart on purpose. `message` is written by arthron — method, URL without query, status — so a log line or an error tracker says which request failed, and never carries text the server chose. `detail` is what the server said: the right thing for a toast (`e.detail ?? "Something went wrong"`), but untrusted — render it as text, never as HTML, and filter it if your gateway leaks internal routes in it.
 
-**Body rules.** `string`, `FormData`, `Blob`, `ArrayBuffer`/views, `URLSearchParams`, `ReadableStream` are sent as-is with no `Content-Type` added. Anything else is `JSON.stringify`-ed with `content-type: application/json`, unless you already set a content type.
+Not every non-ok response is a failure. An opaque response (`mode: "no-cors"`) and the 3xx of `redirect: "manual"` come back as a `Response`, since you asked for them. `throwOn` picks which other non-ok responses reject, for the client or one call: `api.get("/maybe", { throwOn: (res) => res.status !== 404 })` returns the 404 to inspect. An ok response never rejects.
 
-**URL rules.** `baseURL` and `path` are joined by string concatenation — `"https://a/v1" + "/users"` → `https://a/v1/users`. The prefix survives a leading slash (unlike `new URL()`). Absolute paths skip `baseURL`.
+`.json(schema)` takes any [Standard Schema](https://standardschema.dev) — Zod, Valibot, ArkType and others — validates the body with it, and resolves with the schema's output (transforms included). A body that does not match rejects with a `SchemaError` whose `issues` list each problem and its path. It is not an `ArthronError`: the request worked, the data did not. arthron stays dependency-free; the schema library is yours.
 
-### Return value — `ArthronPromise`
+A request that is aborted or times out rejects with the abort reason — `AbortError` / `TimeoutError`, or whatever you passed to `abort(reason)` — not an `ArthronError`.
 
-Every method returns `Promise<Response>` with convenience helpers:
+### Derive clients
+
+Clients are immutable. `use` and `extend` return a new client and leave the original alone.
 
 ```ts
-const res  = await api.get("/me");                 // Response, untouched
-const body = await api.get("/me").json<User>();    // (await res).json() — T is a cast, not validation
-                     .text() .blob() .arrayBuffer() .formData()
+const base = arthron({ baseURL: API, use: [logging(), retry()] });
+const authed = base.use(auth()); // base + auth
+const admin = authed.extend({ headers: { "x-role": "admin" } }); // authed + header
 ```
 
-A `204`/empty body makes `.json()` reject, exactly like `Response.json()` would.
+`extend` shallow-merges the config, merges headers case-insensitively (child wins), and adds plugins the way `use` does: a plugin whose `name` is already there replaces it in place — so `streaming = base.use(timeout(120_000))` loosens the inherited `timeout`, and a second `retry()` does not multiply attempts — while unnamed plugins append. `without("retry")` returns a client without that plugin. The built-ins are named `retry`, `timeout` and `logging`.
+
+## Plugins
 
-### Errors — `ArthronError`
+A plugin is an object with any of four slots:
 
 ```ts
-class ArthronError extends Error {
-  status: number;        // HTTP status; 0 for network failures
-  statusText: string;
-  headers: Headers;
-  data: unknown;         // parsed body: JSON if it parses, else text, else undefined
-  response?: Response;   // the original; its body is already consumed into `data`. Absent for network failures
-  request: RequestContext;
-  cause?: unknown;       // the original error for network failures
-}
+type Plugin = {
+  name?: string; // identity: use/extend replace the plugin of the same name, without(name) removes it
+  middleware?: (ctx: RequestContext, next: (ctx: RequestContext) => Promise<Response>) => Promise<Response>;
+  request?: (ctx: RequestContext) => RequestContext | Promise<RequestContext>;
+  response?: (res: Response, ctx: RequestContext) => Response | Promise<Response>;
+  error?: (err: ArthronError, ctx: RequestContext) => ArthronError | Promise<ArthronError>;
+};
+
+type RequestContext = {
+  url: string;
+  init: Omit<RequestInit, "headers"> & { headers: Record<string, string> }; // lowercase names
+  meta: ArthronMeta; // per-call plugin settings, never sent
+};
 ```
 
-Only two things become an `ArthronError`: a response with `ok === false`, and `fetch` itself rejecting (network failure, `status: 0`). **Everything else is rethrown untouched and skips the error interceptors** — `AbortError`, `TimeoutError`, and anything a plugin throws. A bug in an interceptor is a bug, not a 500.
+How one request runs:
 
-The message is picked from the body by `message` → `error` (string) → `error.message` → `detail`, falling back to `Request failed with status N`. Override with `errorMessage` in the config.
+```
+middleware 1
+  middleware 2
+    attempt ─ request interceptors → fetch → response interceptors
+                                           ↘ error interceptors → throw
+```
 
-```ts
-import { isArthronError } from "arthron";
+| | Middleware | Interceptor |
+|---|---|---|
+| Runs | Once per call, wrapping everything below | Once per attempt |
+| Gets | `ctx` and `next` | A value: context, `Response`, or `ArthronError` |
+| Can | Call `next` again (retry), skip it, add a deadline | Return a changed value |
+| Cannot | — | Retry, skip, or stop the error from being thrown |
+| Examples | `retry`, `timeout`, `logging`, auth refresh, error pages | auth header, tracing id, per-attempt error details |
 
-try { await api.get("/me"); }
-catch (e) { if (isArthronError(e) && e.status === 404) { /* … */ } else throw e; }
-```
+Every attempt starts from a fresh copy of the context, so a header set by an interceptor on attempt one does not leak into attempt two. `ctx.init.headers` is always a plain record with lowercased names, restored to that shape after every request interceptor, so `{ ...ctx.init.headers, name: value }` is safe.
 
-## Built-in plugins
+### Built in
 
-### `logging(options?)`
+#### `retry(options)`
 
-One line when a request starts, one when it settles. The query string is dropped (it tends to carry tokens). Cancellations are not logged.
+Re-runs the attempt on network failure or a retryable status. Because it re-runs the whole attempt, request interceptors run again — a refreshed token or a new trace id is picked up automatically.
 
 | option | default | |
 |---|---|---|
-| `enabled` | `true` | arthron never reads `NODE_ENV` — pass `isDev` yourself |
-| `logger` | `console` | needs `log` and `error` |
+| `retries` | `2` | retries after the first attempt (3 requests total); a whole number ≥ 0 |
+| `retryOn` | `[408, 429, 500, 502, 503, 504]` | network failures (`status: 0`) are always retried |
+| `methods` | `GET HEAD OPTIONS QUERY PUT DELETE` | case-insensitive |
+| `delay` | `(retry) => Math.random() * 300 * 2 ** retry` | ms; `retry` counts from 0. Full jitter, so clients that failed together don't retry together |
+| `maxRetryAfter` | `60_000` | a `Retry-After` longer than this means "don't retry" |
+| `shouldRetry` | — | `(error, attempt, ctx) => boolean \| undefined`: `true` retries, `false` stops, `undefined` uses the rules above. Sees every error, an inner `TimeoutError` included |
+| `onRetry` | — | `(error, attempt, waitMs) => void`, before each wait |
 
-```
-[arthron] → GET /users
-[arthron] ← GET /users 200 42ms
-[arthron] ✕ GET /users 503 1203ms
+Honours `Retry-After` (seconds or HTTP date). Never retries a `ReadableStream` body or an aborted request, and never more than `retries` times — `shouldRetry` cannot lift those.
+
+Opting a non-idempotent method in (`methods: ["POST"]`) means a network failure is retried too, and a dropped connection may already have reached the server. Where a duplicate would hurt — a payment, an LLM completion you pay for — keep retries to statuses: `shouldRetry: (e) => (isArthronError(e) && e.status === 0 ? false : undefined)`. Per call, `meta: { retry: false }` turns it off and `meta: { retry: { retries: 5 } }` overrides any option but `sleep`.
+
+#### `timeout(ms, { idle? })`
+
+Aborts the attempt after `ms`, counted until the body has been fully read — a server that sends headers and then stalls still trips it. Rejects with a `TimeoutError`, which `retry` and error interceptors ignore. Combines with a `signal` you pass yourself. `Infinity` means no deadline. The timer never keeps a Node process alive on its own. Per call, `meta: { timeout: 120_000 }` replaces the deadline (`Infinity` lifts it).
+
+A total deadline also cuts off a stream that is still flowing. For streams, bound the silence instead: `timeout(Infinity, { idle: 30_000 })` aborts only after 30 s without data — waiting for headers or between chunks — however long the stream runs. Both can be combined: `timeout(600_000, { idle: 30_000 })`.
+
+```ts
+arthron({ use: [retry(), timeout(5_000)] }); // 5 s per attempt — a timed-out attempt is not retried
+arthron({ use: [timeout(5_000), retry()] }); // 5 s for all attempts together
 ```
 
-### `retry(options?)`
+#### `logging(options)`
 
-Retries by calling `next` again, so request interceptors (fresh auth header, fresh trace id) run on every attempt.
+```
+[arthron] → GET https://api.example.com/users
+[arthron] ← GET https://api.example.com/users 200 42ms
+[arthron] ✕ GET https://api.example.com/users 503 1203ms
+```
 
 | option | default | |
 |---|---|---|
-| `retries` | `2` | retries *after* the first attempt — 3 requests total |
-| `retryOn` | `[408, 429, 500, 502, 503, 504]` | network failures (`status 0`) are always retried |
-| `methods` | `GET HEAD OPTIONS PUT DELETE` | case-insensitive |
-| `delay` | `retry => 300 * 2 ** retry` | ms; `retry` is 0-based |
-| `maxRetryAfter` | `60_000` | a `Retry-After` longer than this (ms) means "don't retry" |
+| `enabled` | `true` | pass `process.env.NODE_ENV !== "production"` or similar — arthron never reads env |
+| `logger` | `console` | anything with `log` and `error` |
+| `onEvent` | — | receive `{ phase, method, path, status, ms, error }` instead of console lines |
+
+Query strings and `user:pass@` are never printed. Cancellations are not logged.
 
-`Retry-After` (seconds or HTTP-date) wins over `delay` when present and within `maxRetryAfter`; beyond it the error is thrown without retrying. `ReadableStream` bodies are never retried (they can only be read once). Respects `signal` — an aborted request stops retrying immediately.
+### Write your own
 
-## Writing your own plugin
+`definePlugin`, `defineMiddleware` and `defineInterceptor.{request,response,error}` are identity functions that give you the parameter types without annotations.
 
-`defineMiddleware`, `defineInterceptor.{request,response,error}` and `definePlugin` are identity functions that give you contextual typing. Use them or annotate — same result.
+**Per-call settings.** `api.get(path, { meta })` hands `meta` to every plugin as `ctx.meta` and never sends it. Declare your own keys once and they are typed everywhere:
+
+```ts
+declare module "arthron" {
+  interface ArthronMeta {
+    skipAuth?: boolean;
+  }
+}
 
-### `auth` — refresh on 401, then re-run the request
+api.use({ request: (ctx) => (ctx.meta.skipAuth ? ctx : withToken(ctx)) });
+api.get("/health", { meta: { skipAuth: true } });
+```
 
-This is the case the middleware/interceptor split exists for. The refresh and the retry are *flow*, so they live in middleware. Attaching the header is a *value change*, so it is a request interceptor — and because every `next` re-runs the interceptors, the retried request automatically picks up the new token.
+**Refresh a session on 401, then redo the request.** The refresh is flow, so it is middleware. The header is a value, so it is a request interceptor — and because `next` re-runs the interceptors, the retried request carries the new token without extra code. Two details matter in production: concurrent 401s must share one refresh (with refresh-token rotation, parallel refreshes revoke each other), and the token must only go to your API's origin. Tested in [`examples/auth-refresh.ts`](examples/auth-refresh.ts).
 
 ```ts
 import { definePlugin, isArthronError } from "arthron";
 
-export const auth = ({ getToken, refresh }: {
-  getToken: () => string | null;
-  refresh: () => Promise<void>;
-}) =>
-  definePlugin({
+export const auth = (store: { token: () => string | null; refresh: () => Promise<void> }, origin: string) => {
+  let refreshing: Promise<void> | undefined;
+  const bearer = () => (store.token() ? `Bearer ${store.token()}` : undefined);
+  return definePlugin({
     name: "auth",
     request: (ctx) => {
-      const token = getToken();
-      if (!token) return ctx;
-      return { ...ctx, init: { ...ctx.init, headers: { ...ctx.init.headers, authorization: `Bearer ${token}` } } };
+      const value = bearer();
+      if (!value || new URL(ctx.url).origin !== origin) return ctx;
+      return { ...ctx, init: { ...ctx.init, headers: { ...ctx.init.headers, authorization: value } } };
     },
     middleware: async (ctx, next) => {
       try {
         return await next(ctx);
       } catch (e) {
         if (!isArthronError(e) || e.status !== 401) throw e;
-        await refresh();          // throws → propagates; caller decides to log out
-        return next(ctx);         // whole attempt again, request interceptor adds the new token
+        // Refresh only if the failed token is still current — else another call already did.
+        if (e.request.init.headers.authorization === bearer()) {
+          refreshing ??= store.refresh().finally(() => (refreshing = undefined));
+          await refreshing; // a failed refresh rejects here: the caller sees it
+        }
+        return next(ctx);
       }
     },
   });
+};
 ```
 
-### `errorRedirect` — react to errors without changing them
-
-An error interceptor can only *look* and *return*; it cannot swallow. That makes it the right home for side effects like navigation.
+**Send users to an error page.** This reacts to how the *call* ended, so it is middleware placed before `retry()`: it sees only the final result. An error interceptor would run on every failed attempt and navigate away even when the next retry succeeds. Error interceptors are for enriching the error of one attempt. Tested in [`examples/error-page.ts`](examples/error-page.ts).
 
 ```ts
-import { defineInterceptor } from "arthron";
+import { definePlugin, isArthronError } from "arthron";
 
 export const errorRedirect = (navigate: (to: string) => void) =>
-  defineInterceptor.error((err, ctx) => {
-    const isGet = (ctx.init.method ?? "GET") === "GET";
-    if (isGet && err.status === 404) navigate("/not-found");
-    if (isGet && err.status >= 500) navigate("/error");
-    return err; // still thrown
+  definePlugin({
+    name: "errorRedirect",
+    middleware: async (ctx, next) => {
+      try {
+        return await next(ctx);
+      } catch (error) {
+        if (isArthronError(error) && (ctx.init.method ?? "GET") === "GET") {
+          if (error.status === 404) navigate("/not-found");
+          else if (error.status >= 500) navigate("/error");
+        }
+        throw error;
+      }
+    },
   });
 
-api.use({ error: errorRedirect(router.push) });
+const api = arthron({ baseURL: API, use: [errorRedirect(router.push), retry()] }); // first: wraps retry
+```
+
+The same shape maps errors to your own types: `catch (e) { throw toDomainError(e); }` in an outermost middleware runs once per call, after retries.
+
+**Attach a trace id.** A one-line request interceptor.
+
+```ts
+api.use({ request: (ctx) => ({ ...ctx, init: { ...ctx.init, headers: { ...ctx.init.headers, "x-trace-id": crypto.randomUUID() } } }) });
 ```
 
-### `timeout` — a four-line middleware
+## Reference
+
+### `arthron(config)`
+
+```ts
+type ArthronConfig = {
+  baseURL?: string;
+  allowAbsoluteUrls?: boolean; // let absolute URLs leave baseURL's origin (without config headers)
+  headers?: HeadersInit | Record<string, string | null>; // null drops a header (in extend)
+  fetch?: typeof fetch; // inject for tests or a polyfill; resolved per request
+  use?: Plugin[];
+  errorDetail?: (data: unknown, res: Response) => string | undefined; // picks ArthronError.detail out of the body
+  throwOn?: (res: Response) => boolean; // which non-ok responses reject (also per call)
+  // …plus any fetch option as a default: credentials, cache, redirect, mode,
+  // keepalive, referrerPolicy, priority, integrity. Not body, method or signal —
+  // those belong to one request (passing them throws).
+};
+```
 
-`AbortSignal.any` needs Node 20.3+ or a current browser; on Node 18 combine the signals with an `AbortController` by hand.
+### Client
 
 ```ts
-import { defineMiddleware } from "arthron";
+get(path, init) · delete(path, init) · head(path, init)
+post(path, body, init) · put(path, body, init) · patch(path, body, init)
+query(path, body, init) // RFC 10008 QUERY
+request(path, { method, body, ...init })
+use(...plugins) → new client (same-name plugins replaced in place)
+extend(config) → new client
+without(...names) → new client without those plugins
+```
+
+All arguments after `path` are optional, except `method` in `request`. `request` is the way to any other verb; its `method` autocompletes the standard ones, and those go out uppercased whatever case you write them in (fetch itself leaves `"patch"` lowercase, which servers answer with 405). Other method names are sent as written.
+
+The public object types — `ArthronConfig`, `RequestOptions`, `RequestContext`, `ArthronMeta`, `Plugin`, `ArthronPromise`, `Arthron` — are interfaces, so a plugin package can add its own options with `declare module "arthron" { interface RequestOptions { … } }`.
+
+### `ArthronError`
 
-export const timeout = (ms: number) =>
-  defineMiddleware((ctx, next) =>
-    next({ ...ctx, init: { ...ctx.init, signal: AbortSignal.any([ctx.init.signal, AbortSignal.timeout(ms)].filter(Boolean) as AbortSignal[]) } }),
-  );
+```ts
+class ArthronError extends Error {
+  status: number; // 0 for network failures
+  statusText: string;
+  headers: Headers; // not enumerable
+  data: unknown;
+  detail?: string; // the server's explanation, picked out of data; untrusted text
+  response?: Response; // absent for network failures; not enumerable
+  request: RequestContext; // not enumerable — holds credentials
+  cause?: unknown; // the underlying error for network failures
+  toJSON(): { name; message; detail; status; statusText; method; url; data }; // url without query/userinfo
+}
 ```
 
-The resulting `TimeoutError` is rethrown untouched — it is not an `ArthronError`, so `retry` will not retry it.
+### Rules worth knowing
+
+- **Fill path segments with `path`.** `{name}` placeholders are encoded per segment; `""`, `.` and `..` are refused, as are missing or unused values. Without `path`, braces are left alone.
+- **URLs are joined by string concatenation.** `baseURL: "https://a/v1"` + `"/users"` → `https://a/v1/users`. The `/v1` survives, unlike with `new URL()`.
+- **Absolute URLs stay on `baseURL`'s origin.** `api.get("https://other.example/x")` on a client with a `baseURL` rejects with a `TypeError`, because a path built from user input or an API response must not carry your credentials elsewhere. Same-origin absolute URLs work. `allowAbsoluteUrls: true` lets other origins through, with per-call headers only. Only `http(s)` URLs are accepted.
+- **Error bodies are read up to 64 KiB.** That is enough for any error message and keeps a huge or endless error body from filling memory. Past the limit `data` is the raw text and the rest of the body is cancelled.
+- **Redirects follow fetch's rules.** On a redirect to another origin, fetch drops `Authorization` but keeps other headers such as `x-api-key`. Pass `redirect: "error"` (or `"manual"`) for calls that carry such keys if the server could redirect off-origin.
+- **Bodies.** `string`, `FormData`, `Blob`, `ArrayBuffer`/views, `URLSearchParams` and `ReadableStream` go through untouched — recognised by type tag, so polyfill and cross-realm instances count too. A `ReadableStream` is sent with `duplex: "half"`, which fetch requires. Anything else — including `null` — becomes JSON with `content-type: application/json`; a content type you set must be a JSON one. Bodies JSON would mangle — a `Map`, `Set`, generator, Node stream or function — are rejected with a `TypeError` that says what to pass instead. A `FormData` body is always sent without a `content-type` header, even with a JSON default, so the runtime can add the multipart boundary. `GET`/`HEAD` with a body is rejected with a `TypeError`.
+- **Fetch defaults are flat and only sent when set.** Config takes the same fetch options per-call calls do (`credentials`, `cache`, `redirect`, …) as defaults; a per-call value wins and `extend` overrides. Nothing is sent that you did not set — cross-origin cookies need `credentials: "include"`. `signal`, `body` and `method` are per call: a client-wide signal would fail every call once aborted.
+- **Response bodies are single-use.** A response interceptor that wants to inspect the body must `res.clone()`; one that changes it returns a new `Response`.
+- **Argument errors reject, they don't throw.** No `baseURL` with a relative path, a URL the global fetch cannot parse (`baseURL: "api.example.com"` without `https://`), a `BigInt` in a JSON body, a missing `method` in `request` — all surface as a rejected `TypeError` before anything is sent, never as a retried `status: 0`. An injected `fetch` is the judge of its own URLs: arthron does not pre-check them, so one that accepts relative URLs (SvelteKit's server-side `fetch`) works with `baseURL: "/api"`.
 
-## Gotchas
+## For tooling and agents
 
-- **`Response` bodies are single-use.** A response interceptor that wants to peek must `res.clone()` first; one that wants to change the body returns a new `Response`.
-- **`credentials` is not set by default.** Cookie-based sessions need `credentials: "include"` in the config (cross-origin) — arthron will not guess.
-- **`baseURL` joining is string concatenation.** `"…/v1"` + `"/users"` keeps `/v1`. Pass an absolute URL to escape the base.
-- **Only `!ok` and network failures become `ArthronError`.** Cancellations and plugin exceptions propagate as-is and do not reach error interceptors or `retry`.
-- **`.json<T>()` is a cast.** Validate with your schema library if you need to.
+- `CHANGELOG.md` lists every release and the semver rules arthron follows since 1.0.
+- `llms.txt` ships in the package — a compressed API reference meant to be read by LLM-based tools (`node_modules/arthron/llms.txt`).
+- `examples/` holds type-checked, runnable recipes: LLM streaming, auth refresh, an error page, upload/download. `examples/recipes.test.ts` keeps the auth and error-page recipes honest.
+- Error messages state the fix (`… — pass baseURL in arthron({ baseURL }) or use an absolute URL`).
 
 ## License