@kubb/plugin-fetch 5.14.0-canary.20261109T134631 → 6.0.0

package/docs/guides/interceptors.md

@@ -1,6 +1,6 @@
 # Add interceptors
 
-Register handlers on `client.interceptors.request`, `.response`, or `.error` to apply behavior across calls. Handlers receive the resolved request and result objects.
+Register handlers on `client.interceptors.request`, `.response`, or `.error` to apply behavior across calls. Handlers receive the resolved request, the decoded result, or the error a call ends with.
 
 ## Run before the send
 
@@ -16,37 +16,47 @@ client.interceptors.request.use((request) => {
 ```
 
 The handler receives a `ResolvedRequest` (`url`, `method`, `headers`, `body`, `signal`,
-`credentials`, `options`, `responseType`).
+`credentials`, `options`, `stream`).
 
 ## 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`):
+Response handlers run after the body is decoded and before the status check and the validator, so a JSON body is
+already parsed. On a `client.stream` call, `data` is the raw body stream. The handler receives a `DecodedResponse`
+(`data`, `status`, `statusText`, `headers`, `contentType`, `request`, `response`):
 
 ```typescript
 client.interceptors.response.use((result) => {
-  console.info(`${result.status} ${result.request.url}`)
+  console.info(`${result.status} ${result.contentType}`)
   return result
 })
 ```
 
 ## React to an error
 
-Use an error handler to react to HTTP errors on the throwing path. The handler receives the
-`ResponseError`:
+Error handlers get every failure: a `ResponseError` for a non-2xx status, a network error, an abort, or a
+`ParseError`. Narrow with `ResponseError.is`:
 
 ```typescript
+import { client, ResponseError } from './gen/.kubb/client'
+
 client.interceptors.error.use((error) => {
-  if (error.status === 401) scheduleTokenRefresh()
+  if (ResponseError.is(error) && error.status === 401) scheduleTokenRefresh()
+  if (error.name === 'AbortError') console.info('canceled')
   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.
+Return another error, such as a domain error, and the call throws it instead. Each handler receives the error the one
+before it returned. A handler that returns nothing keeps the error:
+
+```typescript
+class NotFoundError extends Error {}
+
+client.interceptors.error.use((error) => (ResponseError.is(error) && error.status === 404 ? new NotFoundError(error.message) : error))
+```
+
+With `throwOnError: false`, a documented non-2xx response resolves and no error handler runs for it, so inspect the
+returned `error` on the result. An error inside a stream loop throws from the loop and skips the error handlers.
 
 ## Add, replace, and remove handlers
 
@@ -69,4 +79,14 @@ 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.
+Register handlers on the shared `client` for all operations. `client.createClient(config)` returns an instance with the
+same config and no handlers. `client.extend(config)` returns one that runs the parent's handlers, even those added
+later, before its own:
+
+```typescript
+import { client } from './gen/.kubb/client'
+
+const admin = client.extend({ headers: { 'X-Role': 'admin' } })
+admin.interceptors.request.use((request) => request) // runs after the handlers on client
+await getPetById({ path: { petId: 1 }, client: admin })
+```

package/docs/guides/migrate-to-v6.md

@@ -0,0 +1,235 @@
+# Migrate to v6
+
+`@kubb/plugin-fetch` 6 runs on the shared client core from `@kubb/plugin-client`, the same core as `@kubb/plugin-axios`. Code that only calls the generated functions, SDK classes, or hooks needs a regenerate and nothing else. Code that configures `client`, adds media types, streams, or writes a transport needs the edits below.
+
+## Upgrade steps
+
+1. Upgrade `kubb` and `@kubb/plugin-fetch` together. v6 needs Kubb 5.18.4 or later:
+
+   ```bash
+   npm install --save-dev kubb@latest @kubb/plugin-fetch@6
+   ```
+
+2. Regenerate. This rewrites `.kubb/` and the operation files:
+
+   ```bash
+   npx kubb generate
+   ```
+
+3. Run the type checker. Most breaking changes show up as compile errors in your own code:
+
+   ```bash
+   npx tsc --noEmit
+   ```
+
+4. Fix each error with its row in [What to change](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/migrate-to-v6#what-to-change). Then read [Behavior changes](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/migrate-to-v6#behavior-changes), which the type checker does not catch.
+
+## What to change
+
+| Your code                                                                                       | What to do                                                                                                                                                          |
+| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Calls generated functions, SDK methods, or hooks                                                | Regenerate. Then check [Behavior changes](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/migrate-to-v6#behavior-changes).                                |
+| Imports from `@kubb/plugin-fetch/templates/fetch.ts` or `templates/core.ts`                     | Change the import path. See [Template imports](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/migrate-to-v6#template-imports).                           |
+| Uses `FetchOptions`, `defaultQuerySerializer`, `toEventStream`, or another removed export       | Use the replacement. See [Renamed and removed exports](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/migrate-to-v6#renamed-and-removed-exports).        |
+| Sets `codecs`, `serializer.body`, or `responseType`                                             | Use `mediaTypes` and `parseAs`. See [Media types](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/migrate-to-v6#media-types).                             |
+| Streams Server-Sent Events, or names `EventStreamResult`                                        | Use `client.stream` and `StreamResult`. See [Streams](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/migrate-to-v6#streams).                             |
+| Writes a `transport`                                                                            | Return a web `Response`. See [Transports](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/migrate-to-v6#transports).                                      |
+| Registers `client.interceptors.error` handlers                                                  | Narrow the error first. See [Error interceptors](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/migrate-to-v6#error-interceptors).                       |
+| Imports a `…Status2XX` type, or writes a `'2XX'` key                                            | Write the range in lower case. See [Status ranges](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/migrate-to-v6#status-ranges).                          |
+| Imports generated files by path, and groups by tag or has a schema and an operation of one name | Update the import paths. See [Generated file paths](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/migrate-to-v6#generated-file-paths).                  |
+| Uses SDK classes with `group: { type: 'tag' }`, such as `new pet(config)`                       | Use the new names, such as `new PetClient(config)`. See [SDK class names](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/migrate-to-v6#sdk-class-names). |
+| Comes from 5.12 or earlier and uses streams                                                     | Check [From 5.12 or earlier](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/migrate-to-v6#from-5-12-or-earlier).                                         |
+
+## Template imports
+
+`templates/fetch.ts` is gone, and the package no longer publishes its own `templates/core.ts`, `templates/serializers.ts`, or `templates/standardSchema.ts`. Import the client types from `@kubb/plugin-fetch/templates/client.ts`, and the shared runtime from `@kubb/plugin-client/templates/*`:
+
+```typescript
+// before
+import type { RequestConfig } from '@kubb/plugin-fetch/templates/fetch.ts'
+import type { ResolvedRequest } from '@kubb/plugin-fetch/templates/core.ts'
+
+// after
+import type { RequestConfig } from '@kubb/plugin-fetch/templates/client.ts'
+import type { ResolvedRequest } from '@kubb/plugin-client/templates/core.ts'
+```
+
+The package exports `templates/client.ts` for its types only. Runtime values such as `client` still come from the generated `.kubb/client.ts`.
+
+## Renamed and removed exports
+
+| Before                                                             | After                                                                                                                               |
+| ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `FetchOptions`                                                     | `NativeOptions`, the same type: `RequestInit` plus Next.js's `next`.                                                                |
+| `defaultQuerySerializer`                                           | `serializeQuery`, or `serializeStyledQuery` for a styled query parameter or a urlencoded body                                       |
+| `defaultPathSerializer`                                            | `serializePath`, plus `serializeStyledPath` for a `label` or `matrix` parameter                                                     |
+| `applyHeaderStyles`                                                | `serializeHeaders`                                                                                                                  |
+| `toEventStream`, `EventStreamCall`, `EventStreamResult`            | `client.stream` and `StreamResult`. See [Streams](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/migrate-to-v6#streams). |
+| `Codec`, `Deserializer`, `ContentBodySerializer`, `BodySerializer` | `MediaType`. See [Media types](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/migrate-to-v6#media-types).                |
+| `defaultBodySerializer`, `isDefaultJsonBody`                       | A `mediaTypes` entry, or `defaultMediaTypes`.                                                                                       |
+| `ResponseType`, `ResponseTypeMap`, `resolveResponseType`           | `ParseAs` and `parseAs`.                                                                                                            |
+| `CallResult`, `isStreamed`, `getResponseContentType`               | Removed. Read `result.contentType`.                                                                                                 |
+| `clientGenerator` from `@kubb/plugin-fetch`                        | Removed. Build on `setupClient` and `clientDependencies` from `@kubb/plugin-client`.                                                |
+
+The serializers now live in one file each under `.kubb/serializers/`, and Kubb writes a file only when the document needs it. `.kubb/config.ts` registers them, and `setConfig({ serializer })` merges per key, so setting `serializer.query` keeps the others. A client you build with `createClientCore` gets none, so pass them in its `serializer` config. `serializer.header` and `serializer.cookie` are new keys.
+
+`ServerSentEvent`, `TypedEvent`, and `StreamResult` moved from `.kubb/sse.ts` to `.kubb/client.ts`.
+
+## Media types
+
+`codecs` is now `mediaTypes`, and its methods are renamed:
+
+| Before                                                          | After                                        | Migration                                                                      |
+| --------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------ |
+| `codecs`                                                        | `mediaTypes`                                 | Rename the key.                                                                |
+| `codecs[type].serialize(body, contentType)`                     | `mediaTypes[type].encode(body, context)`     | Read `context.contentType`.                                                    |
+| `codecs[type].deserialize(raw, contentType)` with a parsed body | `mediaTypes[type].decode(response, context)` | Read the body yourself: `await response.text()`.                               |
+| `serializer.body`                                               | removed                                      | Move a custom body serializer into a `mediaTypes` entry.                       |
+| `responseType` on a call, a string or a map                     | removed                                      | Use `parseAs`, such as `parseAs: 'blob'`, or a media type entry for that call. |
+
+```typescript
+// before
+client.setConfig({ codecs: { 'application/xml': { deserialize: (raw) => parseXml(raw as string) } } })
+
+// after
+client.setConfig({ mediaTypes: { 'application/xml': { decode: async (response) => parseXml(await response.text()) } } })
+```
+
+A key can be a pattern, such as `application/*+json` or `text/*`. The form media types are written to `.kubb/mediaTypes/` as `multipartFormData` and `urlencoded`, only when the document has a form body. See [Configure serialization](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/serialization).
+
+## Streams
+
+Send a stream request with `client.stream`. Its result is already the stream:
+
+```typescript
+// before
+const { stream } = await toEventStream(client({ method: 'GET', url: '/events', responseType: 'stream' }), { shape: 'data' })
+
+// after
+const { stream } = await client.stream({ method: 'GET', url: '/events', eventShape: 'data' })
+```
+
+`StreamResult` and `UnwrappedStreamResult` take the responses record and the full event type. Wrap a payload in `ServerSentEvent`. A stream typed with `TypedEvent<…>` stays the same:
+
+```typescript
+// before
+let result: EventStreamResult<PetEvent>
+
+// after
+let result: StreamResult<StreamPetsResponses, true, ServerSentEvent<PetEvent>>
+```
+
+An operation whose only success content type is JSON Lines, such as `application/jsonl` or `application/x-ndjson`, now returns a `StreamResult` with one parsed item per line. It used to return the whole body as one string:
+
+```typescript
+for await (const entry of await streamLogs()) {
+  console.info(entry.message) // LogEntry
+}
+```
+
+A stream response that declares headers returns `StreamResultWithHeaders`, or `UnwrappedStreamResultWithHeaders` with `returnType: 'data'`. See [Stream Server-Sent Events](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/server-sent-events).
+
+## Transports
+
+A transport returns a web `Response`, or `{ webResponse, request, response }` to also set the native objects. Build the `RequestInit` with `toRequestInit(request)`. The core decodes the body, and response interceptors receive a `DecodedResponse`, the shape `TransportResult` had:
+
+```typescript
+// before
+transport: async () => ({ data: { id: 1 }, status: 200, statusText: 'OK', headers: new Headers(), request, response })
+
+// after
+transport: async () => Response.json({ id: 1 })
+```
+
+See [Use a custom transport](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/transport).
+
+## Error interceptors
+
+`client.interceptors.error` handlers now also get network errors, aborts, and validation errors. Narrow with `ResponseError.is` before you read `status`. Each handler gets the error the previous one returned:
+
+```typescript
+client.interceptors.error.use((error) => {
+  if (ResponseError.is(error) && error.status === 401) refreshToken()
+  return error
+})
+```
+
+See [Handle errors](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/error-handling).
+
+## Status ranges
+
+A status range is written in lower case in generated names and keys. Rename the imports, and the range keys in a responses record or `validator.error` map you wrote by hand. An upper-case key such as `'2XX'` is no longer read:
+
+```diff
+- import type { ListPetsStatus4XX } from './gen/types/ListPets'
++ import type { ListPetsStatus4xx } from './gen/types/ListPets'
+```
+
+## Generated file paths
+
+Two changes move generated files. The exported names stay the same:
+
+- With `group: { type: 'tag' }`, a tag whose OpenAPI 3.2 `parent` is `store` writes to `store/payment/` instead of `payment/`. Pass `group.name` to keep one folder per tag: `pluginFetch({ group: { type: 'tag', name: ({ group }) => group } })`.
+- An operation file gets an `Operation` suffix when a schema file has the same name, ignoring case. Operation `point` goes to `types/PointOperation.ts`, next to schema `Point`.
+
+```diff
+- import { listPayments } from './gen/clients/payment/listPayments'
++ import { listPayments } from './gen/clients/store/payment/listPayments'
+```
+
+## SDK class names
+
+With `sdk` and `group: { type: 'tag' }`, tag classes are named like `PetClient` instead of `pet`. The files and the root class's `pet` and `store` fields stay the same:
+
+```diff
+- import { pet } from './gen/sdk/pet/pet'
+- const api = new pet({ baseURL })
++ import { PetClient } from './gen/sdk/pet/pet'
++ const api = new PetClient({ baseURL })
+```
+
+The root class shares one client with every tag. Add interceptors on `api.client`.
+
+## Behavior changes
+
+These compile without errors, so check them by hand.
+
+Requests:
+
+- A path or operation with its own `servers` sends its calls there instead of to the client's `baseURL`. Pass `baseURL` on the call to override it. See [Set the base URL](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/base-url).
+- An object query parameter without a `style` goes out as `name=odie&age=3`, not `filter[name]=odie`. Set `style: deepObject` in the document to keep the brackets.
+- An array or object header without a `style` goes out as `X-Ids: 3,4`, not as JSON.
+- A space in a query value goes out as `%20`, not `+`.
+- `spaceDelimited` and `pipeDelimited` default `explode` to `false`, so an array goes out as `ids=1%7C2`.
+- A `style: cookie` parameter goes out without percent-encoding. A value it cannot send, such as one with `;`, throws a `TypeError`.
+- `body: null` goes out as the JSON document `null`.
+- A stream call sends `Accept: text/event-stream`, or the JSON Lines media type.
+- An auth requirement that needs several schemes sends all of them.
+
+Responses:
+
+- Invalid JSON under a JSON media type throws a `ParseError` instead of becoming a string. Catch it, or register a lenient `application/json` entry.
+- An empty body is `undefined` for every media type, text included.
+- A failed call without a body reports `{ status, statusText }` as `error`.
+- `ResponseError.data` holds the validated body. Set `validator.error` to a map keyed by status, such as `{ 404: getPetStatus404Schema }`, to check an error body against the schema of its status.
+- An aborted call or stream rejects with the signal's reason.
+- Every result, and a thrown `ResponseError`, has the response's `Headers` as `headers`.
+
+Types:
+
+- A `2xx` response key is a success, and range keys such as `4xx` type `status` as the numbers they cover. An exact code such as `200` wins over a range listed before it.
+- An XML, YAML, or CSV response is typed `string`. An operation that returns JSON and XML has `data: Pet | string`, so narrow on `result.contentType`.
+- An image, audio, video, PDF, or `application/octet-stream` response is typed `Blob`, even when its schema says `type: string`.
+- `result.contentType` is the bare media type, such as `'text/html'`.
+- `server.index` no longer counts a server without a `url`. Servers with a `name` are exported as `servers` from `.kubb/client.ts`, for `client.setConfig({ baseURL: servers.staging })`.
+
+## From 5.12 or earlier
+
+These changed in 5.13 and compile without errors:
+
+- A successful stream call with a body that is not a stream, such as a JSON body, throws a `TypeError` with the body as its `cause`. A successful answer with no body still ends as an empty stream.
+- An event the server ends without a blank line is dropped, as browser `EventSource` does, so end every event with one.
+
+## Query plugins
+
+`@kubb/plugin-react-query`, `@kubb/plugin-vue-query`, `@kubb/plugin-swr`, and `@kubb/plugin-mcp` work with v5 and v6, so you can upgrade them separately. They skip hooks for JSON Lines operations, as they do for event streams.

package/docs/guides/serialization.md

@@ -1,12 +1,57 @@
 # 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.
+The generated client encodes parameters by their OpenAPI `style` and `explode`, and encodes and decodes bodies by their media type. Each generated operation carries its parameter styles and content types, so most requests need no extra setup.
 
-## Override parameter serialization
+## Parameter styles
+
+A parameter without `style` or `explode` in the spec uses the default for its location.
+
+### Query
+
+Query parameters default to the `form` style. Arrays explode into repeated keys unless the spec
+says otherwise, and `spaceDelimited`, `pipeDelimited`, and `deepObject` change how arrays and
+objects collapse.
+
+| Style            | `explode` | Input               | Result           |
+| ---------------- | --------- | ------------------- | ---------------- |
+| `form` (default) | `true`    | `{ id: [3, 4, 5] }` | `id=3&id=4&id=5` |
+| `form`           | `false`   | `{ id: [3, 4, 5] }` | `id=3,4,5`       |
+| `spaceDelimited` | `false`   | `{ id: [3, 4, 5] }` | `id=3%204%205`   |
+| `pipeDelimited`  | `false`   | `{ id: [3, 4, 5] }` | `id=3\|4\|5`     |
+| `deepObject`     | `n/a`     | `{ a: { b: 1 } }`   | `a%5Bb%5D=1`     |
+
+With `explode: true`, `spaceDelimited` and `pipeDelimited` fall back to repeated keys like `form`,
+so the delimiter only shows with `explode: false`.
+
+### Path
+
+Path parameters default to the `simple` style, which emits the bare value. `label` prefixes a
+`.` and `matrix` prefixes a `;name=` segment. The results below are the serialized segment for a
+parameter named `id`.
+
+| Style              | `explode` | Input            | Result            |
+| ------------------ | --------- | ---------------- | ----------------- |
+| `simple` (default) | `false`   | `[3, 4, 5]`      | `3,4,5`           |
+| `label`            | `true`    | `[3, 4, 5]`      | `.3.4.5`          |
+| `matrix`           | `true`    | `[3, 4, 5]`      | `;id=3;id=4;id=5` |
+| `simple`           | `false`   | `{ x: 1, y: 2 }` | `x,1,y,2`         |
 
-Check the [default parameter styles and encoding](https://kubb.dev/docs/5.x/reference/serialization#parameter-styles) before replacing a serializer.
+### Header and cookie
 
-Override `serializer.query`, `.body`, or `.path` on the client. Omitted functions retain their defaults:
+Header parameters use the `simple` style and cookie parameters use the `form` style. Both fix the
+style and only let `explode` vary, so the metadata for these locations carries `explode` alone.
+Header values are sent as-is, and cookie values are URL-encoded into a single `Cookie` header.
+
+| Location | `explode` | Input                             | Result                 |
+| -------- | --------- | --------------------------------- | ---------------------- |
+| header   | `false`   | `[3, 4]`                          | `X-Ids: 3,4`           |
+| header   | `true`    | `{ role: 'admin' }`               | `X-Filter: role=admin` |
+| cookie   | `false`   | `{ session: 'abc', ids: [1, 2] }` | `session=abc; ids=1,2` |
+| cookie   | `true`    | `{ ids: [1, 2] }`                 | `ids=1; ids=2`         |
+
+## Override parameter serialization
+
+To replace these defaults, override `serializer.query` or `serializer.path` on the client. Omitted functions keep their defaults:
 
 ```typescript
 import { client } from './gen/.kubb/client'
@@ -19,83 +64,102 @@ client.setConfig({
 })
 ```
 
-A serializer set this way runs for every call, but you can pass `serializer` on a single call to
-override only that request.
+A serializer set this way runs for every call. Pass `serializer` on a single call to override only that request.
+
+Kubb writes each serializer a spec needs into `.kubb/serializers/` and lists it in `.kubb/config.ts`, which `.kubb/client.ts` passes to `setConfig`. The core has no serializer of its own.
+
+| Key in `serializer` | File                                                                                 | Written for                    |
+| ------------------- | ------------------------------------------------------------------------------------ | ------------------------------ |
+| `query`             | `query.ts`, or `queryStyles.ts` for a spec with a styled query parameter             | every spec                     |
+| `path`              | `path.ts`, plus `pathStyles.ts` for a spec with a `label` or `matrix` path parameter | every spec                     |
+| `header`            | `headers.ts`                                                                         | a spec with a header parameter |
+| `cookie`            | `cookies.ts`                                                                         | a spec with a cookie parameter |
+
+A call that needs a serializer the spec did not register throws a `TypeError` that names the key, such as `serializer.cookie`. Set it on the client to send such a call. Without `serializer.header`, an array or object header value is sent as JSON.
+
+## Built-in media types
+
+| Keys                                                                                     | Encodes                                           | Decodes                                    |
+| ---------------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------ |
+| `application/json`, `application/*+json`, `text/json`                                    | JSON                                              | JSON                                       |
+| `text/*`                                                                                 | a string                                          | text                                       |
+| `multipart/form-data`, `application/x-www-form-urlencoded`                               | `FormData` or `URLSearchParams` from an object    | `FormData`                                 |
+| `application/octet-stream`, `application/pdf`, `image/*`, `audio/*`, `video/*`           | a `Blob` as is                                    | `Blob`                                     |
+| `text/event-stream`, `application/jsonl`, `application/x-ndjson`, `application/json-seq` |                                                   | text, or item by item with `client.stream` |
+| `*/*`                                                                                    | JSON for objects, strings and binary bodies as is | JSON, or text when the body is not JSON    |
+
+`.kubb/client.ts` registers a form media type only when the document has a body of that type, and the stream media types only when it streams. `multipartFormData` is in `.kubb/mediaTypes/formData.ts` and `urlencoded` in `.kubb/mediaTypes/urlencoded.ts`. The stream media types are `streamMediaTypes` in `.kubb/sse.ts`.
+
+A key can be a pattern. The runtime lower-cases the type, drops its parameters, and tries the exact type, then a suffix such as `application/*+json`, then a wildcard such as `text/*`, then `*/*`. Write your own keys in lower case.
 
 ## 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 one 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. A body without a content type is sent as `application/json`, unless it is already encoded.
 
-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.
+Bodies that are already encoded (`FormData`, `URLSearchParams`, `Blob`, `ArrayBuffer`, typed arrays, streams, and strings) pass through every built-in media type as they are. A string under a JSON media type is JSON-encoded.
 
 > [!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.
+> When the body is `FormData`, the runtime removes any `Content-Type` header so the transport sets it with the multipart boundary.
+
+An XML, YAML, or CSV media type has no built-in handler, so an object sent under one throws a `TypeError`. Pass the encoded body as a string, or register a media type. The generated body type is the schema, such as `Pet`, so a string body needs a cast: `body: xml as unknown as AddPetBodyXml`.
 
-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:
+## Add a media type
+
+Register a handler under its media type with `mediaTypes`. `encode` gets the body and a context with the full `contentType`, and returns what `fetch` can send. `decode` gets the `Response`, so a binary format can read bytes:
 
 ```typescript
 import { client } from './gen/.kubb/client'
-import { stringify } from 'yaml'
+import { XMLBuilder, XMLParser } from 'fast-xml-parser'
 
 client.setConfig({
-  codecs: {
-    'application/yaml': { serialize: (body) => stringify(body) },
+  mediaTypes: {
+    'application/xml': {
+      encode: (body) => new XMLBuilder().build(body),
+      decode: async (response) => new XMLParser().parse(await response.text()),
+    },
   },
 })
 ```
 
-## Decode responses
+Handlers merge per key over the built-ins, over earlier `setConfig` calls, and, when passed on a single call, over the client ones. An entry with only `decode` still encodes through the next match, such as `*/*`.
 
-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.
-
-When that success response declares several content types that do not share one parser, the
-generated call sets `responseType` to a map from content type to parser, for example
-`{ 'audio/mpeg': 'blob', 'text/event-stream': 'stream' }`. The runtime matches the response
-`Content-Type` against the map, including a `type/*` wildcard, before the media-type heuristic.
-A schema with `format: binary` is a blob even when the media type is not a well-known binary type.
-
-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:
+A streaming format adds `stream`, which reads the 2xx body item by item. The runtime validates each item:
 
 ```typescript
-import { client } from './gen/.kubb/client'
-
 client.setConfig({
-  codecs: {
-    'application/xml': { deserialize: (raw) => new DOMParser().parseFromString(raw as string, 'application/xml') },
+  mediaTypes: {
+    'multipart/mixed': { stream: (body, { contentType }) => readParts(body, boundaryOf(contentType)) },
   },
 })
 ```
 
-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.
+## Decode responses
+
+The runtime decodes each body by the response `Content-Type`. The media type is on the result as `contentType`, so a `switch (result.contentType)` narrows `data` for an operation that returns more than one.
+
+- A 2xx response without a `Content-Type` is decoded as the media type the call asked for in `contentType.response`, then as `*/*`.
+- A 204, 205, or 304 response, a `HEAD` request, and an empty body give `data: undefined`.
+- Invalid JSON under a JSON media type throws a `ParseError`. Catch it, or register a lenient `application/json` handler.
+
+To skip the lookup for one call, set `parseAs` to `'json'`, `'text'`, `'blob'`, `'arrayBuffer'`, or `'stream'`. It applies to a 2xx body only. Kubb sets `parseAs: 'blob'` on an operation with only binary success content:
 
-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 getReport({ path: { id: '123' }, parseAs: 'text' })
+```
+
+The generated types follow what the built-in media types return. A response read as text, such as `application/xml`, `application/yaml`, or `text/csv`, is typed `string`, even when the document gives it an object schema. A vendor type such as `application/vnd.github.object` keeps its schema type, because the client parses its JSON body. A media type you register changes the value but not that type, so narrow or cast `data` to what it returns:
 
 ```typescript
-const { data } = await downloadInvoice({ path: { id: '123' }, responseType: 'blob' })
-// data is a Blob even when the server leaves Content-Type unset
+const result = await getPetById({ path: { petId: 1 }, contentType: { response: 'application/xml' } })
+if (result.contentType === 'application/xml') {
+  const pet = result.data as unknown as Pet
+}
 ```
 
-[Server-sent events](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/server-sent-events) covers `responseType: 'stream'`.
+[Server-sent events](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/server-sent-events) covers stream media types and `client.stream`.
 
-For bidirectional formats, supply both `serialize` and `deserialize` in the media type codec, then set the operation's request and response `contentType`.
+> [!NOTE]
+> With the adapter's default [`integerType: 'bigint'`](https://kubb.dev/extensions/kubb-labs/adapter-oas/options#integertype), a `format: int64` field is typed `bigint`, but `JSON.parse` returns a `number`. Set `integerType: 'number'` on `adapterOas`, or turn on [`validator: 'zod'`](#validate-responses), which converts the field to `bigint`. Either way, `JSON.parse` loses precision above `Number.MAX_SAFE_INTEGER`, so declare an exact 64-bit ID as a string in the document.
 
 ## Validate responses
 
@@ -107,14 +171,10 @@ 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:
+`'zod'` validates the success response body and the error body. 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`.
+With a validator set, Kubb passes the matching schema to each generated call, and the runtime parses the decoded body through it. A body that does not match throws a `ParseError` with the schema's `issues`.