@kubb/plugin-ky 0.0.0-stage → 0.0.0
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/LICENSE +21 -0
- package/README.md +73 -2
- package/dist/index.cjs +66 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +48 -0
- package/dist/index.d.ts +48 -0
- package/dist/index.js +60 -0
- package/dist/index.js.map +1 -0
- package/dist/templates/client.d.ts +53 -0
- package/docs/guides/calling-operations.md +145 -0
- package/docs/guides/configure-requests.md +197 -0
- package/docs/guides/error-handling.md +155 -0
- package/docs/guides/serialization.md +226 -0
- package/docs/guides/server-sent-events.md +300 -0
- package/docs/guides/transport.md +92 -0
- package/docs/options.md +209 -0
- package/docs/overview.md +60 -0
- package/kubb-extension.json +236 -0
- package/package.json +107 -3
- package/src/index.ts +2 -0
- package/src/plugin.ts +47 -0
- package/src/types.ts +22 -0
- package/templates/client.ts +98 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Kubb Labs
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,74 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
|
+
<a href="https://kubb.dev" target="_blank" rel="noopener noreferrer">
|
|
3
|
+
<img src="https://kubb.dev/og.png" alt="Kubb banner">
|
|
4
|
+
</a>
|
|
2
5
|
|
|
3
|
-
|
|
6
|
+
[![npm version][npm-version-src]][npm-version-href]
|
|
7
|
+
[![npm downloads][npm-downloads-src]][npm-downloads-href]
|
|
8
|
+
[![Stars][stars-src]][stars-href]
|
|
9
|
+
[![License][license-src]][license-href]
|
|
10
|
+
[![Node][node-src]][node-href]
|
|
11
|
+
|
|
12
|
+
<h4>
|
|
13
|
+
<a href="https://kubb.dev/extensions/kubb-labs/plugin-ky" target="_blank">Documentation</a>
|
|
14
|
+
<span> · </span>
|
|
15
|
+
<a href="https://github.com/kubb-labs/kubb/issues/" target="_blank">Report Bug</a>
|
|
16
|
+
<span> · </span>
|
|
17
|
+
<a href="https://github.com/kubb-labs/kubb/issues/" target="_blank">Request Feature</a>
|
|
18
|
+
</h4>
|
|
19
|
+
</div>
|
|
20
|
+
|
|
21
|
+
<br />
|
|
22
|
+
|
|
23
|
+
# @kubb/plugin-ky
|
|
24
|
+
|
|
25
|
+
### Generate Ky clients with Kubb
|
|
26
|
+
|
|
27
|
+
`@kubb/plugin-ky` generates a type-safe HTTP client from your OpenAPI spec, with one async function per operation and the runtime bundled into `.kubb/client.ts`.
|
|
28
|
+
|
|
29
|
+
## Installation
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
npx kubb add plugin-ky
|
|
33
|
+
# or
|
|
34
|
+
bun add @kubb/plugin-ky ky
|
|
35
|
+
# or
|
|
36
|
+
pnpm add @kubb/plugin-ky ky
|
|
37
|
+
# or
|
|
38
|
+
npm install @kubb/plugin-ky ky
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
`kubb add` installs the version the [Kubb registry](https://kubb.dev/registry) pins and adds `pluginKy()` to your `kubb.config.ts`. Run `npx kubb init` first if you have no config. It installs only Kubb packages, so also install `ky`.
|
|
42
|
+
|
|
43
|
+
## Documentation
|
|
44
|
+
|
|
45
|
+
See the [full documentation](https://kubb.dev/extensions/kubb-labs/plugin-ky) for configuration options and examples.
|
|
46
|
+
|
|
47
|
+
## Supporting Kubb
|
|
48
|
+
|
|
49
|
+
Kubb is an open source project, and its development is funded entirely by sponsors. If you would like to become a sponsor, please consider:
|
|
50
|
+
|
|
51
|
+
- [Become a Sponsor on GitHub](https://github.com/sponsors/stijnvanhulle)
|
|
52
|
+
|
|
53
|
+
<p align="center">
|
|
54
|
+
<a href="https://github.com/sponsors/stijnvanhulle">
|
|
55
|
+
<img src="https://raw.githubusercontent.com/stijnvanhulle/sponsors/main/sponsors.svg" alt="My sponsors" />
|
|
56
|
+
</a>
|
|
57
|
+
</p>
|
|
58
|
+
|
|
59
|
+
## License
|
|
60
|
+
|
|
61
|
+
[MIT](https://github.com/kubb-labs/plugins/blob/main/LICENSE)
|
|
62
|
+
|
|
63
|
+
<!-- Badges -->
|
|
64
|
+
|
|
65
|
+
[npm-version-src]: https://shieldcn.dev/npm/v/@kubb/plugin-ky.svg?variant=secondary&size=xs&theme=zinc&mode=dark
|
|
66
|
+
[npm-version-href]: https://npmx.dev/package/@kubb/plugin-ky
|
|
67
|
+
[npm-downloads-src]: https://shieldcn.dev/npm/dm/@kubb/plugin-ky.svg?variant=secondary&size=xs&theme=zinc&mode=dark
|
|
68
|
+
[npm-downloads-href]: https://npmx.dev/package/@kubb/plugin-ky
|
|
69
|
+
[stars-src]: https://shieldcn.dev/github/stars/kubb-labs/kubb.svg?variant=secondary&size=xs&theme=zinc&mode=dark
|
|
70
|
+
[stars-href]: https://github.com/kubb-labs/kubb
|
|
71
|
+
[license-src]: https://shieldcn.dev/npm/license/@kubb/plugin-ky.svg?variant=secondary&size=xs&theme=zinc
|
|
72
|
+
[license-href]: https://github.com/kubb-labs/kubb/blob/main/LICENSE
|
|
73
|
+
[node-src]: https://shieldcn.dev/npm/node/@kubb/plugin-ky.svg?variant=secondary&size=xs&theme=zinc&mode=dark
|
|
74
|
+
[node-href]: https://npmx.dev/package/@kubb/plugin-ky
|
package/dist/index.cjs
ADDED
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
Object.defineProperties(exports, {
|
|
2
|
+
__esModule: { value: true },
|
|
3
|
+
[Symbol.toStringTag]: { value: "Module" }
|
|
4
|
+
});
|
|
5
|
+
let node_url = require("node:url");
|
|
6
|
+
let _kubb_kit = require("@kubb/kit");
|
|
7
|
+
let _kubb_plugin_client = require("@kubb/plugin-client");
|
|
8
|
+
// kubb-extension.json
|
|
9
|
+
var compatibility = {
|
|
10
|
+
"kubb": ">=5.19.0",
|
|
11
|
+
"node": ">=22.22"
|
|
12
|
+
};
|
|
13
|
+
// package.json
|
|
14
|
+
var version = "0.0.0";
|
|
15
|
+
// src/plugin.ts
|
|
16
|
+
/**
|
|
17
|
+
* Canonical plugin name for `@kubb/plugin-ky`. Used for driver lookups and cross-plugin
|
|
18
|
+
* dependency references.
|
|
19
|
+
*/
|
|
20
|
+
const pluginKyName = "plugin-ky";
|
|
21
|
+
/**
|
|
22
|
+
* Generates a type-safe HTTP client pinned to Ky. Each operation becomes one async function
|
|
23
|
+
* that takes a single grouped `options` object and returns the shared `RequestResult` contract. The
|
|
24
|
+
* runtime is always bundled into `.kubb/client.ts`, so generated code never imports from
|
|
25
|
+
* `@kubb/plugin-ky` and the only runtime dependency is `ky`.
|
|
26
|
+
*
|
|
27
|
+
* @example
|
|
28
|
+
* ```ts
|
|
29
|
+
* import { defineConfig } from 'kubb/config'
|
|
30
|
+
* import { pluginTs } from '@kubb/plugin-ts'
|
|
31
|
+
* import { pluginKy } from '@kubb/plugin-ky'
|
|
32
|
+
*
|
|
33
|
+
* export default defineConfig({
|
|
34
|
+
* input: './petStore.yaml',
|
|
35
|
+
* output: { path: './src/gen' },
|
|
36
|
+
* plugins: [
|
|
37
|
+
* pluginTs(),
|
|
38
|
+
* pluginKy({ output: { path: './clients' } }),
|
|
39
|
+
* ],
|
|
40
|
+
* })
|
|
41
|
+
* ```
|
|
42
|
+
*/
|
|
43
|
+
const pluginKy = (0, _kubb_kit.defineExtension)({
|
|
44
|
+
kind: "plugin",
|
|
45
|
+
meta: {
|
|
46
|
+
name: pluginKyName,
|
|
47
|
+
version,
|
|
48
|
+
compatibility
|
|
49
|
+
},
|
|
50
|
+
dependencies: _kubb_plugin_client.clientDependencies,
|
|
51
|
+
setup(options) {
|
|
52
|
+
const resolved = (0, _kubb_plugin_client.resolveClientOptions)(options);
|
|
53
|
+
(0, _kubb_plugin_client.setupClient)({
|
|
54
|
+
name: "ky",
|
|
55
|
+
resolved,
|
|
56
|
+
macros: options.macros,
|
|
57
|
+
client: (0, node_url.fileURLToPath)(new URL("../templates/client.ts", require("url").pathToFileURL(__filename).href))
|
|
58
|
+
});
|
|
59
|
+
return resolved;
|
|
60
|
+
}
|
|
61
|
+
});
|
|
62
|
+
exports.default = pluginKy;
|
|
63
|
+
exports.pluginKy = pluginKy;
|
|
64
|
+
exports.pluginKyName = pluginKyName;
|
|
65
|
+
|
|
66
|
+
//# sourceMappingURL=index.cjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.cjs","names":["defineExtension","clientDependencies","resolveClientOptions","fileURLToPath"],"sources":["../kubb-extension.json","../package.json","../src/plugin.ts"],"sourcesContent":["","","import { fileURLToPath } from 'node:url'\nimport { defineExtension } from '@kubb/kit'\nimport { clientDependencies, resolveClientOptions, setupClient } from '@kubb/plugin-client'\nimport { compatibility } from '../kubb-extension.json'\nimport { version } from '../package.json'\nimport type { PluginKy } from './types.ts'\n\n/**\n * Canonical plugin name for `@kubb/plugin-ky`. Used for driver lookups and cross-plugin\n * dependency references.\n */\nexport const pluginKyName = 'plugin-ky' satisfies PluginKy['name']\n\n/**\n * Generates a type-safe HTTP client pinned to Ky. Each operation becomes one async function\n * that takes a single grouped `options` object and returns the shared `RequestResult` contract. The\n * runtime is always bundled into `.kubb/client.ts`, so generated code never imports from\n * `@kubb/plugin-ky` and the only runtime dependency is `ky`.\n *\n * @example\n * ```ts\n * import { defineConfig } from 'kubb/config'\n * import { pluginTs } from '@kubb/plugin-ts'\n * import { pluginKy } from '@kubb/plugin-ky'\n *\n * export default defineConfig({\n * input: './petStore.yaml',\n * output: { path: './src/gen' },\n * plugins: [\n * pluginTs(),\n * pluginKy({ output: { path: './clients' } }),\n * ],\n * })\n * ```\n */\nexport const pluginKy = defineExtension<PluginKy>({\n kind: 'plugin',\n meta: { name: pluginKyName, version, compatibility },\n dependencies: clientDependencies,\n setup(options) {\n const resolved = resolveClientOptions(options)\n setupClient({ name: 'ky', resolved, macros: options.macros, client: fileURLToPath(new URL('../templates/client.ts', import.meta.url)) })\n return resolved\n },\n})\n\nexport default pluginKy\n"],"mappings":";;;;;;;;;;;;;;;;;;;AEWA,MAAa,eAAe;;;;;;;;;;;;;;;;;;;;;;;AAwB5B,MAAa,YAAA,GAAWA,UAAAA,gBAAAA,CAA0B;CAChD,MAAM;CACN,MAAM;EAAE,MAAM;EAAc;EAAS;CAAc;CACnD,cAAcC,oBAAAA;CACd,MAAM,SAAS;EACb,MAAM,YAAA,GAAWC,oBAAAA,qBAAAA,CAAqB,OAAO;EAC7C,CAAA,GAAA,oBAAA,YAAA,CAAY;GAAE,MAAM;GAAM;GAAU,QAAQ,QAAQ;GAAQ,SAAA,GAAQC,SAAAA,cAAAA,CAAc,IAAI,IAAI,0BAAA,QAAA,KAAA,CAAA,CAAA,cAAA,UAAA,CAAA,CAAA,IAAyC,CAAC;EAAE,CAAC;EACvI,OAAO;CACT;AACF,CAAC"}
|
package/dist/index.d.cts
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
import { PluginType } from "@kubb/kit";
|
|
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
|
+
};
|
|
7
|
+
/**
|
|
8
|
+
* The plugin factory type for `@kubb/plugin-ky`. Shares the options surface, resolver, and
|
|
9
|
+
* resolved-options shape with the other client plugins; only the plugin name and transport
|
|
10
|
+
* differ.
|
|
11
|
+
*/
|
|
12
|
+
type PluginKy = PluginType<'plugin-ky', Options, ClientResolvedOptions, ResolverClient$1>;
|
|
13
|
+
declare global {
|
|
14
|
+
namespace Kubb {
|
|
15
|
+
interface PluginRegistry {
|
|
16
|
+
'plugin-ky': PluginKy;
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Canonical plugin name for `@kubb/plugin-ky`. Used for driver lookups and cross-plugin
|
|
22
|
+
* dependency references.
|
|
23
|
+
*/
|
|
24
|
+
export declare const pluginKyName = "plugin-ky";
|
|
25
|
+
/**
|
|
26
|
+
* Generates a type-safe HTTP client pinned to Ky. Each operation becomes one async function
|
|
27
|
+
* that takes a single grouped `options` object and returns the shared `RequestResult` contract. The
|
|
28
|
+
* runtime is always bundled into `.kubb/client.ts`, so generated code never imports from
|
|
29
|
+
* `@kubb/plugin-ky` and the only runtime dependency is `ky`.
|
|
30
|
+
*
|
|
31
|
+
* @example
|
|
32
|
+
* ```ts
|
|
33
|
+
* import { defineConfig } from 'kubb/config'
|
|
34
|
+
* import { pluginTs } from '@kubb/plugin-ts'
|
|
35
|
+
* import { pluginKy } from '@kubb/plugin-ky'
|
|
36
|
+
*
|
|
37
|
+
* export default defineConfig({
|
|
38
|
+
* input: './petStore.yaml',
|
|
39
|
+
* output: { path: './src/gen' },
|
|
40
|
+
* plugins: [
|
|
41
|
+
* pluginTs(),
|
|
42
|
+
* pluginKy({ output: { path: './clients' } }),
|
|
43
|
+
* ],
|
|
44
|
+
* })
|
|
45
|
+
* ```
|
|
46
|
+
*/
|
|
47
|
+
export declare const pluginKy: import("@kubb/kit").PluginFactory<PluginKy>;
|
|
48
|
+
export { type Options, type PluginKy, type ResolvedOptions, type ResolverClient, pluginKy as default };
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
import { PluginType } from "@kubb/kit";
|
|
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
|
+
};
|
|
7
|
+
/**
|
|
8
|
+
* The plugin factory type for `@kubb/plugin-ky`. Shares the options surface, resolver, and
|
|
9
|
+
* resolved-options shape with the other client plugins; only the plugin name and transport
|
|
10
|
+
* differ.
|
|
11
|
+
*/
|
|
12
|
+
type PluginKy = PluginType<'plugin-ky', Options, ClientResolvedOptions, ResolverClient$1>;
|
|
13
|
+
declare global {
|
|
14
|
+
namespace Kubb {
|
|
15
|
+
interface PluginRegistry {
|
|
16
|
+
'plugin-ky': PluginKy;
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Canonical plugin name for `@kubb/plugin-ky`. Used for driver lookups and cross-plugin
|
|
22
|
+
* dependency references.
|
|
23
|
+
*/
|
|
24
|
+
export declare const pluginKyName = "plugin-ky";
|
|
25
|
+
/**
|
|
26
|
+
* Generates a type-safe HTTP client pinned to Ky. Each operation becomes one async function
|
|
27
|
+
* that takes a single grouped `options` object and returns the shared `RequestResult` contract. The
|
|
28
|
+
* runtime is always bundled into `.kubb/client.ts`, so generated code never imports from
|
|
29
|
+
* `@kubb/plugin-ky` and the only runtime dependency is `ky`.
|
|
30
|
+
*
|
|
31
|
+
* @example
|
|
32
|
+
* ```ts
|
|
33
|
+
* import { defineConfig } from 'kubb/config'
|
|
34
|
+
* import { pluginTs } from '@kubb/plugin-ts'
|
|
35
|
+
* import { pluginKy } from '@kubb/plugin-ky'
|
|
36
|
+
*
|
|
37
|
+
* export default defineConfig({
|
|
38
|
+
* input: './petStore.yaml',
|
|
39
|
+
* output: { path: './src/gen' },
|
|
40
|
+
* plugins: [
|
|
41
|
+
* pluginTs(),
|
|
42
|
+
* pluginKy({ output: { path: './clients' } }),
|
|
43
|
+
* ],
|
|
44
|
+
* })
|
|
45
|
+
* ```
|
|
46
|
+
*/
|
|
47
|
+
export declare const pluginKy: import("@kubb/kit").PluginFactory<PluginKy>;
|
|
48
|
+
export { type Options, type PluginKy, type ResolvedOptions, type ResolverClient, pluginKy as default };
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
import { fileURLToPath } from "node:url";
|
|
2
|
+
import { defineExtension } from "@kubb/kit";
|
|
3
|
+
import { clientDependencies, resolveClientOptions, setupClient } from "@kubb/plugin-client";
|
|
4
|
+
// kubb-extension.json
|
|
5
|
+
var compatibility = {
|
|
6
|
+
"kubb": ">=5.19.0",
|
|
7
|
+
"node": ">=22.22"
|
|
8
|
+
};
|
|
9
|
+
// package.json
|
|
10
|
+
var version = "0.0.0";
|
|
11
|
+
// src/plugin.ts
|
|
12
|
+
/**
|
|
13
|
+
* Canonical plugin name for `@kubb/plugin-ky`. Used for driver lookups and cross-plugin
|
|
14
|
+
* dependency references.
|
|
15
|
+
*/
|
|
16
|
+
const pluginKyName = "plugin-ky";
|
|
17
|
+
/**
|
|
18
|
+
* Generates a type-safe HTTP client pinned to Ky. Each operation becomes one async function
|
|
19
|
+
* that takes a single grouped `options` object and returns the shared `RequestResult` contract. The
|
|
20
|
+
* runtime is always bundled into `.kubb/client.ts`, so generated code never imports from
|
|
21
|
+
* `@kubb/plugin-ky` and the only runtime dependency is `ky`.
|
|
22
|
+
*
|
|
23
|
+
* @example
|
|
24
|
+
* ```ts
|
|
25
|
+
* import { defineConfig } from 'kubb/config'
|
|
26
|
+
* import { pluginTs } from '@kubb/plugin-ts'
|
|
27
|
+
* import { pluginKy } from '@kubb/plugin-ky'
|
|
28
|
+
*
|
|
29
|
+
* export default defineConfig({
|
|
30
|
+
* input: './petStore.yaml',
|
|
31
|
+
* output: { path: './src/gen' },
|
|
32
|
+
* plugins: [
|
|
33
|
+
* pluginTs(),
|
|
34
|
+
* pluginKy({ output: { path: './clients' } }),
|
|
35
|
+
* ],
|
|
36
|
+
* })
|
|
37
|
+
* ```
|
|
38
|
+
*/
|
|
39
|
+
const pluginKy = defineExtension({
|
|
40
|
+
kind: "plugin",
|
|
41
|
+
meta: {
|
|
42
|
+
name: pluginKyName,
|
|
43
|
+
version,
|
|
44
|
+
compatibility
|
|
45
|
+
},
|
|
46
|
+
dependencies: clientDependencies,
|
|
47
|
+
setup(options) {
|
|
48
|
+
const resolved = resolveClientOptions(options);
|
|
49
|
+
setupClient({
|
|
50
|
+
name: "ky",
|
|
51
|
+
resolved,
|
|
52
|
+
macros: options.macros,
|
|
53
|
+
client: fileURLToPath(new URL("../templates/client.ts", import.meta.url))
|
|
54
|
+
});
|
|
55
|
+
return resolved;
|
|
56
|
+
}
|
|
57
|
+
});
|
|
58
|
+
export { pluginKy as default, pluginKy, pluginKyName };
|
|
59
|
+
|
|
60
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","names":[],"sources":["../kubb-extension.json","../package.json","../src/plugin.ts"],"sourcesContent":["","","import { fileURLToPath } from 'node:url'\nimport { defineExtension } from '@kubb/kit'\nimport { clientDependencies, resolveClientOptions, setupClient } from '@kubb/plugin-client'\nimport { compatibility } from '../kubb-extension.json'\nimport { version } from '../package.json'\nimport type { PluginKy } from './types.ts'\n\n/**\n * Canonical plugin name for `@kubb/plugin-ky`. Used for driver lookups and cross-plugin\n * dependency references.\n */\nexport const pluginKyName = 'plugin-ky' satisfies PluginKy['name']\n\n/**\n * Generates a type-safe HTTP client pinned to Ky. Each operation becomes one async function\n * that takes a single grouped `options` object and returns the shared `RequestResult` contract. The\n * runtime is always bundled into `.kubb/client.ts`, so generated code never imports from\n * `@kubb/plugin-ky` and the only runtime dependency is `ky`.\n *\n * @example\n * ```ts\n * import { defineConfig } from 'kubb/config'\n * import { pluginTs } from '@kubb/plugin-ts'\n * import { pluginKy } from '@kubb/plugin-ky'\n *\n * export default defineConfig({\n * input: './petStore.yaml',\n * output: { path: './src/gen' },\n * plugins: [\n * pluginTs(),\n * pluginKy({ output: { path: './clients' } }),\n * ],\n * })\n * ```\n */\nexport const pluginKy = defineExtension<PluginKy>({\n kind: 'plugin',\n meta: { name: pluginKyName, version, compatibility },\n dependencies: clientDependencies,\n setup(options) {\n const resolved = resolveClientOptions(options)\n setupClient({ name: 'ky', resolved, macros: options.macros, client: fileURLToPath(new URL('../templates/client.ts', import.meta.url)) })\n return resolved\n },\n})\n\nexport default pluginKy\n"],"mappings":";;;;;;;;;;;;;;;AEWA,MAAa,eAAe;;;;;;;;;;;;;;;;;;;;;;;AAwB5B,MAAa,WAAW,gBAA0B;CAChD,MAAM;CACN,MAAM;EAAE,MAAM;EAAc;EAAS;CAAc;CACnD,cAAc;CACd,MAAM,SAAS;EACb,MAAM,WAAW,qBAAqB,OAAO;EAC7C,YAAY;GAAE,MAAM;GAAM;GAAU,QAAQ,QAAQ;GAAQ,QAAQ,cAAc,IAAI,IAAI,0BAA0B,YAAY,GAAG,CAAC;EAAE,CAAC;EACvI,OAAO;CACT;AACF,CAAC"}
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
import { KyInstance, Options as Options$1 } from "ky";
|
|
2
|
+
import * as core from "@kubb/plugin-client/templates/core.ts";
|
|
3
|
+
export * from "@kubb/plugin-client/templates/core.ts";
|
|
4
|
+
/**
|
|
5
|
+
* The native request and response that every result and error carries.
|
|
6
|
+
*/
|
|
7
|
+
export type NativeRequest = Request;
|
|
8
|
+
export type NativeResponse = Response;
|
|
9
|
+
/**
|
|
10
|
+
* Extra Ky options for a call or client, such as `retry`, `timeout`, or `hooks`. The left-out options would replace
|
|
11
|
+
* the body or URL the core built, or its status handling. The intersection keeps the options assignable to
|
|
12
|
+
* `RequestInit` under `exactOptionalPropertyTypes`.
|
|
13
|
+
*/
|
|
14
|
+
export type NativeOptions = Omit<Options$1, 'json' | 'prefix' | 'searchParams' | 'throwHttpErrors'> & RequestInit;
|
|
15
|
+
export type ResponseError<TError = unknown, TRequest = NativeRequest, TResponse = NativeResponse> = core.ResponseError<TError, TRequest, TResponse>;
|
|
16
|
+
export declare const ResponseError: {
|
|
17
|
+
new <TError = unknown, TRequest = NativeRequest, TResponse = NativeResponse>(config: ConstructorParameters<typeof core.ResponseError<TError, TRequest, TResponse>>[0]): core.ResponseError<TError, TRequest, TResponse>;
|
|
18
|
+
is: typeof core.ResponseError.is;
|
|
19
|
+
prototype: core.ResponseError<unknown, NativeRequest, NativeResponse>;
|
|
20
|
+
};
|
|
21
|
+
export type RequestConfig<TBody = unknown, TRequest = NativeRequest, TResponse = NativeResponse> = core.RequestConfig<TBody, TRequest, TResponse> & {
|
|
22
|
+
options?: NativeOptions;
|
|
23
|
+
};
|
|
24
|
+
export type Options<TData extends core.DataShape, ThrowOnError extends boolean = true, TRequest = NativeRequest, TResponse = NativeResponse> = core.Options<TData, ThrowOnError, TRequest, TResponse> & {
|
|
25
|
+
options?: NativeOptions;
|
|
26
|
+
};
|
|
27
|
+
export type ClientConfig<TRequest = NativeRequest, TResponse = NativeResponse> = core.ClientConfig<TRequest, TResponse> & {
|
|
28
|
+
options?: NativeOptions;
|
|
29
|
+
};
|
|
30
|
+
export type ResolvedRequest = core.ResolvedRequest & {
|
|
31
|
+
options?: NativeOptions;
|
|
32
|
+
};
|
|
33
|
+
export type RequestResult<TResponses, ThrowOnError extends boolean = true, TRequest = NativeRequest, TResponse = NativeResponse, THeaders = unknown> = core.RequestResult<TResponses, ThrowOnError, TRequest, TResponse, THeaders>;
|
|
34
|
+
export type UnwrappedResult<TResponses, ThrowOnError extends boolean = true, TRequest = NativeRequest, TResponse = NativeResponse, THeaders = unknown> = core.UnwrappedResult<TResponses, ThrowOnError, TRequest, TResponse, THeaders>;
|
|
35
|
+
export type ResponseErrorConfig<TError = unknown> = core.ResponseError<TError, NativeRequest, NativeResponse>;
|
|
36
|
+
export type TransportResult<TRequest = NativeRequest, TResponse = NativeResponse> = core.TransportResult<TRequest, TResponse>;
|
|
37
|
+
export type DecodedResponse<TData = unknown, TRequest = NativeRequest, TResponse = NativeResponse> = core.DecodedResponse<TData, TRequest, TResponse>;
|
|
38
|
+
export type Transport<TRequest = NativeRequest, TResponse = NativeResponse> = core.Transport<TRequest, TResponse>;
|
|
39
|
+
export type Interceptors<TRequest = NativeRequest, TResponse = NativeResponse> = core.Interceptors<TRequest, TResponse>;
|
|
40
|
+
export type ClientInstance<TRequest = NativeRequest, TResponse = NativeResponse> = core.ClientInstance<TRequest, TResponse>;
|
|
41
|
+
export type StreamResult<TResponses, ThrowOnError extends boolean = true, TEvent = core.ServerSentEvent<core.SuccessOf<TResponses>>, TRequest = NativeRequest, TResponse = NativeResponse, THeaders = unknown> = core.StreamResult<TResponses, ThrowOnError, TEvent, TRequest, TResponse, THeaders>;
|
|
42
|
+
export type ResponseErrorOf<TResponses, TRequest = NativeRequest, TResponse = NativeResponse, THeaders = unknown> = core.ResponseErrorOf<TResponses, TRequest, TResponse, THeaders>;
|
|
43
|
+
export declare const isResponseError: <TResponses = unknown, TRequest = NativeRequest, TResponse = NativeResponse, THeaders = unknown>(error: unknown) => error is ResponseErrorOf<TResponses, TRequest, TResponse, THeaders>;
|
|
44
|
+
/**
|
|
45
|
+
* Turns a Ky instance into a transport that keeps its defaults and hooks.
|
|
46
|
+
*/
|
|
47
|
+
export declare function createKyTransport(instance: KyInstance): Transport;
|
|
48
|
+
export declare const defaultTransport: Transport;
|
|
49
|
+
/**
|
|
50
|
+
* The client every generated operation uses unless a call passes its own. It is created on first use.
|
|
51
|
+
*/
|
|
52
|
+
export declare const client: ClientInstance;
|
|
53
|
+
export declare const createClient: ClientInstance['createClient'];
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
# Call operations
|
|
2
|
+
|
|
3
|
+
Call a generated function with grouped request options, read the typed result, and pass content types or Ky options for one call.
|
|
4
|
+
|
|
5
|
+
## Call an operation
|
|
6
|
+
|
|
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
|
+
|
|
9
|
+
```typescript
|
|
10
|
+
import { getPetById } from './gen/clients/getPetById'
|
|
11
|
+
import { updatePet } from './gen/clients/updatePet'
|
|
12
|
+
|
|
13
|
+
const { data } = await getPetById({ path: { petId: 1 } })
|
|
14
|
+
// ^ the parsed pet, typed from the 200 response
|
|
15
|
+
|
|
16
|
+
await updatePet({ path: { petId: 1 }, headers: { 'X-Request-ID': 'r-1' }, body: { name: 'Rex', status: 'sold' } })
|
|
17
|
+
|
|
18
|
+
await getStatus() // no required parameters, no argument
|
|
19
|
+
```
|
|
20
|
+
|
|
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`.
|
|
25
|
+
|
|
26
|
+
## Read the result
|
|
27
|
+
|
|
28
|
+
A call resolves to a `RequestResult`, a union narrowed by the numeric `status`:
|
|
29
|
+
|
|
30
|
+
```typescript
|
|
31
|
+
type RequestResult = {
|
|
32
|
+
status: number
|
|
33
|
+
data: TData // the parsed success body, undefined on an error result
|
|
34
|
+
error: TError // the parsed error body, undefined on a success result
|
|
35
|
+
contentType: string | undefined // the response media type, without parameters
|
|
36
|
+
headers: Headers // the response headers
|
|
37
|
+
request: Request // rebuilt from the resolved request
|
|
38
|
+
response: Response // the native response
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
With the default `throwOnError: true`, a resolved call is always a success. Narrow on `status` when an operation has several success statuses:
|
|
43
|
+
|
|
44
|
+
```typescript
|
|
45
|
+
const result = await getPetById({ path: { petId: 1 } })
|
|
46
|
+
|
|
47
|
+
console.info(result.headers.get('x-ratelimit-remaining')) // suggests the declared header names
|
|
48
|
+
if (result.status === 200) console.info(result.data)
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Unwrap the success body
|
|
52
|
+
|
|
53
|
+
Call `.unwrap()` to get only the success body:
|
|
54
|
+
|
|
55
|
+
```typescript
|
|
56
|
+
const pet = await getPetById({ path: { petId: 1 } }).unwrap()
|
|
57
|
+
// ^ the parsed pet
|
|
58
|
+
```
|
|
59
|
+
|
|
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. |
|
|
64
|
+
|
|
65
|
+
To get the body from every call, set [`returnType: 'data'`](https://kubb.dev/extensions/kubb-labs/plugin-ky/options#returntype) on the plugin.
|
|
66
|
+
|
|
67
|
+
## Set the content type
|
|
68
|
+
|
|
69
|
+
When an operation accepts or returns several content types, set `contentType` on the call. A string sets `Content-Type`, and `response` sets `Accept`:
|
|
70
|
+
|
|
71
|
+
::code-group
|
|
72
|
+
|
|
73
|
+
```typescript [Request only]
|
|
74
|
+
await uploadAvatar({ path: { petId: 1 }, body: avatarBlob, contentType: 'image/png' })
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
```typescript [Request and Accept]
|
|
78
|
+
await getPet({ path: { petId: 1 }, contentType: { request: 'application/json', response: 'application/xml' } })
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
::
|
|
82
|
+
|
|
83
|
+
## Pass Ky options
|
|
84
|
+
|
|
85
|
+
Pass `options` for [Ky options](https://github.com/sindresorhus/ky#options) such as `retry`, `timeout`, and `hooks`, or `fetch` settings such as `cache` and `redirect`:
|
|
86
|
+
|
|
87
|
+
```typescript
|
|
88
|
+
await getPetById({ path: { petId: 1 }, options: { timeout: 5000, retry: { limit: 3 } } })
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
`client.setConfig({ options })` sets shared defaults, and per-call options win. Kubb sets the method, headers, body, and signal over them, and sets `throwHttpErrors: false` to keep control of status handling. `options` does not take `json`, `prefix`, or `searchParams`, because Kubb builds the body and the URL: pass `body`, `baseURL`, and `query` on the call.
|
|
92
|
+
|
|
93
|
+
The client sets `retry: 0`, so a call is sent once, where Ky's own default is 2. See [Retry a call](#retry-a-call) to turn it on. Ky's `timeout` default stays: 10 seconds to get the response headers, or `false` to wait without a limit.
|
|
94
|
+
|
|
95
|
+
## Build a URL without sending
|
|
96
|
+
|
|
97
|
+
`client.getUrl` builds the URL a request would use, with the same base URL and serialization:
|
|
98
|
+
|
|
99
|
+
```typescript
|
|
100
|
+
import { client } from './gen/.kubb/client'
|
|
101
|
+
|
|
102
|
+
const url = client.getUrl({ url: '/pets/{petId}', path: { petId: 1 }, query: { fields: 'name' } })
|
|
103
|
+
// https://petstore.swagger.io/v2/pets/1?fields=name
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Next, [handle errors](https://kubb.dev/extensions/kubb-labs/plugin-ky/guides/error-handling), including `throwOnError: false`.
|
|
107
|
+
|
|
108
|
+
## Less common cases
|
|
109
|
+
|
|
110
|
+
### Path parameter casing
|
|
111
|
+
|
|
112
|
+
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.
|
|
113
|
+
|
|
114
|
+
### Retry a call
|
|
115
|
+
|
|
116
|
+
Set Ky's `retry` option to retry a network error, for every call or for one. Ky retries only the methods in `retry.methods`, which leaves out `POST` and `PATCH`:
|
|
117
|
+
|
|
118
|
+
```typescript
|
|
119
|
+
import { client } from './gen/.kubb/client'
|
|
120
|
+
|
|
121
|
+
client.setConfig({ options: { retry: { limit: 2 } } })
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
`retry` alone does not retry an error status such as `503`, because Kubb reads the error response itself, and Ky only retries a status it throws on. To retry a status, return `ky.retry()` from an `afterResponse` hook, and stop at the limit so the call gets the last response:
|
|
125
|
+
|
|
126
|
+
```typescript
|
|
127
|
+
import ky from 'ky'
|
|
128
|
+
import { client } from './gen/.kubb/client'
|
|
129
|
+
|
|
130
|
+
client.setConfig({
|
|
131
|
+
options: {
|
|
132
|
+
retry: { limit: 2 },
|
|
133
|
+
hooks: {
|
|
134
|
+
afterResponse: [({ response, retryCount, options }) => (response.status === 503 && retryCount < options.retry.limit ? ky.retry() : undefined)],
|
|
135
|
+
},
|
|
136
|
+
},
|
|
137
|
+
})
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
> [!WARNING]
|
|
141
|
+
> `ky.retry()` skips Ky's `retry.methods` check, so this hook also resends a `POST`. Check `request.method` in the hook when that is not safe.
|
|
142
|
+
|
|
143
|
+
### TRACE operations
|
|
144
|
+
|
|
145
|
+
When the spec has a `trace` operation, Kubb generates a call for it, but Ky rejects the `TRACE` method. Use `@kubb/plugin-axios` or a [custom transport](https://kubb.dev/extensions/kubb-labs/plugin-ky/guides/transport) for it.
|