arthron 1.0.1 → 1.2.0

package/README.md

@@ -3,18 +3,19 @@
 A `fetch` client you assemble from plugins.
 
 ```ts
-import { arthron, logging, retry, timeout } from "arthron";
+import { arthron } from "arthron";
+import { logging, retry, timeout } from "arthron/plugins";
 
 const api = arthron({
   baseURL: "https://api.example.com",
-  use: [logging(), timeout(10_000), retry()],
+  use: [logging(), timeout(10_000), retry()], // 10 s for the whole call, retries included
 });
 
 const user = await api.get("/me").json<User>();
 ```
 
 - **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.
+- **A plugin holds middleware and interceptors, kept apart by the types.** Middleware wraps the call and controls the flow — it can call `next` again to retry, or not at all. Interceptors transform one value and return it; they cannot retry, skip, or swallow. Retry, timeouts, logging, auth refresh, 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 plugin can use both: `bearerAuth` sets the header in an interceptor and refreshes in middleware.
 - **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, for TypeScript 5.0+. Node 22+ and browsers.
 
@@ -118,15 +119,15 @@ A request that is aborted or times out rejects with the abort reason — `AbortE
 
 ### Derive clients
 
-Clients are immutable. `use` and `extend` return a new client and leave the original alone.
+Clients are immutable. `use`, `extend` and `without` return a new client and leave the original alone — so keep what they return. `api.use(plugin)` on its own line does nothing.
 
 ```ts
 const base = arthron({ baseURL: API, use: [logging(), retry()] });
-const authed = base.use(auth()); // base + auth
+const authed = base.use(bearerAuth({ origin: API, token })); // base + auth
 const admin = authed.extend({ headers: { "x-role": "admin" } }); // authed + header
 ```
 
-`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`.
+`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 `bearerAuth`, `logging`, `retry`, `timeout` and `uploadProgress`.
 
 ## Plugins
 
@@ -145,18 +146,22 @@ type RequestContext = {
   url: string;
   init: Omit<RequestInit, "headers"> & { headers: Record<string, string> }; // lowercase names
   meta: ArthronMeta; // per-call plugin settings, never sent
+  fetch?: typeof fetch; // the fetch this attempt is sent with — replace it to change the transport, wrap it to observe
 };
 ```
 
-How one request runs:
+How one request runs, with `use: [m1, m2]`:
 
 ```
-middleware 1
-  middleware 2
-    attempt ─ request interceptors → fetch → response interceptors
-                                           ↘ error interceptors → throw
+call → m1 (before next) → m2 (before next) ─┐
+                                             │  attempt — runs again each time a middleware calls next again
+                                             │  request interceptors → fetch → response interceptors
+                                             │                              ↘ error interceptors → throw
+call ← m1 (after next)  ← m2 (after next)  ←─┘
 ```
 
+A middleware is called once. `await next(ctx)` runs everything inside it and resumes the same call with the result — or the error, to `catch`. Request interceptors are not the outermost layer, as axios users may expect: they run inside every middleware, on every attempt. That is why a retry sends a refreshed token or a new trace id without extra code, and why a `timeout` also bounds a slow interceptor.
+
 | | Middleware | Interceptor |
 |---|---|---|
 | Runs | Once per call, wrapping everything below | Once per attempt |
@@ -169,6 +174,30 @@ Every attempt starts from a fresh copy of the context, so a header set by an int
 
 ### Built in
 
+The built-in plugins come from `arthron/plugins`: `import { bearerAuth, logging, retry, timeout, uploadProgress } from "arthron/plugins"`. They are plain plugins — anything they do, yours can. `logging`, `retry` and `timeout` are also exported from `arthron` itself, as they were in 1.0; those exports are deprecated and go in the next major.
+
+| plugin | slots | per call |
+|---|---|---|
+| `bearerAuth` | request interceptor (the header) + middleware (refresh on 401) | `meta: { bearerAuth: false }` |
+| `retry` | middleware | `meta: { retry: false \| options }` |
+| `timeout` | middleware | `meta: { timeout: ms }` |
+| `logging` | middleware | — |
+| `uploadProgress` | request interceptor (picks the transport) | `meta: { onUploadProgress }` — only calls that pass it |
+
+Order is meaning: the first plugin is outermost. A good default:
+
+```ts
+use: [logging(), bearerAuth(…), timeout(10_000), retry()]
+```
+
+`logging` first logs each call once — its start, and its end with the total time, retries included. A `timeout` before `retry` bounds the whole call; after it, each attempt — and a timed-out attempt is not retried. `bearerAuth` sets its header on every attempt wherever it sits. Anything that should see only the final outcome — an error page, mapping to domain errors — goes before `retry`.
+
+Plugins with the same name replace each other, so a second `timeout()` takes the first one's place instead of adding a deadline. For both a total and a per-attempt deadline, rename one:
+
+```ts
+use: [{ ...timeout(30_000), name: "callTimeout" }, retry(), timeout(10_000)] // 30 s in all, 10 s per attempt
+```
+
 #### `retry(options)`
 
 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.
@@ -187,11 +216,13 @@ Honours `Retry-After` (seconds or HTTP date). Never retries a `ReadableStream` b
 
 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? })`
