@gcmdev/faxios 0.1.0 → 0.2.1

package/skills/configure-requests/SKILL.md

@@ -0,0 +1,380 @@
+---
+name: configure-requests
+description: >
+  Use when writing, reviewing or porting code that sends HTTP requests with @gcmdev/faxios:
+  creating an instance with baseURL, headers or timeout; cancelling requests; handling
+  FaxiosError codes; validating responses with a schema; adding auth, retry or timing with
+  .use() middleware and the built-in plugins; or replacing Axios interceptors, CancelToken,
+  adapters or proxy options. Not for Axios itself or for other fetch wrappers.
+metadata:
+  purpose: >
+    Teach agents the request surface faxios actually implements (one fetch transport, .use()
+    middleware, AbortSignal cancellation, Standard Schema validation) and stop them from
+    generating Axios APIs that faxios removed or never verified.
+  type: core
+  library: '@gcmdev/faxios'
+  library_version: '0.2.1'
+sources:
+  - src/index.ts
+  - src/lib/faxios.ts
+  - src/lib/core/Faxios.ts
+  - src/lib/core/mergeConfig.ts
+  - src/lib/core/buildFullPath.ts
+  - src/lib/core/dispatchRequest.ts
+  - src/lib/core/FaxiosError.ts
+  - src/lib/core/define.ts
+  - src/lib/core/route.ts
+  - src/lib/types.ts
+  - src/lib/adapters/fetch.ts
+  - src/lib/helpers/composeSignals.ts
+  - src/lib/plugins/definePlugin.ts
+  - src/lib/plugins/authBearer.ts
+  - src/lib/plugins/retry.ts
+  - src/lib/plugins/timing.ts
+  - package.json
+  - adrianbrowning/faxios:packages/tests/unit/api.test.ts
+  - adrianbrowning/faxios:packages/tests/unit/core/middleware.test.ts
+  - adrianbrowning/faxios:packages/tests/unit/plugins/*.test.ts
+  - adrianbrowning/faxios:MIGRATION_GUIDE.md
+---
+
+# Configure faxios requests
+
+faxios is a promise-based HTTP client with an Axios-like call shape and one transport: the
+runtime's `fetch`. It runs in browsers, Node 24+, Deno and Bun, and ships as ESM only.
+Assume nothing from Axios that this skill or the installed package's types do not show.
+When the installed `@gcmdev/faxios` types disagree with this file, follow the types and report
+the mismatch.
+
+## Setup
+
+```ts
+import faxios from "@gcmdev/faxios";
+
+const api = faxios.create({
+  baseURL: "https://api.example.com/v1",
+  timeout: 5000,
+  headers: { common: { "X-Client": "web" } },
+});
+
+const { data, status } = await api.get<{ id: number; name: string }>("/users/1");
+```
+
+- Install with `npm i @gcmdev/faxios`. From CommonJS, load it with `await import("@gcmdev/faxios")`;
+  there is no `require` build and no UMD/CDN bundle.
+- Check: the call resolves with a `FaxiosResponse` whose `data` is parsed JSON for JSON responses.
+
+## Core patterns
+
+### Choose the right call form
+
+- `api(config)`, `api(url, config?)` and `api.request(config)`.
+- `get`, `delete`, `head`, `options` take `(url, config?)`.
+- `post`, `put`, `patch`, `query` take `(url, data?, config?)`. `query` sends the HTTP QUERY method.
+- `postForm`, `putForm`, `patchForm` send `multipart/form-data`.
+- `api.getUri(config)` builds the URL from `baseURL`, `url` and `params` without sending anything. It doesn't substitute `pathParams`, so `{key}` placeholders stay as written.
+
+Path and query parameters:
+
+```ts
+import faxios from "@gcmdev/faxios";
+
+const res = await faxios.get("https://api.example.com/users/{id}/posts", {
+  pathParams: { id: 42 },
+  params: { page: 2, tag: "news" },
+});
+// GET https://api.example.com/users/42/posts?page=2&tag=news
+```
+
+`pathParams` values are `encodeURIComponent`-encoded. A missing or `null` value rejects with
+`ERR_BAD_OPTION_VALUE`.
+
+Binary downloads need `responseType`, and a type argument because `data` is `unknown`:
+
+```ts
+import faxios from "@gcmdev/faxios";
+
+const { data } = await faxios.get<ArrayBuffer>("https://example.com/report.zip", {
+  responseType: "arraybuffer",
+  maxContentLength: 50 * 1024 * 1024, // the body is buffered; cap it for untrusted servers
+});
+console.log(data.byteLength);
+```
+
+Unset `responseType` reads the body as text, then JSON-parses it if it parses. `"text"` skips the
+JSON parse; `"blob"`, `"formdata"` and `"stream"` (a `ReadableStream`) are also supported.
+
+### Merge defaults the way faxios does
+
+`faxios.create(config)` merges `config` over the parent's defaults with `mergeConfig`:
+
+- `url`, `method` and `data` never inherit; they come from the request only.
+- `headers` deep-merge case-insensitively. Group headers by method with `common`, `get`, `post`,
+  etc. Flat keys apply to every method and win over the same key in a group. Header values must
+  be strings, numbers, string arrays, booleans, `null` or `undefined`; convert anything else with
+  `String(...)`.
+- Arrays such as `transformRequest` and `transformResponse` are replaced, not concatenated.
+- An explicit `undefined` in the request clears an inherited `baseURL`, `timeout` or schema.
+- `params`, `auth`, `env` and other plain objects deep-merge.
+- Middleware added with `.use()` is not copied into `create()` children. Register it on each
+  instance that needs it.
+
+To remove an inherited header for one request, set it to `undefined`. To keep a header off the
+wire entirely, including ones faxios adds itself, set it to `null` or `false`.
+
+### Validate and type responses with a schema
+
+Any Standard Schema v1 library works (Zod, Valibot, ArkType). Passing `responseSchema` types
+`response.data` as the schema's output:
+
+```ts
+import faxios, { isSchemaValidationError } from "@gcmdev/faxios";
+import { z } from "zod";
+
+const User = z.object({ id: z.number(), name: z.string() });
+
+try {
+  const { data } = await faxios.get("https://api.example.com/users/1", { responseSchema: User });
+  console.log(data.name);
+}
+catch (error) {
+  if (isSchemaValidationError(error)) console.error(error.code, error.issues);
+  else throw error;
+}
+```
+
+- Order: `pathParamsSchema` → `paramsSchema` → `requestSchema` run before `transformRequest`,
+  fail-fast, and nothing is sent when one fails. `responseSchema` runs after `transformResponse`,
+  only for responses that pass `validateStatus`.
+- Error codes: `ERR_BAD_PATH_PARAMS_SCHEMA`, `ERR_BAD_PARAMS_SCHEMA`, `ERR_BAD_REQUEST_SCHEMA`,
+  `ERR_BAD_RESPONSE_SCHEMA`. `error.issues` holds `{ message, path? }` entries. On
+  `ERR_BAD_RESPONSE_SCHEMA`, `error.response.data` is the body the schema rejected. Schemas run
+  inside dispatch, so middleware sees the unvalidated config before `next(ctx)`.
+- For reusable typed endpoints, use `api.define(method, url, config)` or `api.route(url, config)`
+  rather than wrapping calls by hand. They return plain functions with no `.use()`
+  (`api.define(...).use(...)` is a TypeError), so put middleware on the instance and call
+  `define()`/`route()` on the value `.use()` returned. Middleware added later still runs (the
+  endpoint calls `api.request()` each time), but only that value types plugin options.
+  `pathParams` is accepted only when `pathParamsSchema` is set.
+
+```ts
+import faxios from "@gcmdev/faxios";
+import { z } from "zod";
+
+const api = faxios
+  .create({ baseURL: "https://api.example.com" })
+  .use(async (ctx, next) => next(ctx));
+const getUser = api.define("get", "/users/{id}", {
+  pathParamsSchema: z.object({ id: z.string() }),
+  responseSchema: z.object({ name: z.string() }),
+});
+const { data } = await getUser({ pathParams: { id: "123" } });
+console.log(data.name);
+```
+
+- With a plugin such as `retry()`, see "Define endpoints on a plugin instance" in
+  [references/plugins.md](references/plugins.md).
+
+### Cancel requests and apply timeouts
+
+```ts
+import faxios, { FaxiosError, isCancel } from "@gcmdev/faxios";
+
+const controller = new AbortController();
+const request = faxios.get("https://api.example.com/search", {
+  params: { q: "faxios" },
+  signal: controller.signal,
+  timeout: 3000,
+});
+controller.abort();
+
+try {
+  await request;
+}
+catch (error) {
+  if (isCancel(error)) console.log("canceled");                         // code ERR_CANCELED
+  else if (error instanceof FaxiosError && error.code === FaxiosError.ETIMEDOUT) console.log("timed out");
+  else throw error;
+}
+```
+
+- Cancellation uses `AbortSignal` only. faxios checks the signal before middleware, before each
+  schema step and right before `fetch`, so an abort during pre-flight work sends nothing.
+- A timeout always rejects with `ETIMEDOUT`. `ECONNABORTED` is never raised, and
+  `transitional.clarifyTimeoutError` has no effect.
+
+### Handle errors by code
+
+```ts
+import faxios, { isFaxiosError } from "@gcmdev/faxios";
+
+try {
+  await faxios.get("https://api.example.com/users/404");
+}
+catch (error) {
+  if (!isFaxiosError(error)) throw error;
+  switch (error.code) {
+    case "ERR_BAD_REQUEST":  console.log("4xx", error.response?.status); break;
+    case "ERR_BAD_RESPONSE": console.log("5xx or unparsable JSON"); break;
+    case "ERR_NETWORK":      console.log("transport failed", error.cause); break;
+    default: throw error;
+  }
+}
+```
+
+- Non-2xx statuses reject because of the default `validateStatus`. Pass your own `validateStatus`
+  to change which statuses resolve.
+- Transport failures (DNS, refused connection, CORS) reject with `ERR_NETWORK`; the runtime's
+  original error is on `error.cause`. `ECONNREFUSED` is not raised as the error's own code.
+- `error.toJSON()` never includes the response; list sensitive config keys in `redact` to mask
+  them in that output.
+
+### Add behaviour with `.use()` middleware
+
+faxios has no `interceptors`. Middleware wraps each request and runs in registration order on the
+way in and in reverse on the way out:
+
+```ts
+import faxios, { FaxiosError } from "@gcmdev/faxios";
+
+const api = faxios
+  .create({ baseURL: "https://api.example.com" })
+  .use(async (ctx, next) => {
+    ctx.config.headers.set("X-Request-Id", crypto.randomUUID());
+    try {
+      return await next(ctx);
+    }
+    catch (error) {
+      if (error instanceof FaxiosError && error.response?.status === 401) console.warn("signed out");
+      throw error;
+    }
+  });
+```
+
+- Keep the value `.use()` returns; plugins that add options or capabilities type only that value.
+- Return without calling `next` to short-circuit, for example from a cache. Each `next(ctx)` call
+  dispatches a fresh copy of `ctx.config`, so calling it again retries from the same input.
+- `api.eject(sameMiddleware)` removes middleware by identity; requests in flight keep running it.
+- `ctx.config.headers` is a `FaxiosHeaders`. Mutate it with `.set()`/`.delete()`, or assign
+  another `FaxiosHeaders`; never assign a plain object.
+- `ctx.config.method` is always lower-case in middleware: compare with `"post"`, not `"POST"`.
+- Per-request scratch data goes on `ctx.state`.
+
+### Use the built-in plugins from their subpaths
+
+Each built-in plugin has its own subpath and is not exported from the root:
+`authBearer` from `@gcmdev/faxios/plugins/auth-bearer`, `retry` from
+`@gcmdev/faxios/plugins/retry`, `timing` from `@gcmdev/faxios/plugins/timing`. Install them with
+`.use()` on the instance and keep the returned value, because it is the only value typed with the
+plugin's request options (such as `retry: false`). Before writing plugin code, read
+[plugins](references/plugins.md) for a complete installation example.
+
+- `authBearer(getToken, { scheme, header, origins, overwrite })` sends the token only to the
+  `baseURL` origin when `baseURL` is absolute; otherwise only to relative request URLs. Use
+  `origins` to allow more. It leaves an explicit `Authorization` header alone unless
+  `overwrite: true`. Install `retry` before it if each attempt should call `getToken` again.
+- `retry` defaults: 3 attempts, statuses 408/429/500/502/503/504 plus `ERR_NETWORK` and
+  `ETIMEDOUT`, exponential backoff from 100 ms with full jitter. A 429/503 `Retry-After` sets the
+  wait unless `respectRetryAfter: false`. Turn that off when something else, such as a queue
+  throttle, already honours `Retry-After`.
+  Only GET, HEAD, OPTIONS, PUT, DELETE and QUERY retry; list POST or PATCH in `methods` only when
+  the API dedupes repeats. Stream bodies are never replayed. Cancellation never retries. A custom
+  `retryOn` replaces the whole default predicate (`statuses`, `ERR_NETWORK`, `ETIMEDOUT`), and a
+  `Retry-After` longer than `maxRetryAfter` (default 5 min) rejects without retrying.
+- `timing(onTiming)` reports `{ method, url, attempt?, durationMs, status | error }` with no
+  headers or body; `url` has no query string and keeps `{param}` placeholders.
+  Install it before `retry` for one event per call, after it for one event per attempt.
+- To write your own plugin, use `definePlugin` from `@gcmdev/faxios/plugins`. The same
+  [plugins](references/plugins.md) reference covers authoring.
+
+### Customise the transport through fetch, not adapters
+
+There is no `adapter` option. Supply `fetch` itself to swap the transport, for example in tests or
+custom runtimes:
+
+```ts
+import faxios from "@gcmdev/faxios";
+
+// Tests or custom runtimes: every request on this instance goes through mockFetch.
+const mockFetch: typeof fetch = async () => Response.json({ ok: true });
+const testApi = faxios.create({ env: { fetch: mockFetch } });
+const { data } = await testApi.get("https://api.example.com/feed"); // { ok: true }
+
+// Real fetch, with extra RequestInit fields for this request.
+await faxios.get("https://api.example.com/feed", { fetchOptions: { cache: "no-store" } });
+```
+
+- `fetchOptions` is spread into the init object passed to `fetch`. faxios sets `signal`, `method`,
+  `headers`, `body`, `duplex` and `credentials` itself, and those override the same keys in
+  `fetchOptions`.
+- Plain-object values inside `fetchOptions` are copied when configs merge; class instances are
+  passed by reference.
+- Proxies are runtime configuration, not a faxios option. In Node, the project docs route a
+  proxy through `fetchOptions: { dispatcher: new ProxyAgent(url) }` with the project's own
+  `undici` dependency (`packages/docs/pages/advanced/fetch-adapter.md`, `MIGRATION_GUIDE.md`).
+  faxios passes the instance through to `fetch` but does not test proxying. Browsers, Deno and Bun
+  use their platform's proxy settings.
+
+## Import boundaries
+
+| Import | Status |
+| --- | --- |
+| `@gcmdev/faxios` | Stable: default `faxios`, `Faxios`, `FaxiosError`, `FaxiosHeaders`, `CanceledError`, `isCancel`, `isFaxiosError`, `isSchemaValidationError`, `mergeConfig`, `toFormData`, `formToJSON`, `HttpStatusCode`, `all`, `create`, `VERSION`, and the types |
+| `@gcmdev/faxios/plugins` | Stable: `definePlugin` only |
+| `@gcmdev/faxios/plugins/auth-bearer`, `/retry`, `/timing` | Stable: one plugin each |
+| `@gcmdev/faxios/unsafe/*` | Internal helpers (`buildFullPath`, `buildURL`, `combineURLs`, `isAbsoluteURL`, `utils`). No stability promise; do not use them in application code, and say so if a task seems to need them |
+
+Use `faxios.create()` for instances. An instance made with `new Faxios()` has no `use()` or
+`eject()`.
+
+Statics such as `isCancel`, `mergeConfig`, `HttpStatusCode` and `spread` exist on the default
+export only. Instances from `create()` do not have them; import them by name instead.
+
+## Common mistakes
+
+1. **HIGH: Using Axios interceptors.** `api.interceptors.request.use(...)` throws because
+   `interceptors` is undefined. Use `.use(async (ctx, next) => ...)`. Axios ran request
+   interceptors last-registered-first; faxios middleware runs in registration order.
+   Source: `packages/tests/unit/api.test.ts`, `src/lib/core/Faxios.ts`.
+2. **HIGH: Passing Axios transport options.** `adapter`, `proxy`, `httpAgent`, `httpsAgent`,
+   `maxRedirects`, `socketPath`, `decompress` and `cancelToken` are not faxios options. Typed object
+   literals reject them, but untyped or spread configs pass and are silently ignored at runtime.
+   Use `fetchOptions` or `env.fetch`. Source: `src/lib/types.ts`, `MIGRATION_GUIDE.md`.
+3. **HIGH: Using `CancelToken`.** It does not exist. Use `AbortController` and `signal`.
+4. **HIGH: Checking for `ECONNABORTED` on timeout.** faxios raises `ETIMEDOUT`. Code that checks
+   `ECONNABORTED` never matches. Source: `src/lib/helpers/composeSignals.ts`.
+5. **HIGH: Sending an absolute URL through an instance with `baseURL`.** When an instance has a
+   `baseURL` and `allowAbsoluteUrls` is unset, faxios appends even an absolute request URL to the
+   base: `api.get("https://other.example/x")` requests
+   `https://api.example.com/v1/https://other.example/x`. Use a separate instance, or set
+   `allowAbsoluteUrls: true` when the absolute URL is trusted. Source:
+   `src/lib/core/Faxios.ts` (`resolveAllowAbsoluteUrls`), `src/lib/core/buildFullPath.ts`.
+6. **MEDIUM: Importing plugins from the root.** `import { retry } from "@gcmdev/faxios"` fails and
+   `faxios.plugins` is undefined. Import from `@gcmdev/faxios/plugins/<name>`.
+7. **MEDIUM: Calling statics on an instance.** `api.isCancel(e)` is undefined on a `create()`
+   instance. Use the named import.
+8. **MEDIUM: Expecting `onUploadProgress` everywhere.** It fires only where `fetch` can stream a
+   request body (`duplex: "half"`, for example Node). Browsers generally do not report upload
+   progress through fetch; do not promise it there.
+9. **MEDIUM: Retrying POST by accident or by assumption.** The retry plugin skips POST and PATCH
+   unless they are listed in `methods`; a custom `retryOn` cannot override that.
+10. **MEDIUM: Downloading a binary body without `responseType`.** The bytes are decoded as UTF-8
+    text and come back corrupted. Set `responseType: "arraybuffer"` and type the call with
+    `get<ArrayBuffer>`. Source: `src/lib/adapters/fetch.ts`.
+
+## Completion
+
+- Every import resolves to an entry in the table above; nothing imports `unsafe/*` in application
+  code.
+- No `interceptors`, `CancelToken`, `adapter`, `proxy`, `httpAgent` or `ECONNABORTED` remains.
+- Type-check the project. A type error on a config key means faxios does not support it; find the
+  faxios equivalent above instead of casting it away.
+- Exercise one success path and one failure path (an aborted signal or a non-2xx response) and
+  confirm the error code matches the handling code.
+
+## References
+
+- When porting an Axios codebase, read [Axios differences](references/axios-differences.md)
+  before changing call sites.
+- When installing `authBearer`, `retry` or `timing`, or writing a reusable plugin or typed
+  middleware, read [plugins](references/plugins.md).

package/skills/configure-requests/references/axios-differences.md

@@ -0,0 +1,67 @@
+# Axios differences
+
+Read this before porting Axios code to faxios or reviewing a port. faxios keeps Axios's call shape
+(`faxios.get(url, config)`, `response.data`, `create()`, `defaults`), but treat every Axios
+behaviour outside this list as unverified until the installed types and a test prove it.
+
+## Mapping
+
+| Axios code | faxios replacement | Notes |
+| --- | --- | --- |
+| `import axios from "axios"` | `import faxios from "@gcmdev/faxios"` | ESM only; use `await import()` from CommonJS |
+| `axios.interceptors.request.use(fn)` | `api.use(async (ctx, next) => { ...; return next(ctx); })` | Registration order, not reverse |
+| `axios.interceptors.response.use(ok, fail)` | `try { const res = await next(ctx); ...; return res } catch (e) { ... }` inside `.use()` | Non-2xx arrives as a rejection. Middleware must return a response, so an interceptor that unwraps to `response.data` can't be ported; take `data` at the call site |
+| `interceptors.request.eject(id)` | `api.eject(sameFunctionOrPlugin)` | By identity, not numeric id |
+| `interceptors.request.clear()` | `eject()` each middleware, or a fresh `create()` | No `clear()` |
+| interceptor `synchronous` / `runWhen` options | `if` inside the middleware for `runWhen` | `synchronous` has no equivalent |
+| `transitional.legacyInterceptorReqResOrdering` | remove it | Throws `ERR_BAD_OPTION` ("Unknown option"), like any unknown `transitional` key |
+| `CancelToken.source()` / `cancelToken` | `AbortController` + `signal` | `isCancel(e)` or `e.code === "ERR_CANCELED"` |
+| `axios.isAxiosError(e)` | `isFaxiosError(e)` (named import) | Type guard |
+| `error.code === "ECONNABORTED"` (timeout) | `error.code === "ETIMEDOUT"` | `clarifyTimeoutError` is inert |
+| `error.code === "ECONNREFUSED"` | `error.code === "ERR_NETWORK"`, details on `error.cause` | All transport failures |
+| `adapter: ...` / custom adapter | `env: { fetch }` or `fetchOptions` | No adapter option exists |
+| `proxy: {...}` / `httpAgent` / `httpsAgent` | Runtime-level proxy config. In Node the project docs pass an `undici` `ProxyAgent` as `fetchOptions.dispatcher`, using the app's own `undici` dependency | Not faxios options; faxios passes the dispatcher to `fetch` but does not test proxying |
+| `maxRedirects`, `beforeRedirect` | fetch follows redirects; `fetchOptions: { redirect: "manual" }` to stop | `ERR_FR_TOO_MANY_REDIRECTS` is never raised |
+| `maxRate`, `socketPath`, `decompress`, `insecureHTTPParser`, `httpVersion`, HTTP/2 options, `lookup`, `family` | none | Removed; ignored at runtime when untyped |
+| `onUploadProgress` | same option | Fires only where fetch streams request bodies (Node); not a browser guarantee |
+| `responseType: "document"` | none in practice | Falls back to text |
+| retry via `axios-retry` | `retry()` from `@gcmdev/faxios/plugins/retry` | POST/PATCH excluded by default |
+| auth header interceptor | `authBearer()` from `@gcmdev/faxios/plugins/auth-bearer` | Sends only to the baseURL origin by default |
+
+## Behaviour that changes silently
+
+These ports compile and run but behave differently:
+
+1. **Absolute URL on a `baseURL` instance.** Axios sends an absolute request URL as-is. faxios
+   appends it to the instance `baseURL` unless `allowAbsoluteUrls: true` is set on the instance or
+   request. Search ports for instance calls with `http://` or `https://` URLs.
+2. **Untyped configs with removed keys.** A config built with spread or `any` keeps `proxy`,
+   `adapter` or `httpAgent` and faxios ignores them. The request then goes direct, without the
+   proxy or agent the code expected. Delete the keys and move the behaviour to `fetchOptions`.
+3. **Interceptor order.** Axios ran request interceptors last-registered-first and response
+   interceptors first-registered-first. Middleware runs in registration order on the way in and
+   in reverse on the way out, so both sides flip; reorder the `.use()` calls.
+4. **Timeout handling.** Branches that check `ECONNABORTED` never run.
+5. **Statics on instances.** `instance.isCancel`, `instance.mergeConfig` and similar are undefined
+   on `create()` instances.
+
+## Port checklist
+
+- [ ] No `axios` import remains, and no `interceptors`, `CancelToken`, `adapter`, `proxy`,
+      `httpAgent`, `httpsAgent` or `ECONNABORTED` reference.
+- [ ] Every instance with `baseURL` is checked for absolute-URL calls.
+- [ ] Error handling branches on faxios codes: `ERR_BAD_REQUEST`, `ERR_BAD_RESPONSE`,
+      `ERR_NETWORK`, `ETIMEDOUT`, `ERR_CANCELED`, and the `ERR_BAD_*_SCHEMA` codes if schemas are
+      used.
+- [ ] The project type-checks without casts on faxios configs.
+- [ ] One success and one failure path run against the ported client.
+
+`MIGRATION_GUIDE.md` section "h) Interceptors replaced by `.use()` middleware" and the docs pages
+`advanced/middleware.md` and `advanced/migrating-from-interceptors.md` show interceptor-to-middleware
+conversions; any `interceptors` code there is the "before" side. The guide's Fetch-Only section
+still says Node 18+ and that custom adapters work through `adapter`. Both are wrong: faxios needs
+Node 24+ and has no `adapter` option.
+
+Sources: `MIGRATION_GUIDE.md` (Fetch-Only Migration), `src/lib/types.ts`, `src/lib/core/Faxios.ts`,
+`src/lib/core/buildFullPath.ts`, `src/lib/helpers/composeSignals.ts`,
+`src/lib/adapters/fetch-helpers.ts`, `packages/tests/unit/api.test.ts`.

package/skills/configure-requests/references/plugins.md

@@ -0,0 +1,127 @@
+# Plugins
+
+Read this before installing the built-in plugins (`authBearer`, `retry`, `timing`), writing a
+reusable faxios plugin, typing middleware options, or sharing a value between plugins. Plain
+one-off middleware (`api.use(async (ctx, next) => ...)`) does not need it.
+
+## Install the built-in plugins
+
+```ts
+import faxios from "@gcmdev/faxios";
+import { authBearer } from "@gcmdev/faxios/plugins/auth-bearer";
+import { retry } from "@gcmdev/faxios/plugins/retry";
+import { timing } from "@gcmdev/faxios/plugins/timing";
+
+const api = faxios
+  .create({ baseURL: "https://api.example.com" })
+  .use(timing(event => console.log(event.method, event.url, event.durationMs)))
+  .use(retry({ attempts: 3 }))
+  .use(authBearer(async () => "token-from-your-store"));
+
+await api.get("/reports", { retry: { attempts: 5 } }); // per-request override
+await api.post("/reports", { title: "Q3" });           // POST is not retried by default
+await api.get("/health", { retry: false });
+```
+
+Check: `faxios.get("/health", { retry: false })` on the default export (or any instance without
+`retry()` installed) is a type error. Use the value `.use()` returned. The option defaults and
+ordering rules are in the SKILL.md "Use the built-in plugins from their subpaths" section.
+
+## Define endpoints on a plugin instance
+
+`define()` and `route()` return plain functions with no `.use()`. Install plugins first and call
+`define()` on the value `.use()` returned, so the endpoint's per-call config types `retry`:
+
+```ts
+import faxios from "@gcmdev/faxios";
+import { retry } from "@gcmdev/faxios/plugins/retry";
+import { z } from "zod";
+
+const api = faxios.create({ baseURL: "https://tags.tiqcdn.com" }).use(retry());
+const getDistro = api.define("get", "/utag/{account}/{profile}/prod/distro.zip", {
+  pathParamsSchema: z.object({ account: z.string(), profile: z.string() }),
+});
+await getDistro({ pathParams: { account: "acme", profile: "main" }, retry: { attempts: 2 } });
+```
+
+## Build a plugin with `definePlugin`
+
+`definePlugin` comes from `@gcmdev/faxios/plugins`. It returns the same object and only changes the
+types. faxios infers the plugin's slots:
+
+- **options**: request options the plugin reads, from the first type argument of the middleware's
+  `ctx: FaxiosContext<Options, Capabilities>` annotation. They become valid keys on every
+  config-taking call of the instance `.use()` returns.
+- **requires**: capabilities that must already be installed, from the second type argument.
+- **provides**: capabilities this plugin adds to `ctx.capabilities`, from the `provides` value.
+
+```ts
+import faxios, { type FaxiosContext } from "@gcmdev/faxios";
+import { definePlugin } from "@gcmdev/faxios/plugins";
+
+type TraceOptions = { trace?: string | false };
+
+export function traceHeader(header = "X-Trace-Id") {
+  return definePlugin({
+    name: "traceHeader",
+    middleware: async (ctx: FaxiosContext<TraceOptions>, next) => {
+      const trace = ctx.config.trace;
+      if (trace !== false) ctx.config.headers.set(header, trace ?? crypto.randomUUID());
+      return next(ctx);
+    },
+  });
+}
+
+const api = faxios.create({ baseURL: "https://api.example.com" }).use(traceHeader());
+await api.get("/orders", { trace: "abc-123" }); // `trace` type-checks only on `api`
+```
+
+Check: `faxios.get("/orders", { trace: "x" })` on an instance without the plugin is a type error.
+
+## Require a capability from another plugin
+
+`authBearer` provides `{ auth: { getToken(): Promise<string> } }`, exported as
+`AuthBearerCapability`. A plugin that needs it declares it in its context type, and `.use()` rejects
+installing it before `authBearer`:
+
+```ts
+import faxios, { FaxiosError, type FaxiosContext } from "@gcmdev/faxios";
+import { definePlugin } from "@gcmdev/faxios/plugins";
+import { authBearer, type AuthBearerCapability } from "@gcmdev/faxios/plugins/auth-bearer";
+
+function refreshOn401(refresh: () => Promise<void>) {
+  return definePlugin({
+    name: "refreshOn401",
+    middleware: async (ctx: FaxiosContext<unknown, AuthBearerCapability>, next) => {
+      try {
+        return await next(ctx);
+      }
+      catch (error) {
+        if (!(error instanceof FaxiosError) || error.response?.status !== 401) throw error;
+        await refresh();
+        ctx.config.headers.set("Authorization", `Bearer ${await ctx.capabilities.auth.getToken()}`);
+        return next(ctx);
+      }
+    },
+  });
+}
+
+let token = "old";
+const api = faxios
+  .create({ baseURL: "https://api.example.com" })
+  .use(authBearer(() => token))
+  .use(refreshOn401(async () => { token = "new"; }));
+```
+
+## Rules `.use()` enforces at runtime
+
+- `name` must be a non-empty own string, otherwise `ERR_BAD_OPTION_VALUE`.
+- Two plugins on one instance cannot provide the same capability name (`ERR_BAD_OPTION`).
+- Built-in plugin options are validated strictly: unknown or mistyped keys throw
+  `ERR_BAD_OPTION` / `ERR_BAD_OPTION_VALUE` when the plugin is created or when a per-request
+  override is read.
+- `create()` children do not inherit middleware or plugins.
+
+Sources: `src/lib/plugins/definePlugin.ts`, `src/lib/types.ts` (`FaxiosContext`, `FaxiosPlugin`),
+`src/lib/core/Faxios.ts` (`use`), `packages/tests/unit/plugins/authBearer.test.ts`,
+`packages/tests/unit/plugins/definePlugin.test.ts`.

package/src/index.ts

@@ -0,0 +1,57 @@
+// @ts-self-types="./index.d.ts"
+/* eslint-disable no-barrel-files/no-barrel-files */
+import faxios from "./lib/faxios.ts";
+import type { FaxiosInstance, FaxiosStatic } from "./lib/faxios.ts";
+import type { CreateFaxiosDefaults } from "./lib/types.ts";
+
+// Static re-exports so the emitted .d.ts references source modules.
+// zshy rewrites .ts -> .js for static import/export, but NOT for inline
+// import() type expressions (ImportTypeNode). Destructuring these off the
+// runtime instance forced TS to emit the broken inline `import("./x.ts")` form.
+export { default as Faxios } from "./lib/core/Faxios.ts";
+export { default as FaxiosError, isSchemaValidationError } from "./lib/core/FaxiosError.ts";
+export type { SchemaValidationError } from "./lib/core/FaxiosError.ts";
+export { default as CanceledError, default as Cancel } from "./lib/cancel/CanceledError.ts";
+export { default as isCancel } from "./lib/cancel/isCancel.ts";
+export { default as isFaxiosError } from "./lib/helpers/isFaxiosError.ts";
+export { default as toFormData } from "./lib/helpers/toFormData.ts";
+export { default as FaxiosHeaders } from "./lib/core/FaxiosHeaders.ts";
+export { default as HttpStatusCode } from "./lib/helpers/HttpStatusCode.ts";
+export { default as mergeConfig } from "./lib/core/mergeConfig.ts";
+export { VERSION } from "./lib/env/data.ts";
+
+export type { FaxiosInstance, FaxiosStatic } from "./lib/faxios.ts";
+export type { StandardSchemaV1 } from "./lib/types/standard-schema.ts";
+export type { BasePerCallConfig, DefineConfig, DefinedEndpoint, FaxiosLike, PerCallConfig } from "./lib/core/define.ts";
+export type { RouteConfig, RouteMethodConfig, RouteBuilder } from "./lib/core/route.ts";
+
+export type {
+  FaxiosRequestConfig,
+  InternalFaxiosRequestConfig,
+  FaxiosResponse,
+  FaxiosRequestHeaders,
+  FaxiosResponseHeadersLike,
+  FaxiosHeaderValue,
+  Method,
+  ResponseType,
+  GenericHTMLFormElement,
+  RawFaxiosRequestConfig,
+  FaxiosPromise,
+  CreateFaxiosDefaults,
+  FaxiosConfigHeaders,
+  RawFaxiosRequestHeaders,
+  HeadersDefaults,
+  FaxiosContext,
+  FaxiosNext,
+  FaxiosMiddleware,
+  FaxiosPlugin
+} from "./lib/types.ts";
+
+// Instance-synthesized members (no 1:1 source module). Types are self-contained
+// (all/formToJSON) or annotated with statically imported types (create), so no
+// inline import() is emitted. Runtime values are the same references as on the instance.
+export const all: FaxiosStatic["all"] = faxios.all;
+export const formToJSON: FaxiosStatic["formToJSON"] = faxios.formToJSON;
+export const create: (instanceConfig?: CreateFaxiosDefaults) => FaxiosInstance = faxios.create;
+
+export { faxios as default };