@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 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
- # Temporary Holding Version
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
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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"}
@@ -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 };
@@ -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.