+#### `timeout(ms)` / `timeout({ total?, 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 })`.
+A total deadline also cuts off a stream that is still flowing. For streams, bound the silence instead: `timeout({ 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({ total: 600_000, idle: 30_000 })`; `timeout(ms)` is `timeout({ total: ms })`. Options with neither are a `TypeError`.
+
+`timeout(ms, { idle })` still works but is deprecated; it goes in the next major.
 
 ```ts
 arthron({ use: [retry(), timeout(5_000)] }); // 5 s per attempt — a timed-out attempt is not retried
@@ -214,54 +245,93 @@ arthron({ use: [timeout(5_000), retry()] }); // 5 s for all attempts together
 
 Query strings and `user:pass@` are never printed. Cancellations are not logged.
 
+#### `bearerAuth(options)`
+
+Bearer tokens, with a refresh on 401.
+
+```ts
+const api = arthron({
+  baseURL: API,
+  use: [
+    bearerAuth({
+      origin: API,
+      token: () => session.accessToken,
+      refresh: async () => {
+        const res = await api.post("/token/refresh", undefined, { meta: { bearerAuth: false } }).json<{ access_token: string }>();
+        session.accessToken = res.access_token;
+      },
+    }),
+  ],
+});
+```
+
+| option | default | |
+|---|---|---|
+| `origin` | required | a URL or several; only their origins count, so `baseURL` works as is. Anything that is not an http(s) URL is a `TypeError` |
+| `token` | required | `() => string \| null \| undefined`, or a promise of one; read on every attempt. No token, no header |
+| `refresh` | — | `() => Promise<void>`, called after a 401; then the call is redone once. Without it, a 401 is thrown as is |
+
+The token goes to `origin` only — never to a CDN or a URL taken from a response body. Concurrent 401s share one refresh: with refresh-token rotation, parallel refreshes would revoke each other and log the user out. A call whose token was already replaced by another call's refresh retries without refreshing again. A second 401 is thrown, and so is a failed refresh — every call waiting on it rejects with the error `refresh` threw, so that is the place to send the user to a login page. The 401 of a `ReadableStream` body is thrown without a refresh: the first try has read the stream, so there is nothing to resend.
+
+Per call, `meta: { bearerAuth: false }` sends no token and never refreshes. Use it for the login and refresh endpoints: a refresh request that went through `bearerAuth()` would, on its own 401, wait for itself.
+
+The token is treated as opaque: to refresh a JWT ahead of its `exp`, do it inside `token()`. It is not for cookie sessions: it tells whether another call already refreshed by comparing the `authorization` header a call sent with the current one, and an httpOnly cookie cannot be read to compare.
+
+#### `uploadProgress()`
+
+Does nothing by itself — only a call that passes `meta.onUploadProgress` reports progress. Every other call, on the same client too, goes out exactly as before.
+
+```ts
+const api = arthron({ baseURL: API, use: [retry(), uploadProgress()] }); // last in use
+
+await api.get("/me"); // as usual
+await api.post("/files", file, {
+  meta: { onUploadProgress: ({ loaded, total, progress }) => setBar(progress) }, // this call only
+});
+```
+
+The event: `loaded` (bytes sent), `total` (bytes in the body, `undefined` when unknown — a stream without `content-length`), `progress` (`loaded / total` from 0 to 1, `undefined` with `total`). Progress counts what was handed to the network, so it reaches 1 a moment before the server has it all; the response arriving is the end. Each attempt counts from 0 again, so a retried upload starts the bar over.
+
+How that call is sent depends on where it runs:
+
+- **Browser:** over `XMLHttpRequest`, the only browser API that reports upload progress. On another origin, the upload listener makes every such call send a CORS preflight — an S3 bucket's CORS rules must allow the method and headers. The response arrives whole: `.sse()` / `.ndjson()` are not live on that call. What XHR cannot honour and would change the call is refused with a `TypeError` before sending: `redirect: "manual" | "error"`, `mode: "no-cors"`, and `credentials: "omit"` to the page's own origin (XHR always sends its cookies there). What only tunes fetch — `cache`, `priority`, `referrerPolicy`, `integrity`, `keepalive` — is ignored on that call. A `ReadableStream` body is sent as usual, without progress.
+- **Node:** with `fetch` as usual, the body counted as it is read, in steps of at most 64 KiB. `content-length` and the content type a `Blob` would set are kept, so an S3 presigned `PUT` accepts it. A `FormData` body is encoded with its length known up front, its files streamed rather than read into memory. jsdom on Node counts the same way.
+- **Anywhere else** — Deno, Bun, Cloudflare Workers, an Electron main process, a service worker — and on a client with an injected `fetch` or another plugin's transport: sent as usual, without progress.
+
+A callback that throws fails the call with its own error, untouched: not an `ArthronError`, not retried. Put `uploadProgress()` last in `use`: a request interceptor after it that replaces `init.signal` would cut that path, and the error would come back as a network failure.
+
 ### Write your own
 
 `definePlugin`, `defineMiddleware` and `defineInterceptor.{request,response,error}` are identity functions that give you the parameter types without annotations.
 
+**`return await next(ctx)` inside `try`.** Without `await`, the promise is returned before it settles, and the `catch` never sees its error.
+
+**Per attempt or per call.** A request interceptor runs on every attempt, so it fits a value that must be fresh each time: a token, a signature with a timestamp, a span id. A value that must be the same on every attempt — an idempotency key, so the server can tell a retry from a second payment — is set once, by a middleware placed before `retry()`:
+
+```ts
+const idempotent = defineMiddleware((ctx, next) =>
+  next({ ...ctx, init: { ...ctx.init, headers: { ...ctx.init.headers, "idempotency-key": crypto.randomUUID() } } }),
+);
+// A client of its own, so the order is exactly this: the key first, then retry.
+const payments = arthron({ baseURL: API, use: [{ name: "idempotency", middleware: idempotent }, retry({ methods: ["POST"] })] });
+```
+
+(`api.use(…)` would not do here if `api` already has a `retry()`: the new one takes the old one's place, which may be before the key.)
+
 **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;
+    skipTrace?: boolean;
   }
 }
 
-api.use({ request: (ctx) => (ctx.meta.skipAuth ? ctx : withToken(ctx)) });
-api.get("/health", { meta: { skipAuth: true } });
+const traced = api.use({ request: (ctx) => (ctx.meta.skipTrace ? ctx : withTraceId(ctx)) });
+traced.get("/health", { meta: { skipTrace: true } });
 ```
 
