@kubb/plugin-axios 6.0.3 → 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 +2 -2
- package/dist/index.js +2 -2
- package/docs/guides/calling-operations.md +45 -80
- package/docs/guides/configure-requests.md +206 -0
- package/docs/guides/error-handling.md +73 -81
- package/docs/guides/migrate-to-v6.md +147 -202
- package/docs/guides/serialization.md +135 -91
- package/docs/guides/server-sent-events.md +136 -276
- package/docs/guides/transport.md +53 -30
- package/docs/options.md +72 -85
- package/docs/overview.md +33 -15
- package/kubb-extension.json +1 -1
- package/package.json +2 -2
- package/docs/guides/authentication.md +0 -101
- package/docs/guides/base-url.md +0 -102
- package/docs/guides/interceptors.md +0 -109
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.
|
|
10
|
+
"kubb": ">=5.19.0",
|
|
11
11
|
"node": ">=22.22"
|
|
12
12
|
};
|
|
13
13
|
// package.json
|
|
14
|
-
var version = "6.0.
|
|
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.
|
|
6
|
+
"kubb": ">=5.19.0",
|
|
7
7
|
"node": ">=22.22"
|
|
8
8
|
};
|
|
9
9
|
// package.json
|
|
10
|
-
var version = "6.0.
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
73
|
-
|
|
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
|
|
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
|
|
57
|
+
// ^ the parsed pet
|
|
86
58
|
```
|
|
87
59
|
|
|
88
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
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
|
-
|
|
77
|
+
```typescript [Request and Accept]
|
|
78
|
+
await getPet({ path: { petId: 1 }, contentType: { request: 'application/json', response: 'application/xml' } })
|
|
79
|
+
```
|
|
119
80
|
|
|
120
|
-
|
|
81
|
+
::
|
|
121
82
|
|
|
122
|
-
Pass
|
|
83
|
+
## Pass native axios options
|
|
123
84
|
|
|
124
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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.
|