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

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,104 @@ 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.
 
-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'`:
+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:
 
 ```typescript
-const { data } = await downloadInvoice({ path: { id: '123' }, responseType: 'blob' })
-// data is a Blob even when the server leaves Content-Type unset
+const { data } = await getReport({ path: { id: '123' }, parseAs: 'text' })
 ```
 
-[Server-sent events](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/server-sent-events) covers `responseType: 'stream'`.
+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:
 
-For bidirectional formats, supply both `serialize` and `deserialize` in the media type codec, then set the operation's request and response `contentType`.
+```typescript
+const result = await getPetById({ path: { petId: 1 }, contentType: { response: 'application/xml' } })
+if (result.contentType === 'application/xml') {
+  const pet = result.data as unknown as Pet
+}
+```
+
+The examples set [`integerType: 'number'`](https://kubb.dev/extensions/kubb-labs/adapter-oas/options#integertype) on the adapter, so an `int64` id such as `petId` is a `number`. With the default it is a `bigint` and the call takes `1n`.
+
+[Server-sent events](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/server-sent-events) covers stream media types and `client.stream`.
+
+> [!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 +173,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`.

package/docs/guides/server-sent-events.md

@@ -7,7 +7,7 @@ Each event on the wire has up to four fields, and a blank line ends it:
 | Field   | Meaning                                                                          |
 | ------- | -------------------------------------------------------------------------------- |
 | `event` | The event name. `message` when the server sends none.                            |
-| `data`  | The payload. Parsed as JSON unless the document types it as a string.            |
+| `data`  | The payload. Parsed as JSON when it is valid JSON, and kept as text otherwise.   |
 | `id`    | The last event ID. It carries over to later events and resumes a dropped stream. |
 | `retry` | The reconnect delay in milliseconds.                                             |
 
@@ -33,7 +33,7 @@ For one payload on every event, such as a feed of pet changes. The item declares
 
 ### Describe it
 
-In OpenAPI 3.2, put one `oneOf` member per event name on `itemSchema`, with a `const` on `event`. Describe JSON inside `data` with `contentMediaType` and `contentSchema`:
+In OpenAPI 3.2, put one `oneOf` member per event name on `itemSchema`, with a `const` on `event`. Point `data` at the payload schema with `$ref`. A `data` string described with `contentMediaType: application/json` and `contentSchema` is typed and parsed as that schema too:
 
 ```yaml
 /chat:
@@ -53,13 +53,16 @@ In OpenAPI 3.2, put one `oneOf` member per event name on `itemSchema`, with a `c
                 id: { type: string }
                 retry: { type: integer, minimum: 0 }
               oneOf:
-                - properties:
-                    event: { const: message_delta }
-                    data:
-                      contentMediaType: application/json
-                      contentSchema: { $ref: '#/components/schemas/MessageDelta' }
-                - properties:
-                    event: { const: ping }
+                - type: object
+                  required: [event, data]
+                  properties:
+                    event: { type: string, const: message_delta }
+                    data: { $ref: '#/components/schemas/MessageDelta' }
+                - type: object
+                  required: [event]
+                  properties:
+                    event: { type: string, const: ping }
+                    data: { type: string }
 ```
 
 In OpenAPI 3.0 and 3.1, put the same `oneOf` on `schema`, with a `discriminator` on `event`. Kubb reads `schema` as one event.
@@ -89,7 +92,7 @@ Kubb generates one union member per event name:
 
 ```typescript
 export type StreamChatStatus200 =
-  | { data?: MessageDelta; event: 'message_delta'; id?: string; retry?: number }
+  | { data: MessageDelta; event: 'message_delta'; id?: string; retry?: number }
   | { data?: string; event: 'ping'; id?: string; retry?: number }
 ```
 
@@ -103,7 +106,7 @@ const { stream } = await streamChat({ body: { prompt: 'Hi' } })
 for await (const event of stream) {
   switch (event.event) {
     case 'message_delta':
-      render(event.data?.text) // MessageDelta
+      render(event.data.text) // MessageDelta
       break
     case 'ping':
       break
@@ -173,16 +176,65 @@ for await (const { data } of stream) {
 }
 ```
 
+The examples set [`integerType: 'number'`](https://kubb.dev/extensions/kubb-labs/adapter-oas/options#integertype) on the adapter, so an `int64` id such as `petId` is a `number`. With the default it is a `bigint` and the call takes `1n`.
+
+## JSON Lines
+
+An operation whose only success content type is a JSON sequence, such as `application/jsonl`, `application/x-ndjson`, or `application/json-seq`, streams one item per line. Each line is parsed as JSON, so the loop gets each item as soon as its line arrives instead of waiting for the whole body. An `application/json-seq` record must fit on one line. A record that spans several lines fails to parse.
+
+### Describe it
+
+Point `itemSchema` at the schema of one line:
+
+```yaml
+/logs:
+  get:
+    operationId: streamLogs
+    responses:
+      '200':
+        description: One LogEntry per line
+        content:
+          application/jsonl:
+            itemSchema:
+              $ref: '#/components/schemas/LogEntry'
+```
+
+In OpenAPI 3.0 and 3.1, `schema` on one of these media types describes one line.
+
+### The stream
+
+```text
+{"level": "info", "message": "started"}
+{"level": "warn", "message": "slow"}
+```
+
+The call asks for the declared media type in `Accept`. A line may end with CRLF, CR, or LF, blank lines are skipped, and a last line without a line break still counts. A line that is not valid JSON throws a `SyntaxError` from the loop.
+
+### Use it
+
+Each item is a `LogEntry`, with no event wrapper:
+
+```typescript
+import { streamLogs } from './gen/clients/streamLogs'
+
+for await (const entry of await streamLogs()) {
+  console.info(entry.level, entry.message) // LogEntry
+}
+```
+
+`terminator`, `maxEventSize`, and `signal` work per line. `transform` only applies to Server-Sent Events. With `validator: 'zod'`, the validator runs on each line. `lastEventId` stays empty, since JSON Lines has no event IDs.
+
 ## Stream options
 
 Pass these on the call, next to its request params:
 
-| Option         | What it does                                                                                                                    |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `terminator`   | Ends the stream when `data` equals this value, such as `[DONE]`. Without it, the sentinel reaches your loop.                    |
-| `transform`    | Maps each event before validation, for example to camelCase its keys.                                                           |
-| `maxEventSize` | Largest event in characters. A larger one throws a `RangeError`. Defaults to `16 * 1024 * 1024`. Set `Infinity` to turn it off. |
-| `signal`       | An `AbortSignal` that ends the request and the loop.                                                                            |
+| Option         | What it does                                                                                                                                                                   |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `terminator`   | Ends the stream when `data` equals this value, such as `[DONE]`. Without it, the sentinel reaches your loop, or fails the `validator` when it does not match the event schema. |
+| `transform`    | Maps each event before validation, for example to camelCase its keys.                                                                                                          |
+| `maxEventSize` | Largest event in characters. A larger one throws a `RangeError`. Defaults to `16 * 1024 * 1024`. Set `Infinity` to turn it off.                                                |
+| `signal`       | An `AbortSignal` that ends the request and the loop.                                                                                                                           |
+| `eventShape`   | What the validator checks: `data` for the payload, `event` for the whole event. Generated calls set it.                                                                        |
 
 To stop reading, `break` out of the loop. The runtime then cancels the reader and releases the connection.
 
@@ -202,9 +254,19 @@ const { stream } = await streamChat({
 
 Set `validate: false` on the call or the client to skip it. See [Handle errors](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/error-handling) for the validation options.
 
+## Read the response headers
+
+A stream result carries the response `headers`, as a regular result does. When the response declares headers, such as an `X-Request-ID`, the call returns `StreamResultWithHeaders`, so `headers.get` suggests their names for the narrowed `status`:
+
+```typescript
+const result = await streamChat({ body: { prompt: 'Hi' } })
+
+console.info(result.headers.get('X-Request-ID'))
+```
+
 ## Resume after a drop
 
-A dropped connection ends the loop with the transport's error. The result's `lastEventId` is the `id` of the last event the server completed, so a new call with a `Last-Event-ID` header continues where the stream stopped. The runtime does not reconnect by itself, because many streams, such as a chat completion, end on purpose, and the retry policy belongs to your app:
+A dropped connection ends the loop with the transport's error. The result's `lastEventId` is the `id` of the last event the server completed, so a new call with a `Last-Event-ID` header continues where the stream stopped. Declare `Last-Event-ID` as a header parameter of the operation, so the call accepts it in `headers`. The runtime does not reconnect by itself, because many streams, such as a chat completion, end on purpose, and the retry policy belongs to your app:
 
 ```typescript
 let lastEventId = ''
@@ -239,7 +301,7 @@ try {
 }
 ```
 
-With `throwOnError: false`, the call resolves instead of throwing, as a regular call does. The result then carries the `status` and the `error` body, its `data` is `undefined`, and its stream yields nothing. Check `data` rather than `error`, because an empty error body leaves `error` undefined. Checking `status` narrows `error` to the body the document declares for that status:
+With `throwOnError: false`, the call resolves instead of throwing, as a regular call does. The result then carries the `status` and the `error` body, its `data` is `undefined`, and its stream yields nothing. Check `data` to tell the two apart. An empty error body sets `error` to `{ status, statusText }`. Checking `status` narrows `error` to the body the document declares for that status:
 
 ```typescript
 const result = await streamChat({ body, throwOnError: false })
@@ -253,10 +315,51 @@ As on a regular call, `.unwrap()` resolves to the events. A failed call rejects
 for await (const event of await streamChat({ body }).unwrap()) render(event)
 ```
 
-A stream call that gets a JSON response, such as an error body, parses it like any other call, so a 2xx JSON body yields an empty stream. An operation that declares another content type next to `text/event-stream` is generated as a normal call.
+A stream call that gets a JSON error body parses it like any other call. A 2xx answer that is not an event stream, such as a JSON body, throws a `TypeError` with the body as its `cause`, and an empty 2xx answer ends as an empty stream. An operation that declares another content type next to `text/event-stream` or a JSON Lines type is a normal call. See [JSON or an event stream](#json-or-an-event-stream).
 
 Declare heartbeat and `error` events in the document, so each has a `case` in your `switch`.
 
+## JSON or an event stream
+
+Some APIs, such as Wikimedia EventStreams, declare the same response as `application/json` and as `text/event-stream`. Kubb generates a normal call for it, which returns a `RequestResult`. The call sends `Accept: text/event-stream`, so the server streams events. To ask for JSON, pass `contentType: { response: 'application/json' }`. Wikimedia answers JSON with an endless JSON Lines body, so also pass `parseAs: 'stream'` and read `result.data` with `parseJsonLines({ stream: result.data })` from `.kubb/client`. Without it, the call waits for a body that never ends.
+
+Check `contentType` on the result. For `text/event-stream`, `data` is the raw `ReadableStream<Uint8Array>`. Pass it to `parseEventStream` from `.kubb/client` to read the events:
+
+```typescript
+import { parseEventStream } from './gen/.kubb/client'
+import { getV2StreamRecentchange } from './gen/clients/getV2StreamRecentchange'
+
+const result = await getV2StreamRecentchange({ signal })
+
+if (result.contentType === 'text/event-stream') {
+  for await (const { data } of parseEventStream(result.data)) render(data)
+} else {
+  render(result.data) // the JSON body
+}
+```
+
+To get a stream result with `lastEventId`, send the same request with `client.stream`. It throws a `TypeError` when the server answers with JSON:
+
+```typescript
+import { client } from './gen/.kubb/client'
+
+const result = await client.stream({ method: 'GET', url: '/v2/stream/recentchange', eventShape: 'data', signal })
+for await (const event of result) render(event.data)
+```
+
+## Stream with the client
+
+`client.stream(config)` runs the same interceptors and transport as `client(config)`. On a 2xx answer, it reads the body item by item and validates each item with `validator.response`. A non-2xx body is decoded whole, so `error` stays a value. Type it with the responses record, `ThrowOnError`, and the item type, which defaults to `ServerSentEvent` around the success body:
+
+```typescript
+import { client, type SuccessOf } from './gen/.kubb/client'
+import type { StreamLogsResponses } from './gen/types/StreamLogs'
+
+const result = await client.stream<StreamLogsResponses, true, SuccessOf<StreamLogsResponses>>({ method: 'GET', url: '/logs' })
+```
+
+To stream another format, register a `stream` handler, as [Configure serialization](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/serialization#add-a-media-type) shows.
+
 ## Return only the events
 
 With `returnType: 'data'` in the plugin options, a stream call returns its events, as a regular call returns only its body:
@@ -269,16 +372,16 @@ pluginFetch({ returnType: 'data' })
 
 Both modes read the same events. The table compares them for one call:
 
-|                                     | `returnType: 'full'` (default)                                 | `returnType: 'data'`                                           |
-| ----------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------- |
-| The call returns                    | `Unwrappable<StreamResult<…>>`                                 | `Promise<UnwrappedStreamResult<…>>`                            |
-| Call it                             | `const result = await streamPetEvents({ path: { petId: 1 } })` | `const events = await streamPetEvents({ path: { petId: 1 } })` |
-| Loop over the events                | `for await (const event of result.stream)`                     | `for await (const event of events)`                            |
-| Other ways to loop                  | `result`, `result.data`, or `.unwrap()`                        | none                                                           |
-| `event.data`                        | `PetEvent`                                                     | `PetEvent`                                                     |
-| A failed call, by default           | throws a `ResponseError`                                       | throws a `ResponseError`                                       |
-| With `throwOnError: false`          | the full result                                                | the full result, as in `'full'`                                |
-| `status`, `response`, `lastEventId` | available                                                      | only with `throwOnError: false`                                |
+|                                                | `returnType: 'full'` (default)                                 | `returnType: 'data'`                                           |
+| ---------------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------- |
+| The call returns                               | `Unwrappable<StreamResult<…>>`                                 | `Promise<UnwrappedStreamResult<…>>`                            |
+| Call it                                        | `const result = await streamPetEvents({ path: { petId: 1 } })` | `const events = await streamPetEvents({ path: { petId: 1 } })` |
+| Loop over the events                           | `for await (const event of result.stream)`                     | `for await (const event of events)`                            |
+| Other ways to loop                             | `result`, `result.data`, or `.unwrap()`                        | none                                                           |
+| `event.data`                                   | `PetEvent`                                                     | `PetEvent`                                                     |
+| A failed call, by default                      | throws a `ResponseError`                                       | throws a `ResponseError`                                       |
+| With `throwOnError: false`                     | the full result                                                | the full result, as in `'full'`                                |
+| `status`, `headers`, `response`, `lastEventId` | available                                                      | only with `throwOnError: false`                                |
 
 Loop over the events the call resolves to:
 
@@ -323,7 +426,7 @@ The events alone carry no `response` or `lastEventId`. To resume a dropped strea
 
 ## The runtime files
 
-`.kubb/sse.ts` holds the parser, `toEventStream`, and the `ServerSentEvent`, `TypedEvent`, `EventStreamOptions`, and `EventStreamResult` types. A stream operation takes `StreamOptions` and returns `StreamResult`, the stream versions of `Options` and `RequestResult`. Kubb writes it only when the document has a `text/event-stream` operation, and `.kubb/client.ts` then re-exports it, so the types import from either file. Kubb regenerates both on each run, so do not edit them:
+`.kubb/sse.ts` holds `parseEventStream`, `parseJsonLines`, and the `eventStream`, `jsonLines`, and `streamMediaTypes` media types. The `ServerSentEvent`, `TypedEvent`, `EventStreamOptions`, `StreamOptions`, `StreamResult`, and `StreamResultWithHeaders` types live in `.kubb/core.ts`. A stream operation takes `StreamOptions` and returns `StreamResult`, or `StreamResultWithHeaders` when the response declares headers. These types are the stream versions of `Options`, `RequestResult`, and `RequestResultWithHeaders`. `.kubb/client.ts` re-exports `sse.ts`, so everything imports from the client. Kubb regenerates these files on each run, so do not edit them:
 
 ```typescript
 import type { ServerSentEvent } from './gen/.kubb/client'

package/docs/guides/transport.md

@@ -6,10 +6,10 @@ The transport is a function. Use interceptors for request headers or response lo
 
 ## Write a transport function
 
-`@kubb/plugin-fetch` types the transport as a function that receives a fully resolved request and returns a result:
+`@kubb/plugin-fetch` types the transport as a function that receives a fully resolved request and returns a web `Response`:
 
 ```typescript
-type Transport = (request: ResolvedRequest) => Promise<TransportResult>
+type Transport = (request: ResolvedRequest) => Promise<Response | TransportResult>
 
 type ResolvedRequest = {
   url: string
@@ -18,22 +18,37 @@ type ResolvedRequest = {
   body?: RequestBody
   signal?: AbortSignal
   credentials?: RequestCredentials
-  options?: FetchOptions
-  responseType?: ResponseType
+  options?: NativeOptions
+  // Set when the call streams the response. Do not buffer the body.
+  stream?: boolean
 }
 
-type TransportResult<TData = unknown> = {
-  data: TData
-  status: number
-  statusText: string
-  headers: Headers
-  contentType?: string
+type TransportResult = {
+  webResponse: Response
   request: Request
   response: Response
 }
 ```
 
-The core hands you a `ResolvedRequest` with the URL built, the query and body serialized, and auth headers set. Return the parsed `data` along with the native `request` and `response`, so status, headers, and the raw body stay reachable on the result.
+The `ResolvedRequest` has the URL built, the query and body encoded, and auth headers set. Return the `Response` with its body unread. Return a `TransportResult` to set the native `request` and `response` on results and errors.
+
+## Send with another library
+
+A library that returns a `Response`, such as [ky](https://github.com/sindresorhus/ky), needs only the send. `toRequestInit(request)` gives the `RequestInit` that `fetch` and ky take:
+
+```typescript
+import ky from 'ky'
+import { client, toRequestInit } from './gen/.kubb/client'
+
+client.setConfig({
+  // The client splits success from error itself, so ky must not throw or retry on an error status. ky's `timeout`
+  // (10 seconds by default) only waits for the response headers and never ends a started body or stream. Turn it
+  // off and bound the whole call with `signal: AbortSignal.timeout(ms)`.
+  transport: (request) => ky(request.url, { ...toRequestInit(request), throwHttpErrors: false, retry: 0, timeout: false }),
+})
+```
+
+The library must hand back the body unread. `result.request` is then a `Request` built from the resolved request, without its body, since the library keeps its own. With a relative URL, it is the resolved request itself.
 
 ## Mock the network in tests
 
@@ -44,20 +59,15 @@ import { createClient } from './gen/.kubb/client'
 import { getPetById } from './gen/clients/getPetById'
 
 const testClient = createClient({
-  transport: async (request) => ({
-    data: { id: 1, name: 'Fluffy' },
-    status: 200,
-    statusText: 'OK',
-    headers: new Headers(),
-    request: new Request(request.url),
-    response: new Response(),
-  }),
+  transport: async () => Response.json({ id: 1, name: 'Fluffy' }),
 })
 
 const { data } = await getPetById({ path: { petId: 1 }, client: testClient })
 //      ^ { id: 1, name: 'Fluffy' }
 ```
 
+The examples set [`integerType: 'number'`](https://kubb.dev/extensions/kubb-labs/adapter-oas/options#integertype) on the adapter, so an `int64` id such as `petId` is a `number`. With the default it is a `bigint` and the call takes `1n`.
+
 Pass the isolated client per operation or to a query plugin.
 
 ## Where to set it