@kubb/plugin-fetch 5.5.9 → 5.5.11

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

@@ -0,0 +1,99 @@
+# Server-sent events
+
+Operations returning `text/event-stream` produce a typed stream rather than a `RequestResult`.
+
+## Consume a stream
+
+Read the `EventStreamResult.stream` with `for await`:
+
+```typescript
+import { streamEvents } from './gen/clients/streamEvents'
+
+const { stream } = await streamEvents({})
+
+for await (const event of stream) {
+  console.info(event.data)
+}
+```
+
+`data` is typed from the operation's response schema. Each event also carries the optional SSE
+fields, so you can branch on the event name or read the id:
+
+```typescript
+type ServerSentEvent<TData> = {
+  data: TData
+  event?: string
+  id?: string
+  retry?: number
+}
+```
+
+The runtime parses each event's `data` as JSON when it is valid and keeps it as the raw string
+otherwise.
+
+## Stop early
+
+Break out of the loop to stop reading. The underlying reader is canceled when the iterator
+finishes, so an early `break` releases the stream:
+
+```typescript
+const { stream } = await streamEvents({})
+
+for await (const event of stream) {
+  if (event.event === 'done') break
+  render(event.data)
+}
+```
+
+To stop a stream from outside the loop, pass an `AbortSignal` and abort it. Aborting ends the
+request and the iteration:
+
+```typescript
+const controller = new AbortController()
+const { stream } = await streamEvents({ signal: controller.signal })
+
+// elsewhere, for example on component unmount
+controller.abort()
+```
+
+## Read the response
+
+Read status and headers from the native `response` before iterating:
+
+```typescript
+const { stream, response } = await streamEvents({})
+
+console.info(response.status) // 200
+console.info(response.headers.get('x-stream-id'))
+
+for await (const event of stream) {
+  handle(event.data)
+}
+```
+
+## Handle errors
+
+Catch non-2xx responses around the call and iteration, and rethrow other errors such as connection failures:
+
+```typescript
+import { ResponseError } from './gen/.kubb/client'
+
+try {
+  const { stream } = await streamEvents({})
+  for await (const event of stream) {
+    handle(event.data)
+  }
+} catch (error) {
+  if (!ResponseError.is(error)) throw error
+  console.error('stream rejected', error.status)
+}
+```
+
+> [!NOTE]
+> A drop mid-stream ends the `for await` loop. Track the last event's `id` if you need to reconnect
+> from where the stream stopped.
+
+## See also
+
+- [Call operations](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/calling-operations)
+- [Handle errors](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/error-handling)

package/docs/guides/transport.md

