arthron 2.0.1 → 2.1.0

package/dist/shared.cjs

@@ -13,7 +13,7 @@ function redactUrl(url) {
 		const parsed = new URL(url);
 		return `${parsed.origin}${parsed.pathname}`;
 	} catch {
-		return url.split(/[?#]/)[0] ?? url;
+		return withoutSecrets(url);
 	}
 }
 /**
@@ -66,9 +66,15 @@ function httpOrigin(url) {
 function httpOrigins(urls, errors) {
 	if (urls.length === 0) throw new TypeError(errors.empty);
 	return new Set(urls.map((url) => {
-		const origin = httpOrigin(url);
+		const value = url;
+		if (typeof value !== "string") {
+			const kind = value === null ? "null" : typeof value;
+			const shown = kind === "null" ? kind : `${/^[aeiou]/.test(kind) ? "an" : "a"} ${kind}`;
+			throw new TypeError(errors.invalid(shown));
+		}
+		const origin = httpOrigin(value);
 		if (origin) return origin;
-		throw new TypeError(errors.invalid(JSON.stringify(withoutSecrets(url))));
+		throw new TypeError(errors.invalid(JSON.stringify(withoutSecrets(value))));
 	}));
 }
 /** `allowedOrigins` as origins, checked once when the client is created. */
@@ -326,7 +332,7 @@ function serializeBody(body, headers) {
 * redirects keep working.
 */
 function rebuildResponse(original, body) {
-	const rebuilt = new Response(body, {
+	const rebuilt = createResponse(body, {
 		status: original.status,
 		statusText: original.statusText,
 		headers: original.headers
@@ -338,6 +344,37 @@ function rebuildResponse(original, body) {
 		type
 	});
 }
+/** A status text `new Response` takes: tab, space, visible ASCII, Latin-1. */
+const REASON_PHRASE = /^[\t\x20-\x7e\x80-\xff]*$/;
+/**
+* `new Response(body, init)` for anything fetch hands over. The constructor
+* takes a status of 200–599 and a Latin-1 status text, but fetch passes on
+* what a server sends (LinkedIn answers bots with 999, and Node's fetch reads
+* a reason phrase as UTF-8). One it refuses is built as 599 or "" and set
+* back as an own property; built as 599, an unusual status is never `ok`.
+*/
+function createResponse(body, init) {
+	const { status, statusText = "" } = init;
+	const statusFits = status >= 200 && status <= 599;
+	const textFits = REASON_PHRASE.test(statusText);
+	if (statusFits && textFits) return new Response(body, init);
+	return withStatus(new Response(body, {
+		...init,
+		status: statusFits ? status : 599,
+		statusText: textFits ? statusText : ""
+	}), status, statusText);
+}
+function withStatus(target, status, statusText) {
+	const clone = target.clone.bind(target);
+	return Object.defineProperties(target, {
+		status: { value: status },
+		statusText: { value: statusText },
+		clone: {
+			value: () => withStatus(clone(), status, statusText),
+			configurable: true
+		}
+	});
+}
 /** Set those fields on `target` — and on its `clone()`s as well. */
 function withFields(target, fields) {
 	const clone = target.clone.bind(target);
@@ -357,8 +394,11 @@ function withFields(target, fields) {
 */
 function isCancellation(error, signal) {
 	if (signal?.aborted) return true;
-	const name = error?.name;
-	return name === "AbortError" || name === "TimeoutError";
+	return error?.name === "AbortError" || isTimeout(error);
+}
+/** A deadline ran out: `timeout()`, or `AbortSignal.timeout()` as the signal. Matched by name, like isCancellation. */
+function isTimeout(error) {
+	return error?.name === "TimeoutError";
 }
 /**
 * What a cancelled call rejects with: its signal's reason. WebKit's fetch
@@ -390,16 +430,16 @@ async function readCapped(response, limit) {
 		while (size <= limit) {
 			const { value, done } = await reader.read();
 			if (done) break;
-			chunks.push(value);
+			chunks.push(value.subarray(0, Math.max(0, limit - size)));
 			size += value.byteLength;
 		}
 	} catch {
 		return;
 	} finally {
-		await reader?.cancel().catch(() => {});
+		reader?.cancel().catch(() => {});
 		reader?.releaseLock();
 	}
-	const bytes = new Uint8Array(size);
+	const bytes = new Uint8Array(Math.min(size, limit));
 	let offset = 0;
 	for (const chunk of chunks) {
 		bytes.set(chunk, offset);
@@ -454,17 +494,64 @@ async function responseError(response, requestContext, extractDescription = defa
 * "Failed to fetch" / "Load failed" as a dead server, so name the likely cause.
 */
 const STREAM_BODY_HINT = " — in a browser, a ReadableStream body streams only over HTTP/2; send a Blob or ArrayBuffer to an HTTP/1.1 server";
+/** `error[key]`, or `undefined` if reading it throws. */
+function readField(error, key) {
+	try {
+		return error[key];
+	} catch {
+		return;
+	}
+}
+/**
+* An error that cannot be changed, copied with its prototype and own fields
+* so the copy can be. Values are read through the original: V8's own
+* `stack` accessor reads nothing on another object, and DOMException's
+* `name`, `message` and `code` getters throw on one. Those become writable
+* fields: stack rewriters assign to `stack`.
+*/
+function copyError(error) {
+	const descriptors = Object.getOwnPropertyDescriptors(error);
+	for (const key of Reflect.ownKeys(descriptors)) {
+		const descriptor = descriptors[key];
+		descriptors[key] = descriptor.get || descriptor.set ? {
+			value: readField(error, key),
+			writable: true,
+			enumerable: descriptor.enumerable ?? false,
+			configurable: true
+		} : {
+			...descriptor,
+			configurable: true
+		};
+	}
+	for (const key of [
+		"name",
+		"message",
+		"stack",
+		"code"
+	]) {
+		if (Object.hasOwn(descriptors, key)) continue;
+		const value = readField(error, key);
+		if (value !== void 0) descriptors[key] = {
+			value,
+			writable: true,
+			configurable: true
+		};
+	}
+	return Object.create(Object.getPrototypeOf(error), descriptors);
+}
 /**
 * Take `url`'s query and userinfo out of an error the runtime threw, in
-* place: its message and stack, string fields (Node's `input`), and its
-* causes. `console.error` and error trackers print that chain, not
-* `toJSON()`. It stays the same object, so `cause.code` and `instanceof`
-* still work; a field that cannot be redefined (a frozen error) is left.
+* place when possible: its message and stack, string fields (Node's
+* `input`), and its causes. An immutable error is copied with its prototype
+* and fields so it cannot put the full URL back into logs via `cause`.
 */
-function redactErrorUrl(error, url, seen = /* @__PURE__ */ new Set()) {
-	if (typeof error !== "object" || error === null || seen.has(error)) return;
-	seen.add(error);
+function redactErrorUrl(error, url, seen = /* @__PURE__ */ new Map()) {
+	if (typeof error === "string") return redactUrlIn(error, url);
+	if (typeof error !== "object" || error === null) return error;
+	if (seen.has(error)) return seen.get(error);
 	const fields = error;
+	let safe = error;
+	const changes = /* @__PURE__ */ new Map();
 	for (const key of /* @__PURE__ */ new Set([
 		"message",
 		"stack",
@@ -474,15 +561,32 @@ function redactErrorUrl(error, url, seen = /* @__PURE__ */ new Set()) {
 		if (typeof value !== "string") continue;
 		const redacted = redactUrlIn(value, url);
 		if (redacted === value) continue;
-		try {
+		changes.set(key, redacted);
+		if (safe === error) try {
 			Object.defineProperty(error, key, { value: redacted });
-		} catch {}
+		} catch {
+			safe = copyError(error);
+		}
+	}
+	seen.set(error, safe);
+	if (safe !== error) for (const [key, value] of changes) Object.defineProperty(safe, key, {
+		value,
+		configurable: true
+	});
+	const cause = fields.cause;
+	const safeCause = redactErrorUrl(cause, url, seen);
+	if (safeCause !== cause) try {
+		Object.defineProperty(safe, "cause", { value: safeCause });
+	} catch {
+		safe = copyError(safe);
+		Object.defineProperty(safe, "cause", { value: safeCause });
+		seen.set(error, safe);
 	}
-	redactErrorUrl(fields.cause, url, seen);
+	return safe;
 }
 function networkError(cause, requestContext) {
-	redactErrorUrl(cause, requestContext.url);
-	const reason = cause instanceof Error && cause.message ? cause.message : "network error";
+	const safeCause = redactErrorUrl(cause, requestContext.url);
+	const reason = safeCause instanceof Error && safeCause.message ? safeCause.message : "network error";
 	const hint = isReadableStream(requestContext.init.body) ? STREAM_BODY_HINT : "";
 	return new ArthronError({
 		message: `${describeRequest(requestContext)} failed: ${reason}${hint}`,
@@ -491,7 +595,7 @@ function networkError(cause, requestContext) {
 		headers: new Headers(),
 		payload: void 0,
 		requestContext,
-		cause
+		cause: safeCause
 	});
 }
 //#endregion
@@ -507,6 +611,12 @@ Object.defineProperty(exports, "cancellationError", {
 		return cancellationError;
 	}
 });
+Object.defineProperty(exports, "createResponse", {
+	enumerable: true,
+	get: function() {
+		return createResponse;
+	}
+});
 Object.defineProperty(exports, "fillPath", {
 	enumerable: true,
 	get: function() {
@@ -543,6 +653,12 @@ Object.defineProperty(exports, "isReadableStream", {
 		return isReadableStream;
 	}
 });
+Object.defineProperty(exports, "isTimeout", {
+	enumerable: true,
+	get: function() {
+		return isTimeout;
+	}
+});
 Object.defineProperty(exports, "leavesBase", {
 	enumerable: true,
 	get: function() {

package/dist/shared.mjs

@@ -13,7 +13,7 @@ function redactUrl(url) {
 		const parsed = new URL(url);
 		return `${parsed.origin}${parsed.pathname}`;
 	} catch {
-		return url.split(/[?#]/)[0] ?? url;
+		return withoutSecrets(url);
 	}
 }
 /**
@@ -66,9 +66,15 @@ function httpOrigin(url) {
 function httpOrigins(urls, errors) {
 	if (urls.length === 0) throw new TypeError(errors.empty);
 	return new Set(urls.map((url) => {
-		const origin = httpOrigin(url);
+		const value = url;
+		if (typeof value !== "string") {
+			const kind = value === null ? "null" : typeof value;
+			const shown = kind === "null" ? kind : `${/^[aeiou]/.test(kind) ? "an" : "a"} ${kind}`;
+			throw new TypeError(errors.invalid(shown));
+		}
+		const origin = httpOrigin(value);
 		if (origin) return origin;
-		throw new TypeError(errors.invalid(JSON.stringify(withoutSecrets(url))));
+		throw new TypeError(errors.invalid(JSON.stringify(withoutSecrets(value))));
 	}));
 }
 /** `allowedOrigins` as origins, checked once when the client is created. */
@@ -326,7 +332,7 @@ function serializeBody(body, headers) {
 * redirects keep working.
 */
 function rebuildResponse(original, body) {
-	const rebuilt = new Response(body, {
+	const rebuilt = createResponse(body, {
 		status: original.status,
 		statusText: original.statusText,
 		headers: original.headers
@@ -338,6 +344,37 @@ function rebuildResponse(original, body) {
 		type
 	});
 }
+/** A status text `new Response` takes: tab, space, visible ASCII, Latin-1. */
+const REASON_PHRASE = /^[\t\x20-\x7e\x80-\xff]*$/;
+/**
+* `new Response(body, init)` for anything fetch hands over. The constructor
+* takes a status of 200–599 and a Latin-1 status text, but fetch passes on
+* what a server sends (LinkedIn answers bots with 999, and Node's fetch reads
+* a reason phrase as UTF-8). One it refuses is built as 599 or "" and set
+* back as an own property; built as 599, an unusual status is never `ok`.
+*/
+function createResponse(body, init) {
+	const { status, statusText = "" } = init;
+	const statusFits = status >= 200 && status <= 599;
+	const textFits = REASON_PHRASE.test(statusText);
+	if (statusFits && textFits) return new Response(body, init);
+	return withStatus(new Response(body, {
+		...init,
+		status: statusFits ? status : 599,
+		statusText: textFits ? statusText : ""
+	}), status, statusText);
+}
+function withStatus(target, status, statusText) {
+	const clone = target.clone.bind(target);
+	return Object.defineProperties(target, {
+		status: { value: status },
+		statusText: { value: statusText },
+		clone: {
+			value: () => withStatus(clone(), status, statusText),
+			configurable: true
+		}
+	});
+}
 /** Set those fields on `target` — and on its `clone()`s as well. */
 function withFields(target, fields) {
 	const clone = target.clone.bind(target);
@@ -357,8 +394,11 @@ function withFields(target, fields) {
 */
 function isCancellation(error, signal) {
 	if (signal?.aborted) return true;
-	const name = error?.name;
-	return name === "AbortError" || name === "TimeoutError";
+	return error?.name === "AbortError" || isTimeout(error);
+}
+/** A deadline ran out: `timeout()`, or `AbortSignal.timeout()` as the signal. Matched by name, like isCancellation. */
+function isTimeout(error) {
+	return error?.name === "TimeoutError";
 }
 /**
 * What a cancelled call rejects with: its signal's reason. WebKit's fetch
@@ -390,16 +430,16 @@ async function readCapped(response, limit) {
 		while (size <= limit) {
 			const { value, done } = await reader.read();
 			if (done) break;
-			chunks.push(value);
+			chunks.push(value.subarray(0, Math.max(0, limit - size)));
 			size += value.byteLength;
 		}
 	} catch {
 		return;
 	} finally {
-		await reader?.cancel().catch(() => {});
+		reader?.cancel().catch(() => {});
 		reader?.releaseLock();
 	}
-	const bytes = new Uint8Array(size);
+	const bytes = new Uint8Array(Math.min(size, limit));
 	let offset = 0;
 	for (const chunk of chunks) {
 		bytes.set(chunk, offset);
@@ -454,17 +494,64 @@ async function responseError(response, requestContext, extractDescription = defa
 * "Failed to fetch" / "Load failed" as a dead server, so name the likely cause.
 */
 const STREAM_BODY_HINT = " — in a browser, a ReadableStream body streams only over HTTP/2; send a Blob or ArrayBuffer to an HTTP/1.1 server";
+/** `error[key]`, or `undefined` if reading it throws. */
+function readField(error, key) {
+	try {
+		return error[key];
+	} catch {
+		return;
+	}
+}
+/**
+* An error that cannot be changed, copied with its prototype and own fields
+* so the copy can be. Values are read through the original: V8's own
+* `stack` accessor reads nothing on another object, and DOMException's
+* `name`, `message` and `code` getters throw on one. Those become writable
+* fields: stack rewriters assign to `stack`.
+*/
+function copyError(error) {
+	const descriptors = Object.getOwnPropertyDescriptors(error);
+	for (const key of Reflect.ownKeys(descriptors)) {
+		const descriptor = descriptors[key];
+		descriptors[key] = descriptor.get || descriptor.set ? {
+			value: readField(error, key),
+			writable: true,
+			enumerable: descriptor.enumerable ?? false,
+			configurable: true
+		} : {
+			...descriptor,
+			configurable: true
+		};
+	}
+	for (const key of [
+		"name",
+		"message",
+		"stack",
+		"code"
+	]) {
+		if (Object.hasOwn(descriptors, key)) continue;
+		const value = readField(error, key);
+		if (value !== void 0) descriptors[key] = {
+			value,
+			writable: true,
+			configurable: true
+		};
+	}
+	return Object.create(Object.getPrototypeOf(error), descriptors);
+}
 /**
 * Take `url`'s query and userinfo out of an error the runtime threw, in
-* place: its message and stack, string fields (Node's `input`), and its
-* causes. `console.error` and error trackers print that chain, not
-* `toJSON()`. It stays the same object, so `cause.code` and `instanceof`
-* still work; a field that cannot be redefined (a frozen error) is left.
+* place when possible: its message and stack, string fields (Node's
+* `input`), and its causes. An immutable error is copied with its prototype
+* and fields so it cannot put the full URL back into logs via `cause`.
 */
-function redactErrorUrl(error, url, seen = /* @__PURE__ */ new Set()) {
-	if (typeof error !== "object" || error === null || seen.has(error)) return;
-	seen.add(error);
+function redactErrorUrl(error, url, seen = /* @__PURE__ */ new Map()) {
+	if (typeof error === "string") return redactUrlIn(error, url);
+	if (typeof error !== "object" || error === null) return error;
+	if (seen.has(error)) return seen.get(error);
 	const fields = error;
+	let safe = error;
+	const changes = /* @__PURE__ */ new Map();
 	for (const key of /* @__PURE__ */ new Set([
 		"message",
 		"stack",
@@ -474,15 +561,32 @@ function redactErrorUrl(error, url, seen = /* @__PURE__ */ new Set()) {
 		if (typeof value !== "string") continue;
 		const redacted = redactUrlIn(value, url);
 		if (redacted === value) continue;
-		try {
+		changes.set(key, redacted);
+		if (safe === error) try {
 			Object.defineProperty(error, key, { value: redacted });
-		} catch {}
+		} catch {
+			safe = copyError(error);
+		}
+	}
+	seen.set(error, safe);
+	if (safe !== error) for (const [key, value] of changes) Object.defineProperty(safe, key, {
+		value,
+		configurable: true
+	});
+	const cause = fields.cause;
+	const safeCause = redactErrorUrl(cause, url, seen);
+	if (safeCause !== cause) try {
+		Object.defineProperty(safe, "cause", { value: safeCause });
+	} catch {
+		safe = copyError(safe);
+		Object.defineProperty(safe, "cause", { value: safeCause });
+		seen.set(error, safe);
 	}
-	redactErrorUrl(fields.cause, url, seen);
+	return safe;
 }
 function networkError(cause, requestContext) {
-	redactErrorUrl(cause, requestContext.url);
-	const reason = cause instanceof Error && cause.message ? cause.message : "network error";
+	const safeCause = redactErrorUrl(cause, requestContext.url);
+	const reason = safeCause instanceof Error && safeCause.message ? safeCause.message : "network error";
 	const hint = isReadableStream(requestContext.init.body) ? STREAM_BODY_HINT : "";
 	return new ArthronError({
 		message: `${describeRequest(requestContext)} failed: ${reason}${hint}`,
@@ -491,8 +595,8 @@ function networkError(cause, requestContext) {
 		headers: new Headers(),
 		payload: void 0,
 		requestContext,
-		cause
+		cause: safeCause
 	});
 }
 //#endregion
-export { withoutSecrets as C, resolveUrl as S, leavesBase as _, responseError as a, redactUrl as b, isReadableStream as c, tagOf as d, ArthronError as f, httpOrigins as g, httpOrigin as h, redactErrorUrl as i, runtimeStreamsRequestBody as l, fillPath as m, isCancellation as n, rebuildResponse as o, isArthronError as p, networkError as r, withFields as s, cancellationError as t, serializeBody as u, originOf as v, redactUrlIn as x, originSet as y };
+export { redactUrlIn as C, redactUrl as S, withoutSecrets as T, httpOrigin as _, redactErrorUrl as a, originOf as b, rebuildResponse as c, runtimeStreamsRequestBody as d, serializeBody as f, fillPath as g, isArthronError as h, networkError as i, withFields as l, ArthronError as m, isCancellation as n, responseError as o, tagOf as p, isTimeout as r, createResponse as s, cancellationError as t, isReadableStream as u, httpOrigins as v, resolveUrl as w, originSet as x, leavesBase as y };

package/llms.txt

@@ -30,13 +30,13 @@ api.request(path, { method, body?, ...requestOptions })   // method: HttpMethod
 // 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:
+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); 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 event the stream ends inside (spec).
+- `.sse()`/`.ndjson()`: leaving the loop early cancels the body. `.sse()` drops an incomplete event at the end of the stream (spec).
 
 ## Errors
 
@@ -57,8 +57,8 @@ class ArthronError extends Error {
 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(response)` (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.
+- 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
@@ -76,7 +76,7 @@ type RequestContext = { url: string; init: Omit<RequestInit, "headers"> & { head
 // 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(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).
+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(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.
 
@@ -85,9 +85,9 @@ Order: `middleware[0]( middleware[1]( attempt: request interceptors → fetch
 ## Built-in plugins (from "arthron/plugins")
 
 - `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 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; so is an object second argument (the 1.x `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: 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; a relative URL is on the page's origin). `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? })` — start/success/error lines or structured events `{ phase, method, url /* query and userinfo removed */, status?, duration? /* ms, retries included */, error? }`. Does not log cancellations.
+- `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

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "arthron",
-  "version": "2.0.1",
+  "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,6 +62,9 @@
     "check:types-pkg": "attw --pack .",
     "check:types-consumer": "node test/types-consumer/check.mjs",
     "check:browsers": "pnpm --dir test/browser test",
+    "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"
   },