@kubb/plugin-fetch 5.5.8 → 5.5.10

package/docs/guides/authentication.md

@@ -0,0 +1,77 @@
+# Authenticate requests
+
+Set an `auth` resolver on the generated client. Operations use the [security schemes](https://spec.openapis.org/oas/v3.1.0#security-scheme-object) declared in your OpenAPI spec. Requests remain unauthenticated until you provide credentials.
+
+## Set the auth resolver
+
+Set the resolver for all secured operations:
+
+```typescript
+import { client } from './gen/.kubb/client'
+
+client.setConfig({
+  auth: () => localStorage.getItem('token') ?? undefined,
+})
+```
+
+`auth` takes a token string or a function. The function can be async and returns a token, or `undefined` to skip that scheme. When an operation accepts several schemes, the runtime tries each until one returns a token.
+
+## Return the right token per scheme
+
+Use the scheme passed to the resolver to select a credential:
+
+```typescript
+type Auth = {
+  type: 'http' | 'apiKey' | 'oauth2' | 'openIdConnect'
+  scheme?: 'bearer' | 'basic'
+  name?: string
+  in?: 'header' | 'query' | 'cookie'
+}
+```
+
+The scheme decides where the runtime puts the token:
+
+| Scheme in the spec | `Auth` object                            | Where the token goes            |
+| ------------------ | ---------------------------------------- | ------------------------------- |
+| `http` bearer      | `{ type: 'http', scheme: 'bearer' }`     | `Authorization: Bearer <token>` |
+| `http` basic       | `{ type: 'http', scheme: 'basic' }`      | `Authorization: Basic <token>`  |
+| `apiKey` header    | `{ type: 'apiKey', name, in: 'header' }` | request header named `name`     |
+| `apiKey` query     | `{ type: 'apiKey', name, in: 'query' }`  | query parameter named `name`    |
+| `apiKey` cookie    | `{ type: 'apiKey', name, in: 'cookie' }` | `Cookie` header                 |
+| `oauth2`           | `{ type: 'oauth2' }`                     | `Authorization: Bearer <token>` |
+| `openIdConnect`    | `{ type: 'openIdConnect' }`              | `Authorization: Bearer <token>` |
+
+> [!NOTE]
+> For basic auth, return the raw `username:password` string. The runtime base64-encodes it and writes the `Basic` prefix, so you never build the header yourself.
+
+When a spec mixes schemes, branch on the `Auth` object and return the matching credential:
+
+```typescript
+client.setConfig({
+  auth: (auth) => (auth.type === 'apiKey' ? apiKey : accessToken),
+})
+```
+
+## Use a separate client per environment
+
+To give each environment its own token, such as one per tenant in a multi-tenant app, build an isolated client with `createClient`:
+
+```typescript
+import { createClient } from './gen/.kubb/client'
+
+const tenant = createClient({
+  baseURL: 'https://tenant.example.com',
+  auth: () => tenantToken,
+})
+
+const { data } = await getPetById({ path: { petId: 1 }, client: tenant })
+```
+
+To override the client for one request, pass `auth` on that single call, which suits a one-off token refresh. An explicit `headers` value you set on a call always wins over the resolved token.
+
+For authentication outside OpenAPI security schemes, use an async request interceptor to sign requests or supply custom headers.
+
+## See also
+
+- [Add interceptors](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/interceptors)
+- [Set the base URL](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/base-url)

package/docs/guides/base-url.md

@@ -0,0 +1,63 @@
+# Set the base URL
+
+Set `baseURL` on the client plugin or on the generated client.
+
+> [!NOTE]
+> OpenAPI server URLs do not configure the client automatically. The `server` option of `adapterOas` only sets document metadata. It does not set `baseURL`.
+
+## Use the baseURL option
+
+Pass `baseURL` to `pluginFetch` to set the generated default. Add `pluginTs` for the operation types.
+
+```typescript [kubb.config.ts]
+import { defineConfig } from 'kubb/config'
+import { pluginTs } from '@kubb/plugin-ts'
+import { pluginFetch } from '@kubb/plugin-fetch'
+
+export default defineConfig({
+  input: './petStore.yaml',
+  output: { path: './src/gen' },
+  plugins: [
+    pluginTs(),
+    pluginFetch({ baseURL: 'https://localhost:8080/api/v1' }),
+  ],
+})
+```
+
+A value containing a `${...}` interpolation stays dynamic. The plugin emits it as a template literal in the generated client config, so `baseURL: '${process.env.API_URL}'` reads the environment variable when the app runs instead of baking in the build-time value.
+
+## Set it at runtime
+
+Use `client.setConfig` to configure all operations at startup:
+
+```typescript
+import { client } from './gen/.kubb/client'
+
+client.setConfig({ baseURL: import.meta.env.VITE_API_URL })
+```
+
+Use `createClient` for an isolated client, then pass it to an operation:
+
+```typescript
+import { createClient } from './gen/.kubb/client'
+import { getPetById } from './gen/clients/getPetById'
+
+const staging = createClient({ baseURL: 'https://staging.petstore.swagger.io/v2' })
+
+const { data } = await getPetById({ path: { petId: 1 }, client: staging })
+```
+
+Pass `baseURL` on a single call to override the client for that one request:
+
+```typescript
+import { getPetById } from './gen/clients/getPetById'
+
+const { data } = await getPetById({ path: { petId: 1 }, baseURL: 'https://localhost:3000' })
+```
+
+A `baseURL` set on the call wins over `createClient`, which wins over `setConfig`, which wins over the build-time value.
+
+## See also
+
+- [Authenticate requests](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/authentication)
+- [Use a custom transport](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/transport)

package/docs/guides/calling-operations.md

@@ -0,0 +1,147 @@
+# Call operations
+
+The generated client accepts grouped request options on every operation and returns a typed `RequestResult` by default.
+
+## Call an operation
+
+Pass parameters under `path`, `query`, `headers`, `cookies`, or `body`, matching the OpenAPI operation.
+
+```typescript
+import { getPetById } from './gen/clients/getPetById'
+
+const { data } = await getPetById({ path: { petId: 1 } })
+//      ^ the parsed pet, typed from the 200 response
+```
+
+Query, header, and cookie parameters sit under their own keys, and a request body goes under
+`body`:
+
+```typescript
+import { searchPets } from './gen/clients/searchPets'
+import { updatePet } from './gen/clients/updatePet'
+
+await searchPets({
+  query: { status: 'available', category: 'dogs', limit: 10, offset: 0 },
+})
+
+await updatePet({
+  path: { petId: '123' },
+  headers: { 'X-Request-ID': 'req-123456' },
+  body: { name: 'Updated name', status: 'sold' },
+})
+```
+
+Each key is optional and only appears when the operation declares it. Call an operation with no parameters with an empty object: `getStatus({})`.
+
+## Read the result
+
+A resolved call returns a `RequestResult` discriminated by the numeric `status`:
+
+```typescript
+type RequestResult = {
+  status: number
+  data: TData // the parsed success body, undefined on an error result
+  error: TError // the parsed error body, undefined on a success result
+  contentType: string | undefined // the negotiated response media type
+  request: Request // the native request
+  response: Response // the native response
+}
+```
+
+When `throwOnError` is `true` (the generated default), a resolved call is always a success, so you
+read `data` straight away:
+
+```typescript
+const { data, status, response } = await getPetById({ path: { petId: 1 } })
+
+console.info(status) // 200
+console.info(response.headers.get('x-ratelimit-remaining'))
+```
+
+When an operation documents more than one success status, narrow on `status` to reach the body
+for that case, and TypeScript follows the check:
+
+```typescript
+const result = await getPetById({ path: { petId: 1 } })
+
+if (result.status === 200) {
+  console.info(result.data.name)
+}
+```
+
+## Unwrap the success body
+
+Call `.unwrap()` to return the success body. Awaiting the operation directly returns the full result.
+
+```typescript
+import { getPetById } from './gen/clients/getPetById'
+
+const pet = await getPetById({ path: { petId: 1 } }).unwrap()
+//    ^ the parsed pet, not the full RequestResult
+```
+
+With `throwOnError: true`, a non-2xx response throws the same `ResponseError` a plain `await` would. With `throwOnError: false`, `.unwrap()` rejects with the parsed error body instead:
+
+```typescript
+try {
+  const pet = await getPetById({ path: { petId: 1 }, throwOnError: false }).unwrap()
+} catch (error) {
+  // the parsed error body, not a ResponseError
+  console.error(error)
+}
+```
+
+## Set the content type
+
+When an operation accepts or returns more than one media type, set `contentType` on the call. A
+bare string sets the request content type. The object form also sends an `Accept` header for the
+response:
+
+```typescript
+await uploadAvatar({
+  path: { petId: '123' },
+  body: avatarBlob,
+  contentType: 'image/png',
+})
+
+await getPet({
+  path: { petId: '123' },
+  contentType: { request: 'application/json', response: 'application/xml' },
+})
+```
+
+An operation that declares a single content type has it built in, so a multipart upload such as `uploadFile({ path: { petId: '123' }, body: { file: pngBlob } })` needs only the body.
+
+## Pass native client options
+
+Pass `options` on an operation for native fetch settings, such as `cache`, `mode`, `redirect`, `keepalive`, `duplex`, or `next`:
+
+```typescript [src/app.ts]
+import { getPetById } from './gen/clients/getPetById'
+
+await getPetById({ path: { petId: 1 }, options: { cache: 'no-store' } })
+```
+
+Set `client.setConfig({ options })` for shared defaults. Per-call options take precedence. Kubb keeps control of serialization and HTTP error handling. See [Use a custom transport](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/transport).
+
+## Build a URL without sending
+
+Use `client.getUrl` to build a URL with the same base URL, path interpolation, and query serialization as a request:
+
+```typescript
+import { client } from './gen/.kubb/client'
+
+const url = client.getUrl({
+  url: '/pets/{petId}',
+  path: { petId: 1 },
+  query: { fields: 'name' },
+})
+// https://api.example.com/v1/pets/1?fields=name
+```
+
+## See also
+
+- [Handle errors](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/error-handling)
+- [Configure serialization](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/serialization)
+- [Set the base URL](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/base-url)
+- [Server-sent events](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/server-sent-events)

package/docs/guides/error-handling.md

@@ -0,0 +1,124 @@
+# Handle errors
+
+Handle failures from the client Kubb generates. Catch a `ResponseError`, switch to a returned error result with `throwOnError`, and tell a network failure apart from a 4xx or 5xx response.
+
+The generated client throws a `ResponseError` on non-2xx responses by default:
+
+```typescript
+import { getPetById } from './gen/clients/getPetById'
+import { ResponseError } from './gen/.kubb/client'
+
+try {
+  const { data } = await getPetById({ path: { petId: 1 } })
+  console.info(data.name)
+} catch (error) {
+  if (ResponseError.is(error)) {
+    console.error(error.status) // 404
+    console.error(error.data) // the parsed error body
+  }
+}
+```
+
+The `message` holds the HTTP method and the URL without its query string, so query credentials stay out of logs. For example: `GET https://api.example.com/pets/1 failed with status 404 Not Found`.
+
+The error exposes these fields:
+
+```typescript
+class ResponseError extends Error {
+  static is(error: unknown): error is ResponseError<unknown, unknown, unknown>
+  data: TError // the parsed error body
+  status: number
+  statusText: string
+  contentType: string | undefined
+  request: Request
+  response: Response
+}
+```
+
+Each generated package bundles its own `ResponseError` class, so narrow with `ResponseError.is(error)` instead of `instanceof`. `is()` checks the error name.
+
+## Return the error instead
+
+Pass `throwOnError: false` and the call resolves for every documented status. The result is a
+discriminated union: `data` is set on success and `error` on failure. Branch on `status`,
+because an empty error body can leave `error` empty or undefined.
+
+```typescript
+const result = await getPetById({ path: { petId: 1 }, throwOnError: false })
+
+if (result.status === 200) {
+  console.info(result.data.name)
+}
+if (result.status !== 200) {
+  console.error(result.status, result.error)
+}
+```
+
+## Set the generated default
+
+Set `throwOnErrorDefault` on the client plugin to choose how generated operations handle non-2xx
+responses by default. Each call can still override that setting with `throwOnError`:
+
+```typescript
+import { pluginFetch } from '@kubb/plugin-fetch'
+
+pluginFetch({ throwOnErrorDefault: false })
+
+// resolves with an error result
+const list = await searchPets({ query: { status: 'available' } })
+
+// opt one call back into throwing
+const pet = await getPetById({ path: { petId: 1 }, throwOnError: true })
+```
+
+`client.setConfig({ throwOnError })` does not change this default, because each generated
+operation passes its own value. Set it on the plugin.
+
+## Network failures still throw
+
+> [!IMPORTANT]
+> `throwOnError` only applies when the server answers. A dropped connection, a DNS failure, or an
+> aborted `AbortSignal` always rejects. A `ResponseError` means the server answered with a non-2xx
+> status, and a `ParseError` means a body failed validation. Any other error usually means the
+> request never completed.
+
+```typescript
+try {
+  const { data } = await getPetById({ path: { petId: 1 }, throwOnError: false })
+  use(data)
+} catch (error) {
+  // not a ResponseError: the request never completed
+  console.error('request failed to send', error)
+}
+```
+
+Pass an `AbortSignal` to cancel a request. The call rejects with the abort reason.
+
+## Validation failures
+
+When you turn on the `validator` option, a body that does not match its Zod schema throws a
+`ParseError` instead of returning. It carries the schema's raw `issues`:
+
+```typescript
+import { ParseError } from './gen/.kubb/standardSchema'
+
+try {
+  const { data } = await getPetById({ path: { petId: 1 } })
+  use(data)
+} catch (error) {
+  if (error instanceof ParseError) {
+    console.error(error.issues) // [{ message, path }]
+  }
+}
+```
+
+A `ParseError` reports schema validation issues. A `ResponseError` reports a non-2xx status. With `throwOnError: false`, the error body is checked against its own error schema.
+
+Calling `.unwrap()` on a `throwOnError: false` call turns that same `error` into a rejection, so a
+`try`/`catch` works there too.
+
+## See also
+
+- [Call operations](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/calling-operations)
+- [Configure serialization](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/serialization)
+- [Add interceptors](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/interceptors)

package/docs/guides/interceptors.md

@@ -0,0 +1,78 @@
+# Add interceptors
+
+Register handlers on `client.interceptors.request`, `.response`, or `.error` to apply behavior across calls. Handlers receive the resolved request and result objects.
+
+## Run before the send
+
+Request handlers run after URL construction, serialization, and authentication. Return the modified request:
+
+```typescript
+import { client } from './gen/.kubb/client'
+
+client.interceptors.request.use((request) => {
+  request.headers['X-Request-ID'] = crypto.randomUUID()
+  return request
+})
+```
+
+The handler receives a `ResolvedRequest` (`url`, `method`, `headers`, `body`, `signal`,
+`credentials`, `options`, `responseType`).
+
+## Run after the send
+
+Response handlers run before calls resolve, and before the status split and deserialization, so
+`data` is the raw body. The handler receives a `TransportResult` (`data`, `status`, `statusText`,
+`headers`, `contentType`, `request`, `response`):
+
+```typescript
+client.interceptors.response.use((result) => {
+  console.info(`${result.status} ${result.request.url}`)
+  return result
+})
+```
+
+## React to an error
+
+Use an error handler to react to HTTP errors on the throwing path. The handler receives the
+`ResponseError`:
+
+```typescript
+client.interceptors.error.use((error) => {
+  if (error.status === 401) scheduleTokenRefresh()
+  return error
+})
+```
+
+This channel only fires on the throw path. When you read with `throwOnError: false`, a documented
+non-2xx response resolves and no error interceptor runs, so inspect the returned `error` on the
+result instead. A transport failure (no response) still throws. The error handler does not run,
+because there is no result to pass it.
+
+## Add, replace, and remove handlers
+
+`use` registers a handler and returns an id. Pass that id to `eject` to remove it, or to `update`
+to swap its function in place.
+
+> [!NOTE]
+> Handlers run in the order you register them.
+
+```typescript
+const id = client.interceptors.request.use((request) => request)
+
+client.interceptors.request.update(id, (request) => {
+  request.headers['X-Trace'] = 'on'
+  return request
+})
+
+client.interceptors.request.eject(id)
+```
+
+## Where to set them
+
+Register handlers on the shared `client` for all operations, or on a separate `createClient` instance for isolated calls. Interceptors are instance-level settings.
+
+## See also
+
+- [Handle errors](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/error-handling)
+- [Authenticate requests](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/authentication)
+- [Use a custom transport](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/transport)

package/docs/guides/serialization.md

@@ -0,0 +1,120 @@
+# Configure serialization
+
+The generated client encodes parameters using OpenAPI `style` and `explode`, serializes request bodies by content type, and decodes responses by media type. Each generated operation carries its parameter styles and content types, so most requests need no extra setup.
+
+## Override parameter serialization
+
+Check the [default parameter styles and encoding](https://kubb.dev/docs/5.x/reference/serialization#parameter-styles) before replacing a serializer.
+
+Override `serializer.query`, `.body`, or `.path` on the client. Omitted functions retain their defaults:
+
+```typescript
+import { client } from './gen/.kubb/client'
+import qs from 'qs'
+
+client.setConfig({
+  serializer: {
+    query: (params) => qs.stringify(params, { arrayFormat: 'brackets' }),
+  },
+})
+```
+
+A serializer set this way runs for every call, but you can pass `serializer` on a single call to
+override only that request.
+
+## Encode request bodies
+
+The request content type decides how the body is encoded. The default serializer handles the
+common types: a plain object becomes JSON, `multipart/form-data` becomes `FormData`, and
+`application/x-www-form-urlencoded` becomes `URLSearchParams`. Binary and already-encoded bodies
+(`FormData`, `URLSearchParams`, `Blob`, `ArrayBuffer`, typed arrays, and strings) pass through
+untouched.
+
+When an operation declares a single request content type, Kubb sets it on the generated function,
+so you pass only the body. For an operation that accepts more than one, set `contentType` on the
+call.
+
+> [!NOTE]
+> When the body is `FormData`, the runtime removes any `Content-Type` header so the transport sets
+> it with the multipart boundary. You do not need to set `multipart/form-data` yourself, and a
+> value you set is dropped for that request.
+
+To encode a content type the default serializer does not handle, register a codec for that media
+type. `codecs` is keyed by content type. Each entry takes a `serialize` for the request body, a
+`deserialize` for the response, or both:
+
+```typescript
+import { client } from './gen/.kubb/client'
+import { stringify } from 'yaml'
+
+client.setConfig({
+  codecs: {
+    'application/yaml': { serialize: (body) => stringify(body) },
+  },
+})
+```
+
+## Decode responses
+
+The runtime reads the response `Content-Type` and decodes the body by it: JSON is parsed, text
+stays a string, and a binary type becomes a `Blob`. The negotiated media type is on the result as
+`contentType`, so a `switch (result.contentType)` narrows `data` for an operation that returns
+more than one.
+
+To decode a media type the runtime does not handle, register a codec's `deserialize` for it.
+`deserialize` receives the raw body and the content type and returns the parsed value. It runs
+before validation, so the schema checks the parsed value:
+
+```typescript
+import { client } from './gen/.kubb/client'
+
+client.setConfig({
+  codecs: {
+    'application/xml': { deserialize: (raw) => new DOMParser().parseFromString(raw as string, 'application/xml') },
+  },
+})
+```
+
+Like the other config, `codecs` can also be passed on a single call, and a per-call entry merges
+over the client one for that content type.
+
+When the runtime picks the wrong parse mode because a response omits its `Content-Type` or sets a
+misleading one, force the mode with `responseType` on the call. It accepts `'json'`, `'text'`,
+`'blob'`, `'arraybuffer'`, and `'document'`:
+
+```typescript
+const { data } = await downloadInvoice({ path: { id: '123' }, responseType: 'blob' })
+// data is a Blob even when the server leaves Content-Type unset
+```
+
+[Server-sent events](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/server-sent-events) covers `responseType: 'stream'`.
+
+For bidirectional formats, supply both `serialize` and `deserialize` in the media type codec, then set the operation's request and response `contentType`.
+
+## Validate responses
+
+Enable `validator` on the client plugin and register `pluginZod` in the same configuration. Validation is disabled by default.
+
+```typescript
+import { pluginFetch } from '@kubb/plugin-fetch'
+
+pluginFetch({ validator: 'zod' })
+```
+
+`'zod'` validates the success response body, and the error body when a non-2xx call does not
+throw. Use the object form to opt in per direction, where `request` validates the request
+body before the call goes out:
+
+```typescript
+pluginFetch({ validator: { request: 'zod', response: 'zod' } })
+```
+
+With a validator set, Kubb passes the matching schema to each generated call, and the runtime
+parses the body through it. A body that does not match throws a `ParseError` with the schema's
+`issues`.
+
+## See also
+
+- [Call operations](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/calling-operations)
+- [Handle errors](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/error-handling)
+- [Server-sent events](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/server-sent-events)