@kubb/plugin-fetch 5.5.8 → 5.5.10

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,200 @@
+# 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`                                          |
+| [`comments`](#comments)                                                   | How much of each description reaches the JSDoc.                        | `'full'`                                         |
+| [`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' } }),
+  ],
+})
+```
+
+### comments
+
+Controls generated JSDoc.
+
+|          |                               |
+| -------- | ----------------------------- |
+| Type     | `'full' \| 'brief' \| 'none'` |
+| Required | `false`                       |
+| Default  | `'full'`                      |
+
+::field-group
+
+:::field{name="'full'"}
+Default value. Keeps complete descriptions and tags.
+:::
+
+:::field{name="'brief'"}
+Keeps the first sentence and other tags. Descriptions over 150 characters without a sentence ending are cut at the last word before 120.
+:::
+
+:::field{name="'none'"}
+Omits JSDoc but keeps the generated-by banner.
+:::
+
+::
+
+### 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,41 @@
+# 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`.
+
+## Example
+
+```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' }),
+  ],
+})
+```
+
+## See also
+
+- [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
+- [`@kubb/plugin-ts`](https://kubb.dev/extensions/kubb-labs/plugin-ts)

package/kubb-extension.json

@@ -0,0 +1,198 @@
+{
+  "$schema": "https://kubb.dev/schemas/kubb-extension.json",
+  "kind": "plugin",
+  "name": "plugin-fetch",
+  "export": "pluginFetch",
+  "displayName": "Fetch",
+  "description": "Generates a type-safe Fetch API client from your OpenAPI spec, one async function per operation, so each call stays in sync with the API.",
+  "category": "client",
+  "icon": {
+    "light": "https://kubb.dev/feature/javascript.svg"
+  },
+  "tags": ["api-client", "fetch", "http-client", "codegen", "openapi", "validator"],
+  "docs": "https://kubb.dev/extensions/kubb-labs/plugin-fetch",
+  "maintainers": [
+    {
+      "name": "Stijn Van Hulle",
+      "github": "stijnvanhulle"
+    }
+  ],
+  "dependencies": ["plugin-ts"],
+  "compatibility": {
+    "kubb": ">=5.8.3",
+    "node": ">=22"
+  },
+  "role": "client",
+  "options": [
+    {
+      "key": "outputPath",
+      "path": ["output", "path"],
+      "label": "Output Path",
+      "description": "Output folder for generated files",
+      "type": "text",
+      "default": "clients"
+    },
+    {
+      "key": "barrel",
+      "path": ["output", "barrel"],
+      "label": "Barrel",
+      "description": "How index.ts barrel files are generated",
+      "type": "select",
+      "default": {
+        "type": "named"
+      },
+      "choices": [
+        {
+          "label": "named",
+          "value": {
+            "type": "named"
+          }
+        },
+        {
+          "label": "named (nested)",
+          "value": {
+            "type": "named",
+            "nested": true
+          }
+        },
+        {
+          "label": "all",
+          "value": {
+            "type": "all"
+          }
+        },
+        {
+          "label": "all (nested)",
+          "value": {
+            "type": "all",
+            "nested": true
+          }
+        },
+        {
+          "label": "false (disabled)",
+          "value": false
+        }
+      ]
+    },
+    {
+      "key": "outputMode",
+      "path": ["output", "mode"],
+      "label": "Output Mode",
+      "description": "How the plugin consolidates its code into files. File mode writes everything into a single file, so the output path must include a file extension and cannot be grouped.",
+      "type": "select",
+      "default": "directory",
+      "choices": [
+        {
+          "label": "directory (one file per schema)",
+          "value": "directory"
+        },
+        {
+          "label": "file (single file)",
+          "value": "file"
+        }
+      ]
+    },
+    {
+      "key": "validator",
+      "path": ["validator"],
+      "label": "Validator",
+      "description": "Validate request and response bodies with schemas from @kubb/plugin-zod",
+      "type": "select",
+      "default": false,
+      "choices": [
+        {
+          "label": "false (disabled)",
+          "value": false
+        },
+        {
+          "label": "zod",
+          "value": "zod"
+        }
+      ]
+    },
+    {
+      "key": "group",
+      "path": ["group"],
+      "label": "Group",
+      "description": "Group generated operations by OpenAPI tag or path",
+      "type": "select",
+      "default": null,
+      "choices": [
+        {
+          "label": "none",
+          "value": null
+        },
+        {
+          "label": "by tag",
+          "value": {
+            "type": "tag"
+          }
+        },
+        {
+          "label": "by path",
+          "value": {
+            "type": "path"
+          }
+        }
+      ]
+    },
+    {
+      "key": "excludeTags",
+      "path": ["exclude"],
+      "label": "Exclude Tags",
+      "description": "Comma-separated OpenAPI tags to exclude from generation",
+      "type": "list",
+      "item": {
+        "type": "tag",
+        "pattern": "$item"
+      }
+    },
+    {
+      "key": "includeTags",
+      "path": ["include"],
+      "label": "Include Tags",
+      "description": "Comma-separated OpenAPI tags to include. Only operations with these tags are generated",
+      "type": "list",
+      "item": {
+        "type": "tag",
+        "pattern": "$item"
+      }
+    },
+    {
+      "key": "baseURL",
+      "path": ["baseURL"],
+      "label": "Base URL",
+      "description": "Custom API base URL",
+      "type": "text"
+    },
+    {
+      "key": "sdkMode",
+      "path": ["sdk", "mode"],
+      "label": "SDK Mode",
+      "description": "Group generated operations into an SDK client by tag or flat",
+      "type": "select",
+      "default": null,
+      "choices": [
+        {
+          "label": "off (standalone functions)",
+          "value": null
+        },
+        {
+          "label": "tag",
+          "value": "tag"
+        },
+        {
+          "label": "flat",
+          "value": "flat"
+        }
+      ]
+    },
+    {
+      "key": "sdkName",
+      "path": ["sdk", "name"],
+      "label": "SDK Name",
+      "description": "Root client name for the generated SDK",
+      "type": "text"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/plugin-fetch",
-  "version": "5.5.8",
+  "version": "5.5.10",
   "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": {
@@ -39,6 +39,8 @@
     "src",
     "dist",
     "templates",
+    "kubb-extension.json",
+    "docs",
     "!/**/**.test.**",
     "!/**/__tests__/**",
     "!/**/__snapshots__/**"
@@ -58,6 +60,7 @@
       "require": "./dist/index.cjs"
     },
     "./package.json": "./package.json",
+    "./kubb-extension.json": "./kubb-extension.json",
     "./templates/*": "./templates/*"
   },
   "publishConfig": {
@@ -65,17 +68,17 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@kubb/plugin-ts": "^5.0.7",
-    "@kubb/plugin-zod": "^5.4.5"
+    "@kubb/plugin-ts": "^5.0.9",
+    "@kubb/plugin-zod": "^5.4.7"
   },
   "devDependencies": {
     "@internals/client": "0.0.0",
     "@internals/shared": "0.0.0",
-    "kubb": "^5.8.0",
+    "kubb": "^5.8.3",
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "kubb": "^5.8.0"
+    "kubb": "^5.8.3"
   },
   "engines": {
     "node": ">=22"

package/src/plugin.ts

@@ -1,7 +1,8 @@
 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'
 import { pluginZodName } from '@kubb/plugin-zod'
@@ -37,8 +38,9 @@ export const pluginFetchName = 'plugin-fetch' satisfies PluginFetch['name']
  * })
  * ```
  */
-export const pluginFetch = definePlugin<PluginFetch>({
-  meta: { name: pluginFetchName, version, compatibility: { kubb: '>=5.8.0' } },
+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.
   dependencies: { [pluginTsName]: { optional: true }, [pluginZodName]: { optional: true } },