@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.
@@ -1,102 +0,0 @@
1
- # Set the base URL
2
-
3
- Set `baseURL` on the client plugin or on the generated client.
4
-
5
- > [!NOTE]
6
- > Top-level OpenAPI server URLs do not set the client's `baseURL`, even with the `server` option of `adapterOas`.
7
-
8
- ## Operations with their own server
9
-
10
- A path or operation can declare its own `servers`, such as an upload or streaming host next to the main API. Its URL becomes that operation's default `baseURL`, so the call goes to that host. The `server.index` of `adapterOas` picks the entry, falling back to the first one.
11
-
12
- ```yaml [petStore.yaml]
13
- paths:
14
- /.sse:
15
- servers:
16
- - url: https://echo.websocket.org
17
- get:
18
- operationId: streamEvents
19
- ```
20
-
21
- A relative server URL, such as `/v2`, or one with `{variable}` placeholders is skipped, so the client's `baseURL` applies.
22
-
23
- ## Pick a server by name
24
-
25
- OpenAPI 3.2 lets a server have a `name`. The generated `.kubb/client.ts` exports the document's named servers as `servers`, so you can pick one by name:
26
-
27
- ```yaml [petStore.yaml]
28
- servers:
29
- - url: https://api.example.com
30
- name: production
31
- - url: https://staging.example.com
32
- name: staging
33
- ```
34
-
35
- ```typescript
36
- import { client, servers } from './gen/.kubb/client'
37
-
38
- client.setConfig({ baseURL: servers.staging })
39
- ```
40
-
41
- ## Use the baseURL option
42
-
43
- Pass `baseURL` to `pluginAxios` to set the generated default. Add `pluginTs` for the operation types.
44
-
45
- ```typescript [kubb.config.ts]
46
- import { defineConfig } from 'kubb/config'
47
- import { adapterOas } from '@kubb/adapter-oas'
48
- import { pluginTs } from '@kubb/plugin-ts'
49
- import { pluginAxios } from '@kubb/plugin-axios'
50
-
51
- export default defineConfig({
52
- input: './petStore.yaml',
53
- output: { path: './src/gen' },
54
- adapter: adapterOas({ integerType: 'number' }),
55
- plugins: [
56
- pluginTs(),
57
- pluginAxios({ baseURL: 'https://localhost:8080/api/v1' }),
58
- ],
59
- })
60
- ```
61
-
62
- A value containing a `${...}` interpolation stays dynamic. The plugin emits it as a template literal in the generated client config, so `baseURL: '${process.env.API_URL}'` reads the environment variable when the app runs instead of baking in the build-time value.
63
-
64
- ## Set it at runtime
65
-
66
- Use `client.setConfig` to configure all operations at startup:
67
-
68
- ```typescript
69
- import { client } from './gen/.kubb/client'
70
-
71
- client.setConfig({ baseURL: import.meta.env.VITE_API_URL })
72
- ```
73
-
74
- Use `createClient` for an isolated client, then pass it to an operation:
75
-
76
- ```typescript
77
- import { createClient } from './gen/.kubb/client'
78
- import { getPetById } from './gen/clients/getPetById'
79
-
80
- const staging = createClient({ baseURL: 'https://staging.petstore.swagger.io/v2' })
81
-
82
- const { data } = await getPetById({ path: { petId: 1 }, client: staging })
83
- ```
84
-
85
- Pass `baseURL` on a single call to override the client for that one request:
86
-
87
- ```typescript
88
- import { getPetById } from './gen/clients/getPetById'
89
-
90
- const { data } = await getPetById({ path: { petId: 1 }, baseURL: 'https://localhost:3000' })
91
- ```
92
-
93
- ## Which base URL a call uses
94
-
95
- A call uses the first base URL it finds, in this order:
96
-
97
- 1. `baseURL` passed on the call.
98
- 2. The operation's own `servers`.
99
- 3. The path's `servers`.
100
- 4. The client passed as `client`, made with `createClient({ baseURL })`.
101
- 5. `client.setConfig({ baseURL })`.
102
- 6. The `baseURL` option of `pluginAxios`.
@@ -1,109 +0,0 @@
1
- # Add interceptors
2
-
3
- Register handlers on `client.interceptors.request`, `.response`, or `.error` to apply behavior across calls. Handlers receive the resolved request, the decoded result, or the error a call ends with.
4
-
5
- ## Run before the send
6
-
7
- Request handlers run after URL construction, serialization, and authentication. Return the modified request:
8
-
9
- ```typescript
10
- import { client } from './gen/.kubb/client'
11
-
12
- client.interceptors.request.use((request) => {
13
- request.headers['X-Request-ID'] = crypto.randomUUID()
14
- return request
15
- })
16
- ```
17
-
18
- The handler receives a `ResolvedRequest` (`url`, `method`, `headers`, `body`, `signal`,
19
- `credentials`, `options`, `stream`).
20
-
21
- ## Run after the send
22
-
23
- Response handlers run after the body is decoded and before the status check and the validator, so a JSON body is
24
- already parsed. On a `client.stream` call, `data` is the raw body stream. The handler receives a `DecodedResponse`
25
- (`data`, `status`, `statusText`, `headers`, `contentType`, `request`, `response`):
26
-
27
- ```typescript
28
- client.interceptors.response.use((result) => {
29
- console.info(`${result.status} ${result.contentType}`)
30
- return result
31
- })
32
- ```
33
-
34
- ## React to an error
35
-
36
- Error handlers get every failure: a `ResponseError` for a non-2xx status, a network error, an abort, or a
37
- `ParseError`. Narrow with `ResponseError.is`:
38
-
39
- ```typescript
40
- import { client, ResponseError } from './gen/.kubb/client'
41
-
42
- client.interceptors.error.use((error) => {
43
- if (ResponseError.is(error) && error.status === 401) scheduleTokenRefresh()
44
- if (error.name === 'AbortError') console.info('canceled')
45
- return error
46
- })
47
- ```
48
-
49
- Return another error, such as a domain error, and the call throws it instead. Each handler receives the error the one
50
- before it returned. A handler that returns nothing keeps the error:
51
-
52
- ```typescript
53
- class NotFoundError extends Error {}
54
-
55
- client.interceptors.error.use((error) => (ResponseError.is(error) && error.status === 404 ? new NotFoundError(error.message) : error))
56
- ```
57
-
58
- With `throwOnError: false`, a documented non-2xx response resolves and no error handler runs for it, so inspect the
59
- returned `error` on the result. An error inside a stream loop throws from the loop and skips the error handlers.
60
-
61
- ## Add, replace, and remove handlers
62
-
63
- `use` registers a handler and returns an id. Pass that id to `eject` to remove it, or to `update`
64
- to swap its function in place.
65
-
66
- > [!NOTE]
67
- > Handlers run in the order you register them.
68
-
69
- ```typescript
70
- const id = client.interceptors.request.use((request) => request)
71
-
72
- client.interceptors.request.update(id, (request) => {
73
- request.headers['X-Trace'] = 'on'
74
- return request
75
- })
76
-
77
- client.interceptors.request.eject(id)
78
- ```
79
-
80
- ## Where to set them
81
-
82
- Register handlers on the shared `client` for all operations. `client.createClient(config)` returns an instance with the
83
- same config and no handlers. `client.extend(config)` returns one that runs the parent's handlers, even those added
84
- later, before its own:
85
-
86
- ```typescript
87
- import { client } from './gen/.kubb/client'
88
-
89
- const admin = client.extend({ headers: { 'X-Role': 'admin' } })
90
- admin.interceptors.request.use((request) => request) // runs after the handlers on client
91
- await getPetById({ path: { petId: 1 }, client: admin })
92
- ```
93
-
94
- 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`.
95
-
96
- ## Native axios interceptors
97
-
98
- To get the native `InternalAxiosRequestConfig`, `AxiosResponse`, or `AxiosError`, register an axios interceptor on `getAxiosInstance()`:
99
-
100
- ```typescript
101
- import { getAxiosInstance } from './gen/.kubb/client'
102
-
103
- getAxiosInstance().interceptors.request.use((config) => {
104
- config.headers.set('traceparent', currentTraceparent())
105
- return config
106
- })
107
- ```
108
-
109
- Native axios interceptors run after the `client.interceptors` request handlers, in reverse order of registration, and response interceptors see the raw bytes. An instance you wrap with `createAxiosTransport` keeps its own interceptors. See [Use a custom transport](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/transport).