@@ -0,0 +1,71 @@
+# Use a custom transport
+
+Set a transport at runtime to replace the network send. The client still builds URLs, serializes parameters, resolves authentication, and handles results.
+
+The transport is a function. Use interceptors for request headers or response logging.
+
+## Write a transport function
+
+`@kubb/plugin-fetch` types the transport as a function that receives a fully resolved request and returns a result:
+
+```typescript
+type Transport = (request: ResolvedRequest) => Promise<TransportResult>
+
+type ResolvedRequest = {
+  url: string
+  method: string
+  headers: Record<string, string>
+  body?: RequestBody
+  signal?: AbortSignal
+  credentials?: RequestCredentials
+  options?: FetchOptions
+  responseType?: ResponseType
+}
+
+type TransportResult<TData = unknown> = {
+  data: TData
+  status: number
+  statusText: string
+  headers: Headers
+  contentType?: string
+  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.
+
+## Mock the network in tests
+
+Return a fixed result from an isolated client in tests:
+
+```typescript
+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(),
+  }),
+})
+
+const { data } = await getPetById({ path: { petId: 1 }, client: testClient })
+//      ^ { id: 1, name: 'Fluffy' }
+```
+
+Pass the isolated client per operation or to a query plugin.
+
+## Where to set it
+
+Use `client.setConfig({ transport })` for shared configuration, `createClient({ transport })` for an isolated instance, or pass `transport` on an operation to override it for one call.
+
+## See also
+
+- [Add interceptors](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/interceptors)
+- [Set the base URL](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/base-url)
+- [Call operations](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/calling-operations)

package/docs/options.md

@@ -0,0 +1,173 @@
+# Options
+
+Pass these options to `pluginFetch()`. Shared options link to [Shared plugin options](https://kubb.dev/docs/5.x/reference/plugin-options).
+
+## Options overview
+
+| Option                                                                    | Purpose                                                                | Default                                          |
+| ------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------ |
+| [`output`](https://kubb.dev/docs/5.x/reference/plugin-options#output)     | Where files are written: `path`, `mode`, `barrel`, `banner`, `footer`. | `{ path: 'clients', barrel: { type: 'named' } }` |
+| [`group`](https://kubb.dev/docs/5.x/reference/plugin-options#group)       | Split output by tag or path: `type`, `name`.                           | None                                             |
+| [`baseURL`](#baseurl)                                                     | Base URL prepended to every request.                                   | None                                             |
+| [`throwOnErrorDefault`](#throwonerrordefault)                             | Default error behavior and return type for generated operations.       | `true`                                           |
+| [`validator`](#validator)                                                 | Validate request and response bodies with Zod.                         | `false`                                          |
+| [`sdk`](#sdk)                                                             | Generate a class-based SDK instead of functions.                       | None                                             |
+| [`returnType`](#returntype)                                               | Shape of the value a generated call resolves to.                       | `'full'`                                         |
+| [`include`](https://kubb.dev/docs/5.x/reference/plugin-options#include)   | Keep only operations that match.                                       | None                                             |
+| [`exclude`](https://kubb.dev/docs/5.x/reference/plugin-options#exclude)   | Skip operations that match.                                            | `[]`                                             |
+| [`override`](https://kubb.dev/docs/5.x/reference/plugin-options#override) | Apply different options per pattern.                                   | `[]`                                             |
+| [`resolver`](#resolver)                                                   | Customize generated names and file paths.                              | `resolverClient`                                 |
+| [`macros`](https://kubb.dev/docs/5.x/reference/plugin-options#macros)     | Rewrite AST nodes before printing.                                     | `[]`, run after the built-in client macros       |
+
+## Option details
+
+### baseURL
+
+Base URL prepended to every request. When omitted, each request uses the operation's relative path from the spec. A value with a `${...}` interpolation is emitted as a template literal in the generated client config, so `baseURL: '${process.env.API_URL}'` reads the environment variable at runtime.
+
+|          |          |
+| -------- | -------- |
+| Type     | `string` |
+| Required | `false`  |
+
+### throwOnErrorDefault
+
+Set `throwOnErrorDefault: false` to return documented error responses as values by default. It sets the fallback on each generated request and the default `ThrowOnError` type parameter on functions and SDK methods. It applies to the whole plugin, so `override` cannot set it. A call that passes `throwOnError` still wins. With `throwOnError: true`, a non-2xx response throws and the return type narrows to successful responses. Query hooks always pass `throwOnError: true`.
+
+|          |           |
+| -------- | --------- |
+| Type     | `boolean` |
+| Required | `false`   |
+| Default  | `true`    |
+
+```typescript
+// with pluginFetch({ throwOnErrorDefault: false })
+const result = await getPetById({ path: { petId: 1 } })
+if (result.status !== 200) console.error(result.status, result.error)
+```
+
+### validator
+
+Validates request and response bodies with schemas from `@kubb/plugin-zod`, so add `pluginZod()` too. An invalid body makes the generated function throw a `ParseError`.
+
+|          |                                                           |
+| -------- | --------------------------------------------------------- |
+| Type     | `false \| 'zod' \| { request?: 'zod'; response?: 'zod' }` |
+| Required | `false`                                                   |
+| Default  | `false`                                                   |
+
+::field-group
+
+:::field{name="false"}
+Default value. Does no validation and returns the response cast to the generated type.
+:::
+
+:::field{name="'zod'"}
+Validates the success response body, and the error body when a non-2xx call does not throw.
+:::
+
+:::field{name="{ request?: 'zod', response?: 'zod' }"}
+Opts in per direction. `request` validates the request body before the call, and `response` validates the response body after it.
+:::
+
+::
+
+```typescript [kubb.config.ts]
+import { defineConfig } from 'kubb/config'
+import { pluginTs } from '@kubb/plugin-ts'
+import { pluginZod } from '@kubb/plugin-zod'
+import { pluginFetch } from '@kubb/plugin-fetch'
+
+export default defineConfig({
+  input: './petStore.yaml',
+  output: { path: './src/gen' },
+  plugins: [
+    pluginTs(),
+    pluginZod(),
+    pluginFetch({ validator: { request: 'zod', response: 'zod' } }),
+  ],
+})
+```
+
+### sdk
+
+Generates a class-based SDK. Each instance takes its own client config, so environments can use separate clients. Leave `sdk` unset to keep the standalone functions that query plugins call.
+
+|          |                                             |
+| -------- | ------------------------------------------- |
+| Type     | `{ mode?: 'tag' \| 'flat'; name?: string }` |
+| Required | `false`                                     |
+
+::field-group
+
+:::field{name="'tag'"}
+Default value for `sdk.mode`. Generates one class per tag, such as `PetClient`. Set `sdk.name` to also get a root class that shares one config, used as `new PetStore(config).pet.getPetById(...)`.
+:::
+
+:::field{name="'flat'"}
+Generates one class named by `sdk.name`, with every operation as a method. Supports single-file output.
+:::
+
+::
+
+`mode: 'tag'` needs one file per tag, so it throws [`KUBB_INVALID_PLUGIN_OPTIONS`](https://kubb.dev/docs/5.x/reference/diagnostics#kubb-invalid-plugin-options) with single-file output. Use `mode: 'flat'` for a single file.
+
+Methods take the same grouped options and return the same result as the standalone functions. See [Call operations](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/calling-operations).
+
+```typescript
+const pet = new PetClient({ baseURL: 'https://petstore.swagger.io/v2' })
+const { data } = await pet.getPetById({ path: { petId: 1 } })
+```
+
+### returnType
+
+Shape of the value a generated call resolves to.
+
+|          |                    |
+| -------- | ------------------ |
+| Type     | `'full' \| 'data'` |
+| Required | `false`            |
+| Default  | `'full'`           |
+
+::field-group
+
+:::field{name="'full'"}
+Default value. Returns `{ status, data, error, contentType, request, response }`.
+:::
+
+:::field{name="'data'"}
+Returns the success body when `throwOnError` is `true`. With `throwOnError: false`, returns the full result so callers can tell errors from successes.
+:::
+
+::
+
+```typescript
+pluginFetch({ returnType: 'data' })
+
+const pet = await getPetById({ path: { petId: 1 } }) // Pet, not { status, data, ... }
+```
+
+It applies to the functions and the SDK. The query plugins and `@kubb/plugin-mcp` read it too, including a per-operation value set through [`override`](https://kubb.dev/docs/5.x/reference/plugin-options#override). To read headers such as `ETag` under `'data'`, pass `throwOnError: false` and call `result.response.headers.get('etag')`.
+
+### resolver
+
+Overrides generated file and symbol names. Omitted members keep `resolverClient`. The shared members (`name`, `file`, `imports`) and the `this` context are described under [`resolver`](https://kubb.dev/docs/5.x/reference/plugin-options#resolver).
+
+|          |                                 |
+| -------- | ------------------------------- |
+| Type     | `ResolverPatch<ResolverClient>` |
+| Required | `false`                         |
+
+```typescript [Partial override]
+type ResolverClientPatch = {
+  name?(name: string): string
+  file?: {
+    baseName?(params: { name: string; extname: string }): string
+    path?(params: { baseName: string; output: Output }): string
+  }
+  imports?(options: ResolveImportsOptions): Array<ImportNode>
+  className?(name: string): string
+  groupName?(name: string): string     // → 'PetClient'
+  propertyName?(name: string): string
+}
+```

package/docs/overview.md

@@ -0,0 +1,40 @@
+# Fetch
+
+The Fetch plugin turns each operation in your OpenAPI spec into a typed async function that sends the request with the native Fetch API. Each function takes grouped `path`, `query`, `headers`, and `body` parameters and returns a result keyed by status code.
+
+The query plugins (`@kubb/plugin-react-query`, `@kubb/plugin-vue-query`, and `@kubb/plugin-swr`) and `@kubb/plugin-mcp` call these functions. The plugin also copies its runtime files (`client.ts`, `serializers.ts`, and `standardSchema.ts`) to `.kubb/` in the root output folder.
+
+## Setup
+
+- 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. Without the plugin, `validator` does nothing.
+- No HTTP client package is needed. The generated code calls the global `fetch`.
+
+## Options worth knowing
+
+- `baseURL` is prepended to every request. The spec's `servers` URL is not used, so without `baseURL` you set one at runtime with `client.setConfig({ baseURL })`.
+- `validator: 'zod'` validates response bodies with the schemas from `@kubb/plugin-zod`. Use `{ request: 'zod', response: 'zod' }` to also validate request bodies.
+- `throwOnErrorDefault: false` returns non-2xx responses as values instead of throwing. A single call can still pass `throwOnError`.
+- `returnType: 'data'` makes a call resolve to the success body instead of the full result. With `throwOnError: false`, the call still returns the full result.
+- `sdk` generates a class-based SDK, grouped by tag or flat, instead of standalone functions. The query plugins and `@kubb/plugin-mcp` need the standalone functions, so leave `sdk` unset when you use them.
+
+See [Options](https://kubb.dev/extensions/kubb-labs/plugin-fetch/options) for every option and its default.
+
+## Example
+
+The config below generates a Fetch client that sends every request to the Petstore API.
+
+```typescript [kubb.config.ts]
+import { defineConfig } from 'kubb/config'
+import { pluginTs } from '@kubb/plugin-ts'
+import { pluginFetch } from '@kubb/plugin-fetch'
+
+export default defineConfig({
+  input: './petStore.yaml',
+  output: { path: './src/gen' },
+  plugins: [
+    pluginTs(),
+    pluginFetch({ baseURL: 'https://petstore.swagger.io/v2' }),
+  ],
+})
+```

package/kubb-extension.json

@@ -10,9 +10,16 @@
     "light": "https://kubb.dev/feature/javascript.svg"
   },
   "tags": ["api-client", "fetch", "http-client", "codegen", "openapi", "validator"],
-  "docs": "https://kubb.dev/plugins/plugin-fetch",
+  "docs": "https://kubb.dev/extensions/kubb-labs/plugin-fetch",
+  "maintainers": [
+    {
+      "name": "Stijn Van Hulle",
+      "github": "stijnvanhulle"
+    }
+  ],
+  "dependencies": ["plugin-ts"],
   "compatibility": {
-    "kubb": ">=5.8.0",
+    "kubb": ">=5.8.3",
     "node": ">=22"
   },
   "role": "client",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/plugin-fetch",
-  "version": "5.5.9",
+  "version": "5.5.11",
   "description": "Generate a slim, type-safe HTTP client with Kubb based on the native Fetch api.",
   "keywords": [
     "api-client",
@@ -13,7 +13,7 @@
     "swagger",
     "typescript"
   ],
-  "homepage": "https://kubb.dev/plugins/plugin-fetch",
+  "homepage": "https://kubb.dev/extensions/kubb-labs/plugin-fetch",
   "license": "MIT",
   "author": "stijnvanhulle",
   "repository": {
@@ -40,7 +40,7 @@
     "dist",
     "templates",
     "kubb-extension.json",
-    "OVERVIEW.md",
+    "docs",
     "!/**/**.test.**",
     "!/**/__tests__/**",
     "!/**/__snapshots__/**"
@@ -68,17 +68,17 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@kubb/plugin-ts": "^5.0.8",
-    "@kubb/plugin-zod": "^5.4.6"
+    "@kubb/plugin-ts": "^5.0.10",
+    "@kubb/plugin-zod": "^5.4.8"
   },
   "devDependencies": {
     "@internals/client": "0.0.0",
     "@internals/shared": "0.0.0",
-    "kubb": "^5.8.1",
+    "kubb": "^5.8.3",
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "kubb": "^5.8.1"
+    "kubb": "^5.8.3"
   },
   "engines": {
     "node": ">=22"

package/src/plugin.ts

@@ -1,7 +1,7 @@
 import path from 'node:path'
 import { createSdkGenerator, defaultMacros, resolverClient } from '@internals/client'
 import { createGroupConfig } from '@internals/shared'
-import { addGenerator, definePlugin, injectFile, Resolver, setMacros, setResolver, useConfig } from 'kubb/kit'
+import { addGenerator, defineExtension, injectFile, Resolver, setMacros, setResolver, useConfig } from 'kubb/kit'
 import { compatibility } from '../kubb-extension.json'
 import { version } from '../package.json'
 import { pluginTsName } from '@kubb/plugin-ts'
@@ -38,7 +38,8 @@ export const pluginFetchName = 'plugin-fetch' satisfies PluginFetch['name']
  * })
  * ```
  */
