@kubb/plugin-client 5.10.0-canary.20261105T164114 → 5.10.0

package/README.md

@@ -10,7 +10,7 @@ pluginClient({ importPath: '../api/client' })
 
 `importPath` is written into each generated import as-is, so it must resolve from the generated operation file (for example `../../../client`, or a package or alias specifier). The module must export `client`, plus the `Options` and `RequestResult` types. Generated operations call `client` with a config containing `method`, `url`, and the operation options, and return its promise typed as `RequestResult`. There are no `withUnwrap` or `unwrapResult` helpers to write, and `returnType` is not an option.
 
-If your spec has server-sent event operations, also export `toEventStream` and the `EventStreamResult` and `SuccessOf` types. Implement the behavior your application needs in that module.
+If your spec has server-sent event operations, also export `toEventStream` and the `EventStreamResult`, `SuccessOf`, and `TypedEvent` types. A generated function calls `toEventStream<TData>(promise)` with the promise your `client` returns and nothing else, and leaves the response validator on `config.validator.response`, so your module decides how to validate events.
 
 Set the base URL, auth, retries, and any other behavior inside your `client`. `sdk`, `returnType`, and `baseURL` are not options of this plugin. `validator: 'zod'` needs `pluginZod()` in the plugins, and generation stops with an error if it is missing. Your `client` receives the schemas on `config.validator` (`{ request?, response?, error? }`), so add that field to your `RequestConfig` and run them yourself.
 

package/dist/client-CiHb_Cfg.d.ts

