tanstack-fetch 1.0.0 → 1.0.2

package/README.md

@@ -1,8 +1,13 @@
 # tanstack-fetch
 
-Typed `fetch` client shaped for **TanStack Query**.
+Typed `fetch` client shaped for **TanStack Query** — tiny HTTP core, optional SSE / React.
 
-`queryFn` / `mutationFn` ready by default: returns **data**, throws **`FetchError`**, passes **`signal`**. Works in browser, SSR, and Edge — with SSE, named interceptors, and OpenAPI codegen.
+| Import | What you get | Typical gzip |
+| --- | --- | --- |
+| `tanstack-fetch` | HTTP only (`get/post/…`) | **~3.5KB** |
+| `tanstack-fetch/sse` | + `api.sse()` | **~4.7KB** |
+| `tanstack-fetch/plugins` | plugin factories | **~0.9KB** |
+| `tanstack-fetch/react` | `FetchProvider` / hooks (peer: core) | **~1KB** |
 
 ```bash
 npm install tanstack-fetch
@@ -14,6 +19,24 @@ Node 18+ (native `fetch`).
 
 ---
 
+## Bundle size
+
+Tree-shake by importing only what you need:
+
+```ts
+// smallest — HTTP for TanStack Query
+import { createFetch } from 'tanstack-fetch'
+
+// only when you need streams
+import { createFetch } from 'tanstack-fetch/sse'
+```
+
+`yaml` is an **optional** peer (CLI YAML specs only). React is optional too.
+
+Run `npm run size` after build to print local gzip numbers.
+
+---
+
 ## Two ways to configure
 
 ### 1) Simple path — `baseUrl`, token, status handlers
@@ -451,6 +474,87 @@ await api.request<User>('GET', '/users/:id', { params: { id: '1' } })
 
 ---
 
+## Upload
+
+`FormData` / `Blob` / `File` are sent as-is (no JSON, no forced `Content-Type` — the boundary stays correct).
+
+The call still returns the **typed response body** from the server (same as `post`), not a special upload envelope.
+
+### `api.upload()` — file + fields + progress
+
+```ts
+type UploadResponse = { id: string; url: string }
+
+const file = input.files[0]
+
+const uploaded = await api.upload<UploadResponse>('/files', {
+  file,
+  fieldName: 'avatar', // default: 'file'
+  fields: { folder: 'avatars', public: true },
+  onUploadProgress: ({ loaded, total, progress }) => {
+    // progress is 0–1 when total is known (browser / XHR)
+    console.log(loaded, total, progress)
+  },
+})
+
+uploaded.url
+```
+
+Multiple files or raw `FormData`:
+
+```ts
+await api.upload('/docs', {
+  method: 'PUT',
+  files: [fileA, fileB],
+  fieldName: 'docs',
+})
+
+await api.upload<UploadResponse>('/files', {
+  body: createFormData({ file, note: 'cv' }),
+})
+```
+
+### `createFormData` helper
+
+```ts
+import { createFetch, createFormData } from 'tanstack-fetch'
+
+const api = createFetch({ baseUrl: 'https://api.example.com' })
+
+const body = createFormData({
+  title: 'Report',
+  tags: ['a', 'b'], // repeated field
+  file,
+})
+
+await api.post<UploadResponse>('/files', {
+  body,
+  onUploadProgress: ({ progress }) => console.log(progress),
+})
+```
+
+| Option | Notes |
+| --- | --- |
+| `file` / `files` | Appended under `fieldName` (default `"file"`) |
+| `fields` | Extra multipart values (string / number / boolean / `Blob` / arrays) |
+| `body` | Pre-built `FormData` / `Blob` / … |
+| `method` | `POST` (default), `PUT`, or `PATCH` |
+| `onUploadProgress` | Browser-only — uses XHR under the hood (`fetch` has no upload progress). No-ops on runtimes without `XMLHttpRequest` (falls back to `fetch`) |
+
+Works with TanStack Query mutations the same way as `post`:
+
+```ts
+useMutation({
+  mutationFn: (file: File) =>
+    api.upload<UploadResponse>('/files', {
+      file,
+      onUploadProgress: ({ progress }) => setProgress(progress ?? 0),
+    }),
+})
+```
+
+---
+
 ## `FetchError`
 
 ```ts
