tanstack-fetch 1.0.0 → 1.0.1

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
@@ -555,6 +578,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 +728,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 +748,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 +780,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-BE-mgD4y.d.cts

@@ -0,0 +1,116 @@
+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 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;
+};
+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 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;
+    /**
+     * 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, CreateClientOptions as a, SseEvent as b, SseHandlers as c, SseSubscription as d };

package/dist/client.type-D1zw5tFf.d.ts

@@ -0,0 +1,116 @@
+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.js';
+
+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 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;
+};
+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 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;
+    /**
+     * 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, CreateClientOptions as a, SseEvent as b, SseHandlers as c, SseSubscription as d };