-**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 = (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 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;
-        // 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);
-      }
-    },
-  });
-};
-```
+**Refresh a session on 401, then redo the request.** That is the built-in [`bearerAuth()`](#bearerauthoptions), and a model for your own: 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 redone request carries the new token without extra code. Read [`src/plugins/bearer-auth/bearer-auth.ts`](src/plugins/bearer-auth/bearer-auth.ts) before writing a variant for another scheme.
 
 **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).
 
@@ -292,7 +362,7 @@ The same shape maps errors to your own types: `catch (e) { throw toDomainError(e
 **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() } } }) });
+const traced = api.use({ request: (ctx) => ({ ...ctx, init: { ...ctx.init, headers: { ...ctx.init.headers, "x-trace-id": crypto.randomUUID() } } }) });
 ```
 
 ## Reference
@@ -303,7 +373,7 @@ api.use({ request: (ctx) => ({ ...ctx, init: { ...ctx.init, headers: { ...ctx.in
 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)
+  headers?: HeadersOption; // anything fetch's headers take, or a record whose 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
@@ -363,7 +433,7 @@ class ArthronError extends Error {
 
 - `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.
+- `examples/` holds type-checked, runnable recipes: LLM streaming, auth refresh, an error page, upload/download. `examples/recipes.test.ts` keeps the error-page recipe honest.
 - Error messages state the fix (`… — pass baseURL in arthron({ baseURL }) or use an absolute URL`).
 
 ## Security

package/dist/index-C3lylSNd.d.cts

@@ -0,0 +1,333 @@
+//#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