@@ -555,6 +659,8 @@ await api.post('/orders', { body: { sku: 'A' } }) // not retried
 ### `sse-resume`
 
 ```ts
+import { createFetch } from 'tanstack-fetch/sse'
+
 const api = createFetch({
   baseUrl: 'https://api.example.com',
   plugins: ['sse-resume'],
@@ -703,6 +809,13 @@ Uses `fetch` streams (not `EventSource`) — Authorization, cookies, and SSR wor
 ### Simple — `onMessage`
 
 ```ts
+import { createFetch } from 'tanstack-fetch/sse'
+
+const api = createFetch({
+  baseUrl: 'https://api.example.com',
+  plugins: ['sse-resume'],
+})
+
 const stream = api.sse<OrderEvent>('/orders/stream', {
   onMessage: (data) => {
     console.log(data) // just the payload
@@ -716,8 +829,22 @@ stream.close()
 
 ### React — `useSse`
 
+Pass a client created from `tanstack-fetch/sse`:
+
 ```tsx
-import { useSse } from 'tanstack-fetch/react'
+import { createFetch } from 'tanstack-fetch/sse'
+import { FetchProvider, useSse } from 'tanstack-fetch/react'
+
+const api = createFetch({
+  baseUrl: import.meta.env.VITE_API_URL,
+  plugins: ['sse-resume'],
+})
+
+const App = () => (
+  <FetchProvider client={api}>
+    <OrdersLive />
+  </FetchProvider>
+)
 
 const OrdersLive = () => {
   const { data, isConnected, error } = useSse<OrderEvent>('/orders/stream')
@@ -734,6 +861,10 @@ const OrdersLive = () => {
 ### Advanced — `for await`
 
 ```ts
+import { createFetch } from 'tanstack-fetch/sse'
+
+const api = createFetch({ baseUrl: 'https://api.example.com' })
+
 for await (const event of api.sse<OrderEvent>('/orders/stream', { signal })) {
   event.event
   event.data

package/dist/cli.js

@@ -1,234 +1,35 @@
 #!/usr/bin/env node
-
-// src/cli/generate.ts
-import { mkdir, writeFile } from "fs/promises";
-import { join } from "path";
-
-// src/cli/schema-to-ts.ts
-var toPascal = (value) => value.replace(/[^A-Za-z0-9]+/g, " ").trim().split(" ").filter(Boolean).map((part) => part[0].toUpperCase() + part.slice(1)).join("") || "Schema";
-var toCamel = (value) => {
-  const pascal = toPascal(value);
-  return pascal[0].toLowerCase() + pascal.slice(1);
-};
-var refName = (ref) => {
-  const parts = ref.split("/");
-  return toPascal(parts[parts.length - 1] ?? "Schema");
-};
-var schemaToTs = (schema) => {
-  if (!schema) {
-    return "unknown";
-  }
-  if (schema.$ref) {
-    return refName(schema.$ref);
-  }
-  if (schema.enum && schema.enum.length > 0) {
-    return schema.enum.map((value) => JSON.stringify(value)).join(" | ");
-  }
-  const typeValue = Array.isArray(schema.type) ? schema.type[0] : schema.type;
-  if (typeValue === "string") {
-    return "string";
-  }
-  if (typeValue === "integer" || typeValue === "number") {
-    return "number";
-  }
-  if (typeValue === "boolean") {
-    return "boolean";
-  }
-  if (typeValue === "array") {
-    return `Array<${schemaToTs(schema.items)}>`;
-  }
-  if (typeValue === "object" || schema.properties) {
-    return objectToTs(schema);
-  }
-  return "unknown";
-};
-var objectToTs = (schema) => {
-  const required = new Set(schema.required ?? []);
-  const fields = Object.entries(schema.properties ?? {}).map(([key, value]) => {
-    const optional = required.has(key) ? "" : "?";
-    return `  ${key}${optional}: ${schemaToTs(value)}`;
-  });
-  if (fields.length === 0) {
-    return "Record<string, unknown>";
-  }
-  return `{
-${fields.join("\n")}
-}`;
-};
-
-// src/cli/collect-operations.ts
-var HTTP_METHODS = ["get", "post", "put", "patch", "delete"];
-var isSseOperation = (operation) => {
-  const contents = Object.values(operation.responses ?? {}).flatMap(
-    (response) => Object.keys(response.content ?? {})
-  );
-  return contents.some((type) => type.includes("event-stream"));
-};
-var collectOperations = (spec) => {
-  const operations = [];
-  Object.entries(spec.paths ?? {}).forEach(([path, methods]) => {
-    HTTP_METHODS.forEach((method) => {
-      const operation = methods?.[method];
-      if (!operation) {
-        return;
-      }
-      const tag = operation.tags?.[0] ?? "api";
-      const fallbackId = `${method}_${path}`;
-      operations.push({
-        method: method.toUpperCase(),
-        path,
-        operationId: toCamel(operation.operationId ?? fallbackId),
-        tag: toCamel(tag),
-        isSse: isSseOperation(operation),
-        parameters: operation.parameters ?? [],
-        bodySchema: operation.requestBody?.content?.["application/json"]?.schema,
-        successSchema: pickSuccessSchema(operation)
-      });
-    });
-  });
-  return operations;
-};
-var pickSuccessSchema = (operation) => {
-  const success = operation.responses?.["200"] ?? operation.responses?.["201"];
-  const content = success?.content ?? {};
-  return content["application/json"]?.schema ?? content["text/event-stream"]?.schema;
-};
-
-// src/cli/generate.ts
-var generateTypesFile = (spec) => {
-  const schemas = Object.entries(spec.components?.schemas ?? {});
-  const types = schemas.map(([name, schema]) => `type ${toPascal(name)} = ${schemaToTs(schema)}`);
-  const exports = schemas.map(([name]) => toPascal(name));
-  if (exports.length === 0) {
-    return "export {}\n";
-  }
-  const body = `${types.join("\n\n")}
-
-export type { ${exports.join(", ")} }
-`;
-  return body.trimStart();
-};
-var paramsType = (operation, kind) => {
-  const params = operation.parameters.filter((item) => item.in === kind);
-  if (params.length === 0) {
-    return void 0;
-  }
-  const fields = params.map((item) => {
-    const optional = item.required ? "" : "?";
-    return `${item.name}${optional}: ${schemaToTs(item.schema)}`;
-  });
-  return `{ ${fields.join("; ")} }`;
-};
-var optionsType = (operation) => {
-  const fields = [];
-  const pathType = paramsType(operation, "path");
-  const queryType = paramsType(operation, "query");
-  if (pathType) {
-    fields.push(`params: ${pathType}`);
-  }
-  if (queryType) {
-    fields.push(`query?: ${queryType}`);
-  }
-  if (operation.bodySchema) {
-    fields.push(`body: ${schemaToTs(operation.bodySchema)}`);
-  }
-  if (fields.length === 0) {
-    return "RequestOptions | undefined";
-  }
-  return `Omit<RequestOptions, 'params' | 'query' | 'body'> & { ${fields.join("; ")} }`;
-};
-var clientPath = (path) => path.replace(/\{([A-Za-z0-9_]+)\}/g, ":$1");
-var methodLine = (operation) => {
-  const response = schemaToTs(operation.successSchema);
-  const options = optionsType(operation);
-  const optional = options.endsWith("| undefined") ? "?" : "";
-  if (operation.isSse) {
-    return `    ${operation.operationId}: (options${optional}: ${options}) => api.sse<${response}>('${clientPath(operation.path)}', options),`;
-  }
-  const method = operation.method.toLowerCase();
-  const call = method === "delete" ? "delete" : method;
-  return `    ${operation.operationId}: (options${optional}: ${options}) => api.${call}<${response}>('${clientPath(operation.path)}', options),`;
-};
-var generateClientFile = (spec, operations) => {
-  const tags = [...new Set(operations.map((item) => item.tag))];
-  const groups = tags.map((tag) => {
-    const lines = operations.filter((item) => item.tag === tag).map(methodLine);
-    return `    ${tag}: {
-${lines.join("\n")}
-    },`;
-  });
-  const schemaNames = Object.keys(spec.components?.schemas ?? {}).map((name) => toPascal(name));
-  const typesImport = schemaNames.length > 0 ? `import type { ${schemaNames.join(", ")} } from './types'
-` : "";
-  return `import { createFetch } from 'tanstack-fetch'
-import type { CreateFetchOptions, RequestOptions } from 'tanstack-fetch'
-${typesImport}
+import{mkdir as T,writeFile as f}from"fs/promises";import{join as h}from"path";var i=e=>e.replace(/[^A-Za-z0-9]+/g," ").trim().split(" ").filter(Boolean).map(t=>t[0].toUpperCase()+t.slice(1)).join("")||"Schema",u=e=>{let t=i(e);return t[0].toLowerCase()+t.slice(1)},k=e=>{let t=e.split("/");return i(t[t.length-1]??"Schema")},p=e=>{if(!e)return"unknown";if(e.$ref)return k(e.$ref);if(e.enum&&e.enum.length>0)return e.enum.map(n=>JSON.stringify(n)).join(" | ");let t=Array.isArray(e.type)?e.type[0]:e.type;return t==="string"?"string":t==="integer"||t==="number"?"number":t==="boolean"?"boolean":t==="array"?`Array<${p(e.items)}>`:t==="object"||e.properties?C(e):"unknown"},C=e=>{let t=new Set(e.required??[]),n=Object.entries(e.properties??{}).map(([r,s])=>{let o=t.has(r)?"":"?";return`  ${r}${o}: ${p(s)}`});return n.length===0?"Record<string, unknown>":`{
+${n.join(`
+`)}
+}`};var j=["get","post","put","patch","delete"],b=e=>Object.values(e.responses??{}).flatMap(n=>Object.keys(n.content??{})).some(n=>n.includes("event-stream")),d=e=>{let t=[];return Object.entries(e.paths??{}).forEach(([n,r])=>{j.forEach(s=>{let o=r?.[s];if(!o)return;let a=o.tags?.[0]??"api",m=`${s}_${n}`;t.push({method:s.toUpperCase(),path:n,operationId:u(o.operationId??m),tag:u(a),isSse:b(o),parameters:o.parameters??[],bodySchema:o.requestBody?.content?.["application/json"]?.schema,successSchema:x(o)})})}),t},x=e=>{let n=(e.responses?.["200"]??e.responses?.["201"])?.content??{};return n["application/json"]?.schema??n["text/event-stream"]?.schema};var q=e=>{let t=Object.entries(e.components?.schemas??{}),n=t.map(([o,a])=>`type ${i(o)} = ${p(a)}`),r=t.map(([o])=>i(o));return r.length===0?`export {}
+`:`${n.join(`
+
+`)}
+
+export type { ${r.join(", ")} }
+`.trimStart()},g=(e,t)=>{let n=e.parameters.filter(s=>s.in===t);return n.length===0?void 0:`{ ${n.map(s=>{let o=s.required?"":"?";return`${s.name}${o}: ${p(s.schema)}`}).join("; ")} }`},F=e=>{let t=[],n=g(e,"path"),r=g(e,"query");return n&&t.push(`params: ${n}`),r&&t.push(`query?: ${r}`),e.bodySchema&&t.push(`body: ${p(e.bodySchema)}`),t.length===0?"RequestOptions | undefined":`Omit<RequestOptions, 'params' | 'query' | 'body'> & { ${t.join("; ")} }`},y=e=>e.replace(/\{([A-Za-z0-9_]+)\}/g,":$1"),I=e=>{let t=p(e.successSchema),n=F(e),r=n.endsWith("| undefined")?"?":"";if(e.isSse)return`    ${e.operationId}: (options${r}: ${n}) => api.sse<${t}>('${y(e.path)}', options),`;let s=e.method.toLowerCase(),o=s==="delete"?"delete":s;return`    ${e.operationId}: (options${r}: ${n}) => api.${o}<${t}>('${y(e.path)}', options),`},E=(e,t)=>{let r=[...new Set(t.map(c=>c.tag))].map(c=>{let l=t.filter(A=>A.tag===c).map(I);return`    ${c}: {
+${l.join(`
+`)}
+    },`}),s=Object.keys(e.components?.schemas??{}).map(c=>i(c)),o=s.length>0?`import type { ${s.join(", ")} } from './types'
+`:"";return`${t.some(c=>c.isSse)?`import { createFetch } from 'tanstack-fetch/sse'
+import type { CreateFetchOptions, RequestOptions } from 'tanstack-fetch'`:`import { createFetch } from 'tanstack-fetch'
+import type { CreateFetchOptions, RequestOptions } from 'tanstack-fetch'`}
+${o}
 const createApi = (options: CreateFetchOptions = {}) => {
   const api = createFetch(options)
   return {
-${groups.join("\n")}
+${r.join(`
+`)}
   }
 }
 
 export { createApi }
-`;
-};
-var generateIndexFile = () => `import { createApi } from './client'
+`},J=()=>`import { createApi } from './client'
 
 export { createApi }
 export type * from './types'
-`;
-var generateClient = async (spec, outDir) => {
-  const operations = collectOperations(spec);
-  await mkdir(outDir, { recursive: true });
-  await writeFile(join(outDir, "types.ts"), generateTypesFile(spec), "utf8");
-  await writeFile(join(outDir, "client.ts"), generateClientFile(spec, operations), "utf8");
-  await writeFile(join(outDir, "index.ts"), generateIndexFile(), "utf8");
-};
-
-// src/cli/load-spec.ts
-import { readFile } from "fs/promises";
-import { parse as parseYaml } from "yaml";
-var loadSpec = async (specPath) => {
-  const raw = await readFile(specPath, "utf8");
-  const parsed = specPath.endsWith(".yaml") || specPath.endsWith(".yml") ? parseYaml(raw) : JSON.parse(raw);
-  if (!parsed || typeof parsed !== "object") {
-    throw new Error("tanstack-fetch: OpenAPI spec must be an object");
-  }
-  return parsed;
-};
-
-// src/cli/parse-args.ts
-var parseArgs = (argv) => {
-  const [command, ...rest] = argv;
-  if (!command || command === "--help" || command === "help" || command === "-h") {
-    return { command: "help" };
-  }
-  if (command !== "generate") {
-    throw new Error(`tanstack-fetch: unknown command "${command}"`);
-  }
-  const flags = /* @__PURE__ */ new Map();
-  for (let index = 0; index < rest.length; index += 1) {
-    const token = rest[index];
-    if (!token.startsWith("--")) {
-      continue;
-    }
-    const key = token.slice(2);
-    const value = rest[index + 1];
-    if (!value || value.startsWith("--")) {
-      throw new Error(`tanstack-fetch: missing value for --${key}`);
-    }
-    flags.set(key, value);
-    index += 1;
-  }
-  const spec = flags.get("spec");
-  const out = flags.get("out");
-  if (!spec || !out) {
-    throw new Error("tanstack-fetch: generate requires --spec and --out");
-  }
-  return { command: "generate", spec, out };
-};
-var helpText = `tanstack-fetch
+`,O=async(e,t)=>{let n=d(e);await T(t,{recursive:!0}),await f(h(t,"types.ts"),q(e),"utf8"),await f(h(t,"client.ts"),E(e,n),"utf8"),await f(h(t,"index.ts"),J(),"utf8")};import{readFile as v}from"fs/promises";var L=async e=>{try{return(await import("yaml")).parse(e)}catch{throw new Error('tanstack-fetch: install optional peer "yaml" to load YAML specs (npm i yaml)')}},$=async e=>{let t=await v(e,"utf8"),n=e.endsWith(".yaml")||e.endsWith(".yml")?await L(t):JSON.parse(t);if(!n||typeof n!="object")throw new Error("tanstack-fetch: OpenAPI spec must be an object");return n};var S=e=>{let[t,...n]=e;if(!t||t==="--help"||t==="help"||t==="-h")return{command:"help"};if(t!=="generate")throw new Error(`tanstack-fetch: unknown command "${t}"`);let r=new Map;for(let a=0;a<n.length;a+=1){let m=n[a];if(!m.startsWith("--"))continue;let c=m.slice(2),l=n[a+1];if(!l||l.startsWith("--"))throw new Error(`tanstack-fetch: missing value for --${c}`);r.set(c,l),a+=1}let s=r.get("spec"),o=r.get("out");if(!s||!o)throw new Error("tanstack-fetch: generate requires --spec and --out");return{command:"generate",spec:s,out:o}},w=`tanstack-fetch
 
 Usage:
   tanstack-fetch generate --spec ./openapi.json --out ./src/api
@@ -236,22 +37,4 @@ Usage:
 Flags:
   --spec   OpenAPI/Swagger JSON or YAML file
   --out    Directory for generated client files
-`;
-
-// src/cli/index.ts
-var runCli = async (argv = process.argv.slice(2)) => {
-  const args = parseArgs(argv);
-  if (args.command === "help") {
-    console.log(helpText);
-    return;
-  }
-  const spec = await loadSpec(args.spec);
-  await generateClient(spec, args.out);
-  console.log(`tanstack-fetch: generated client in ${args.out}`);
-};
-runCli().catch((error) => {
-  const message = error instanceof Error ? error.message : "Unknown CLI error";
-  console.error(message);
-  process.exitCode = 1;
-});
-//# sourceMappingURL=cli.js.map
+`;var P=async(e=process.argv.slice(2))=>{let t=S(e);if(t.command==="help"){console.log(w);return}let n=await $(t.spec);await O(n,t.out),console.log(`tanstack-fetch: generated client in ${t.out}`)};P().catch(e=>{let t=e instanceof Error?e.message:"Unknown CLI error";console.error(t),process.exitCode=1});

package/dist/client.type-BBYqVrTM.d.cts

@@ -0,0 +1,156 @@
+import { M as MaybePromise, C as ClientSource, I as IncomingHeaders, b as HttpInterceptor, P as PluginName, A as AuthConfig, S as StatusHandler, g as StatusHandlers, c as HttpMethod, h as PathParams, Q as QueryParams, a as FetchErrorInfo, F as FetchResult } from './config.type-eG_cuxpu.cjs';
+
+type SseEvent<T = unknown> = {
+    event?: string;
+    data: T;
+    id?: string;
+    retry?: number;
+};
+type SseSubscription = {
+    /** Stop the stream. */
+    close: () => void;
+};
+type SseHandlers<T = unknown> = {
+    /** Simple path — only the payload. */
+    onMessage?: (data: T, event: SseEvent<T>) => void;
+    /** Full SSE event (`event`, `data`, `id`). */
+    onEvent?: (event: SseEvent<T>) => void;
+    onOpen?: () => void;
+    onError?: (error: unknown) => void;
+    onClose?: () => void;
+};
+
+type UploadProgressEvent = {
+    loaded: number;
+    total?: number;
+    /** `loaded / total` when `total` is known (0–1). */
+    progress?: number;
+};
+type UploadProgressHandler = (event: UploadProgressEvent) => void;
+type FormDataPrimitive = string | number | boolean | Blob;
+type FormDataFieldValue = FormDataPrimitive | null | undefined | FormDataPrimitive[];
+type FormDataFields = Record<string, FormDataFieldValue>;
+type UploadBody = FormData | Blob | ArrayBuffer | URLSearchParams | string;
+type UploadOptions = {
+    /** Pre-built body (`FormData`, `Blob`, `File`, …). */
+    body?: UploadBody;
+    /** Single file — appended as `fieldName` (default `"file"`). */
+    file?: Blob;
+    /** Multiple files — same field name repeated. */
+    files?: Blob[];
+    /** Extra multipart fields (strings, numbers, Blobs). */
+    fields?: FormDataFields;
+    /** Form field name for `file` / `files`. Default `"file"`. */
+    fieldName?: string;
+    /** HTTP method. Default `POST`. */
+    method?: 'POST' | 'PUT' | 'PATCH';
+    onUploadProgress?: UploadProgressHandler;
+};
+
+type RequestInterceptorConfig = {
+    use?: HttpInterceptor[];
+    eject?: string[];
+};
+type RequestOptions = {
+    params?: PathParams;
+    query?: QueryParams;
+    body?: unknown;
+    headers?: HeadersInit;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    /** Default `true` — matches TanStack Query `queryFn` (throw on HTTP error). */
+    throwOnError?: boolean;
+    parseAs?: 'json' | 'text' | 'blob';
+    operation?: string;
+    interceptors?: RequestInterceptorConfig;
+    /** Browser-only — uses XHR under the hood when set (fetch has no upload progress). */
+    onUploadProgress?: UploadProgressHandler;
+};
+type CreateFetchOptions = {
+    baseUrl?: string;
+    headers?: HeadersInit | (() => MaybePromise<HeadersInit>);
+    source?: ClientSource;
+    incoming?: IncomingHeaders | (() => MaybePromise<IncomingHeaders>);
+    timeoutMs?: number;
+    /** Default `true` for TanStack Query. Set `false` to get `FetchResult`. */
+    throwOnError?: boolean;
+    interceptors?: HttpInterceptor[];
+    plugins?: PluginName[];
+    fetch?: typeof fetch;
+    credentials?: RequestCredentials;
+    maxRetries?: number;
+    /** Simple auth: attach Bearer token on every request. */
+    getToken?: () => MaybePromise<string | null | undefined>;
+    /** Advanced auth config (overrides `getToken` when both set via `auth`). */
+    auth?: AuthConfig;
+    /** Called on HTTP 401 before the error is thrown / returned. */
+    onUnauthorized?: StatusHandler;
+    /** Called on HTTP 403. */
+    onForbidden?: StatusHandler;
+    /** Called on HTTP 404. */
+    onNotFound?: StatusHandler;
+    /** Called on HTTP 5xx (500–599). */
+    onServerError?: StatusHandler;
+    /** Advanced per-status map (`401`, `403`, `4xx`, `5xx`, `default`, …). */
+    onStatus?: StatusHandlers;
+};
+type ThrowingOptions = Omit<RequestOptions, 'throwOnError'> & {
+    throwOnError?: true;
+};
+type ResultOptions = Omit<RequestOptions, 'throwOnError'> & {
+    throwOnError: false;
+};
+type FetchMethod = {
+    <T>(path: string, options?: ThrowingOptions): Promise<T>;
+    <T, E = FetchErrorInfo>(path: string, options: ResultOptions): Promise<FetchResult<T, E>>;
+};
+type FetchRequest = {
+    <T>(method: HttpMethod, path: string, options?: ThrowingOptions): Promise<T>;
+    <T, E = FetchErrorInfo>(method: HttpMethod, path: string, options: ResultOptions): Promise<FetchResult<T, E>>;
+};
+type UploadCallOptions = Omit<RequestOptions, 'body' | 'onUploadProgress'> & UploadOptions;
+type UploadMethod = {
+    <T>(path: string, options?: UploadCallOptions & {
+        throwOnError?: true;
+    }): Promise<T>;
+    <T, E = FetchErrorInfo>(path: string, options: UploadCallOptions & {
+        throwOnError: false;
+    }): Promise<FetchResult<T, E>>;
+};
+type SseCallOptions<T = unknown> = RequestOptions & SseHandlers<T> & {
+    lastEventId?: string;
+};
+type FetchClient = {
+    use: (name: string, interceptor: Omit<HttpInterceptor, 'name'> & {
+        name?: string;
+    }, config?: {
+        order?: number;
+    }) => void;
+    eject: (name: string) => void;
+    request: FetchRequest;
+    get: FetchMethod;
+    post: FetchMethod;
+    put: FetchMethod;
+    patch: FetchMethod;
+    delete: FetchMethod;
+    /** Multipart / file upload — returns the same typed response body as `post`. */
+    upload: UploadMethod;
+    /**
+     * Simple: pass `onMessage` / `onEvent` → returns `{ close }`.
+     * Advanced: no handlers → `AsyncIterable` for `for await`.
+     */
+    sse: {
+        <T>(path: string, options: SseCallOptions<T> & ({
+            onMessage: SseHandlers<T>['onMessage'];
+        } | {
+            onEvent: SseHandlers<T>['onEvent'];
+        })): SseSubscription;
+        <T>(path: string, options?: SseCallOptions<T>): AsyncIterable<SseEvent<T>>;
+    };
+};
+/** @deprecated Use CreateFetchOptions */
+type CreateClientOptions = CreateFetchOptions;
+/** @deprecated Use FetchClient */
+type HttpClient = FetchClient;
+
+export type { CreateFetchOptions as C, FetchClient as F, HttpClient as H, RequestOptions as R, SseCallOptions as S, UploadCallOptions as U, FormDataFields as a, CreateClientOptions as b, FormDataFieldValue as c, SseEvent as d, SseHandlers as e, SseSubscription as f, UploadOptions as g, UploadProgressEvent as h, UploadProgressHandler as i };