arthron 1.2.0 → 2.1.0

package/llms.txt

@@ -1,97 +1,100 @@
 # arthron
 
-> A fetch client assembled from plugins. Returns native `Response`; middleware controls flow (can retry via `next`), interceptors transform values. Zero dependencies, ESM + CJS, Node 22+ and browsers, TypeScript 5.0+.
+> A lightweight fetch client you assemble from plugins. Returns native `Response`; middleware controls flow (can retry via `next`), interceptors transform values. Zero dependencies, ESM + CJS, Node 22+ and browsers, TypeScript 5.0+.
 
-Import: `import { arthron, isArthronError, SchemaError, definePlugin } from "arthron";` and the built-in plugins `import { bearerAuth, retry, timeout, logging, uploadProgress } from "arthron/plugins";` (also exported from "arthron" as deprecated aliases until the next major, bearerAuth excepted).
+Import: `import { arthron, isArthronError, ArthronError, SchemaMismatchError, createPlugin } from "arthron";` and the built-in plugins `import { bearerAuth, retry, timeout, logging, uploadProgress } from "arthron/plugins";` (only there — not from "arthron"). The plugins' types (`RetryOptions`, `TimeoutOptions`, `BearerAuthOptions`, `LoggingOptions`, `LogEvent`, `UploadProgressEvent`) also come from "arthron/plugins" only. Times are in ms everywhere.
+
+From 1.x: most old names throw a TypeError that names the new one — `use`→`plugins`, `fetch`→`fetchFn`, `errorDetail`→`extractDescription`, `allowAbsoluteUrls`→`allowedOrigins`, `params`/`path`→`queryParams`/`pathParams`, plugin `name`→`pluginName`, slots `request`/`response`/`error`→`requestInterceptor`/`responseInterceptor`/`errorInterceptor`, `requestContext.fetch`→`requestContext.fetchFn`, `token`/`refresh`→`accessTokenFn`/`refreshFn`, bearerAuth `origin`→`tokenOrigins` (a list), `retryOn`/`delay`→`statuses`/`delayFn`, `meta.onUploadProgress`→`meta.uploadProgress: { onProgress }`. Renamed fields and types are TypeScript errors: `e.detail`/`e.data`/`e.request`→`e.description`/`e.payload`/`e.requestContext`, `definePlugin`→`createPlugin`, `SchemaError`→`SchemaMismatchError`, `StandardSchemaV1`/`InferOutput`/`SchemaIssue`→`ArthronSchema`/`ArthronSchema.Infer`/`ArthronSchema.Issue`, SSE `event`/`retry`/`maxEventSize`→`type`/`reconnectionTime`/`maxDataLength`, upload `progress`→`fraction`, `LogEvent` `path`/`ms`→`url`/`duration`.
 
 ## Create
 
 ```ts
 const api = arthron({
-  baseURL?: string,              // prefix for relative paths; required unless you pass absolute URLs
-  allowAbsoluteUrls?: boolean,   // default false: an absolute URL must stay on baseURL's origin
-  headers?: HeadersInit,         // defaults, per-call headers win (case-insensitive); { name: null } in extend/per-call drops one
+  baseURL?: string,              // prefix for relative paths; required unless you pass absolute URLs; an http(s) one without a host → TypeError
+  allowedOrigins?: readonly string[], // other origins an absolute URL may go to (origin of each URL; http(s) only; empty or a single string → TypeError); without baseURL it alone limits absolute URLs, and config headers are refused (TypeError)
+  headers?: HeadersInit | Record<string, string | null | undefined>, // defaults, sent to baseURL's origin only; per-call headers win (case-insensitive); { name: null } in extend/per-call drops one
   credentials?, cache?, redirect?, mode?, keepalive?, …  // any fetch option (RequestInit minus body/method/headers/signal/window) as a default; per-call wins; NOT set unless you set it; passing signal/body/method throws
-  fetch?: typeof fetch,          // injection for tests/polyfills, resolved per request
-  use?: Plugin[],                // plugins, outermost first
-  errorDetail?: (data: unknown, res: Response) => string | undefined, // picks ArthronError.detail
-  throwOn?: (res: Response) => boolean, // which non-ok responses reject; also a per-call option
+  fetchFn?: typeof fetch,        // the function requests are sent with (fake in tests, polyfill, framework fetch); default the global fetch, read per request; not a function → TypeError
+  plugins?: readonly Plugin[],   // outermost first; one with the pluginName of an earlier one replaces it
+  extractDescription?: (payload: unknown, response: Response) => string | undefined, // extracts ArthronError.description; failed responses only; if it throws, description is undefined
+  throwOn?: (response: Response) => boolean, // which non-ok responses reject; also a per-call option
 });
 ```
 
 ## Request
 
 ```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.query(path, body?, init?)   // QUERY = RFC 10008
-api.request(path, { method, body?, ...init })      // method: HttpMethod (GET…QUERY autocomplete, any string allowed); standard ones sent uppercased
-// init = RequestInit minus method/body, plus params?: Record<string, scalar | scalar[] | null | undefined> | URLSearchParams (arrays → repeated keys; object values → TypeError); headers values may be null to drop a default; meta?: ArthronMeta (plugin settings, not sent); path?: Record<string, string|number> fills {name} placeholders, encoded per segment ("", ".", ".." refused) — use it instead of interpolating ids
+api.get(path, requestOptions?) | api.delete(path, requestOptions?) | api.head(path, requestOptions?)
+api.post(path, body?, requestOptions?) | api.put(…) | api.patch(…) | api.query(path, body?, requestOptions?)   // QUERY = RFC 10008
+api.request(path, { method, body?, ...requestOptions })   // method: HttpMethod (GET…QUERY autocomplete, any string allowed); standard ones sent uppercased; no method → TypeError
+// requestOptions = RequestInit minus method/body, plus queryParams?: Record<string, scalar | scalar[] | null | undefined> | URLSearchParams (arrays → repeated keys; object values → TypeError); headers values may be null to drop a default; meta?: ArthronMeta (plugin settings, not sent); pathParams?: Record<string, string|number> fills {name} placeholders, encoded per segment ("", ".", ".." refused) — use it instead of interpolating ids
 ```
 
