@kubb/plugin-axios 6.0.2 → 6.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.cjs CHANGED
@@ -7,11 +7,11 @@ let _kubb_kit = require("@kubb/kit");
7
7
  let _kubb_plugin_client = require("@kubb/plugin-client");
8
8
  // kubb-extension.json
9
9
  var compatibility = {
10
- "kubb": ">=5.18.4",
10
+ "kubb": ">=5.19.0",
11
11
  "node": ">=22.22"
12
12
  };
13
13
  // package.json
14
- var version = "6.0.2";
14
+ var version = "6.0.4";
15
15
  // src/plugin.ts
16
16
  /**
17
17
  * Canonical plugin name for `@kubb/plugin-axios`. Used for driver lookups and cross-plugin
package/dist/index.js CHANGED
@@ -3,11 +3,11 @@ import { defineExtension } from "@kubb/kit";
3
3
  import { clientDependencies, resolveClientOptions, setupClient } from "@kubb/plugin-client";
4
4
  // kubb-extension.json
5
5
  var compatibility = {
6
- "kubb": ">=5.18.4",
6
+ "kubb": ">=5.19.0",
7
7
  "node": ">=22.22"
8
8
  };
9
9
  // package.json
10
- var version = "6.0.2";
10
+ var version = "6.0.4";
11
11
  // src/plugin.ts
12
12
  /**
13
13
  * Canonical plugin name for `@kubb/plugin-axios`. Used for driver lookups and cross-plugin
@@ -1,145 +1,110 @@
1
1
  # Call operations
2
2
 
3
- The generated client accepts grouped request options on every operation and returns a typed `RequestResult` by default.
3
+ Call a generated function with grouped request options, read the typed result, and pass content types or native axios settings for one call.
4
4
 
5
5
  ## Call an operation
6
6
 
7
- Pass parameters under `path`, `query`, `headers`, `cookies`, or `body`, matching the OpenAPI operation.
7
+ Pass each request part under its own key: `path`, `query`, `headers`, `cookies`, or `body`. A key exists only when the operation declares that part:
8
8
 
9
9
  ```typescript
10
10
  import { getPetById } from './gen/clients/getPetById'
11
+ import { updatePet } from './gen/clients/updatePet'
11
12
 
12
13
  const { data } = await getPetById({ path: { petId: 1 } })
13
14
  // ^ the parsed pet, typed from the 200 response
14
- ```
15
-
16
- The examples set [`integerType: 'number'`](https://kubb.dev/extensions/kubb-labs/adapter-oas/options#integertype) on the adapter, so an `int64` id such as `petId` is a `number`. With the default it is a `bigint` and the call takes `1n`.
17
-
18
- Path keys keep the names from the spec, so a `{pet-id}` placeholder is passed as `path: { 'pet-id': 1 }`. Set [`pathParamsCasing: 'camelcase'`](https://kubb.dev/extensions/kubb-labs/adapter-oas/options#pathparamscasing) on the adapter (`@kubb/adapter-oas` 5.20.0 or later) to pass `path: { petId: 1 }` instead, the name MSW handlers and query keys already use. The HTTP request stays the same.
19
-
20
- Query, header, and cookie parameters sit under their own keys, and a request body goes under
21
- `body`:
22
-
23
- ```typescript
24
- import { searchPets } from './gen/clients/searchPets'
25
- import { updatePet } from './gen/clients/updatePet'
26
15
 
27
- await searchPets({
28
- query: { status: 'available', category: 'dogs', limit: 10, offset: 0 },
29
- })
16
+ await updatePet({ path: { petId: 1 }, headers: { 'X-Request-ID': 'r-1' }, body: { name: 'Rex', status: 'sold' } })
30
17
 
31
- await updatePet({
32
- path: { petId: '123' },
33
- headers: { 'X-Request-ID': 'req-123456' },
34
- body: { name: 'Updated name', status: 'sold' },
35
- })
18
+ await getStatus() // no required parameters, no argument
36
19
  ```
37
20
 
38
- Each key only appears when the operation declares it. You can call an operation without required parameters with no argument: `getStatus()`.
21
+ Path keys keep the spec's names, so `{pet-id}` takes `path: { 'pet-id': 1 }`. Set [`pathParamsCasing: 'camelcase'`](https://kubb.dev/extensions/kubb-labs/adapter-oas/options#pathparamscasing) on the adapter (`@kubb/adapter-oas` 5.20.0 or later) to pass `petId` instead.
22
+
23
+ > [!NOTE]
24
+ > The examples set [`integerType: 'number'`](https://kubb.dev/extensions/kubb-labs/adapter-oas/options#integertype). With the default `bigint`, an `int64` id takes `1n`.
39
25
 
40
26
  ## Read the result
41
27
 
42
- A resolved call returns a `RequestResult` discriminated by the numeric `status`:
28
+ A call resolves to a `RequestResult`, a union narrowed by the numeric `status`:
43
29
 
44
30
  ```typescript
45
31
  type RequestResult = {
46
32
  status: number
47
33
  data: TData // the parsed success body, undefined on an error result
48
34
  error: TError // the parsed error body, undefined on a success result
49
- contentType: string | undefined // the negotiated response media type
35
+ contentType: string | undefined // the response media type, without parameters
50
36
  headers: Headers // the response headers
51
37
  request: AxiosRequestConfig // the native request config
52
38
  response: AxiosResponse // the native response
53
39
  }
54
40
  ```
55
41
 
56
- When `throwOnError` is `true` (the generated default), a resolved call is always a success, so you
57
- read `data` straight away:
58
-
59
- ```typescript
60
- const { data, status, response } = await getPetById({ path: { petId: 1 } })
61
-
62
- console.info(status) // 200
63
- console.info(response.headers['x-ratelimit-remaining'])
64
- ```
65
-
66
- When an operation documents more than one success status, narrow on `status` to reach the body
67
- for that case, and TypeScript follows the check:
42
+ With the default `throwOnError: true`, a resolved call is always a success. Narrow on `status` when an operation has several success statuses:
68
43
 
69
44
  ```typescript
70
45
  const result = await getPetById({ path: { petId: 1 } })
71
46
 
72
- if (result.status === 200) {
73
- console.info(result.data)
74
- }
47
+ console.info(result.headers.get('x-ratelimit-remaining')) // suggests the declared header names
48
+ if (result.status === 200) console.info(result.data)
75
49
  ```
76
50
 
77
51
  ## Unwrap the success body
78
52
 
79
- Call `.unwrap()` to return the success body. Awaiting the operation directly returns the full result.
53
+ Call `.unwrap()` to get only the success body:
80
54
 
81
55
  ```typescript
82
- import { getPetById } from './gen/clients/getPetById'
83
-
84
56
  const pet = await getPetById({ path: { petId: 1 } }).unwrap()
85
- // ^ the parsed pet, not the full RequestResult
57
+ // ^ the parsed pet
86
58
  ```
87
59
 
88
- With `throwOnError: true`, a non-2xx response throws the same `ResponseError` a plain `await` would. With `throwOnError: false`, `.unwrap()` rejects with the parsed error body instead:
60
+ | `throwOnError` | A non-2xx response makes `.unwrap()` |
61
+ | ---------------- | ------------------------------------------------- |
62
+ | `true` (default) | throw a `ResponseError`, as a plain `await` does. |
63
+ | `false` | reject with the parsed error body. |
89
64
 
90
- ```typescript
91
- try {
92
- const pet = await getPetById({ path: { petId: 1 }, throwOnError: false }).unwrap()
93
- } catch (error) {
94
- // the parsed error body, not a ResponseError
95
- console.error(error)
96
- }
97
- ```
65
+ To get the body from every call, set [`returnType: 'data'`](https://kubb.dev/extensions/kubb-labs/plugin-axios/options#returntype) on the plugin.
98
66
 
99
67
  ## Set the content type
100
68
 
101
- When an operation accepts or returns more than one media type, set `contentType` on the call. A
102
- bare string sets the request content type. The object form also sends an `Accept` header for the
103
- response:
69
+ When an operation accepts or returns several content types, set `contentType` on the call. A string sets `Content-Type`, and `response` sets `Accept`:
104
70
 
105
- ```typescript
106
- await uploadAvatar({
107
- path: { petId: '123' },
108
- body: avatarBlob,
109
- contentType: 'image/png',
110
- })
111
-
112
- await getPet({
113
- path: { petId: '123' },
114
- contentType: { request: 'application/json', response: 'application/xml' },
115
- })
71
+ ::code-group
72
+
73
+ ```typescript [Request only]
74
+ await uploadAvatar({ path: { petId: 1 }, body: avatarBlob, contentType: 'image/png' })
116
75
  ```
117
76
 
118
- An operation that declares a single content type has it built in, so a multipart upload such as `uploadFile({ path: { petId: '123' }, body: { file: pngBlob } })` needs only the body.
77
+ ```typescript [Request and Accept]
78
+ await getPet({ path: { petId: 1 }, contentType: { request: 'application/json', response: 'application/xml' } })
79
+ ```
119
80
 
120
- ## Pass native client options
81
+ ::
121
82
 
122
- Pass `options` on an operation for native axios settings, such as `timeout`, `proxy`, `maxRedirects`, `decompress`, or `onUploadProgress`:
83
+ ## Pass native axios options
123
84
 
124
- ```typescript [src/app.ts]
125
- import { getPetById } from './gen/clients/getPetById'
85
+ Pass `options` for axios settings such as `timeout`, `proxy`, `maxRedirects`, `decompress`, or `onUploadProgress`:
126
86
 
87
+ ```typescript
127
88
  await getPetById({ path: { petId: 1 }, options: { timeout: 5_000 } })
128
89
  ```
129
90
 
130
- Set `client.setConfig({ options })` for shared defaults. Per-call options take precedence. Kubb keeps control of serialization and HTTP error handling. See [Use a custom transport](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/transport).
91
+ `client.setConfig({ options })` sets shared defaults, and per-call options win. Kubb keeps control of the URL, method, headers, body, and status handling, as [Use a custom transport](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/transport) lists.
131
92
 
132
93
  ## Build a URL without sending
133
94
 
134
- Use `client.getUrl` to build a URL with the same base URL, path interpolation, and query serialization as a request:
95
+ `client.getUrl` builds the URL a request would use, with the same base URL and serialization:
135
96
 
136
97
  ```typescript
137
98
  import { client } from './gen/.kubb/client'
138
99
 
139
- const url = client.getUrl({
140
- url: '/pets/{petId}',
141
- path: { petId: 1 },
142
- query: { fields: 'name' },
143
- })
144
- // https://api.example.com/v1/pets/1?fields=name
100
+ const url = client.getUrl({ url: '/pets/{petId}', path: { petId: 1 }, query: { fields: 'name' } })
101
+ // https://petstore.swagger.io/v2/pets/1?fields=name
145
102
  ```
103
+
104
+ Next, [handle errors](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/error-handling), including `throwOnError: false`.
105
+
106
+ ## Less common cases
107
+
108
+ ### Path parameter casing
109
+
110
+ When you set [`pathParamsCasing: 'camelcase'`](https://kubb.dev/extensions/kubb-labs/adapter-oas/options#pathparamscasing), the HTTP request stays the same, because path parameter names never reach the wire. The exception is the `matrix` style, which sends the name (`;group-id=42`), so an operation with a matrix path parameter keeps its spec names.
@@ -0,0 +1,206 @@
1
+ # Configure requests
2
+
3
+ Set the base URL, credentials, shared headers, and interceptors on the generated client, for every call or for one.
4
+
5
+ ## Where settings apply
6
+
7
+ Every generated function sends through the shared `client` from `.kubb/client.ts`, unless a call passes its own:
8
+
9
+ | Scope | How | Effect |
10
+ | ----------------- | --------------------------- | --------------------------------------------------------------------------------------- |
11
+ | Every call | `client.setConfig({ ... })` | Merges into the shared config. `headers`, `mediaTypes`, and `serializer` merge per key. |
12
+ | A separate client | `createClient({ ... })` | Copies the shared config at creation, without its interceptors. |
13
+ | A child client | `client.extend({ ... })` | Copies the shared config and runs the parent's interceptors first. |
14
+ | One call | The same key on the call | Wins over the client for that call. |
15
+
16
+ The client takes `baseURL`, `headers`, `auth`, `credentials`, `options`, `transport`, `serializer`, `mediaTypes`, `validate`, and `onValidationError`:
17
+
18
+ ```typescript
19
+ import { client, createClient } from './gen/.kubb/client'
20
+ import { getPetById } from './gen/clients/getPetById'
21
+
22
+ client.setConfig({ baseURL: import.meta.env.VITE_API_URL, headers: { 'X-Client': 'web' } })
23
+
24
+ const tenant = createClient({ baseURL: 'https://tenant.example.com', auth: () => tenantToken })
25
+ await getPetById({ path: { petId: 1 }, client: tenant })
26
+
27
+ await getPetById({ path: { petId: 1 }, baseURL: 'http://localhost:3000' })
28
+ ```
29
+
30
+ ## Set the base URL
31
+
32
+ A call uses the first base URL it finds:
33
+
34
+ | Order | Source |
35
+ | ----- | ---------------------------------------------------------------------------------------------------- |
36
+ | 1 | `baseURL` on the call. |
37
+ | 2 | The operation's own `servers`, then its path's `servers`. |
38
+ | 3 | The client passed as `client`. |
39
+ | 4 | `client.setConfig({ baseURL })`. |
40
+ | 5 | The plugin's [`baseURL`](https://kubb.dev/extensions/kubb-labs/plugin-axios/options#baseurl) option. |
41
+
42
+ > [!NOTE]
43
+ > The spec's top-level `servers` URL is never used, even with the `server` option of `adapterOas`.
44
+
45
+ See [Which server a call picks](#which-server-a-call-picks) and [Named servers](#named-servers).
46
+
47
+ ## Authenticate requests
48
+
49
+ Set `auth` to a token, or to a sync or async function that gets each [security scheme](https://spec.openapis.org/oas/v3.1.0#security-scheme-object) of the call. It returns the token, or `undefined` to skip the scheme:
50
+
51
+ ```typescript
52
+ client.setConfig({
53
+ auth: (auth) => (auth.type === 'apiKey' ? apiKey : localStorage.getItem('token') ?? undefined),
54
+ })
55
+ ```
56
+
57
+ By default, `auth` adds no credentials. The scheme decides where the token goes:
58
+
59
+ | Scheme in the spec | `auth` gets | The token goes to |
60
+ | ------------------ | ---------------------------------------- | ------------------------------- |
61
+ | `http` bearer | `{ type: 'http', scheme: 'bearer' }` | `Authorization: Bearer <token>` |
62
+ | `http` basic | `{ type: 'http', scheme: 'basic' }` | `Authorization: Basic <base64>` |
63
+ | `apiKey` in header | `{ type: 'apiKey', name, in: 'header' }` | the header named `name` |
64
+ | `apiKey` in query | `{ type: 'apiKey', name, in: 'query' }` | the query parameter `name` |
65
+ | `apiKey` in cookie | `{ type: 'apiKey', name, in: 'cookie' }` | the `Cookie` header |
66
+ | `oauth2` | `{ type: 'oauth2', scopes, flows }` | `Authorization: Bearer <token>` |
67
+ | `openIdConnect` | `{ type: 'openIdConnect', scopes, url }` | `Authorization: Bearer <token>` |
68
+
69
+ > [!NOTE]
70
+ > For basic auth, return the raw `username:password`. The runtime base64-encodes it and adds the `Basic` prefix.
71
+
72
+ For a credential that no security scheme describes, such as a request signature, add a request interceptor. See [Several security schemes](#several-security-schemes) and [Mutual TLS](#mutual-tls).
73
+
74
+ ## Add interceptors
75
+
76
+ `client.interceptors` has three stacks. Each handler gets the value the one before it returned:
77
+
78
+ | Stack | Runs | Gets | Returns |
79
+ | ---------- | -------------------------------------------------------------------- | ----------------- | ---------------------------------------------- |
80
+ | `request` | After the URL, body, and auth are built, before the send. | `ResolvedRequest` | The request. |
81
+ | `response` | After the body is decoded, before the status check and validator. | `DecodedResponse` | The result. |
82
+ | `error` | On any failure: `ResponseError`, network error, abort, `ParseError`. | The error | Another error to throw, or nothing to keep it. |
83
+
84
+ ::code-group
85
+
86
+ ```typescript [request]
87
+ client.interceptors.request.use((request) => {
88
+ request.headers['X-Request-ID'] = crypto.randomUUID()
89
+ return request
90
+ })
91
+ ```
92
+
93
+ ```typescript [response]
94
+ client.interceptors.response.use((result) => {
95
+ console.info(`${result.status} ${result.contentType}`)
96
+ return result
97
+ })
98
+ ```
99
+
100
+ ```typescript [error]
101
+ import { client, ResponseError } from './gen/.kubb/client'
102
+
103
+ class NotFoundError extends Error {}
104
+
105
+ client.interceptors.error.use((error) => {
106
+ if (ResponseError.is(error) && error.status === 401) scheduleTokenRefresh()
107
+ if (ResponseError.is(error) && error.status === 404) return new NotFoundError(error.message)
108
+ })
109
+ ```
110
+
111
+ ::
112
+
113
+ `ResolvedRequest` has `url`, `method`, `headers`, `body`, `signal`, `credentials`, `options`, and `stream`. `DecodedResponse` has `data`, `status`, `statusText`, `headers`, `contentType`, `request`, and `response`.
114
+
115
+ Handlers run in the order you register them. `use` returns an id for `eject` and `update`:
116
+
117
+ ```typescript
118
+ const id = client.interceptors.request.use((request) => request)
119
+ client.interceptors.request.update(id, (request) => ({ ...request, headers: { ...request.headers, 'X-Trace': 'on' } }))
120
+ client.interceptors.request.eject(id)
121
+ ```
122
+
123
+ > [!NOTE]
124
+ > With `throwOnError: false`, a non-2xx response resolves, so no error handler runs for it.
125
+
126
+ ### Native axios interceptors
127
+
128
+ For the native `InternalAxiosRequestConfig`, `AxiosResponse`, or `AxiosError`, register on the axios instance that `getAxiosInstance()` returns. Native response interceptors see the raw bytes, before Kubb decodes them:
129
+
130
+ ```typescript
131
+ import { getAxiosInstance } from './gen/.kubb/client'
132
+
133
+ getAxiosInstance().interceptors.request.use((config) => {
134
+ config.headers.set('traceparent', currentTraceparent())
135
+ return config
136
+ })
137
+ ```
138
+
139
+ For the order native and core handlers run in, see [Interceptor order](#interceptor-order).
140
+
141
+ Next, [use a custom transport](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/transport).
142
+
143
+ ## Less common cases
144
+
145
+ ### Which server a call picks
146
+
147
+ When an operation or path has its own `servers`, the [`server.index`](https://kubb.dev/extensions/kubb-labs/adapter-oas/options#server) of `adapterOas` picks the entry, falling back to the first. A relative URL such as `/v2`, or one with `{variable}` placeholders, is skipped, so the call uses the next source in [Set the base URL](#set-the-base-url).
148
+
149
+ The plugin's [`baseURL`](https://kubb.dev/extensions/kubb-labs/plugin-axios/options#baseurl) option is written into `.kubb/config.ts`, which `.kubb/client.ts` passes to `setConfig`.
150
+
151
+ ### Named servers
152
+
153
+ When an OpenAPI 3.2 server has a `name`, `.kubb/client.ts` exports its URL in `servers`:
154
+
155
+ ::code-group
156
+
157
+ ```yaml [petStore.yaml]
158
+ servers:
159
+ - url: https://api.example.com
160
+ name: production
161
+ - url: https://staging.example.com
162
+ name: staging
163
+ ```
164
+
165
+ ```typescript [src/api.ts]
166
+ import { client, servers } from './gen/.kubb/client'
167
+
168
+ client.setConfig({ baseURL: servers.staging })
169
+ ```
170
+
171
+ ::
172
+
173
+ ### Several security schemes
174
+
175
+ When an operation lists several security requirements, the runtime sends the first one whose schemes all get a token. A requirement that needs an API key and a session cookie sends both. A header or query key you set yourself wins over the token. An `oauth2` scheme also passes `metadataUrl` to `auth` when the spec has one.
176
+
177
+ `.kubb/client.ts` exports the spec's schemes by name as `securitySchemes`, and each generated call points at its own, with the scopes it needs:
178
+
179
+ ```typescript
180
+ security: [{ ...securitySchemes.petstore_auth, scopes: ['write:pets'] }]
181
+ ```
182
+
183
+ ### Mutual TLS
184
+
185
+ When the spec has a `mutualTLS` scheme, `securitySchemes` leaves it out, because its credential is a client certificate on the connection, not on the request. In Node.js, give an axios instance the certificate:
186
+
187
+ ```typescript
188
+ import { readFileSync } from 'node:fs'
189
+ import { Agent } from 'node:https'
190
+ import axios from 'axios'
191
+ import { client, createAxiosTransport } from './gen/.kubb/client'
192
+
193
+ const instance = axios.create({ httpsAgent: new Agent({ cert: readFileSync('client.crt'), key: readFileSync('client.key') }) })
194
+
195
+ client.setConfig({ transport: createAxiosTransport(instance) })
196
+ ```
197
+
198
+ In the browser, the browser picks the client certificate itself.
199
+
200
+ ### Interceptor order
201
+
202
+ When you register [native axios interceptors](#native-axios-interceptors) next to `client.interceptors`:
203
+
204
+ - Native request interceptors run after the `client.interceptors.request` handlers, in reverse order of registration, as axios runs them.
205
+ - Native response interceptors see the raw bytes, before Kubb decodes them.
206
+ - An instance you pass to `createAxiosTransport` keeps its own interceptors.