@kubb/plugin-client 5.12.0 → 6.0.0

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

@@ -0,0 +1,139 @@
+# Migrate to v6
+
+`@kubb/plugin-client` 6 calls your client with type arguments and streams through `client.stream`. Update the `client` export of your module, then regenerate. Find your code in the table, then follow its section.
+
+## What to change
+
+| Your code                                                                       | What to do                                                                                                                                                                   |
+| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Exports a `client` that takes no type arguments                                 | Make it generic. See [A generic client call](https://kubb.dev/extensions/kubb-labs/plugin-client/guides/migrate-to-v6#a-generic-client-call).                                |
+| Exports `toEventStream` or `EventStreamResult`                                  | Add a `stream` method to `client`. See [A stream method](https://kubb.dev/extensions/kubb-labs/plugin-client/guides/migrate-to-v6#a-stream-method-instead-of-toeventstream). |
+| Declares `responseType` on `RequestConfig`, or lacks `contentType` or `cookies` | Add the new fields. See [New fields on the request config](https://kubb.dev/extensions/kubb-labs/plugin-client/guides/migrate-to-v6#new-fields-on-the-request-config).       |
+| Reads `security` entries as single schemes                                      | Handle arrays and the new fields. See [Security requirements](https://kubb.dev/extensions/kubb-labs/plugin-client/guides/migrate-to-v6#security-requirements).               |
+| 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-client/guides/migrate-to-v6#status-ranges).                                  |
+| Groups by tag in an OpenAPI 3.2 document whose tags set `parent`                | Update the import paths. See [Tag folders](https://kubb.dev/extensions/kubb-labs/plugin-client/guides/migrate-to-v6#tag-folders).                                            |
+| Has `servers` on a path or operation, or reads XML, YAML, CSV, or binary bodies | Check [Behavior changes](https://kubb.dev/extensions/kubb-labs/plugin-client/guides/migrate-to-v6#behavior-changes). It compiles.                                            |
+| Wants `.unwrap()` or a call that resolves to the body                           | Set `returnType`. See [Return type](https://kubb.dev/extensions/kubb-labs/plugin-client/guides/migrate-to-v6#return-type). This is optional.                                 |
+
+## Upgrade steps
+
+1. Upgrade `kubb` and `@kubb/plugin-client` together. v6 needs Kubb 5.18.4 or later:
+
+   ```bash
+   npm install --save-dev kubb@latest @kubb/plugin-client@6
+   ```
+
+2. Update your client module with the sections below.
+
+3. Regenerate the operation files:
+
+   ```bash
+   npx kubb generate
+   ```
+
+4. Run the type checker. A missing export or field in your client module shows up as a compile error in the generated files:
+
+   ```bash
+   npx tsc --noEmit
+   ```
+
+## A generic client call
+
+A generated function now calls `client<TResponses, ThrowOnError>(config)`. Make `client` generic:
+
+```typescript
+export const client = <TResponses, ThrowOnError extends boolean = true>(config: RequestConfig) =>
+  send(config) as Promise<RequestResult<TResponses, ThrowOnError>>
+```
+
+## A stream method instead of toEventStream
+
+A Server-Sent Events or JSON Lines operation calls `client.stream<TResponses, ThrowOnError, TItem>(config)`. Remove `toEventStream` and `EventStreamResult`, add `stream` to `client`, and export `StreamResult`, `SuccessOf`, `TypedEvent`, and `ServerSentEvent`:
+
+```typescript
+export type StreamResult<TResponses, ThrowOnError extends boolean = true, TEvent = ServerSentEvent<SuccessOf<TResponses>>> = {
+  stream: AsyncGenerator<TEvent>
+  response: Response
+}
+
+export function client<TResponses, ThrowOnError extends boolean = true>(config: RequestConfig) {
+  return send<TResponses, ThrowOnError>(config)
+}
+
+client.stream = async <TResponses, ThrowOnError extends boolean = true, TEvent = ServerSentEvent<SuccessOf<TResponses>>>(
+  config: RequestConfig,
+): Promise<StreamResult<TResponses, ThrowOnError, TEvent>> => {
+  // send the request and parse the body into TEvent values
+}
+```
+
+A Server-Sent Events call also passes `eventShape: 'event'` or `'data'`. A JSON Lines call, such as `application/jsonl` or `application/x-ndjson`, passes the media type in `contentType.response` and expects one parsed item per line. See [Write your client](https://kubb.dev/extensions/kubb-labs/plugin-client/guides/write-your-client).
+
+## New fields on the request config
+
+Add these fields to your `RequestConfig`, or the generated functions fail to compile:
+
+```typescript
+export type RequestConfig = {
+  // ...
+  contentType?: string | { request?: string; response?: string }
+  // Replaces `responseType`. Binary downloads pass 'blob'.
+  parseAs?: 'json' | 'text' | 'blob' | 'arrayBuffer' | 'stream'
+  eventShape?: 'event' | 'data'
+  // Name and value pairs for `in: cookie` parameters. Join them into a `Cookie` header on the server. Browsers ignore a `Cookie` header set by script and send their own cookies.
+  cookies?: object
+  // `style`, `explode`, `allowReserved`, and `contentType` per parameter, grouped by location.
+  styles?: object
+}
+```
+
+A cookie parameter with the OpenAPI 3.2 `cookie` style passes `style: 'cookie'` in `styles`. Send its values without percent-encoding. See [Serialize parameters](https://kubb.dev/extensions/kubb-labs/plugin-client/guides/write-your-client#serialize-parameters).
+
+## Security requirements
+
+A `security` entry is an array when one requirement needs several schemes together, such as an API key and a session cookie. Send all of them, or skip the entry.
+
+An `oauth2` scheme now also passes `flows` and `metadataUrl`, and an `openIdConnect` scheme passes `url`. Accept them on your auth type:
+
+```typescript
+export type Auth = {
+  type: string
+  scheme?: string
+  name?: string
+  in?: string
+  scopes?: Array<string>
+  flows?: Record<string, Record<string, string>>
+  metadataUrl?: string
+  url?: string
+}
+```
+
+## 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'
+```
+
+## Tag folders
+
+With `group: { type: 'tag' }`, a tag whose OpenAPI 3.2 `parent` is `store` now writes to `store/payment/` instead of `payment/`. `importPath` is written into every file as given, so one relative path cannot serve files at two depths, such as `store/` and `store/payment/`. Pass `group.name` to keep one folder per tag, or set `importPath` to a package name or alias that resolves from every folder:
+
+```typescript
+pluginClient({ importPath: '../../../client', group: { type: 'tag', name: ({ group }) => group } })
+```
+
+## Behavior changes
+
+These compile without errors, so check them by hand:
+
+- A path or operation with its own `servers` passes that server as `baseURL` on the call. Your client must use `config.baseURL` when it is set.
+- A `2xx` response key is a success, and an exact code such as `200` wins over a range listed before it.
+- An XML, YAML, or CSV response is typed `string`. An image, audio, video, PDF, or `application/octet-stream` response is typed `Blob`. When every success content type is binary, the call passes `parseAs: 'blob'`.
+- An operation whose only success content type is JSON Lines returns a `StreamResult`, not the whole body as one string.
+
+## Return type
+
+`returnType` is new and defaults to `'plain'`, so existing code keeps working. With `'full'`, generated calls wrap the result in `withUnwrap`, so your module must also export `withUnwrap`, `resolveThrowOnError`, and the `Unwrappable` type. With `'data'`, calls resolve to the body when `throwOnError` is `true`, and to the full result when it is `false`. Your module must then export `unwrapResult`, `resolveThrowOnError`, and the `UnwrappedResult` type. A stream operation also imports `StreamOptions` with `StreamResult` for `'full'`, or with `UnwrappedStreamResult` for `'data'`. Both modes need a `StreamResult` with `data` and `error`, as the one in `@kubb/plugin-client/templates/core.ts` has, so the minimal type above is not enough. `@kubb/plugin-client/templates/core.ts` exports all of these. See [returnType](https://kubb.dev/extensions/kubb-labs/plugin-client/options#returntype).

package/docs/guides/validate-requests-and-responses.md

@@ -29,11 +29,13 @@ Each generated call now includes the schemas:
 request({
   method: 'POST',
   url: '/pet',
-  validator: { response: addPetResponseSchema, error: addPetErrorSchema },
   ...config,
+  validator: { response: addPetResponseSchema, error: { 405: addPetStatus405Schema }, ...config.validator },
 })
 ```
 
+A `validator` passed on one call is merged per key, so `validator: { request }` adds a request schema and keeps the generated response schema. A per-call `error` replaces the generated error map as a whole.
+
 Add a `validator` field to your `RequestConfig`, then run the schemas in `client`. Zod schemas follow [Standard Schema](https://standardschema.dev), so `~standard.validate` works with any compatible library:
 
 ```typescript [src/client.ts]
@@ -42,7 +44,7 @@ type Schema = { '~standard': { validate: (value: unknown) => Result | Promise<Re
 
 export type RequestConfig = {
   // ...
-  validator?: { request?: Schema; response?: Schema; error?: Schema }
+  validator?: { request?: Schema; response?: Schema; error?: Schema | Record<string, Schema> }
 }
 
 // inside client(), after reading the body
@@ -53,6 +55,8 @@ const validatedBody = result && 'value' in result ? result.value : body
 
 Return `validatedBody` as `data`, so a schema that transforms the value takes effect. Without a response schema, `validatedBody` is the original `body`.
 
+`error` is keyed by status, such as `{ 404: schema, '5xx': schema, default: schema }`. Pick the exact status, then its range, then `default`, and skip validation when none matches.
+
 Set `validator: { request: 'zod' }` or `{ response: 'zod' }` to pass one direction only. Without `pluginZod()` in the plugins list, generation stops with an error.
 
 ## Validate params
@@ -63,12 +67,13 @@ With `validator: { params: 'zod' }`, each call also passes the schemas for its p
 request({
   method: 'PUT',
   url: '/events/{day}',
+  ...config,
   validator: {
     path: putEventPathSchema,
     query: putEventQuerySchema,
     headers: toHeadersStandardSchema(putEventHeadersSchema, putEventHeadersSchema.shape),
+    ...config.validator,
   },
-  ...config,
 })
 ```
 

package/docs/guides/write-your-client.md

@@ -10,7 +10,9 @@ The generated functions import your module through [`importPath`](https://kubb.d
 | `Options`       | type     | The grouped options object a generated function accepts.                                     |
 | `RequestResult` | type     | What a generated function resolves to.                                                       |
 
-If your spec has server-sent event operations, also export `toEventStream` and the `EventStreamResult`, `SuccessOf`, and `TypedEvent` types. A generated function calls `toEventStream<TData>(promise)` with the promise your `client` returns and nothing else, and leaves the response validator on `config.validator.response`, so your module decides how to validate events.
+A generated function calls `client<TResponses, ThrowOnError>(config)`, so type `client` to return `Promise<RequestResult<TResponses, ThrowOnError>>`.
+
+If your spec has server-sent event or JSON Lines operations, `client` also needs a `stream` method, and the module exports the `StreamResult`, `SuccessOf`, `TypedEvent`, and `ServerSentEvent` types. A generated function calls `client.stream<TResponses, ThrowOnError, TItem>(config)` and returns `Promise<StreamResult<TResponses, ThrowOnError, TItem>>`. `TItem` is `TypedEvent<…>` when the document names each event and the success type for JSON Lines. When the document types only the payload, `TItem` is left out and defaults to `ServerSentEvent<SuccessOf<TResponses>>`. A Server-Sent Events call passes `eventShape: 'event'` or `'data'` to say whether `config.validator.response` checks the whole event or its `data`.
 
 The query plugins (`@kubb/plugin-react-query`, `@kubb/plugin-vue-query`, `@kubb/plugin-swr`) and `@kubb/plugin-mcp` call the generated functions with `throwOnError: true` and read `data` off the result. The query plugins also import two more types from your module:
 
@@ -21,6 +23,23 @@ The query plugins (`@kubb/plugin-react-query`, `@kubb/plugin-vue-query`, `@kubb/
 
 With a relative `importPath`, the hooks resolve it from the generated operation file, so one path serves both.
 
+## Build on the shared runtime
+
+To reuse the runtime of the fetch and axios clients instead of writing your own request pipeline:
+
+1. Copy `core.ts`, `mediaTypes.ts`, `serializers.ts`, `standardSchema.ts`, `sse.ts`, and the `mediaTypes/` and `serializers/` files your spec needs from `@kubb/plugin-client/templates` next to your `client.ts`.
+2. In `client.ts`, export the three types the core imports, listed below.
+3. Write a `Transport` function that sends a `ResolvedRequest` and returns a web `Response`. If your library does not return one, wrap its bytes in `new Response(bytes, { status, headers })`.
+4. Export `createLazyClient((config) => createClientCore({ defaultTransport, ...config }))` as `client`. Register the form and stream media types your spec needs with `client.setConfig({ mediaTypes: { 'multipart/form-data': multipartFormData, ...streamMediaTypes } })`, and add `export * from './core.ts'` and `export * from './sse.ts'`. The core has no serializers of its own, so also set `serializer: { query: serializeQuery, path: serializePath }` from `serializers/query.ts` and `serializers/path.ts`, or their styled versions, and `header` and `cookie` for a spec with such parameters.
+
+| Export           | Purpose                                                 | On fetch      | On axios             |
+| ---------------- | ------------------------------------------------------- | ------------- | -------------------- |
+| `NativeRequest`  | The request object on a result and a `ResponseError`.   | `Request`     | `AxiosRequestConfig` |
+| `NativeResponse` | The response object on a result and a `ResponseError`.  | `Response`    | `AxiosResponse`      |
+| `NativeOptions`  | The `options` a call passes to your HTTP library as is. | `RequestInit` | `AxiosRequestConfig` |
+
+[`@kubb/plugin-fetch/templates/client.ts`](https://github.com/kubb-labs/plugins/blob/main/packages/plugin-fetch/templates/client.ts) is a complete example.
+
 ## What a generated function looks like
 
 ```typescript
@@ -31,27 +50,100 @@ import { client } from '../../../client'
 export function getPetById<ThrowOnError extends boolean = true>(
   options: Options<GetPetByIdOptions, ThrowOnError>,
 ): Promise<RequestResult<GetPetByIdResponses, ThrowOnError>> {
-  const { client: request = client, ...config } = options
+  const { client: apiClient = client, ...config } = options
 
-  return request({
+  return apiClient<GetPetByIdResponses, ThrowOnError>({
     method: 'GET',
     url: '/pet/{petId}',
     security: [{ type: 'apiKey', name: 'api_key', in: 'header' }, { type: 'oauth2' }],
     ...config,
     throwOnError: config.throwOnError ?? true,
-  }) as Promise<RequestResult<GetPetByIdResponses, ThrowOnError>>
+  })
+}
+```
+
+Your `client` receives `method`, the `url` template with `{param}` placeholders, `security`, the grouped `path`, `query`, `headers`, `cookies`, and `body`, and `throwOnError`. It returns a promise. `cookies` holds name and value pairs, which your client joins into a `Cookie` header, as the example below does. A `security` entry is one scheme, or an array of schemes to send together.
+
+Read the body by the response `Content-Type`. An operation with only binary success content also passes `parseAs: 'blob'`.
+
+A call can also pass `contentType`: `request` is the body's media type, and `response` is the media type to ask for in `Accept`. A streamed operation always passes its media type, such as `contentType: { response: 'text/event-stream' }` or `contentType: { response: 'application/jsonl' }`. A call whose response offers `text/event-stream` next to another content type passes `text/event-stream` too, unless the caller picks another one. `RequestConfig` needs the field.
+
+## Serialize parameters
+
+When the spec sets `style`, `explode`, `allowReserved`, or `contentType` on a parameter, the generated call also passes `styles`, grouped by location and keyed by the parameter name:
+
+```typescript
+styles: {
+  path: { petId: { style: 'matrix', explode: true } },
+  query: { tags: { style: 'pipeDelimited', explode: false } },
 }
 ```
 
-Your `client` receives `method`, the `url` template with `{param}` placeholders, `security`, the grouped `path`, `query`, `headers`, and `body`, and `throwOnError`. It returns a promise.
+A parameter without an entry uses the default for its location. The shared runtime's `serializers.ts` applies these styles. A client you write from scratch declares `styles` on `RequestConfig` and applies the styles itself, or ignores them when the spec only uses the defaults.
+
+### 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
 
-A non-JSON response also passes `responseType`. It is a string such as `'blob'` when every response content type uses one parser, or a map from content type to parser when they differ, for example `{ 'audio/mpeg': 'blob', 'text/event-stream': 'stream' }`. Read the response `Content-Type`, look it up in the map (exact type, then `type/*`, then `*/*`), and parse the body with that parser.
+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`         |
+
+### Header and cookie
+
+Header parameters use the `simple` style and cookie parameters use the `form` style, so the metadata
+for these locations carries only `explode`, plus `style: 'cookie'` for a cookie parameter with the
+OpenAPI 3.2 `cookie` style. Header values are sent as-is. Cookie values are URL-encoded into a single
+`Cookie` header. The `cookie` style sends them unencoded, as RFC 6265 describes, defaults `explode` to
+`true`, and throws on a value with a character such as `;` or a space, or on an exploded object key that is not a valid
+cookie name, such as `a=b`.
+
+| 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`            |
+| cookie, `cookie` style | default   | `{ sid: 'a%20b', ids: [1, 2] }`   | `sid=a%20b; ids=1; ids=2` |
 
 ## A minimal client
 
 The client below uses `fetch`. Replace the transport with the HTTP library you use.
 
 ```typescript [src/client.ts]
+export type Auth = {
+  type: string
+  scheme?: string
+  name?: string
+  in?: string
+  scopes?: Array<string>
+  flows?: Record<string, Record<string, string>>
+  metadataUrl?: string
+  url?: string
+}
+
 export type RequestConfig = {
   method: 'GET' | 'PUT' | 'PATCH' | 'POST' | 'DELETE' | 'OPTIONS' | 'HEAD'
   url: string
@@ -59,15 +151,18 @@ export type RequestConfig = {
   headers?: object
   path?: object
   query?: object
+  cookies?: object
   body?: unknown
   signal?: AbortSignal
-  responseType?: string | Record<string, string>
+  parseAs?: 'json' | 'text' | 'blob' | 'arrayBuffer' | 'stream'
+  contentType?: string | { request?: string; response?: string }
   throwOnError?: boolean
-  security?: Array<{ type: string; name?: string; in?: string; scopes?: Array<string> }>
+  security?: Array<Auth | Array<Auth>>
+  styles?: object
   client?: typeof client
 }
 
-type DataShape = { body?: unknown; headers?: unknown; path?: unknown; query?: unknown }
+type DataShape = { body?: unknown; cookies?: unknown; headers?: unknown; path?: unknown; query?: unknown }
 
 export type Options<TData extends DataShape, ThrowOnError extends boolean = true> = Omit<RequestConfig, keyof DataShape | 'url' | 'method'> &
   TData & { throwOnError?: ThrowOnError }
@@ -82,13 +177,20 @@ export type ResponseErrorConfig<TError = unknown> = Error & { body?: TError }
 // Set this to your API host. `new URL()` needs an absolute URL.
 export const settings = { baseURL: 'https://petstore3.swagger.io/api/v3' }
 
-export async function client(config: RequestConfig) {
+async function send(config: RequestConfig) {
   const path: Record<string, unknown> = { ...config.path }
   const url = new URL((config.baseURL ?? settings.baseURL) + config.url.replace(/\{(\w+)\}/g, (_, key) => encodeURIComponent(String(path[key]))))
+  const cookie = Object.entries(config.cookies ?? {})
+    .filter(([, value]) => value != null)
+    .map(([name, value]) => `${name}=${encodeURIComponent(String(value))}`)
+    .join('; ')
 
   const response = await fetch(url, {
     method: config.method,
-    headers: config.headers as Record<string, string>,
+    headers: {
+      ...(config.headers as Record<string, string>),
+      ...(cookie ? { Cookie: cookie } : {}),
+    },
     body: config.body === undefined ? undefined : JSON.stringify(config.body),
     signal: config.signal,
   })
@@ -98,6 +200,10 @@ export async function client(config: RequestConfig) {
   if (config.throwOnError ?? true) throw new Error(`Request failed with status ${response.status}`)
   return { data: undefined, error: body ?? { status: response.status }, response }
 }
+
+// Generated functions pass their responses type and `ThrowOnError`.
+export const client = <TResponses, ThrowOnError extends boolean = true>(config: RequestConfig) =>
+  send(config) as Promise<RequestResult<TResponses, ThrowOnError>>
 ```
 
 The [example project](https://github.com/kubb-labs/plugins/tree/main/examples/client) has a fuller version with a base URL setter, query handling, and an async auth hook. The types in this sketch are minimal. Add status-aware response types when you need them.

package/docs/options.md

@@ -55,8 +55,8 @@ The setting applies to the whole plugin, so you cannot set it in `override`.
 Shape of the value a generated operation resolves to.
 
 - `'plain'`: returns what your `client` returns.
-- `'full'`: wraps the call in `withUnwrap`, so the caller can `await` it or call `.unwrap()`. Your module must export `withUnwrap` and the `Unwrappable` type.
-- `'data'`: passes the call through `unwrapResult` and resolves to the body. Your module must export `unwrapResult` and the `UnwrappedResult` type.
+- `'full'`: wraps the call in `withUnwrap`, so the caller can `await` it or call `.unwrap()`. Your module must export `withUnwrap`, `resolveThrowOnError`, and the `Unwrappable` type.
+- `'data'`: passes the call through `unwrapResult` and resolves to the body. Your module must export `unwrapResult`, `resolveThrowOnError`, and the `UnwrappedResult` type.
 
 `@kubb/plugin-client/templates/core.ts` exports all of these, so your module can re-export them from there.
 

package/docs/overview.md

@@ -6,7 +6,7 @@ Each function takes grouped `path`, `query`, `headers`, and `body` parameters an
 
 ## Setup
 
-- Set the required `importPath` option to your client module. The module must export `client` and the `Options` and `RequestResult` types. When the spec has server-sent event operations, it must also export `toEventStream` and the `EventStreamResult`, `SuccessOf`, and `TypedEvent` types.
+- Set the required `importPath` option to your client module. The module must export a generic `client` and the `Options` and `RequestResult` types. When the spec has server-sent event or JSON Lines operations, `client` also needs a `stream` method, and the module exports the `StreamResult`, `SuccessOf`, `TypedEvent`, and `ServerSentEvent` types.
 - Add `@kubb/plugin-ts` for the operation types, or `@kubb/plugin-zod` with `inferred: true`.
 - Add `@kubb/plugin-zod` when you set `validator`, and install `zod` v4. Generation fails without the plugin.
 

package/kubb-extension.json

@@ -20,7 +20,7 @@
   "dependencies": ["plugin-ts"],
   "optionalDependencies": ["plugin-zod"],
   "compatibility": {
-    "kubb": ">=5.16.0",
+    "kubb": ">=5.18.4",
     "node": ">=22.22"
   },
   "options": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/plugin-client",
-  "version": "5.12.0",
+  "version": "6.0.0",
   "description": "Generate typed API operations against your own client module.",
   "keywords": [
     "api-client",
@@ -61,14 +61,15 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@kubb/kit": "^5.16.0",
-    "@kubb/plugin-ts": "^5.4.2",
-    "@kubb/plugin-zod": "^5.8.3",
-    "@kubb/renderer-jsx": "^5.16.0"
+    "@kubb/kit": "^5.18.6",
+    "@kubb/plugin-ts": "^5.5.0",
+    "@kubb/plugin-zod": "^5.9.0",
+    "@kubb/renderer-jsx": "^5.18.6"
   },
   "devDependencies": {
     "@internals/client": "0.0.0",
     "@internals/shared": "0.0.0",
+    "@internals/utils": "0.0.0",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {},

package/src/builders/callConfig.ts

@@ -0,0 +1,80 @@
+import { toLiteral } from '@internals/utils'
+import { getEventStream, hasTextEventData } from '@internals/shared'
+
+import { ast, text } from '@kubb/kit'
+import type { ReturnTypeOption } from '../types.ts'
+import { buildContentType } from './contentType.ts'
+import { buildSecurityMetadata, type SecurityRequirement } from './security.ts'
+import { buildStyles } from './styles.ts'
+import { buildValidatorLiteral, type ValidatorHooks } from './validator.ts'
+
+/**
+ * `parseAs: 'blob'` when every success content type is binary, so a download is a `Blob` whatever its media type, and
+ * also when the server sends no `Content-Type`. Any other body is decoded by its media type at runtime.
+ */
+function buildParseAsLiteral(content: Array<ast.ContentNode>): string | null {
+  return content.length > 0 && content.every((entry) => entry.schema?.type === 'blob') ? `parseAs: 'blob'` : null
+}
+
+/**
+ * Builds the call config literal a generated operation forwards to the client, shared by the standalone
+ * functions and the SDK methods. The operation's own `baseURL` comes before the `...config` spread, so a per-call one wins. The
+ * `validator` and `throwOnError` entries come after it, so a per-call `validator` is merged per key with the generated one instead
+ * of replacing it. `styles` is merged the same way, per parameter, unless `returnType` is `'plain'`.
+ *
+ * `mergeContentType` is `true` when the caller must destructure `contentType` from `options`, and
+ * `eventStream` is `true` when the operation streams `text/event-stream` or JSON Lines. A Server-Sent Events call
+ * carries its `eventShape`, which tells the runtime what the `response` validator checks on each event, and `rawData` when
+ * the document types each event's `data` as a string, so the runtime keeps it as text.
+ */
+export function buildCallConfig({
+  node,
+  validatorHooks,
+  security,
+  baseURL,
+  throwOnErrorDefault,
+  returnType,
+}: {
+  node: ast.HttpOperationNode
+  validatorHooks: ValidatorHooks | null
+  security?: Array<SecurityRequirement>
+  baseURL?: string
+  throwOnErrorDefault: boolean
+  returnType: ReturnTypeOption
+}): { callConfig: string; mergeContentType: boolean; eventStream: boolean } {
+  const stream = getEventStream(node)
+  const content = ast.http.responses.findPrimary(node)?.content ?? []
+  const securityLiteral = buildSecurityMetadata({ security })
+  // A `'plain'` client is the user's own, which may type `styles` as `unknown`, so it keeps the generated styles as a default.
+  const ownRuntime = returnType !== 'plain'
+  const stylesLiteral = buildStyles({ node, merge: ownRuntime })
+  const styles = stylesLiteral ? `styles: ${stylesLiteral}` : null
+  const validatorLiteral = buildValidatorLiteral(validatorHooks, ['request', 'path', 'query', 'headers', 'cookies', 'response', 'error'])
+  const { literal: contentTypeLiteral, merge: mergeContentType } = buildContentType({ node })
+  // The runtime's call types `throwOnError` as the operation's `ThrowOnError`, which the shared helper keeps. A `'plain'`
+  // client takes a boolean.
+  const throwOnError = ownRuntime
+    ? `throwOnError: resolveThrowOnError(config.throwOnError, ${throwOnErrorDefault})`
+    : `throwOnError: config.throwOnError ?? ${throwOnErrorDefault}`
+
+  const rawData = hasTextEventData(node)
+  const callConfig = `{ ${[
+    `method: ${text.quote(node.method.toUpperCase())}`,
+    `url: ${text.quote(node.path)}`,
+    baseURL ? `baseURL: ${JSON.stringify(baseURL)}` : null,
+    securityLiteral ? `security: ${securityLiteral}` : null,
+    ownRuntime ? null : styles,
+    contentTypeLiteral,
+    buildParseAsLiteral(content),
+    stream === 'event' || stream === 'data' ? `eventShape: '${stream}'` : null,
+    rawData ? `rawData: ${toLiteral(rawData)}` : null,
+    '...config',
+    ownRuntime ? styles : null,
+    validatorLiteral,
+    throwOnError,
+  ]
+    .filter(Boolean)
+    .join(', ')} }`
+
+  return { callConfig, mergeContentType, eventStream: stream !== null }
+}

package/src/builders/contentType.ts

@@ -0,0 +1,35 @@
+import { getContentTypeInfo, getResponseContentTypeInfo, hasEventStreamContent, isEventStream } from '@internals/shared'
+import { ast, text } from '@kubb/kit'
+
+/**
+ * Builds the `contentType` entry baked into the call config. It holds the request default when the operation has a body
+ * and `response` set to the streamed media type when it streams items, or `text/event-stream` when it offers events next to
+ * another type, and is `null` with neither.
+ *
+ * `merge` is `true` when the generated function must destructure `contentType` from `options` and merge it over the
+ * baked defaults, because the caller can also pick a response content type or a stream must keep its `Accept`.
+ */
+export function buildContentType({ node }: { node: ast.HttpOperationNode }): { literal: string | null; merge: boolean } {
+  const { defaultContentType } = getContentTypeInfo(node)
+  const hasRequestBody = Boolean(ast.http.requestBody.getSchema(node))
+  // The first declared type is the default; the caller overrides it on `contentType`.
+  const requestContentType = hasRequestBody ? defaultContentType : null
+  // A stream asks for its own media type, and a response that offers events next to JSON asks for the events, so a client whose
+  // default `Accept` prefers JSON, such as axios, gets the stream. The caller picks another type with `contentType.response`.
+  const streamType = isEventStream(node) ? ast.mediaType.getBase(getResponseContentTypeInfo(node).defaultContentType) : null
+  const response = streamType || hasEventStreamContent(node) ? `response: ${text.quote(streamType ?? 'text/event-stream')}` : null
+
+  if (!requestContentType) return { literal: response && `contentType: { ${response} }`, merge: false }
+
+  // When the caller can also pick a response content type, or a stream must keep its `Accept`, a partial `contentType` would
+  // replace the baked default through `...config`, so merge the caller's choice over it instead.
+  const merge = Boolean(response) || getResponseContentTypeInfo(node).isMultipleContentTypes
+  const defaults = [`request: ${text.quote(requestContentType)}`, response].filter(Boolean).join(', ')
+
+  return {
+    merge,
+    literal: merge
+      ? `contentType: { ${defaults}, ...(typeof contentType === 'string' ? { request: contentType } : contentType) }`
+      : `contentType: { ${defaults} }`,
+  }
+}

package/src/builders/generics.ts

@@ -0,0 +1,29 @@
+import type { ast } from '@kubb/kit'
+import { buildResponseHeadersType, buildResultTypeRef, type OperationTypeNames } from '@internals/client'
+import type { ReturnTypeOption } from '../types.ts'
+
+/**
+ * Builds the `RequestResult` type arguments of one operation: responses, `ThrowOnError` and the response headers, when a response declares any.
+ *
+ * @example
+ * `buildRequestResultGenerics({ node, types }) // "LoginUserResponses, ThrowOnError, { '200': LoginUserStatus200Headers }"`
+ */
+export function buildRequestResultGenerics({ node, types }: { node: ast.OperationNode; types: OperationTypeNames }): string {
+  return [types.response.responses(node), 'ThrowOnError', buildResponseHeadersType({ node, types })].filter(Boolean).join(', ')
+}
+
+/**
+ * Builds the full return type an operation's function signature uses: `Unwrappable<RequestResult>`
+ * for the default `returnType: 'full'`, already a promise so no further wrapping is needed, a plain
+ * `Promise<RequestResult>` for the internal `'plain'` shape, or a
+ * `Promise` of the runtime's `UnwrappedResult` when `returnType: 'data'` narrows a resolved call
+ * down to the bare success body.
+ *
+ * @example
+ * `buildResultType({ node, types, returnType: 'data' }) // 'Promise<UnwrappedResult<AddPetResponses, ThrowOnError>>'`
+ */
+export function buildResultType({ node, types, returnType }: { node: ast.OperationNode; types: OperationTypeNames; returnType: ReturnTypeOption }): string {
+  const name = returnType === 'data' ? 'UnwrappedResult' : 'RequestResult'
+  const result = buildResultTypeRef(name, types.response.responses(node), buildResponseHeadersType({ node, types }), ['ThrowOnError'])
+  return returnType === 'full' ? `Unwrappable<${result}>` : `Promise<${result}>`
+}

package/src/builders/operationBody.ts

@@ -0,0 +1,43 @@
+import type { ast } from '@kubb/kit'
+import type { OperationTypeNames } from '@internals/client'
+import type { ReturnTypeOption } from '../types.ts'
+import { buildCallConfig } from './callConfig.ts'
+import { buildEventStreamReturn, buildReturnStatement } from './returnStatement.ts'
+import type { SecurityRequirement } from './security.ts'
+import { buildGroupedOptionsSignature } from './signature.ts'
+import type { ValidatorHooks } from './validator.ts'
+
+/**
+ * The pieces of a generated operation: its generics, `options` parameter, return type, return statement, and whether the
+ * body destructures `contentType` from `options`. Shared by the standalone functions and the SDK methods, so a
+ * streamed operation is wired to `apiClient.stream` in one place.
+ */
+export function buildOperationBody({
+  node,
+  types,
+  validatorHooks,
+  security,
+  baseURL,
+  returnType,
+  throwOnErrorDefault,
+}: {
+  node: ast.HttpOperationNode
+  types: OperationTypeNames
+  validatorHooks: ValidatorHooks | null
+  security?: Array<SecurityRequirement>
+  baseURL?: string
+  returnType: ReturnTypeOption
+  throwOnErrorDefault: boolean
+}): { generics: Array<string>; paramsSignature: string; returnType: string; statement: string; mergeContentType: boolean } {
+  const { callConfig, mergeContentType, eventStream } = buildCallConfig({ node, validatorHooks, security, baseURL, throwOnErrorDefault, returnType })
+  const signature = buildGroupedOptionsSignature({ node, types, returnType, throwOnErrorDefault, eventStream })
+  const stream = eventStream ? buildEventStreamReturn({ node, types, callConfig, returnType, throwOnErrorDefault }) : null
+
+  return {
+    generics: signature.generics,
+    paramsSignature: signature.paramsSignature,
+    returnType: stream?.returnType ?? signature.returnType,
+    statement: stream?.statement ?? buildReturnStatement({ node, types, callConfig, returnType, throwOnErrorDefault }),
+    mergeContentType,
+  }
+}