@kubb/plugin-client 5.5.7 → 5.5.8

package/docs/guides/validate-requests-and-responses.md

@@ -0,0 +1,56 @@
+# Validate requests and responses
+
+`@kubb/plugin-client` does not validate on its own. With `validator` set, it passes the schemas to your client, which runs them.
+
+::code-group
+
+```typescript [kubb.config.ts]
+import { defineConfig } from 'kubb/config'
+import { pluginTs } from '@kubb/plugin-ts'
+import { pluginZod } from '@kubb/plugin-zod'
+import { pluginClient } from '@kubb/plugin-client'
+
+export default defineConfig({
+  input: './petStore.yaml',
+  output: { path: './src/gen' },
+  plugins: [
+    pluginTs(),
+    pluginZod(),
+    pluginClient({ importPath: '../../../client', validator: 'zod' }),
+  ],
+})
+```
+
+::
+
+Each generated call now includes the schemas:
+
+```typescript
+request({
+  method: 'POST',
+  url: '/pet',
+  validator: { response: addPetResponseSchema, error: addPetErrorSchema },
+  ...config,
+})
+```
+
+Add a `validator` field to your `RequestConfig`, then run the schemas in `client`. Zod schemas follow [Standard Schema](https://standardschema.dev), so `~standard.validate` works with any compatible library:
+
+```typescript [src/client.ts]
+type Result = { value: unknown; issues?: undefined } | { issues: ReadonlyArray<unknown> }
+type Schema = { '~standard': { validate: (value: unknown) => Result | Promise<Result> } }
+
+export type RequestConfig = {
+  // ...
+  validator?: { request?: Schema; response?: Schema; error?: Schema }
+}
+
+// inside client(), after reading the body
+const result = await config.validator?.response?.['~standard'].validate(body)
+if (result && 'issues' in result && result.issues) throw new Error('Response validation failed')
+const validatedBody = result && 'value' in result ? result.value : body
+```
+
+Return `validatedBody` as `data`, so a schema that transforms the value takes effect. Without a response schema, `validatedBody` is the original `body`.
+
+Set `validator: { request: 'zod' }` or `{ response: 'zod' }` to pass one direction only. Without `pluginZod()` in the plugins list, generation stops with an error.

package/docs/guides/write-your-client.md

@@ -0,0 +1,91 @@
+# Write your client
+
+The generated functions import your module through [`importPath`](https://kubb.dev/extensions/kubb-labs/plugin-client/options#importpath). That module is the only runtime code the generated functions call, and you own it.
+
+## Required exports
+
+| Export          | Kind     | Purpose                                                                                      |
+| --------------- | -------- | -------------------------------------------------------------------------------------------- |
+| `client`        | function | Sends the request. Every generated function calls it, unless a call passes its own `client`. |
+| `Options`       | type     | The grouped options object a generated function accepts.                                     |
+| `RequestResult` | type     | What a generated function resolves to.                                                       |
+
+If your spec has server-sent event operations, also export `toEventStream` and the `EventStreamResult` and `SuccessOf` types.
+
+## What a generated function looks like
+
+```typescript
+import type { Options, RequestResult } from '../../../client'
+import type { GetPetByIdOptions, GetPetByIdResponses } from '../../models/pet/GetPetById'
+import { client } from '../../../client'
+
+export function getPetById<ThrowOnError extends boolean = true>(
+  options: Options<GetPetByIdOptions, ThrowOnError>,
+): Promise<RequestResult<GetPetByIdResponses, ThrowOnError>> {
+  const { client: request = client, ...config } = options
+
+  return request({
+    method: 'GET',
+    url: '/pet/{petId}',
+    security: [{ type: 'apiKey', name: 'api_key', in: 'header' }, { type: 'oauth2' }],
+    ...config,
+    throwOnError: config.throwOnError ?? true,
+  }) as Promise<RequestResult<GetPetByIdResponses, ThrowOnError>>
+}
+```
+
+Your `client` receives `method`, the `url` template with `{param}` placeholders, `security`, the grouped `path`, `query`, `headers`, and `body`, and `throwOnError`. It returns a promise.
+
+## A minimal client
+
+The client below uses `fetch`. Replace the transport with the HTTP library you use.
+
+```typescript [src/client.ts]
+export type RequestConfig = {
+  method: 'GET' | 'PUT' | 'PATCH' | 'POST' | 'DELETE' | 'OPTIONS' | 'HEAD'
+  url: string
+  baseURL?: string
+  headers?: object
+  path?: object
+  query?: object
+  body?: unknown
+  signal?: AbortSignal
+  throwOnError?: boolean
+  security?: Array<{ type: string; name?: string; in?: string }>
+  client?: typeof client
+}
+
+type DataShape = { body?: unknown; headers?: unknown; path?: unknown; query?: unknown }
+
+export type Options<TData extends DataShape, ThrowOnError extends boolean = true> = Omit<RequestConfig, keyof DataShape | 'url' | 'method'> &
+  TData & { throwOnError?: ThrowOnError }
+
+export type RequestResult<TResponses, ThrowOnError extends boolean = true> = ThrowOnError extends true
+  ? { data: TResponses[keyof TResponses]; error: undefined; response: Response }
+  : { data: TResponses[keyof TResponses]; error: undefined; response: Response } | { data: undefined; error: {}; response: Response }
+
+// Set this to your API host. `new URL()` needs an absolute URL.
+export const settings = { baseURL: 'https://petstore3.swagger.io/api/v3' }
+
+export async function client(config: RequestConfig) {
+  const path: Record<string, unknown> = { ...config.path }
+  const url = new URL((config.baseURL ?? settings.baseURL) + config.url.replace(/\{(\w+)\}/g, (_, key) => encodeURIComponent(String(path[key]))))
+
+  const response = await fetch(url, {
+    method: config.method,
+    headers: config.headers as Record<string, string>,
+    body: config.body === undefined ? undefined : JSON.stringify(config.body),
+    signal: config.signal,
+  })
+  const body = await response.json().catch(() => undefined)
+
+  if (response.ok) return { data: body, error: undefined, response }
+  if (config.throwOnError ?? true) throw new Error(`Request failed with status ${response.status}`)
+  return { data: undefined, error: body ?? { status: response.status }, response }
+}
+```
+
+The [example project](https://github.com/kubb-labs/plugins/tree/main/examples/client) has a fuller version with a base URL setter, query handling, and an async auth hook. The types in this sketch are minimal. Add status-aware response types when you need them.
+
+> [!TIP]
+> Kubb does not depend on retries, interceptors, or request signing. Add them to `client` when you need them.

package/docs/options.md

@@ -0,0 +1,79 @@
+# Options
+
+Pass these options to `pluginClient()`. Shared options link to [Shared plugin options](https://kubb.dev/docs/5.x/reference/plugin-options).
+
+## Options overview
+
+| Option                                                                    | Purpose                                                                | Default                                          |
+| ------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------ |
+| [`importPath`](#importpath)                                               | Import specifier of your client module.                                | Required                                         |
+| [`output`](https://kubb.dev/docs/5.x/reference/plugin-options#output)     | Where files are written: `path`, `mode`, `barrel`, `banner`, `footer`. | `{ path: 'clients', barrel: { type: 'named' } }` |
+| [`group`](https://kubb.dev/docs/5.x/reference/plugin-options#group)       | Split output by tag or path: `type`, `name`.                           | None                                             |
+| [`throwOnErrorDefault`](#throwonerrordefault)                             | Default `throwOnError` value passed to your client.                    | `true`                                           |
+| [`validator`](#validator)                                                 | Pass Zod schemas to your client.                                       | `false`                                          |
+| [`include`](https://kubb.dev/docs/5.x/reference/plugin-options#include)   | Keep only operations that match.                                       | None                                             |
+| [`exclude`](https://kubb.dev/docs/5.x/reference/plugin-options#exclude)   | Skip operations that match.                                            | `[]`                                             |
+| [`override`](https://kubb.dev/docs/5.x/reference/plugin-options#override) | Apply different options per pattern.                                   | `[]`                                             |
+| [`resolver`](https://kubb.dev/docs/5.x/reference/plugin-options#resolver) | Customize generated names and file paths.                              | `resolverClient`                                 |
+| [`macros`](https://kubb.dev/docs/5.x/reference/plugin-options#macros)     | Rewrite AST nodes before printing.                                     | `[]`, run after the built-in client macros       |
+
+## Option details
+
+### importPath
+
+Import specifier of your client module. The plugin writes it into every generated import exactly as given, so it must resolve from the generated file. Use a relative path, a package name, or an alias.
+
+|          |          |
+| -------- | -------- |
+| Type     | `string` |
+| Required | `true`   |
+
+```typescript
+pluginClient({ importPath: '../../../client' }) // relative to src/gen/clients/<tag>/
+pluginClient({ importPath: '@my-org/api-client' }) // a package
+```
+
+With `group: { type: 'tag' }` and `output.path: 'clients'`, a generated file sits in `src/gen/clients/<tag>/`, so `../../../client` points at `src/client.ts`. Without `group` it is `../../client`.
+
+The module must export `client`, plus the `Options` and `RequestResult` types. See [write your client](https://kubb.dev/extensions/kubb-labs/plugin-client/guides/write-your-client).
+
+### throwOnErrorDefault
+
+Default for the `throwOnError` field that every generated function passes to your client. A call that sets `throwOnError` itself wins. Your client decides what the flag does: the [example client](https://kubb.dev/extensions/kubb-labs/plugin-client/guides/write-your-client) throws on a non-2xx status when it is `true` and returns the error as a value when it is `false`.
+
+|          |           |
+| -------- | --------- |
+| Type     | `boolean` |
+| Required | `false`   |
+| Default  | `true`    |
+
+The setting applies to the whole plugin, so you cannot set it in `override`.
+
+### validator
+
+Passes Zod schemas from `@kubb/plugin-zod` to your client on `config.validator`. The plugin does not run the schemas. Your client reads `config.validator` and runs them. See [validate requests and responses](https://kubb.dev/extensions/kubb-labs/plugin-client/guides/validate-requests-and-responses).
+
+|          |                                                           |
+| -------- | --------------------------------------------------------- |
+| Type     | `false \| 'zod' \| { request?: 'zod'; response?: 'zod' }` |
+| Required | `false`                                                   |
+| Default  | `false`                                                   |
+
+::field-group
+
+:::field{name="false"}
+Default value. Passes nothing.
+:::
+
+:::field{name="'zod'"}
+Passes the response and error schemas.
+:::
+
+:::field{name="{ request?: 'zod', response?: 'zod' }"}
+Opts in per direction.
+:::
+
+::
+
+> [!IMPORTANT]
+> Add `pluginZod()` to the plugins list when `validator` is set. Generation stops with an error if it is missing.

package/docs/overview.md

@@ -0,0 +1,47 @@
+# Client
+
+Generates typed operation functions from your OpenAPI spec that call a client module you write. You decide the transport, authentication, and error handling, and the generated code has no Fetch, axios, or Kubb runtime dependency.
+
+Each function takes grouped `path`, `query`, `headers`, and `body` parameters and passes the operation's auth requirements to your client in a `security` list. A single call can pass its own `client` to replace the default.
+
+Use it to connect the generated functions to an HTTP layer you already have, or to sign requests. For a ready-made client, use `@kubb/plugin-fetch` or `@kubb/plugin-axios` instead.
+
+## Setup
+
+- Set `importPath` to your client module. It is required. The module must export `client` and the `Options` and `RequestResult` types.
+- Add `@kubb/plugin-ts` for the operation types.
+- Add `@kubb/plugin-zod` when you set `validator`. Generation fails without it.
+
+## Options worth knowing
+
+- `importPath` is written into every generated import as given, so it must resolve from the generated file. A relative path, a package name, or an alias works.
+- `validator: 'zod'` passes request and response schemas from `@kubb/plugin-zod` to your client.
+- `throwOnErrorDefault` is the `throwOnError` value each call passes to your client. The default is `true`.
+
+## Example
+
+```typescript [kubb.config.ts]
+import { defineConfig } from 'kubb/config'
+import { pluginTs } from '@kubb/plugin-ts'
+import { pluginClient } from '@kubb/plugin-client'
+
+export default defineConfig({
+  input: './petStore.yaml',
+  output: { path: './src/gen' },
+  plugins: [
+    pluginTs(),
+    pluginClient({
+      output: { path: 'clients', mode: 'directory', barrel: { type: 'named' } },
+      group: { type: 'tag' },
+      // resolved from each generated file: src/gen/clients/<tag>/ to src/client.ts
+      importPath: '../../../client',
+    }),
+  ],
+})
+```
+
+## See also
+
+- [`@kubb/plugin-fetch`](https://kubb.dev/extensions/kubb-labs/plugin-fetch)
+- [`@kubb/plugin-axios`](https://kubb.dev/extensions/kubb-labs/plugin-axios)
+- [Example project](https://github.com/kubb-labs/plugins/tree/main/examples/client)

package/kubb-extension.json

@@ -10,9 +10,16 @@
     "light": "https://kubb.dev/feature/javascript.svg"
   },
   "tags": ["api-client", "http-client", "codegen", "openapi"],
-  "docs": "https://kubb.dev/plugins/plugin-client",
+  "docs": "https://kubb.dev/extensions/kubb-labs/plugin-client",
+  "maintainers": [
+    {
+      "name": "Stijn Van Hulle",
+      "github": "stijnvanhulle"
+    }
+  ],
+  "dependencies": ["plugin-ts"],
   "compatibility": {
-    "kubb": ">=5.8.0",
+    "kubb": ">=5.8.3",
     "node": ">=22"
   },
   "options": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/plugin-client",
-  "version": "5.5.7",
+  "version": "5.5.8",
   "description": "Generate typed API operations against your own client module.",
   "keywords": [
     "api-client",
@@ -11,7 +11,7 @@
     "swagger",
     "typescript"
   ],
-  "homepage": "https://kubb.dev/plugins/plugin-client",
+  "homepage": "https://kubb.dev/extensions/kubb-labs/plugin-client",
   "license": "MIT",
   "author": "stijnvanhulle",
   "repository": {
@@ -23,7 +23,7 @@
     "src",
     "dist",
     "kubb-extension.json",
-    "OVERVIEW.md",
+    "docs",
     "!/**/**.test.**",
     "!/**/__tests__/**",
     "!/**/__snapshots__/**"
@@ -47,17 +47,17 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@kubb/plugin-ts": "^5.0.8",
-    "@kubb/plugin-zod": "^5.4.6"
+    "@kubb/plugin-ts": "^5.0.9",
+    "@kubb/plugin-zod": "^5.4.7"
   },
   "devDependencies": {
     "@internals/client": "0.0.0",
     "@internals/shared": "0.0.0",
-    "kubb": "^5.8.1",
+    "kubb": "^5.8.3",
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "kubb": "^5.8.1"
+    "kubb": "^5.8.3"
   },
   "engines": {
     "node": ">=22"

package/src/plugin.ts

@@ -1,5 +1,5 @@
 import { createGroupConfig } from '@internals/shared'
-import { addGenerator, definePlugin, Resolver, setMacros, setResolver } from 'kubb/kit'
+import { addGenerator, defineExtension, Resolver, setMacros, setResolver } from 'kubb/kit'
 import { compatibility } from '../kubb-extension.json'
 import { version } from '../package.json'
 import { pluginTsName } from '@kubb/plugin-ts'
@@ -23,7 +23,8 @@ export const pluginClientName = 'plugin-client' satisfies PluginClient['name']
  * pluginClient({ importPath: '../api/client' })
  * ```
  */
-export const pluginClient = definePlugin<PluginClient>({
+export const pluginClient = defineExtension<PluginClient>({
+  kind: 'plugin',
   meta: { name: pluginClientName, version, compatibility },
   dependencies: (options) => ({ [pluginTsName]: { optional: true }, [pluginZodName]: { optional: !options.validator } }),
   setup(options) {

package/OVERVIEW.md

@@ -1,17 +0,0 @@
-# Client
-
-Generates typed operation functions from your OpenAPI spec that call a client module you write. You decide the transport, authentication, and error handling, and the generated code has no Fetch, axios, or Kubb runtime dependency.
-
-Use it for signed requests, a shared client, or an existing HTTP layer. For a ready-made client, use `@kubb/plugin-fetch` or `@kubb/plugin-axios` instead.
-
-## Setup
-
-- Set `importPath` to your client module. It is required. The module must export `client` and the `Options` and `RequestResult` types.
-- Add `@kubb/plugin-ts` for the operation types.
-- Add `@kubb/plugin-zod` when you set `validator`. Generation fails without it.
-
-## Options worth knowing
-
-- `importPath` is written into every generated import as given, so it must resolve from the generated file. A relative path, a package name, or an alias works.
-- `validator: 'zod'` passes request and response schemas from `@kubb/plugin-zod` to your client.
-- `throwOnErrorDefault` is the `throwOnError` value each call passes to your client. The default is `true`.