@kubb/plugin-axios 5.5.10 → 5.5.12

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`. The client switches to the axios fetch adapter for these calls unless you set `adapter` yourself, because the default XHR adapter buffers the whole body.
+
+## 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-axios/guides/calling-operations)
+- [Handle errors](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/error-handling)

package/docs/guides/transport.md

@@ -0,0 +1,50 @@
+# 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 an `AxiosInstance`. The default is `axios.create()`, and you can replace it with your own pre-configured instance. Use interceptors for request headers or response logging.
+
+```typescript
+type ClientConfig = {
+  // ...
+  transport?: AxiosInstance
+}
+```
+
+Kubb forwards the resolved URL, query, body, and authentication to the instance.
+
+## Pass a pre-configured instance
+
+Give the client an instance with a timeout, default headers, and a logging interceptor:
+
+```typescript
+import axios from 'axios'
+import { client } from './gen/.kubb/client'
+
+const instance = axios.create({
+  timeout: 10_000,
+  headers: { 'X-Client': 'kubb' },
+})
+
+instance.interceptors.response.use((response) => {
+  console.info(`${response.config.method?.toUpperCase()} ${response.config.url} -> ${response.status}`)
+  return response
+})
+
+client.setConfig({ transport: instance })
+```
+
+Every generated function now sends through your instance, so its timeout, headers, and interceptors apply to each call. Interceptors registered through `client.interceptors` move to the new instance and keep their IDs for `eject` and `update`.
+
+> [!NOTE]
+> Kubb sets `transformRequest`, `paramsSerializer`, and `validateStatus` on each request for its own serialization and `throwOnError` handling, so leave those fields alone. Set timeouts, retries, and interceptors on the instance. For one call, pass `options`, such as `{ timeout }` or `{ onUploadProgress }`, instead of building a new instance.
+
+## 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-axios/guides/interceptors)
+- [Set the base URL](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/base-url)
+- [Call operations](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/calling-operations)

package/docs/options.md

@@ -0,0 +1,173 @@
+# Options
+
+Pass these options to `pluginAxios()`. 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)                                                             | Emit a class-based SDK instead of standalone 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, with no server-URL fallback. A value with a `${...}` interpolation is emitted as a template literal, 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 pluginAxios({ 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. Skips validation and casts the response to the generated type.
+:::
+
+:::field{name="'zod'"}
+Validates the success response body and, when a non-2xx call does not throw, the error body.
+:::
+
+:::field{name="{ request?: 'zod', response?: 'zod' }"}
+Enables validation separately for requests and responses.
+:::
+
+::
+
+```typescript [kubb.config.ts]
+import { defineConfig } from 'kubb/config'
+import { pluginTs } from '@kubb/plugin-ts'
+import { pluginZod } from '@kubb/plugin-zod'
+import { pluginAxios } from '@kubb/plugin-axios'
+
+export default defineConfig({
+  input: './petStore.yaml',
+  output: { path: './src/gen' },
+  plugins: [
+    pluginTs(),
+    pluginZod(),
+    pluginAxios({ 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-axios/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
+pluginAxios({ 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 read `result.response.headers`.
+
+### 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 @@
+# Axios
+
+The Axios plugin turns each operation in your OpenAPI spec into a typed async function that sends the request with axios. 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.
+- Install `axios` 1.20 or a later v1 release in the app that uses the generated code.
+
+## 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-axios/options) for every option and its default.
+
+## Example
+
+The config below generates an axios 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 { pluginAxios } from '@kubb/plugin-axios'
+
+export default defineConfig({
+  input: './petStore.yaml',
+  output: { path: './src/gen' },
+  plugins: [
+    pluginTs(),
+    pluginAxios({ baseURL: 'https://petstore.swagger.io/v2' }),
+  ],
+})
+```

package/kubb-extension.json

@@ -10,9 +10,16 @@
     "light": "https://kubb.dev/feature/axios.svg"
   },
   "tags": ["api-client", "axios", "http-client", "codegen", "openapi", "validator"],
-  "docs": "https://kubb.dev/plugins/plugin-axios",
+  "docs": "https://kubb.dev/extensions/kubb-labs/plugin-axios",
+  "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-axios",
-  "version": "5.5.10",
+  "version": "5.5.12",
   "description": "Generate a slim, type-safe HTTP client with Kubb based on axios.",
   "keywords": [
     "api-client",
@@ -13,7 +13,7 @@
     "swagger",
     "typescript"
   ],
-  "homepage": "https://kubb.dev/plugins/plugin-axios",
+  "homepage": "https://kubb.dev/extensions/kubb-labs/plugin-axios",
   "license": "MIT",
   "author": "stijnvanhulle",
   "repository": {
@@ -40,7 +40,7 @@
     "dist",
     "templates",
     "kubb-extension.json",
-    "OVERVIEW.md",
+    "docs",
     "!/**/**.test.**",
     "!/**/__tests__/**",
     "!/**/__snapshots__/**"
@@ -68,19 +68,19 @@
     "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",
     "axios": "^1.20.0",
-    "kubb": "^5.8.1",
+    "kubb": "^5.8.3",
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
     "axios": "^1.20.0",
-    "kubb": "^5.8.1"
+    "kubb": "^5.8.3"
   },
   "peerDependenciesMeta": {
     "axios": {

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 pluginAxiosName = 'plugin-axios' satisfies PluginAxios['name']
  * })
  * ```
  */
-export const pluginAxios = definePlugin<PluginAxios>({
+export const pluginAxios = defineExtension<PluginAxios>({
+  kind: 'plugin',
   meta: { name: pluginAxiosName, 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 @@
-# Axios
-
-Generates a type-safe HTTP client based on axios 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`.
-- Install axios v1 or higher in the app that uses the generated code.
-
-## 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`.