@@ -0,0 +1,345 @@
+import { _ as Serializers, h as RequestBody, o as HeadersInit, s as HttpMethod, v as Styles } from "./serializers-Ds8zZwOO.js";
+import { a as ValidateOption, i as StandardSchemaValidator, s as ValidationErrorHandler } from "./standardSchema-BShJWz2i.js";
+/**
+ * HTTP status codes treated as a success, everything else is an error.
+ */
+type SuccessStatusCode = '200' | '201' | '202' | '203' | '204' | '205' | '206' | '207' | '208' | '226';
+type SuccessOf<TResponses> = TResponses[Extract<keyof TResponses, SuccessStatusCode>];
+type ErrorOf<TResponses> = TResponses[Exclude<keyof TResponses, SuccessStatusCode>];
+/**
+ * Converts a response record's string status key to its numeric literal, leaving non-numeric keys like `default` as `number`.
+ */
+type ToStatusNumber<TStatus> = TStatus extends `${infer TNumber extends number}` ? TNumber : number;
+/**
+ * Unwraps content-type variants to keep the bare body on `error`.
+ */
+type DataOf<T> = T extends {
+  contentType: string;
+  data: infer TData;
+} ? TData : T;
+/**
+ * Keeps `contentType` beside `data` so switching on it narrows the body.
+ */
+type SuccessVariant<TStatus, TEntry, TRequest, TResponse> = TEntry extends {
+  contentType: string;
+  data: unknown;
+} ? TEntry extends {
+  contentType: infer TContentType;
+  data: infer TData;
+} ? {
+  status: ToStatusNumber<TStatus>;
+  data: TData;
+  error: undefined;
+  contentType: TContentType;
+  request: TRequest;
+  response: TResponse;
+} : never : {
+  status: ToStatusNumber<TStatus>;
+  data: TEntry;
+  error: undefined;
+  contentType: string | undefined;
+  request: TRequest;
+  response: TResponse;
+};
+/**
+ * Narrows `data` or `error` when switching on the numeric status.
+ */
+type ResultByStatus<TResponses, TStatus extends keyof TResponses, TRequest, TResponse> = TStatus extends SuccessStatusCode ? SuccessVariant<TStatus, TResponses[TStatus], TRequest, TResponse> : {
+  status: ToStatusNumber<TStatus>;
+  data: undefined;
+  error: DataOf<TResponses[TStatus]>;
+  contentType: string | undefined;
+  request: TRequest;
+  response: TResponse;
+};
+type ResultUnion<TResponses, TRequest, TResponse> = { [TStatus in keyof TResponses]: ResultByStatus<TResponses, TStatus, TRequest, TResponse>; }[keyof TResponses];
+/**
+ * Selects success statuses without letting untyped error payloads widen `data`.
+ */
+type SuccessResultUnion<TResponses, TRequest, TResponse> = { [TStatus in Extract<keyof TResponses, SuccessStatusCode>]: ResultByStatus<TResponses, TStatus, TRequest, TResponse>; }[Extract<keyof TResponses, SuccessStatusCode>];
+/**
+ * Narrows `data` and `error` by status. With `throwOnError`, includes only success variants.
+ */
+type RequestResult<TResponses, ThrowOnError extends boolean = true, TRequest = NativeRequest, TResponse = NativeResponse> = ThrowOnError extends true ? [SuccessResultUnion<TResponses, TRequest, TResponse>] extends [never] ? {
+  status: number;
+  data: SuccessOf<TResponses>;
+  error: undefined;
+  contentType: string | undefined;
+  request: TRequest;
+  response: TResponse;
+} : SuccessResultUnion<TResponses, TRequest, TResponse> : [ResultUnion<TResponses, TRequest, TResponse>] extends [never] ? {
+  status: number;
+  data: undefined;
+  error: undefined;
+  contentType: string | undefined;
+  request: TRequest;
+  response: TResponse;
+} : ResultUnion<TResponses, TRequest, TResponse>;
+/**
+ * A `RequestResult` promise with an extra `unwrap()` method that resolves to the success body.
+ */
+type Unwrappable<T extends {
+  data: unknown;
+  error: unknown;
+}> = Promise<T> & {
+  unwrap: () => Promise<Extract<T, {
+    error: undefined;
+  }>['data']>;
+};
+/**
+ * Attaches `unwrap()` to a result promise, which rejects with `error` when the result carried one.
+ *
+ * @example
+ * ```ts
+ * const { data, error } = await getPetById({ path: { petId: 1 } })
+ * ```
+ *
+ * @example
+ * ```ts
+ * const pet = await getPetById({ path: { petId: 1 } }).unwrap()
+ * ```
+ */
+declare function withUnwrap<T extends {
+  data: unknown;
+  error: unknown;
+}>(promise: Promise<T>): Unwrappable<T>;
+/**
+ * The shape a generated operation returns with `returnType: 'data'`: the success body when
+ * `throwOnError` is true, or the full `RequestResult` when it is false.
+ */
+type UnwrappedResult<TResponses, ThrowOnError extends boolean = true, TRequest = NativeRequest, TResponse = NativeResponse> = ThrowOnError extends true ? RequestResult<TResponses, true, TRequest, TResponse>['data'] : RequestResult<TResponses, ThrowOnError, TRequest, TResponse>;
+/**
+ * Returns the success body when `throwOnError` is true, or the full result when it is false.
+ */
+declare function unwrapResult<T extends {
+  data: unknown;
+  error: unknown;
+}>(promise: Promise<T>, throwOnError: boolean | undefined): Promise<T | T['data']>;
+type DataShape = {
+  body?: unknown;
+  cookies?: unknown;
+  headers?: unknown;
+  path?: unknown;
+  query?: unknown;
+};
+type RequestCredentials = 'omit' | 'same-origin' | 'include';
+type ResponseType = 'arraybuffer' | 'blob' | 'document' | 'json' | 'text' | 'stream' | 'formdata';
+/**
+ * Decodes a response body for a codec's media type.
+ */
+type Deserializer<T = unknown> = (raw: unknown, contentType: string) => T | Promise<T>;
+/**
+ * Encodes a request body for a codec's media type.
+ */
+type ContentBodySerializer = (body: unknown, contentType?: string) => RequestBody | undefined;
+/**
+ * Encodes requests or decodes responses for a media type. Either direction can be omitted.
+ */
+type Codec = {
+  serialize?: ContentBodySerializer;
+  deserialize?: Deserializer;
+};
+/**
+ * A string sets the request content type. The object form can also set `Accept`.
+ */
+type ContentType = string | {
+  request?: string;
+  response?: string;
+};
+/**
+ * Validates request bodies and params, success bodies, or non-throwing error bodies with Standard Schema.
+ */
+type Validator<T = unknown> = StandardSchemaValidator<T>;
+/**
+ * A resolved security scheme carried on each generated call's `security` array and passed to the `auth` resolver.
+ */
+type Auth = {
+  type: 'http' | 'apiKey' | 'oauth2' | 'openIdConnect';
+  scheme?: 'bearer' | 'basic';
+  name?: string;
+  in?: 'header' | 'query' | 'cookie';
+  scopes?: Array<string>;
+};
+/**
+ * Return `user:password` for basic auth, or `undefined` to skip a scheme.
+ */
+type AuthToken = string | undefined;
+/**
+ * Resolves the token for a security scheme, either a static token or a callback called per scheme until one returns a token.
+ */
+type AuthResolver = AuthToken | ((auth: Auth) => AuthToken | Promise<AuthToken>);
+type RequestConfig<TBody = unknown, TRequest = NativeRequest, TResponse = NativeResponse> = {
+  baseURL?: string;
+  url?: string;
+  method?: HttpMethod;
+  path?: unknown;
+  query?: unknown;
+  /** Alias of `query`, kept for callers that pass the query under this name. */
+  params?: unknown;
+  cookies?: unknown;
+  body?: TBody;
+  headers?: unknown;
+  styles?: Styles;
+  signal?: AbortSignal;
+  credentials?: RequestCredentials;
+  options?: Record<string, unknown>;
+  contentType?: ContentType;
+  responseType?: ResponseType;
+  throwOnError?: boolean;
+  client?: ClientInstance<TRequest, TResponse>;
+  transport?: Transport<TRequest, TResponse>;
+  serializer?: Serializers;
+  codecs?: Record<string, Codec>;
+  validator?: {
+    request?: Validator;
+    path?: Validator;
+    query?: Validator;
+    headers?: Validator;
+    response?: Validator;
+    error?: Validator;
+  };
+  onValidationError?: ValidationErrorHandler;
+  validate?: ValidateOption;
+  security?: Array<Auth>;
+  auth?: AuthResolver;
+};
+/**
+ * Combines client options with the operation's typed request params and body.
+ */
+type Options<TData extends DataShape, ThrowOnError extends boolean = true, TRequest = NativeRequest, TResponse = NativeResponse> = Omit<RequestConfig<unknown, TRequest, TResponse>, keyof DataShape | 'url'> & TData & {
+  client?: ClientInstance<TRequest, TResponse>;
+  throwOnError?: ThrowOnError;
+};
+/**
+ * Client-level configuration shared by every call an instance makes, overridden by the per-call `RequestConfig`.
+ */
+type ClientConfig<TRequest = NativeRequest, TResponse = NativeResponse> = {
+  baseURL?: string;
+  headers?: HeadersInit;
+  credentials?: RequestCredentials;
+  options?: Record<string, unknown>;
+  throwOnError?: boolean;
+  transport?: Transport<TRequest, TResponse>;
+  serializer?: Serializers;
+  codecs?: Record<string, Codec>;
+  onValidationError?: ValidationErrorHandler;
+  validate?: ValidateOption;
+  auth?: AuthResolver;
+};
+/**
+ * The normalized request the transport receives, with all serialization, auth, and header work already done.
+ */
+type ResolvedRequest = {
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  body?: RequestBody;
+  signal?: AbortSignal;
+  credentials?: RequestCredentials;
+  options?: Record<string, unknown>;
+  responseType?: ResponseType;
+};
+/**
+ * What a transport returns: the parsed body plus the native request and response objects.
+ */
+type TransportResult<TData = unknown, TRequest = NativeRequest, TResponse = NativeResponse> = {
+  data: TData;
+  status: number;
+  statusText: string;
+  headers: Headers;
+  contentType?: string;
+  request: TRequest;
+  response: TResponse;
+};
+/**
+ * The per-plugin send, supplied to `createClientCore` as `defaultTransport`.
+ */
+type Transport<TRequest = NativeRequest, TResponse = NativeResponse> = (request: ResolvedRequest) => Promise<TransportResult<unknown, TRequest, TResponse>>;
+type CallResult<TRequest = NativeRequest, TResponse = NativeResponse> = {
+  status: number;
+  data: unknown;
+  error: unknown;
+  contentType: string | undefined;
+  request: TRequest;
+  response: TResponse;
+};
+type InterceptorFn<T, TContext = never> = (value: T, context?: TContext) => T | Promise<T>;
+/**
+ * A single interceptor channel with a transport-agnostic `use` / `eject` / `update` API.
+ */
+type InterceptorStack<T, TContext = never> = {
+  use: (fn: InterceptorFn<T, TContext>) => number;
+  eject: (id: number) => void;
+  update: (id: number, fn: InterceptorFn<T, TContext>) => void;
+  run: (value: T, context?: TContext) => Promise<T>;
+};
+type Interceptors<TRequest = NativeRequest, TResponse = NativeResponse> = {
+  request: InterceptorStack<ResolvedRequest, RequestConfig<unknown, TRequest, TResponse>>;
+  response: InterceptorStack<TransportResult<unknown, TRequest, TResponse>, RequestConfig<unknown, TRequest, TResponse>>;
+  error: InterceptorStack<ResponseError<unknown, TRequest, TResponse>, RequestConfig<unknown, TRequest, TResponse>>;
+};
+type UrlConfig = Pick<RequestConfig, 'baseURL' | 'url' | 'path' | 'query' | 'params' | 'serializer' | 'styles'>;
+/**
+ * A client instance: the callable send plus configuration, interceptors, and an isolated
+ * `createClient` factory bound to the same transport.
+ */
+type ClientInstance<TRequest = NativeRequest, TResponse = NativeResponse> = {
+  <TBody = unknown>(config: RequestConfig<TBody, TRequest, TResponse>): Promise<CallResult<TRequest, TResponse>>;
+  getConfig: () => ClientConfig<TRequest, TResponse>;
+  setConfig: (config: ClientConfig<TRequest, TResponse>) => ClientConfig<TRequest, TResponse>;
+  getUrl: (config: UrlConfig) => string;
+  interceptors: Interceptors<TRequest, TResponse>;
+  createClient: (config?: ClientConfig<TRequest, TResponse>) => ClientInstance<TRequest, TResponse>;
+};
+/**
+ * Thrown for a non-2xx response, so a resolved call always means success.
+ */
+declare class ResponseError<TError = unknown, TRequest = NativeRequest, TResponse = NativeResponse> extends Error {
+  data: TError;
+  status: number;
+  statusText: string;
+  contentType: string | undefined;
+  request: TRequest;
+  response: TResponse;
+  constructor(config: {
+    data: TError;
+    status: number;
+    statusText: string;
+    contentType?: string;
+    request: TRequest;
+    response: TResponse;
+    method?: string;
+    url?: string;
+  });
+  /**
+   * Matches on `name`, not `instanceof`: every generated client bundles its own `ResponseError` class.
+   */
+  static is(error: unknown): error is ResponseError<unknown, unknown, unknown>;
+}
+type ResponseErrorConfig<TError = unknown> = ResponseError<TError>;
+/**
+ * Creates a transport-agnostic interceptor channel that runs interceptors in registration order.
+ */
+declare function createInterceptorStack<T, TContext = never>(): InterceptorStack<T, TContext>;
+/**
+ * Walks the per-operation security in order and places the first resolved token on the request, mutating `headers` / `query` in place.
+ */
+declare function resolveAuth(params: {
+  security: Array<Auth> | undefined;
+  auth: AuthResolver | undefined;
+  headers: Record<string, string>;
+  query: Record<string, unknown>;
+}): Promise<void>;
+/** A body a transport left as a stream: a web `ReadableStream` or an async iterable such as a Node readable. */
+declare function isStreamed(data: unknown): data is ReadableStream<Uint8Array> | AsyncIterable<Uint8Array | string>;
+/** The media type of the `Content-Type` response header, without its parameters. */
+declare function getResponseContentType(headers: Headers | Record<string, string> | undefined): string | undefined;
+/**
+ * Creates an isolated client using the supplied default transport.
+ */
+declare function createClientCore<TRequest = NativeRequest, TResponse = NativeResponse>(options: {
+  defaultTransport: Transport<TRequest, TResponse>;
+} & ClientConfig<TRequest, TResponse>): ClientInstance<TRequest, TResponse>;
+type NativeRequest = unknown;
+type NativeResponse = unknown;
+export { SuccessResultUnion as A, createClientCore as B, ResolvedRequest as C, ResultByStatus as D, ResponseType as E, TransportResult as F, unwrapResult as G, getResponseContentType as H, Unwrappable as I, withUnwrap as K, UnwrappedResult as L, SuccessVariant as M, ToStatusNumber as N, ResultUnion as O, Transport as P, UrlConfig as R, RequestResult as S, ResponseErrorConfig as T, isStreamed as U, createInterceptorStack as V, resolveAuth as W, InterceptorStack as _, AuthToken as a, RequestConfig as b, ClientInstance as c, ContentType as d, DataOf as f, InterceptorFn as g, ErrorOf as h, AuthResolver as i, SuccessStatusCode as j, SuccessOf as k, Codec as l, Deserializer as m, NativeResponse as n, CallResult as o, DataShape as p, Auth as r, ClientConfig as s, NativeRequest as t, ContentBodySerializer as u, Interceptors as v, ResponseError as w, RequestCredentials as x, Options as y, Validator as z };