@kubb/plugin-fetch 6.0.0 → 6.0.2
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 +1 -1
- package/dist/index.d.cts +7 -4
- package/dist/index.d.ts +7 -4
- package/dist/index.js +1 -1
- package/docs/guides/authentication.md +2 -0
- package/docs/guides/base-url.md +2 -0
- package/docs/guides/calling-operations.md +8 -3
- package/docs/guides/error-handling.md +8 -5
- package/docs/guides/interceptors.md +2 -0
- package/docs/guides/serialization.md +2 -0
- package/docs/guides/server-sent-events.md +8 -6
- package/docs/guides/transport.md +2 -0
- package/docs/options.md +8 -6
- package/docs/overview.md +4 -2
- package/kubb-extension.json +2 -6
- package/package.json +3 -3
- package/src/types.ts +5 -2
package/dist/index.cjs
CHANGED
package/dist/index.d.cts
CHANGED
|
@@ -1,11 +1,15 @@
|
|
|
1
1
|
import { PluginType } from "@kubb/kit";
|
|
2
|
-
import { ClientOptions,
|
|
2
|
+
import { ClientOptions, ClientResolvedOptions, ClientResolvedOptions as ResolvedOptions, ResolverClient, ResolverClient as ResolverClient$1 } from "@kubb/plugin-client";
|
|
3
|
+
/** The shared client options, without `returnType: 'plain'`, which only fits a client module `@kubb/plugin-client` calls. */
|
|
4
|
+
type Options = ClientOptions & {
|
|
5
|
+
returnType?: 'full' | 'data';
|
|
6
|
+
};
|
|
3
7
|
/**
|
|
4
8
|
* The plugin factory type for `@kubb/plugin-fetch`. Shares the options surface, resolver, and
|
|
5
9
|
* resolved-options shape with the other client plugins; only the plugin name and transport
|
|
6
10
|
* differ.
|
|
7
11
|
*/
|
|
8
|
-
type PluginFetch = PluginType<'plugin-fetch',
|
|
12
|
+
type PluginFetch = PluginType<'plugin-fetch', Options, ClientResolvedOptions, ResolverClient$1>;
|
|
9
13
|
declare global {
|
|
10
14
|
namespace Kubb {
|
|
11
15
|
interface PluginRegistry {
|
|
@@ -41,5 +45,4 @@ export declare const pluginFetchName = "plugin-fetch";
|
|
|
41
45
|
* ```
|
|
42
46
|
*/
|
|
43
47
|
export declare const pluginFetch: import("@kubb/kit").PluginFactory<PluginFetch>;
|
|
44
|
-
export { type Options, type PluginFetch, type ResolvedOptions, type ResolverClient, pluginFetch as default };
|
|
45
|
-
//# sourceMappingURL=index.d.cts.map
|
|
48
|
+
export { type Options, type PluginFetch, type ResolvedOptions, type ResolverClient, pluginFetch as default };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,11 +1,15 @@
|
|
|
1
1
|
import { PluginType } from "@kubb/kit";
|
|
2
|
-
import { ClientOptions,
|
|
2
|
+
import { ClientOptions, ClientResolvedOptions, ClientResolvedOptions as ResolvedOptions, ResolverClient, ResolverClient as ResolverClient$1 } from "@kubb/plugin-client";
|
|
3
|
+
/** The shared client options, without `returnType: 'plain'`, which only fits a client module `@kubb/plugin-client` calls. */
|
|
4
|
+
type Options = ClientOptions & {
|
|
5
|
+
returnType?: 'full' | 'data';
|
|
6
|
+
};
|
|
3
7
|
/**
|
|
4
8
|
* The plugin factory type for `@kubb/plugin-fetch`. Shares the options surface, resolver, and
|
|
5
9
|
* resolved-options shape with the other client plugins; only the plugin name and transport
|
|
6
10
|
* differ.
|
|
7
11
|
*/
|
|
8
|
-
type PluginFetch = PluginType<'plugin-fetch',
|
|
12
|
+
type PluginFetch = PluginType<'plugin-fetch', Options, ClientResolvedOptions, ResolverClient$1>;
|
|
9
13
|
declare global {
|
|
10
14
|
namespace Kubb {
|
|
11
15
|
interface PluginRegistry {
|
|
@@ -41,5 +45,4 @@ export declare const pluginFetchName = "plugin-fetch";
|
|
|
41
45
|
* ```
|
|
42
46
|
*/
|
|
43
47
|
export declare const pluginFetch: import("@kubb/kit").PluginFactory<PluginFetch>;
|
|
44
|
-
export { type Options, type PluginFetch, type ResolvedOptions, type ResolverClient, pluginFetch as default };
|
|
45
|
-
//# sourceMappingURL=index.d.ts.map
|
|
48
|
+
export { type Options, type PluginFetch, type ResolvedOptions, type ResolverClient, pluginFetch as default };
|
package/dist/index.js
CHANGED
|
@@ -75,6 +75,8 @@ const tenant = createClient({
|
|
|
75
75
|
const { data } = await getPetById({ path: { petId: 1 }, client: tenant })
|
|
76
76
|
```
|
|
77
77
|
|
|
78
|
+
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`.
|
|
79
|
+
|
|
78
80
|
To override the client for one request, pass `auth` on that single call, which suits a one-off token refresh. A header you set yourself always wins over the resolved token: client-level `headers`, or `headers` on a call to an operation that declares header parameters.
|
|
79
81
|
|
|
80
82
|
For authentication outside OpenAPI security schemes, use an async request interceptor to sign requests or supply custom headers.
|
package/docs/guides/base-url.md
CHANGED
|
@@ -44,12 +44,14 @@ Pass `baseURL` to `pluginFetch` to set the generated default. Add `pluginTs` for
|
|
|
44
44
|
|
|
45
45
|
```typescript [kubb.config.ts]
|
|
46
46
|
import { defineConfig } from 'kubb/config'
|
|
47
|
+
import { adapterOas } from '@kubb/adapter-oas'
|
|
47
48
|
import { pluginTs } from '@kubb/plugin-ts'
|
|
48
49
|
import { pluginFetch } from '@kubb/plugin-fetch'
|
|
49
50
|
|
|
50
51
|
export default defineConfig({
|
|
51
52
|
input: './petStore.yaml',
|
|
52
53
|
output: { path: './src/gen' },
|
|
54
|
+
adapter: adapterOas({ integerType: 'number' }),
|
|
53
55
|
plugins: [
|
|
54
56
|
pluginTs(),
|
|
55
57
|
pluginFetch({ baseURL: 'https://localhost:8080/api/v1' }),
|
|
@@ -13,6 +13,10 @@ const { data } = await getPetById({ path: { petId: 1 } })
|
|
|
13
13
|
// ^ the parsed pet, typed from the 200 response
|
|
14
14
|
```
|
|
15
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
|
+
|
|
16
20
|
Query, header, and cookie parameters sit under their own keys, and a request body goes under
|
|
17
21
|
`body`:
|
|
18
22
|
|
|
@@ -31,7 +35,7 @@ await updatePet({
|
|
|
31
35
|
})
|
|
32
36
|
```
|
|
33
37
|
|
|
34
|
-
Each key
|
|
38
|
+
Each key only appears when the operation declares it. You can call an operation without required parameters with no argument: `getStatus()`.
|
|
35
39
|
|
|
36
40
|
## Read the result
|
|
37
41
|
|
|
@@ -43,6 +47,7 @@ type RequestResult = {
|
|
|
43
47
|
data: TData // the parsed success body, undefined on an error result
|
|
44
48
|
error: TError // the parsed error body, undefined on a success result
|
|
45
49
|
contentType: string | undefined // the negotiated response media type
|
|
50
|
+
headers: Headers // the response headers
|
|
46
51
|
request: Request // the native request
|
|
47
52
|
response: Response // the native response
|
|
48
53
|
}
|
|
@@ -65,7 +70,7 @@ for that case, and TypeScript follows the check:
|
|
|
65
70
|
const result = await getPetById({ path: { petId: 1 } })
|
|
66
71
|
|
|
67
72
|
if (result.status === 200) {
|
|
68
|
-
console.info(result.data
|
|
73
|
+
console.info(result.data)
|
|
69
74
|
}
|
|
70
75
|
```
|
|
71
76
|
|
|
@@ -114,7 +119,7 @@ An operation that declares a single content type has it built in, so a multipart
|
|
|
114
119
|
|
|
115
120
|
## Pass native client options
|
|
116
121
|
|
|
117
|
-
Pass `options` on an operation for native fetch settings, such as `cache`, `mode`, `redirect`, `keepalive`,
|
|
122
|
+
Pass `options` on an operation for native fetch settings, such as `cache`, `mode`, `redirect`, `keepalive`, or `next`:
|
|
118
123
|
|
|
119
124
|
```typescript [src/app.ts]
|
|
120
125
|
import { getPetById } from './gen/clients/getPetById'
|
|
@@ -10,7 +10,7 @@ import { ResponseError } from './gen/.kubb/client'
|
|
|
10
10
|
|
|
11
11
|
try {
|
|
12
12
|
const { data } = await getPetById({ path: { petId: 1 } })
|
|
13
|
-
console.info(data
|
|
13
|
+
console.info(data)
|
|
14
14
|
} catch (error) {
|
|
15
15
|
if (ResponseError.is(error)) {
|
|
16
16
|
console.error(error.status) // 404
|
|
@@ -19,6 +19,8 @@ try {
|
|
|
19
19
|
}
|
|
20
20
|
```
|
|
21
21
|
|
|
22
|
+
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`.
|
|
23
|
+
|
|
22
24
|
The `message` holds the HTTP method and the URL without its query string, so query credentials stay out of logs. For example: `GET https://api.example.com/pets/1 failed with status 404 Not Found`.
|
|
23
25
|
|
|
24
26
|
The error exposes these fields:
|
|
@@ -30,6 +32,7 @@ class ResponseError extends Error {
|
|
|
30
32
|
status: number
|
|
31
33
|
statusText: string
|
|
32
34
|
contentType: string | undefined
|
|
35
|
+
headers: Headers
|
|
33
36
|
request: Request
|
|
34
37
|
response: Response
|
|
35
38
|
}
|
|
@@ -43,7 +46,7 @@ Each generated package bundles its own `ResponseError` class, so narrow with `Re
|
|
|
43
46
|
|
|
44
47
|
```typescript
|
|
45
48
|
import { isResponseError } from './gen/.kubb/client'
|
|
46
|
-
import type { GetPetByIdResponses } from './gen/
|
|
49
|
+
import type { GetPetByIdResponses } from './gen/types/GetPetById'
|
|
47
50
|
|
|
48
51
|
try {
|
|
49
52
|
await getPetById({ path: { petId: 7 } })
|
|
@@ -71,7 +74,7 @@ declares a `default` response, whose status can be any number:
|
|
|
71
74
|
const result = await getPetById({ path: { petId: 1 }, throwOnError: false })
|
|
72
75
|
|
|
73
76
|
if (result.data !== undefined) {
|
|
74
|
-
console.info(result.data
|
|
77
|
+
console.info(result.data)
|
|
75
78
|
} else {
|
|
76
79
|
console.error(result.status, result.error)
|
|
77
80
|
}
|
|
@@ -135,7 +138,7 @@ try {
|
|
|
135
138
|
}
|
|
136
139
|
```
|
|
137
140
|
|
|
138
|
-
A `ParseError` reports schema validation issues. A `ResponseError` reports a non-2xx status.
|
|
141
|
+
A `ParseError` reports schema validation issues. A `ResponseError` reports a non-2xx status. The error body of a non-2xx response is checked against the schema of its status, then of its range such as `5xx`, then of `default`. An error body that fails its schema throws a `ParseError` in place of the `ResponseError`, also with `throwOnError: false`. A status the document leaves out, such as a `502` from a gateway, keeps its body unchecked.
|
|
139
142
|
|
|
140
143
|
Calling `.unwrap()` on a `throwOnError: false` call turns that same `error` into a rejection, so a
|
|
141
144
|
`try`/`catch` works there too.
|
|
@@ -150,7 +153,7 @@ import { client } from './gen/.kubb/client'
|
|
|
150
153
|
client.setConfig({ validate: import.meta.env.DEV })
|
|
151
154
|
```
|
|
152
155
|
|
|
153
|
-
`validate: false` skips every schema. An object skips only the directions set to `false`: `request` (the body), `params` (path, query, and
|
|
156
|
+
`validate: false` skips every schema. An object skips only the directions set to `false`: `request` (the body), `params` (path, query, header, and cookie params), `response`, and `error`:
|
|
154
157
|
|
|
155
158
|
```typescript
|
|
156
159
|
client.setConfig({ validate: { response: false } })
|
|
@@ -90,3 +90,5 @@ const admin = client.extend({ headers: { 'X-Role': 'admin' } })
|
|
|
90
90
|
admin.interceptors.request.use((request) => request) // runs after the handlers on client
|
|
91
91
|
await getPetById({ path: { petId: 1 }, client: admin })
|
|
92
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`.
|
|
@@ -156,6 +156,8 @@ if (result.contentType === 'application/xml') {
|
|
|
156
156
|
}
|
|
157
157
|
```
|
|
158
158
|
|
|
159
|
+
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`.
|
|
160
|
+
|
|
159
161
|
[Server-sent events](https://kubb.dev/extensions/kubb-labs/plugin-fetch/guides/server-sent-events) covers stream media types and `client.stream`.
|
|
160
162
|
|
|
161
163
|
> [!NOTE]
|
|
@@ -92,7 +92,7 @@ Kubb generates one union member per event name:
|
|
|
92
92
|
|
|
93
93
|
```typescript
|
|
94
94
|
export type StreamChatStatus200 =
|
|
95
|
-
| { data
|
|
95
|
+
| { data: MessageDelta; event: 'message_delta'; id?: string; retry?: number }
|
|
96
96
|
| { data?: string; event: 'ping'; id?: string; retry?: number }
|
|
97
97
|
```
|
|
98
98
|
|
|
@@ -106,7 +106,7 @@ const { stream } = await streamChat({ body: { prompt: 'Hi' } })
|
|
|
106
106
|
for await (const event of stream) {
|
|
107
107
|
switch (event.event) {
|
|
108
108
|
case 'message_delta':
|
|
109
|
-
render(event.data
|
|
109
|
+
render(event.data.text) // MessageDelta
|
|
110
110
|
break
|
|
111
111
|
case 'ping':
|
|
112
112
|
break
|
|
@@ -176,9 +176,11 @@ for await (const { data } of stream) {
|
|
|
176
176
|
}
|
|
177
177
|
```
|
|
178
178
|
|
|
179
|
+
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`.
|
|
180
|
+
|
|
179
181
|
## JSON Lines
|
|
180
182
|
|
|
181
|
-
An operation whose only success content type is a JSON sequence, such as `application/jsonl`, `application/x-ndjson`, or `application/json-seq`, streams one item per line. Each line is parsed as JSON, so the loop gets each item as soon as its line arrives instead of waiting for the whole body. An `application/json-seq` record must fit on one line
|
|
183
|
+
An operation whose only success content type is a JSON sequence, such as `application/jsonl`, `application/x-ndjson`, or `application/json-seq`, streams one item per line. Each line is parsed as JSON, so the loop gets each item as soon as its line arrives instead of waiting for the whole body. An `application/json-seq` record must fit on one line. A record that spans several lines fails to parse.
|
|
182
184
|
|
|
183
185
|
### Describe it
|
|
184
186
|
|
|
@@ -264,7 +266,7 @@ console.info(result.headers.get('X-Request-ID'))
|
|
|
264
266
|
|
|
265
267
|
## Resume after a drop
|
|
266
268
|
|
|
267
|
-
A dropped connection ends the loop with the transport's error. The result's `lastEventId` is the `id` of the last event the server completed, so a new call with a `Last-Event-ID` header continues where the stream stopped. The runtime does not reconnect by itself, because many streams, such as a chat completion, end on purpose, and the retry policy belongs to your app:
|
|
269
|
+
A dropped connection ends the loop with the transport's error. The result's `lastEventId` is the `id` of the last event the server completed, so a new call with a `Last-Event-ID` header continues where the stream stopped. Declare `Last-Event-ID` as a header parameter of the operation, so the call accepts it in `headers`. The runtime does not reconnect by itself, because many streams, such as a chat completion, end on purpose, and the retry policy belongs to your app:
|
|
268
270
|
|
|
269
271
|
```typescript
|
|
270
272
|
let lastEventId = ''
|
|
@@ -351,7 +353,7 @@ for await (const event of result) render(event.data)
|
|
|
351
353
|
|
|
352
354
|
```typescript
|
|
353
355
|
import { client, type SuccessOf } from './gen/.kubb/client'
|
|
354
|
-
import type { StreamLogsResponses } from './gen/
|
|
356
|
+
import type { StreamLogsResponses } from './gen/types/StreamLogs'
|
|
355
357
|
|
|
356
358
|
const result = await client.stream<StreamLogsResponses, true, SuccessOf<StreamLogsResponses>>({ method: 'GET', url: '/logs' })
|
|
357
359
|
```
|
|
@@ -424,7 +426,7 @@ The events alone carry no `response` or `lastEventId`. To resume a dropped strea
|
|
|
424
426
|
|
|
425
427
|
## The runtime files
|
|
426
428
|
|
|
427
|
-
`.kubb/sse.ts` holds `parseEventStream`, `parseJsonLines`, and the `eventStream`, `jsonLines`, and `streamMediaTypes` media types. The `ServerSentEvent`, `TypedEvent`, `EventStreamOptions`, `StreamOptions`, `StreamResult`, and `StreamResultWithHeaders` types live in `.kubb/core.ts`. A stream operation takes `StreamOptions` and returns `StreamResult`, or `StreamResultWithHeaders` when the response declares headers
|
|
429
|
+
`.kubb/sse.ts` holds `parseEventStream`, `parseJsonLines`, and the `eventStream`, `jsonLines`, and `streamMediaTypes` media types. The `ServerSentEvent`, `TypedEvent`, `EventStreamOptions`, `StreamOptions`, `StreamResult`, and `StreamResultWithHeaders` types live in `.kubb/core.ts`. A stream operation takes `StreamOptions` and returns `StreamResult`, or `StreamResultWithHeaders` when the response declares headers. These types are the stream versions of `Options`, `RequestResult`, and `RequestResultWithHeaders`. `.kubb/client.ts` re-exports `sse.ts`, so everything imports from the client. Kubb regenerates these files on each run, so do not edit them:
|
|
428
430
|
|
|
429
431
|
```typescript
|
|
430
432
|
import type { ServerSentEvent } from './gen/.kubb/client'
|
package/docs/guides/transport.md
CHANGED
|
@@ -66,6 +66,8 @@ const { data } = await getPetById({ path: { petId: 1 }, client: testClient })
|
|
|
66
66
|
// ^ { id: 1, name: 'Fluffy' }
|
|
67
67
|
```
|
|
68
68
|
|
|
69
|
+
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`.
|
|
70
|
+
|
|
69
71
|
Pass the isolated client per operation or to a query plugin.
|
|
70
72
|
|
|
71
73
|
## Where to set it
|
package/docs/options.md
CHANGED
|
@@ -32,7 +32,7 @@ Base URL prepended to every request. When omitted, each request uses the operati
|
|
|
32
32
|
|
|
33
33
|
### throwOnErrorDefault
|
|
34
34
|
|
|
35
|
-
Set `throwOnErrorDefault: false` to return documented error responses as values by default.
|
|
35
|
+
Set `throwOnErrorDefault: false` to return documented error responses as values by default. The option sets the fallback on each generated request and the default `ThrowOnError` type parameter on functions and SDK methods. The option 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`.
|
|
36
36
|
|
|
37
37
|
| | |
|
|
38
38
|
| -------- | --------- |
|
|
@@ -46,9 +46,11 @@ const result = await getPetById({ path: { petId: 1 } })
|
|
|
46
46
|
if (result.status !== 200) console.error(result.status, result.error)
|
|
47
47
|
```
|
|
48
48
|
|
|
49
|
+
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`.
|
|
50
|
+
|
|
49
51
|
### validator
|
|
50
52
|
|
|
51
|
-
Validates request bodies, path, query, and
|
|
53
|
+
Validates request bodies, the path, query, header, and cookie params, and response bodies with schemas from `@kubb/plugin-zod`, so add `pluginZod()` too. An invalid value makes the generated function throw a `ParseError`.
|
|
52
54
|
|
|
53
55
|
| | |
|
|
54
56
|
| -------- | ------------------------------------------------------------------------- |
|
|
@@ -67,7 +69,7 @@ Validates the success response body, and the error body against the schema of it
|
|
|
67
69
|
:::
|
|
68
70
|
|
|
69
71
|
:::field{name="{ request?: 'zod', params?: 'zod', response?: 'zod' }"}
|
|
70
|
-
Opts in per direction. `request` validates the request body and `params` validates the path, query, and
|
|
72
|
+
Opts in per direction. `request` validates the request body and `params` validates the path, query, header, and cookie params before the call. `response` validates the response body after it.
|
|
71
73
|
:::
|
|
72
74
|
|
|
73
75
|
::
|
|
@@ -89,9 +91,9 @@ export default defineConfig({
|
|
|
89
91
|
})
|
|
90
92
|
```
|
|
91
93
|
|
|
92
|
-
`params` runs each group through its generated `<operation>PathSchema`, `QuerySchema`, or `
|
|
94
|
+
`params` runs each group through its generated `<operation>PathSchema`, `QuerySchema`, `HeadersSchema`, or `CookiesSchema`, and sends what the schema returns. A codec param such as a `Date` goes out in its wire form, and an invalid param fails before the request. Values added by `auth` are not validated.
|
|
93
95
|
|
|
94
|
-
Only the params your OpenAPI spec declares are sent. Path and query keys the spec does not declare are stripped, so a key such as an undocumented filter or a cache-buster never reaches the URL. Declare it in the spec, or leave `params` off. Headers are the exception
|
|
96
|
+
Only the params your OpenAPI spec declares are sent. Path and query keys the spec does not declare are stripped, so a key such as an undocumented filter or a cache-buster never reaches the URL. Declare it in the spec, or leave `params` off. Headers are the exception. Client-level `headers`, such as `Authorization` or tracing headers, are merged with the call's headers before validation. Headers the spec does not declare pass through unchanged, and declared header params match in any casing.
|
|
95
97
|
|
|
96
98
|
Pair `request` and `params` with `pluginZod({ inferred: 'codec' })` when the schemas use codecs, so the request types accept the domain values (such as a `Date`) that the validators encode. See [`inferred`](https://kubb.dev/extensions/kubb-labs/plugin-zod/options#inferred).
|
|
97
99
|
|
|
@@ -163,7 +165,7 @@ pluginFetch({ returnType: 'data' })
|
|
|
163
165
|
const pet = await getPetById({ path: { petId: 1 } }) // Pet, not { status, data, ... }
|
|
164
166
|
```
|
|
165
167
|
|
|
166
|
-
|
|
168
|
+
`returnType` 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')`.
|
|
167
169
|
|
|
168
170
|
### resolver
|
|
169
171
|
|
package/docs/overview.md
CHANGED
|
@@ -2,12 +2,12 @@
|
|
|
2
2
|
|
|
3
3
|
The Fetch plugin turns each operation in your OpenAPI spec into a typed async function that sends the request with the native Fetch API. Each function takes grouped `path`, `query`, `headers`, and `body` parameters and returns a result keyed by status code.
|
|
4
4
|
|
|
5
|
-
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
|
|
5
|
+
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 to `.kubb/` in the root output folder. Import the client from `.kubb/client.ts`.
|
|
6
6
|
|
|
7
7
|
## Setup
|
|
8
8
|
|
|
9
9
|
- Add `@kubb/plugin-ts` for the operation types, or `@kubb/plugin-zod` with `inferred: true`.
|
|
10
|
-
- Add `@kubb/plugin-zod` when you set `validator`, and install `zod` v4.
|
|
10
|
+
- Add `@kubb/plugin-zod` when you set `validator`, and install `zod` v4. Generation fails without the plugin.
|
|
11
11
|
- No HTTP client package is needed. The generated code calls the global `fetch`.
|
|
12
12
|
|
|
13
13
|
## Options worth knowing
|
|
@@ -26,12 +26,14 @@ The config below generates a Fetch client that sends every request to the Petsto
|
|
|
26
26
|
|
|
27
27
|
```typescript [kubb.config.ts]
|
|
28
28
|
import { defineConfig } from 'kubb/config'
|
|
29
|
+
import { adapterOas } from '@kubb/adapter-oas'
|
|
29
30
|
import { pluginTs } from '@kubb/plugin-ts'
|
|
30
31
|
import { pluginFetch } from '@kubb/plugin-fetch'
|
|
31
32
|
|
|
32
33
|
export default defineConfig({
|
|
33
34
|
input: './petStore.yaml',
|
|
34
35
|
output: { path: './src/gen' },
|
|
36
|
+
adapter: adapterOas({ integerType: 'number' }),
|
|
35
37
|
plugins: [
|
|
36
38
|
pluginTs(),
|
|
37
39
|
pluginFetch({ baseURL: 'https://petstore.swagger.io/v2' }),
|
package/kubb-extension.json
CHANGED
|
@@ -17,8 +17,7 @@
|
|
|
17
17
|
"github": "stijnvanhulle"
|
|
18
18
|
}
|
|
19
19
|
],
|
|
20
|
-
"
|
|
21
|
-
"optionalDependencies": ["plugin-zod"],
|
|
20
|
+
"optionalDependencies": ["plugin-ts", "plugin-zod"],
|
|
22
21
|
"compatibility": {
|
|
23
22
|
"kubb": ">=5.18.4",
|
|
24
23
|
"node": ">=22.22"
|
|
@@ -199,7 +198,7 @@
|
|
|
199
198
|
"key": "returnType",
|
|
200
199
|
"path": ["returnType"],
|
|
201
200
|
"label": "Return Type",
|
|
202
|
-
"description": "What a generated function resolves to. full is the whole result with status and error, data is only the success body when it throws
|
|
201
|
+
"description": "What a generated function resolves to. full is the whole result with status and error, and data is only the success body when it throws",
|
|
203
202
|
"type": "select",
|
|
204
203
|
"default": "full",
|
|
205
204
|
"choices": [
|
|
@@ -208,9 +207,6 @@
|
|
|
208
207
|
},
|
|
209
208
|
{
|
|
210
209
|
"value": "data"
|
|
211
|
-
},
|
|
212
|
-
{
|
|
213
|
-
"value": "plain"
|
|
214
210
|
}
|
|
215
211
|
]
|
|
216
212
|
},
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kubb/plugin-fetch",
|
|
3
|
-
"version": "6.0.
|
|
3
|
+
"version": "6.0.2",
|
|
4
4
|
"description": "Generate a slim, type-safe HTTP client with Kubb based on the native Fetch api.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"api-client",
|
|
@@ -83,8 +83,8 @@
|
|
|
83
83
|
"registry": "https://registry.npmjs.org/"
|
|
84
84
|
},
|
|
85
85
|
"dependencies": {
|
|
86
|
-
"@kubb/kit": "^5.
|
|
87
|
-
"@kubb/plugin-client": "^6.0.
|
|
86
|
+
"@kubb/kit": "^5.19.0",
|
|
87
|
+
"@kubb/plugin-client": "^6.0.2"
|
|
88
88
|
},
|
|
89
89
|
"devDependencies": {
|
|
90
90
|
"typescript": "^7.0.2"
|
package/src/types.ts
CHANGED
|
@@ -1,7 +1,10 @@
|
|
|
1
1
|
import type { PluginType } from '@kubb/kit'
|
|
2
|
-
import type { ClientOptions
|
|
2
|
+
import type { ClientOptions, ClientResolvedOptions as ResolvedOptions, ResolverClient } from '@kubb/plugin-client'
|
|
3
3
|
|
|
4
|
-
export type {
|
|
4
|
+
export type { ClientResolvedOptions as ResolvedOptions, ResolverClient } from '@kubb/plugin-client'
|
|
5
|
+
|
|
6
|
+
/** The shared client options, without `returnType: 'plain'`, which only fits a client module `@kubb/plugin-client` calls. */
|
|
7
|
+
export type Options = ClientOptions & { returnType?: 'full' | 'data' }
|
|
5
8
|
|
|
6
9
|
/**
|
|
7
10
|
* The plugin factory type for `@kubb/plugin-fetch`. Shares the options surface, resolver, and
|