-Every method returns `Promise<Response>` plus helpers:
-`.json<T>()` (cast) / `.json(schema)` (any Standard Schema — Zod, Valibot, ArkType; typed from it; mismatch → SchemaError with .issues, not an ArthronError) `.text()` `.blob()` `.arrayBuffer()` `.formData()` `.sse({ maxLineLength?, maxEventSize? }?): AsyncIterable<{event?,data,id?,lastEventId,retry?}> (lastEventId and retry persist across events, per spec; no reconnection)` `.ndjson<T>({ maxLineLength? }?): AsyncIterable<T>` — limits default to 8 Mi characters; exceeding one rejects with RangeError and cancels the body
+Every request method returns `Promise<Response>` plus helpers:
+`.json<T>()` (cast) / `.json(schema)` (an `ArthronSchema`: `StandardSchemaV1` from @standard-schema/spec under arthron's name — pass a Zod, Valibot or ArkType schema as is; typed as `ArthronSchema.Infer<S>`; a mismatch → `SchemaMismatchError` with `.issues: ArthronSchema.Issue[]`, not an ArthronError) `.text()` `.blob()` `.arrayBuffer()` `.formData()` `.sse({ maxLineLength?, maxDataLength? }?): AsyncIterable<{ type, data, id?, lastEventId, reconnectionTime? }>` (`type` is the `event:` field, `"message"` when there is none, as in a browser; `lastEventId` and `reconnectionTime` (ms, from `retry:`) persist across events, per spec; no reconnection) `.ndjson<T>({ maxLineLength? }?): AsyncIterable<T>` — limits default to 8 Mi characters; exceeding one rejects with RangeError and cancels the body
 
 - Body: string/FormData/Blob/ArrayBuffer/URLSearchParams/ReadableStream sent as-is (matched by type tag, so polyfill/cross-realm instances count; streams get `duplex: "half"`; FormData is sent without content-type so the runtime sets the boundary). Any other value (incl. null) → JSON + `content-type: application/json`; a content type you set must be JSON-ish (else TypeError). Map/Set/iterables/async iterables (Node streams)/functions → TypeError. GET/HEAD with body → TypeError.
-- URL: `baseURL` + path by string concatenation (`"https://a/v1" + "/u"` → `https://a/v1/u`). An absolute path must be http(s) and, when baseURL is set, on baseURL's origin — else TypeError, unless `allowAbsoluteUrls: true`; config headers are never sent to another origin. On cross-origin redirects fetch drops Authorization but keeps custom headers (x-api-key) — use `redirect: "error"` where that matters. `params` appended with `&` if a query exists, placed before `#fragment`.
-- Argument errors (no baseURL, URL the global fetch cannot parse, BigInt body, missing method) reject the promise with TypeError before fetch; they do not throw synchronously and are never retried. URLs are pre-checked only for the global fetch; an injected `fetch` decides its own URL rules (relative URLs are fine if it accepts them).
-- `.sse()`/`.ndjson()`: leaving the loop early cancels the body. `.sse()` drops an event the stream ends inside (spec).
+- URL: `baseURL` + path by string concatenation (`"https://a/v1" + "/u"` → `https://a/v1/u`). An absolute path must be http(s); with a baseURL it must be on baseURL's origin or in `allowedOrigins`, without one in `allowedOrigins` if set — else TypeError (with neither set, any http(s) URL goes). Config headers go to baseURL's origin only, never to an `allowedOrigins` entry (calls there carry per-call headers alone); a client with neither baseURL nor allowedOrigins sends them everywhere. On cross-origin redirects fetch drops Authorization but keeps custom headers (x-api-key) — use `redirect: "error"` where that matters. `queryParams` appended with `&` if a query exists, placed before `#fragment`.
+- Argument errors (no baseURL, a URL that does not parse, BigInt body, missing method) reject the promise with TypeError before fetch; they do not throw synchronously and are never retried. URLs are pre-checked only for the global fetch; a `fetchFn` you pass decides its own URL rules (relative URLs are fine if it accepts them).
+- `.sse()`/`.ndjson()`: leaving the loop early cancels the body. `.sse()` drops an incomplete event at the end of the stream (spec).
 
 ## Errors
 
 ```ts
 class ArthronError extends Error {
+  constructor(options: ArthronErrorOptions); // { message, status, statusText, headers, payload, description?, requestContext, response?, cause? } — for tests and plugins
   status: number;        // HTTP status, 0 = network failure
   statusText: string;
-  headers: Headers;      // not enumerable
+  headers: Headers;      // the response's headers; not enumerable
   message: string;       // arthron's: "GET https://api.test/users/1 failed with 404 Not Found" / "… failed: fetch failed" — no query, no server text
-  detail?: string;       // the server's explanation (body message → error → error.message → detail); untrusted — show as text
-  data: unknown;         // JSON if parseable, else text, else undefined; from at most 64 KiB of body (text if cut)
+  description: string | undefined; // for people: the server's description of the failure (payload message → error → error.message → detail, or extractDescription); untrusted — show as text
+  payload: unknown;      // the failed response's body: JSON if parseable, else text, else undefined; at most 64 KiB read (text if cut)
   response?: Response;   // still readable, holding what was read (≤ 64 KiB); absent for network failure; not enumerable
-  request: { url: string; init: RequestInit }; // not enumerable (holds credentials)
-  cause?: unknown;       // underlying error for network failure
-  toJSON(): { name, message, detail, status, statusText, method, url /* no query/userinfo */, data };
+  requestContext: RequestContext; // the requestContext plugins see, as sent: url, init (method, headers as a lowercase record, body), meta — not a fetch Request; not enumerable (holds credentials)
+  cause?: unknown;       // underlying error for network failure (URL query/userinfo redacted in it too)
+  toJSON(): { name, message, description, status, statusText, method, url /* no query/userinfo */, payload };
 }
 isArthronError(e): e is ArthronError   // branded with Symbol.for: works (and instanceof works) across the ESM and CJS copies
 ```
 
-- Only `!response.ok` and fetch rejection become ArthronError — and not every non-ok: opaque responses (no-cors) and the 3xx of `redirect: "manual"` are returned; `throwOn(res)` (config or per call) narrows further. An ok response never rejects. Aborts (`AbortError`/`TimeoutError` or any custom `abort(reason)`, including during the error-body read) and exceptions thrown by plugins propagate untouched and skip error interceptors.
-- Serializing an ArthronError (JSON.stringify, console.error, error trackers, logging onEvent) never includes request headers, body, query or userinfo. Error messages arthron writes leave the query out too.
-- `message` is arthron's (for logs); `detail` is the server's (for UI: `e.detail ?? fallback`). Default `detail`: body `message` → `error` (string) → `error.message` → `detail`, else undefined. Override with `errorDetail`.
+- Only `!response.ok` and fetch rejection become ArthronError — and not every non-ok: opaque responses (no-cors) and the 3xx of `redirect: "manual"` are returned; `throwOn(response)` (config or per call; the call's wins) replaces that default — it decides for every non-ok response, opaque and manual 3xx included. An ok response never rejects. Aborts (`AbortError`/`TimeoutError` or any custom `abort(reason)`, including during the error-body read) and exceptions thrown by plugins propagate untouched and skip error interceptors.
+- ArthronError keeps requestContext, response and response headers non-enumerable; toJSON() omits request headers, body, URL query and userinfo. It includes server-provided payload and description, which may contain secrets if the API puts them there. The built-in logger prints a redacted URL and status; its onEvent callback receives the error object.
+- `message` is arthron's (for logs); `description` is the server's (for people: `e.description ?? fallback`). Default `description`: payload `message` → `error` (string) → `error.message` → `detail`, else undefined. Override with `extractDescription: (payload) => (payload as { msg?: string }).msg`.
 
 ## Plugins
 
 ```ts
 type Plugin = {
-  name?: string;   // identity: use/extend replace a same-named plugin in place; without(name) removes it
-  middleware?: (ctx, next: (ctx) => Promise<Response>) => Promise<Response>; // wraps the call; may call next again (retry) or not at all
-  request?: (ctx) => ctx;                      // per attempt, before fetch
-  response?: (res, ctx) => Response;           // per successful attempt; body is single-use, clone() to peek
-  error?: (err: ArthronError, ctx) => ArthronError; // per failed attempt; return value is always thrown
+  pluginName: string; // required — identity: use/extend replace a plugin with the same pluginName in place; without(pluginName) removes it. Not `name`: a function has one, and would pass for a plugin
+  middleware?: (requestContext, next: (requestContext) => Promise<Response>) => Promise<Response>; // wraps the call; may call next again (retry) or not at all
+  requestInterceptor?: (requestContext) => requestContext;           // per attempt, before fetch
+  responseInterceptor?: (response, requestContext) => Response; // per successful attempt; body is single-use, clone() to peek
+  errorInterceptor?: (error: ArthronError, requestContext) => ArthronError; // per failed attempt; return value is always thrown
 };
-type RequestContext = { url: string; init: Omit<RequestInit, "headers"> & { headers: Record<string, string> }; meta: ArthronMeta; fetch?: typeof fetch }; // fetch: the fetch this attempt uses (client's, else global) — a plugin may replace or wrap it per attempt; send still makes every ArthronError. headers: lowercase record, re-normalized after each request interceptor — spreading is safe
-// meta: per-call plugin settings from api.get(path, { meta }), never sent. Built-ins read meta.bearerAuth (false), meta.onUploadProgress (callback), meta.retry (false | options) and meta.timeout (ms).
+type RequestContext = { url: string; init: Omit<RequestInit, "headers"> & { headers: Record<string, string> }; meta: ArthronMeta; fetchFn?: typeof fetch }; // fetchFn: the function this attempt is sent with (client's, else global) — a plugin may replace or wrap it per attempt, and a failure through it still becomes an ArthronError; one that is not a function, or the 1.x requestContext.fetch, → TypeError. Call it as requestContext.fetchFn(…) only after copying it to a variable: as a method, the browser's fetch throws "Illegal invocation". headers: lowercase record, re-normalized after each request interceptor — spreading is safe
+// meta: per-call plugin settings from api.get(path, { meta }), never sent. Each built-in with a per-call setting reads the key named after it: meta.bearerAuth (false), meta.retry (false | options), meta.timeout (false | ms | { total?, idle? }), meta.uploadProgress ({ onProgress }).
 // Add keys: declare module "arthron" { interface ArthronMeta { skipTrace?: boolean } }
 ```
 
-Order: `middleware[0]( middleware[1]( attempt: request interceptors → fetch → response | error interceptors ) )` — a middleware is called once; code after `await next(ctx)` runs after the response interceptors. Inside `try`, write `return await next(ctx)` or the catch misses the error. Default order: `[logging(), bearerAuth(…), timeout(ms), retry()]` (timeout before retry = whole call, after = per attempt). Same-named plugins replace each other; for two timeouts rename one: `{ ...timeout(30_000), name: "callTimeout" }`. Values that must be fresh per attempt (token, signature) → request interceptor; the same on every attempt (idempotency key) → middleware before retry. Each attempt gets a fresh copy of ctx (headers, and a FormData/URLSearchParams body).
+Order: `middleware[0]( middleware[1]( attempt: request interceptors → fetch → response | error interceptors ) )` — the outermost middleware runs once per call; one below a middleware that calls `next` again runs again each time; code after `await next(requestContext)` runs after the response interceptors. Inside `try`, write `return await next(requestContext)` or the catch misses the error. Default order: `[logging(), bearerAuth(…), timeout(ms), retry()]` (timeout before retry = whole call, after = per attempt). Plugins with the same pluginName replace each other; for two timeouts rename one: `{ ...timeout(30_000), pluginName: "callTimeout" }`. Values that must be fresh per attempt (token, signature) → request interceptor; the same on every attempt (idempotency key) → middleware before retry. Each attempt gets a fresh copy of requestContext (headers, and a FormData/URLSearchParams body).
 
-`api.use(...plugins)`, `api.extend(config)` and `api.without(...names)` return NEW clients; the original is unchanged. A named plugin replaces the one with the same name at its position (built-ins: "bearerAuth", "retry", "timeout", "logging", "uploadProgress"); unnamed plugins append.
+`api.use(...plugins)`, `api.extend(clientOptions)` and `api.without(...pluginNames)` return NEW clients; the original is unchanged. A plugin replaces the one with the same pluginName at its position (built-ins: "bearerAuth", "retry", "timeout", "logging", "uploadProgress"); other names append.
 
-Helpers (identity, for typing): `definePlugin(p)`, `defineMiddleware(m)`, `defineInterceptor.request(f) / .response(f) / .error(f)`.
+`createPlugin(p)` types a plugin and checks it (TypeError for: no pluginName, an unknown key — keep state in a closure, in a function that returns createPlugin({ … }), as the built-ins do — a 1.x `name` field or `request`/`response`/`error` slot, a slot that is not a function, nothing to run, a bare function); `use`/`plugins` run the same check. `createMiddleware(m)`, `createRequestInterceptor(f)`, `createResponseInterceptor(f)`, `createErrorInterceptor(f)` type a piece written on its own (create + the type's name).
 
 ## Built-in plugins (from "arthron/plugins")
 
-- `retry({ retries=2, retryOn=[408,429,500,502,503,504], methods=[GET,HEAD,OPTIONS,QUERY,PUT,DELETE], delay=(n)=>Math.random()*300*2**n /* full jitter */, maxRetryAfter=60000, shouldRetry?(error, attempt, ctx) → true|false|undefined, onRetry?(error, attempt, waitMs) })` — re-runs the whole attempt (request interceptors included). Honours Retry-After (seconds or HTTP-date). Never retries ReadableStream bodies or aborted requests, nor beyond `retries`; by default never non-ArthronErrors (shouldRetry may opt in, e.g. an inner TimeoutError). With methods: ["POST"], network errors (status 0) are retried too — refuse them with shouldRetry where a duplicate would hurt. Per call: `meta: { retry: false }` or `meta: { retry: { retries: 5 } }`. `retries` must be a whole number ≥ 0 (TypeError otherwise); waits are capped at 2^31-1 ms.
-- `timeout(ms)` | `timeout({ total?, idle? })` — `total` (= `ms`): deadline from attempt start until the body is fully read; `idle`: aborts after that many ms without data (headers or chunks), so `timeout({ idle: 30_000 })` never cuts a flowing stream. Both together: whichever trips first. `{}` → TypeError. Deprecated: `timeout(ms, { idle })`. Rejects with TimeoutError (not ArthronError; retry ignores it). Place after `retry` for per-attempt, before it for total. Per call: `meta: { timeout: ms }` (Infinity lifts it). `Infinity` = no deadline; NaN/negative/>2^31-1 → TypeError. Keeps `res.url`/`redirected`/`type` (through `clone()` too); timers are unref'd.
-- `bearerAuth({ origin, token, refresh? })` — `authorization: Bearer <token>` on every attempt, only to requests on `origin` (a URL or array; only origins count, non-http(s) → TypeError). `token: () => string | null | undefined | Promise<…>`, read per attempt; empty → no header. With `refresh: () => Promise<void>`, a 401 refreshes and redoes the call once: concurrent 401s share one refresh, a call whose token was already replaced retries without refreshing, a second 401 is thrown, a rejected refresh reaches every waiting call unchanged. Without `refresh`, or for a ReadableStream body (cannot be resent), 401 is thrown without refreshing. Per call: `meta: { bearerAuth: false }` = no token, no refresh — required on the login/refresh requests if they use the same client (else the refresh's own 401 waits on itself). Token is opaque: refresh ahead of a JWT's exp inside `token()`.
-- `logging({ enabled=true, logger=console, onEvent?, now? })` — start/success/error lines or structured events `{ phase, method, path, status?, ms?, error? }`. Never prints query strings or userinfo. Does not log cancellations.
-- `uploadProgress()` — does nothing alone; a call with `meta: { onUploadProgress: ({ loaded, total, progress }) => … }` and a body reports upload progress (total/progress undefined when the size is unknown; restarts at 0 per attempt; no events after the response or an abort). Browser (incl. Electron renderer): sent over XMLHttpRequest (cross-origin → CORS preflight; response not streamed; redirect "manual"/"error", mode "no-cors", credentials "omit" to the page's origin → TypeError before sending; cache/priority/referrerPolicy/integrity/keepalive ignored; ReadableStream body → no progress). Node (incl. jsdom on Node): fetch with the body counted in ≤ 64 KiB steps, content-length and Blob content-type kept (S3 presigned PUT works); FormData encoded with a known length, files streamed. Deno/Bun/Cloudflare Workers/Electron main/service workers, an injected fetch or another transport plugin → sent as usual without progress. A throwing callback rejects the call with its own error (not ArthronError, not retried) — keep uploadProgress last in use. Works through ctx.fetch.
+- `retry({ retries=2, statuses=[408,429,500,502,503,504], methods=[GET,HEAD,OPTIONS,QUERY,PUT,DELETE], delayFn=(attempt)=>Math.random()*300*2**attempt /* full jitter; Retry-After wins; must return a finite number ≥ 0, else TypeError */, maxRetryAfter=60000, shouldRetry?(error, attempt, requestContext) → true|false|undefined, onRetry?(error, attempt, delay) })` — `attempt` is 0-based in all three. Re-runs the whole attempt (request interceptors included). Honours Retry-After (seconds or HTTP-date). Never retries ReadableStream bodies or aborted requests, nor beyond `retries`, nor past a Retry-After longer than `maxRetryAfter`; by default never non-ArthronErrors (shouldRetry may opt in, e.g. an inner TimeoutError). With methods: ["POST"], network errors (status 0) are retried too — refuse them with shouldRetry where a duplicate would hurt. Per call: `meta: { retry: false }` or `meta: { retry: { retries: 5 } }`. `retries` must be a whole number ≥ 0 (TypeError otherwise); waits are capped at 2^31-1 ms.
+- `timeout(ms)` | `timeout({ total?, idle? })` — `total` (= `ms`): deadline from the start of what it wraps until the body is fully read; `idle`: aborts after that many ms without data while arthron waits on the server (for the headers, then the next chunk, read one ahead of the caller; time the caller spends between reads does not count), so `timeout({ idle: 30_000 })` never cuts a flowing stream — nor a body left unread past its first chunk (cancel it, or add `total`). Both together: whichever trips first. `{}` → TypeError; so is an object second argument (the 1.x `timeout(ms, { idle })`). Rejects with TimeoutError (not ArthronError; retry does not repeat it unless shouldRetry returns true for it). Place after `retry` for per-attempt, before it for total. Per call: `meta: { timeout: false }` lifts both, `meta: { timeout: ms }` replaces total, `meta: { timeout: { idle: 30_000 } }` replaces the parts it sets. `Infinity` = no deadline; NaN/negative/>2^31-1 → TypeError. Keeps `res.url`/`redirected`/`type` (through `clone()` too); timers are unref'd.
+- `bearerAuth({ tokenOrigins, accessTokenFn, refreshFn? })` — `authorization: Bearer <token>` on every attempt, only to requests on `tokenOrigins` (a list of URLs; only origins count; non-http(s), empty or a single string → TypeError; requests from a relative baseURL are on the page's origin, so list that origin — `"/api"` itself → TypeError). `accessTokenFn: () => string | null | undefined | Promise<…>`, called per attempt; empty → no header. With `refreshFn: () => Promise<void>` (refreshes the session so the next accessTokenFn() returns the new token), a 401 refreshes and redoes the call once: concurrent 401s share one refresh, a call whose token was already replaced retries without refreshing, a second 401 is thrown, a rejected refresh reaches every waiting call unchanged. Without `refreshFn`, or for a ReadableStream body (cannot be resent), 401 is thrown without refreshing. Per call: `meta: { bearerAuth: false }` = no token, no refresh — use it on the login/refresh requests if they use the same client. A request refreshFn starts before its first await gets it automatically; one started after an await must pass it (else its 401 waits on the refresh it belongs to). Token is opaque: refresh ahead of a JWT's exp inside `accessTokenFn`.
+- `logging({ enabled=true, logger=console, onEvent?, timeouts=false })` — start/success/error lines or structured events `{ phase, method, url /* query and userinfo removed */, status?, duration? /* ms, retries included */, error? }`. An error without a status prints its name where the status goes (`TimeoutError`, `TypeError`). A cancelled call has a start event but no success or error event; with `timeouts: true` a TimeoutError before the response arrives gets an error event (status undefined) — one while the body is read only rejects that read, after the success event.
+- `uploadProgress()` — does nothing alone; a call with `meta: { uploadProgress: { onProgress: ({ loaded, total, fraction }) => … } }` and a body reports upload progress (`fraction` is 0–1, not a percentage; total/fraction undefined when the size is unknown; restarts at 0 per attempt; no events after the response or an abort). Browser (incl. Electron renderer): sent over XMLHttpRequest (cross-origin → CORS preflight; response not streamed; redirect "manual"/"error", mode "no-cors", credentials "omit" to the page's origin, a referrerPolicy/referrer of its own, integrity → TypeError before sending; cache/priority/keepalive ignored; ReadableStream body → no progress). Node (incl. jsdom on Node): fetch with the body counted in ≤ 64 KiB steps, content-length and Blob content-type kept (S3 presigned PUT works); FormData encoded with a known length, files streamed. Deno/Bun/Cloudflare Workers/Electron main/service workers, a client fetchFn or another plugin's → sent as usual without progress. A throwing onProgress rejects the call with its own error (not ArthronError, not retried) — keep uploadProgress last in plugins. Works through requestContext.fetchFn.
 
 ## Recipes
 
 Auth refresh — built in (`bearerAuth()` above; examples/auth-refresh.ts). The refresh request skips auth:
 ```ts
-const api = arthron({ baseURL: API, use: [bearerAuth({ origin: API, token: () => tok, refresh: async () => {
+const api = arthron({ baseURL: API, plugins: [bearerAuth({ tokenOrigins: [API], accessTokenFn: () => tok, refreshFn: async () => {
   tok = (await api.post("/token/refresh", undefined, { meta: { bearerAuth: false } }).json<{ access_token: string }>()).access_token;
 } })] });
 ```
@@ -108,8 +111,8 @@ for await (const { data } of api.post("/v1/chat/completions", { model, messages,
 
 ## Non-goals
 
-No request/response key transformation, no caching, no dedupe, no backend-envelope unwrapping. Do those in your adapter layer.
+No request/response key transformation, no caching, no dedupe, no backend-envelope unwrapping. Do those in your own code around the client.
 
 ## Types
 
-Public object types are interfaces (ArthronConfig, RequestOptions, RequestInitWithBody, RequestContext, ArthronMeta, Plugin, ArthronPromise, Arthron): extend them with `declare module "arthron" { interface … }`.
+Public object types are interfaces (ArthronClientOptions, RequestOptions, RequestOptionsWithMethod, RequestContext, ArthronMeta, Plugin, ResponsePromise, ArthronClient, ArthronSchema): extend them with `declare module "arthron" { interface … }`. Also exported: ArthronErrorOptions, DescriptionExtractor, QueryParams, HttpMethod, SseEvent, SseOptions, NdjsonOptions, Middleware and the interceptor types.

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "arthron",
-  "version": "1.2.0",
-  "description": "Composable fetch client — create from config, plug in interceptors and middleware",
+  "version": "2.1.0",
+  "description": "A lightweight fetch client you assemble from plugins. Zero dependencies, returns native Response.",
   "license": "MIT",
   "author": "lapidix",
+  "homepage": "https://lapidix.github.io/arthron/",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/lapidix/arthron.git"
@@ -61,11 +62,16 @@
     "check:types-pkg": "attw --pack .",
     "check:types-consumer": "node test/types-consumer/check.mjs",
     "check:browsers": "pnpm --dir test/browser test",
-    "prepublishOnly": "pnpm lint && pnpm typecheck && pnpm test && pnpm build && pnpm check:types-pkg"
+    "docs:dev": "pnpm --dir docs dev",
+    "docs:build": "pnpm --dir docs build",
+    "docs:preview": "pnpm --dir docs preview",
+    "release:approve": "node scripts/approve-release.mjs",
+    "prepublishOnly": "pnpm lint && pnpm typecheck && pnpm test && pnpm build && node scripts/smoke.mjs && pnpm check:types-pkg"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
     "@biomejs/biome": "^2.5.15",
+    "@standard-schema/spec": "^1.1.0",
     "@types/node": "^26.6.5",
     "tsdown": "^0.23.1",
     "typescript": "^7.0.2",

package/dist/index-C3lylSNd.d.cts

@@ -1,333 +0,0 @@
-//#region src/types/request.types.d.ts
-/**
- * What plugins see and return. `init.headers` is always a plain record with
- * lowercased names — spread it, read it, add to it — and the pipeline puts
- * it back into that shape after every request interceptor.
- */
-interface RequestContext {
-  url: string;
-  init: Omit<RequestInit, "headers"> & {
-    headers: Record<string, string>;
-  };
-  /** Per-call settings for plugins (`RequestOptions.meta`); never sent. */
-  meta: ArthronMeta;
-  /**
-   * The fetch this attempt is sent with — the client's `fetch`, else the
-   * global one. Always set on contexts arthron creates; replace it to change
-   * the transport for this attempt, wrap it to observe. Optional so a
-   * context you build yourself stays valid.
-   */
-  fetch?: typeof fetch;
-}
-/**
- * Per-call settings for plugins, passed as `api.get(path, { meta })` and
- * carried next to `init` — never sent to fetch. The built-in plugins read
- * `bearerAuth`, `onUploadProgress`, `retry` and `timeout`; your own add keys
- * by augmentation:
- *
- * ```ts
- * declare module "arthron" {
- *   interface ArthronMeta { skipTrace?: boolean }
- * }
- * ```
- */
-interface ArthronMeta {
-  /**
-   * `false` sends this call without the `bearerAuth()` token and never refreshes
-   * on its 401 — for the login and token-refresh endpoints.
-   */
-  bearerAuth?: false;
-  /**
-   * Upload progress for this call, with `uploadProgress()` on the client.
-   * Never called without that plugin or without a body, nor where progress
-   * cannot be had: a client with an injected `fetch`, another plugin's
-   * transport, Deno, Bun, Cloudflare Workers, a service worker, or a
-   * `ReadableStream` body in a browser — those calls are sent as usual.
-   */
-  onUploadProgress?: (event: UploadProgressEvent) => void;
-  /** `false` turns `retry()` off for this call; an object overrides its options. */
-  retry?: false | Omit<RetryOptions, "sleep">;
-  /** Deadline for this call in ms, overriding `timeout(ms)`. `Infinity` lifts it. */
-  timeout?: number;
-}
-/** One step of an upload, as `meta.onUploadProgress` receives it. */
-type UploadProgressEvent = {
-  /** Bytes sent so far. */
-  loaded: number;
-  /** Bytes in the whole body; `undefined` when it cannot be known (a stream without content-length). */
-  total: number | undefined;
-  /** `loaded / total`, from 0 to 1; `undefined` when `total` is. */
-  progress: number | undefined;
-};
-type RetryOptions = {
-  /** Number of retries after the first attempt. Default 2 (3 requests total). */
-  retries?: number;
-  /** Statuses worth retrying. Network errors (status 0) always are. */
-  retryOn?: readonly number[];
-  /** Methods safe to repeat (QUERY is, per RFC 10008). Compared case-insensitively. */
-  methods?: readonly string[];
-  /**
-   * Backoff in ms for retry number `retry` (0-based). Default "full jitter":
-   * a random share of 300 · 2^retry, so clients that failed together do not
-   * retry together.
-   */
-  delay?: (retry: number, error: unknown) => number;
-  /**
-   * Your own verdict on one failure: `true` retries, `false` stops,
-   * `undefined` leaves it to `retryOn`/`methods`. It sees every error — a
-   * TimeoutError from a `timeout()` placed after `retry()` included — but
-   * cannot exceed `retries`, resend a `ReadableStream` body, or retry a call
-   * the caller aborted.
-   */
-  shouldRetry?: (error: unknown, attempt: number, ctx: RequestContext) => boolean | undefined;
-  /** Called before each wait, for logs and metrics. */
-  onRetry?: (error: unknown, attempt: number, waitMs: number) => void;
-  /** Injectable for tests. Default `setTimeout`; rejects with the abort reason. */
-  sleep?: (ms: number, signal?: AbortSignal | null) => Promise<void>;
-  /**
-   * Longest `Retry-After` (ms) worth honouring. Beyond it the request is not
-   * retried at all. Default 60 000.
-   */
-  maxRetryAfter?: number;
-};
-type QueryValue = string | number | boolean | null | undefined;
-/**
- * Query parameters. `null`/`undefined` values are skipped, an array becomes
- * repeated keys (`ids=1&ids=2`), and a `URLSearchParams` is used as is.
- */
-type QueryParams = Record<string, QueryValue | readonly QueryValue[]> | URLSearchParams;
-/**
- * Headers as config and per-call options accept them: anything fetch's
- * `headers` takes, or a plain object whose `null`/`undefined` values delete
- * that header from the layer underneath (a client default, an inherited
- * header). Not spelled `HeadersInit`: that name exists only in the DOM lib,
- * and a Node project typed with `@types/node` alone does not have it.
- */
-type HeadersOption = NonNullable<RequestInit["headers"]> | Record<string, string | null | undefined>;
-//#endregion
-//#region src/error/arthron-error.d.ts
-type ArthronErrorInit = {
-  message: string;
-  status: number;
-  statusText: string;
-  headers: Headers;
-  data: unknown;
-  detail?: string | undefined;
-  request: RequestContext;
-  response?: Response;
-  cause?: unknown;
-};
-/**
- * The only error arthron itself produces. Two sources: a response with
- * `ok === false`, or fetch rejecting outright (network failure, `status` 0).
- * Everything else — cancellation, interceptor bugs — is rethrown untouched.
- */
-declare class ArthronError extends Error {
-  readonly name = "ArthronError";
-  /** HTTP status of the failed response; `0` when fetch itself failed (network). */
-  readonly status: number;
-  readonly statusText: string;
-  /** Response headers; empty for network failures. Not enumerable — kept out of logs. */
-  readonly headers: Headers;
-  /** Parsed body: JSON if it parses, else the text, else `undefined`. */
-  readonly data: unknown;
-  /**
-   * The server's own explanation, picked out of `data` (by default
-   * `message` → `error` → `error.message` → `detail`; see the `errorDetail`
-   * config). `undefined` when the body had none. Untrusted server text: show
-   * it to users as text, never as HTML. `message`, by contrast, is written by
-   * arthron — method, URL without query, status — and is meant for logs.
-   */
-  readonly detail: string | undefined;
-  /**
-   * The context that was sent — url and init after request interceptors.
-   * Not enumerable: it holds credentials, so `JSON.stringify`, `console.error`
-   * and error trackers leave it out. Read it directly when you need it.
-   */
-  readonly request: RequestContext;
-  /** The failed Response, still readable — its body holds what arthron read (at most 64 KiB). Absent for network failures. Not enumerable. */
-  readonly response: Response | undefined;
-  /** The underlying error for network failures. */
-  readonly cause: unknown;
-  constructor(init: ArthronErrorInit);
-  /** `instanceof ArthronError` holds for an error from any copy of the package. */
-  static [Symbol.hasInstance](value: unknown): boolean;
-  /** What serializers see: no headers, no body, no query or userinfo. */
-  toJSON(): {
-    name: string;
-    message: string;
-    detail: string | undefined;
-    status: number;
-    statusText: string;
-    method: string;
-    url: string;
-    data: unknown;
-  };
-}
-/** `true` for errors arthron produced: a `!ok` response or a network failure. Cancellations and plugin bugs are not ArthronErrors. */
-declare function isArthronError(error: unknown): error is ArthronError;
-//#endregion
-//#region src/types/plugin.types.d.ts
-/** Runs before each attempt. Returns the context to send (may be a new object). */
-type RequestInterceptor = (ctx: RequestContext) => RequestContext | Promise<RequestContext>;
-/** Runs after a successful attempt. The body is single-use — `clone()` to peek. */
-type ResponseInterceptor = (res: Response, ctx: RequestContext) => Response | Promise<Response>;
-/** Runs after a failed attempt. Returns the error to throw; it is always thrown. */
-type ErrorInterceptor = (err: ArthronError, ctx: RequestContext) => ArthronError | Promise<ArthronError>;
-/**
- * Wraps the whole call. `next` runs everything below it (request interceptors →
- * fetch → response/error interceptors) and may be called again to retry.
- * `next` rejects with an `ArthronError`, or with the untouched original when the
- * failure was a cancellation or a bug in a plugin.
- */
-type Middleware = (ctx: RequestContext, next: (ctx: RequestContext) => Promise<Response>) => Promise<Response>;
-interface Plugin {
-  /**
-   * Identity within a client: `use`/`extend` replace the plugin of the same
-   * name in place, `without(name)` removes it. The built-ins are named
-   * "bearerAuth", "logging", "retry", "timeout" and "uploadProgress". Leave it out to always
-   * append.
-   */
-  name?: string;
-  middleware?: Middleware;
-  request?: RequestInterceptor;
-  response?: ResponseInterceptor;
-  error?: ErrorInterceptor;
-}
-//#endregion
-//#region src/plugins/bearer-auth/bearer-auth.types.d.ts
-type BearerAuthOptions = {
-  /**
-   * Where the token may go: a URL, or several. Only their origins count, so
-   * your `baseURL` works as is. A request anywhere else — a CDN, a URL taken
-   * from a response body — is sent without the token.
-   */
-  origin: string | readonly string[];
-  /**
-   * The current access token, read on every attempt. `null`, `undefined` or
-   * `""` sends no `authorization` header.
-   */
-  token: () => string | null | undefined | Promise<string | null | undefined>;
-  /**
-   * Get a new token after a 401; the call is then redone once. Concurrent
-   * 401s share one refresh, and a call whose token was already replaced
-   * retries without one. Throw when the refresh fails — every waiting call
-   * rejects with that error. Requests the refresh makes through the same
-   * client need `meta: { bearerAuth: false }`. Without `refresh`, or for a
-   * `ReadableStream` body (already read, so it cannot be resent), a 401 is
-   * thrown as is.
-   */
-  refresh?: () => Promise<void>;
-};
-//#endregion
-//#region src/plugins/bearer-auth/bearer-auth.d.ts
-/**
- * Bearer-token auth. A request interceptor sets `authorization: Bearer
- * <token>` on every attempt to `origin`; with `refresh`, a middleware turns a
- * 401 into one refresh and one more try. Concurrent 401s share the refresh
- * (with refresh-token rotation, parallel refreshes revoke each other), and a
- * call whose token was replaced meanwhile just retries. A call opts out with
- * `meta: { bearerAuth: false }`.
- */
-declare function bearerAuth(options: BearerAuthOptions): Plugin;
-//#endregion
-//#region src/plugins/logging/logging.types.d.ts
-type LogEventBase = {
-  method: string;
-  path: string;
-};
-type LogEvent = ({
-  phase: "start";
-} & LogEventBase) | ({
-  phase: "success";
-  status: number;
-  ms: number;
-} & LogEventBase) | ({
-  phase: "error";
-  /** HTTP status for an ArthronError (0 = network); undefined for anything else. */
-  status: number | undefined;
-  ms: number;
-  error: unknown;
-} & LogEventBase);
-type LoggingOptions = {
-  /** Default `true`. The library never reads `NODE_ENV` — pass `isDev` yourself. */
-  enabled?: boolean;
-  logger?: Pick<Console, "log" | "error">;
-  /** Receive structured events instead of the default console lines. */
-  onEvent?: (event: LogEvent) => void;
-  /** Clock in ms. Injectable for tests. */
-  now?: () => number;
-};
-//#endregion
-//#region src/plugins/logging/logging.d.ts
-/**
- * One event when a request starts, one when it settles, with status and
- * elapsed time. Wraps the whole call, so retries are included in the time.
- * Default output is a console line per event; pass `onEvent` to get the
- * structured event instead. Cancellations are not reported.
- */
-declare function logging(options?: LoggingOptions): Plugin;
-//#endregion
-//#region src/plugins/retry/retry.d.ts
-/**
- * Retry on network errors and the configured statuses by calling `next`
- * again — the whole attempt (request interceptors included) is re-run.
- * Only `ArthronError` is considered; cancellation and plugin bugs pass through.
- * A call can turn it off or override its options with `meta.retry`.
- */
-declare function retry(options?: RetryOptions): Plugin;
-//#endregion
-//#region src/plugins/timeout/timeout.types.d.ts
-type TimeoutOptions = {
-  /**
-   * Abort after this many ms in all, counted until the body has been fully
-   * read — the same deadline as `timeout(ms)`. Default: none.
-   */
-  total?: number;
-  /**
-   * Abort when no data has arrived for this many ms — while waiting for the
-   * headers and between body chunks. Unlike `total`, a stream that keeps
-   * flowing is never cut off: `timeout({ idle: 30_000 })`.
-   */
-  idle?: number;
-};
-//#endregion
-//#region src/plugins/timeout/timeout.d.ts
-/**
- * Abort the request when it takes longer than `ms` — counted from the start
- * of the attempt until the body has been fully read, so a server that sends
- * headers and then stalls still trips it. `timeout({ idle })` instead aborts
- * once no data has arrived for that long, and never cuts off a stream that
- * keeps flowing; `timeout({ total, idle })` does both. Rejects with a
- * `TimeoutError` (a `DOMException`, like `AbortSignal.timeout()` would give);
- * it is not an `ArthronError`, so error interceptors and `retry` leave it
- * alone.
- *
- * A call can change the total deadline with `meta.timeout`.
- *
- * Deadlines are timers on an AbortController — not `AbortSignal.timeout`,
- * since the idle one restarts — joined to the caller's signal with
- * `AbortSignal.any`.
- */
-declare function timeout(ms: number): Plugin;
-declare function timeout(options: TimeoutOptions): Plugin;
-/** @deprecated Use `timeout({ total: ms, idle })`; this form goes in the next major. */
-declare function timeout(ms: number, options: Pick<TimeoutOptions, "idle">): Plugin;
-//#endregion
-//#region src/plugins/upload-progress/upload-progress.d.ts
-/**
- * Does nothing by itself — only a call that passes `meta.onUploadProgress`
- * reports upload progress. On such a call it changes how that one attempt
- * is sent: over XMLHttpRequest in a browser, with a counted body in Node.
- * Every other call, on this client too, goes out exactly as before.
- *
- * Progress needs the runtime's own fetch: with an injected `fetch`, another
- * plugin's transport, or a runtime that is neither (Deno, Bun, Cloudflare
- * Workers, a service worker), the call is sent as usual without progress.
- * Put it last in `use`: the call's signal carries a throwing callback's
- * error, and an interceptor after it that replaces the signal would cut it.
- */
-declare function uploadProgress(): Plugin;
-//#endregion
-export { UploadProgressEvent as S, ArthronMeta as _, logging as a, RequestContext as b, bearerAuth as c, Middleware as d, Plugin as f, isArthronError as g, ArthronError as h, retry as i, BearerAuthOptions as l, ResponseInterceptor as m, timeout as n, LogEvent as o, RequestInterceptor as p, TimeoutOptions as r, LoggingOptions as s, uploadProgress as t, ErrorInterceptor as u, HeadersOption as v, RetryOptions as x, QueryParams as y };
-//# sourceMappingURL=index-C3lylSNd.d.cts.map