-export const pluginFetch = definePlugin<PluginFetch>({
+export const pluginFetch = defineExtension<PluginFetch>({
+  kind: 'plugin',
   meta: { name: pluginFetchName, version, compatibility },
   // Both are ordering hints, skipped when the plugin is not in the pipeline. `plugin-ts` supplies
   // the operation types unless it is absent, in which case `pluginZod({ inferred: true })` does.

package/OVERVIEW.md

@@ -1,19 +0,0 @@
-# Fetch
-
-Generates a type-safe HTTP client based on the native Fetch API from your OpenAPI spec. Each operation becomes one async function with grouped `path`, `query`, `headers`, and `body` parameters and a result keyed by status code.
-
-This plugin provides the client runtime. Query plugins such as `@kubb/plugin-react-query`, `@kubb/plugin-vue-query`, `@kubb/plugin-swr`, and `@kubb/plugin-mcp` call the functions it generates.
-
-## Setup
-
-- Add `@kubb/plugin-ts` for the operation types. Without it, `@kubb/plugin-zod` with `inferred: true` supplies them.
-- Add `@kubb/plugin-zod` when you set `validator`.
-- No HTTP client package is needed.
-
-## Options worth knowing
-
-- `baseURL` is prepended to every request.
-- `validator: 'zod'` validates request and response bodies with the schemas from `@kubb/plugin-zod`.
-- `sdk` generates a class-based SDK, grouped by tag or flat, instead of standalone functions. Query plugins need the standalone functions, so leave `sdk` unset when you use them.
-- `returnType: 'data'` makes a call resolve to the success body instead of the full result with status, data, and error.
-- `throwOnErrorDefault: false` returns documented error responses as values instead of throwing. A single call can still pass `throwOnError`.