hanzio 1.2.0 → 2.0.0

package/dist/api-wrapper/builders.d.ts

@@ -4,20 +4,21 @@ import type { ApiEndpoint } from './types';
 export type BuildUrlOptions = {
     endpoint: ApiEndpoint;
     params: PathParams | undefined;
-    queryParams: Record<string, string>;
+    queryParams: QueryParams;
     baseApiUrls: Record<string, BaseApiUrl>;
     defaultBaseApiUrl: string | undefined;
     url: string | undefined;
     doNotEncodeQueryParams?: boolean;
     configError: (msg: string) => ConfigError;
 };
-export declare function formatQueryString(queryParams: Record<string, string>, doNotEncode?: boolean): string;
 export declare function buildUrl(options: BuildUrlOptions): {
     finalUrl: string;
     fullUrl: string;
 };
 export declare function buildPathParams(endpoint: ApiEndpoint, params: PathParams | undefined, ctx: (over?: Partial<ApiErrorContext>) => ApiErrorContext): PathParams | undefined;
-export declare function buildQueryParams(endpoint: ApiEndpoint, query: QueryParams | undefined, ctx: (over?: Partial<ApiErrorContext>) => ApiErrorContext): Record<string, string>;
+export declare function buildQueryParams(endpoint: ApiEndpoint, query: QueryParams | undefined, ctx: (over?: Partial<ApiErrorContext>) => ApiErrorContext): QueryParams;
 export declare function buildRequestBody(endpoint: ApiEndpoint, body: unknown, ctx: (over?: Partial<ApiErrorContext>) => ApiErrorContext): unknown;
 export declare function buildHeaders(endpoint: ApiEndpoint, headers: Record<string, string> | undefined, defaultHeaders: Record<string, string>, ctx: (over?: Partial<ApiErrorContext>) => ApiErrorContext): Record<string, string>;
+/** Joins with exactly one `/`; empty paths and query-only paths are appended as-is. */
+export declare function joinUrlPath(base: string, path: string): string;
 export declare function replacePathParams(path: string, params: PathParams | undefined, configError: (msg: string) => ConfigError): string;

package/dist/api-wrapper/create-client.d.ts

@@ -1,6 +1,6 @@
 import type { ApiAction, ApiClient, ApiClientConfigNoActions, ApiClientConfigWithActions, ApiEndpoint } from './types';
 export interface CreateApiClientFn {
-    <T extends Record<string, ApiEndpoint>>(apiConfig: ApiClientConfigNoActions<T>): ApiClient<T, Record<string, never>>;
     <T extends Record<string, ApiEndpoint>, A extends Record<string, ApiAction>>(apiConfig: ApiClientConfigWithActions<T, A>): ApiClient<T, A>;
+    <T extends Record<string, ApiEndpoint>>(apiConfig: ApiClientConfigNoActions<T>): ApiClient<T, Record<string, never>>;
 }
 export declare const createApiClient: CreateApiClientFn;

package/dist/api-wrapper/describe.d.ts

@@ -0,0 +1,16 @@
+import { type ApiError } from './errors';
+/**
+ * A multi-line, human-readable summary of an `ApiError` that says up front
+ * whether the server, the caller's input, or the response shape is at fault.
+ * The client logs this via `logger.error` for every failed request.
+ *
+ * @example
+ * ✗ github.usersGet failed: output validation failed: the response doesn't match resSchema
+ *   GET https://api.github.com/users/1 · attempt 1/4 · 212ms
+ *   [1] id: Expected number, received string
+ *       value: "oops"
+ *   fix: update resSchema (or resFormatter), or mark changed fields optional
+ */
+export declare function describeApiError(error: ApiError): string;
+/** Flat, primitive attributes for structured loggers and log processors. */
+export declare function apiErrorLogAttributes(error: ApiError): Record<string, string | number | boolean>;

package/dist/api-wrapper/endpoint.d.ts

@@ -0,0 +1,18 @@
+import type { z } from 'zod';
+import type { ApiEndpoint } from './types';
+/**
+ * Defines an endpoint with full inference, as an alternative to
+ * `satisfies ApiEndpoint`: `resFormatter` must return what `resSchema`
+ * accepts, and a literal `path` types its `:params` (making `reqParams`
+ * required when there's no `reqParamsSchema`).
+ *
+ * @example
+ * export const usersGet = defineEndpoint({
+ *   method: 'GET',
+ *   path: '/users/:userId',
+ *   resSchema: User
+ * })
+ */
+export declare function defineEndpoint<const TEndpoint extends ApiEndpoint>(endpoint: TEndpoint & {
+    resFormatter?: (data: unknown, headers: Record<string, string>) => z.input<TEndpoint['resSchema']>;
+}): TEndpoint;

package/dist/api-wrapper/errors.d.ts

@@ -1,9 +1,22 @@
 import type { ZodError } from 'zod';
 import type { ApiErrorContext } from './shared';
 import { type FormattedZodIssue } from './zod-issues';
+/**
+ * Where a request failed, for logs and alerts:
+ * - `server_error`: the API returned 5xx
+ * - `client_error`: the API rejected the request (4xx: auth, params, body)
+ * - `input_validation`: the caller's data failed a request schema; nothing was sent
+ * - `output_validation`: the response wasn't JSON or didn't match `resSchema`
+ * - `response_rejected`: `checkResponse` rejected a valid response
+ * - `network` / `timeout` / `aborted`: the request didn't complete
+ * - `config`: the client or call is misconfigured
+ * - `action`: a composite action handler threw
+ */
+export type ApiErrorCategory = 'server_error' | 'client_error' | 'input_validation' | 'output_validation' | 'response_rejected' | 'network' | 'timeout' | 'aborted' | 'config' | 'action' | 'unknown';
 export declare class ApiError extends Error {
     context: ApiErrorContext;
     cause?: unknown;
+    get category(): ApiErrorCategory;
     constructor(message: string, context: ApiErrorContext, options?: {
         cause?: unknown;
     });
@@ -16,6 +29,7 @@ export declare class HttpResponseError extends ApiError {
     readonly responseHeaders: Record<string, string>;
     readonly requestId?: string;
     constructor(status: number, body: string, responseHeaders: Record<string, string>, context: ApiErrorContext);
+    get category(): ApiErrorCategory;
     toJSON(): Record<string, unknown>;
 }
 export declare class ResponseValidationError extends ApiError {
@@ -23,10 +37,16 @@ export declare class ResponseValidationError extends ApiError {
     readonly rawResponse: unknown;
     readonly issues: FormattedZodIssue[];
     readonly validationIssues: string;
-    constructor(zodError: ZodError, rawResponse: unknown, context: ApiErrorContext);
+    /** True when the body wasn't valid JSON (rather than failing `resSchema`). */
+    readonly invalidJson: boolean;
+    constructor(zodError: ZodError, rawResponse: unknown, context: ApiErrorContext, options?: {
+        invalidJson?: boolean;
+    });
+    get category(): ApiErrorCategory;
     toJSON(): Record<string, unknown>;
 }
-export type RequestValidationTarget = 'body' | 'query' | 'params' | 'headers';
+/** Which request schema failed; `input` is an action's input schema. */
+export type RequestValidationTarget = 'body' | 'query' | 'params' | 'headers' | 'input';
 export declare class RequestValidationError extends ApiError {
     readonly zodError: ZodError;
     readonly target: RequestValidationTarget;
@@ -34,23 +54,39 @@ export declare class RequestValidationError extends ApiError {
     readonly issues: FormattedZodIssue[];
     readonly validationIssues: string;
     constructor(zodError: ZodError, target: RequestValidationTarget, rawInput: unknown, context: ApiErrorContext);
+    get category(): ApiErrorCategory;
     toJSON(): Record<string, unknown>;
 }
 export declare class RequestTimeoutError extends ApiError {
     readonly timeoutMs: number;
     constructor(timeoutMs: number, context: ApiErrorContext);
+    get category(): ApiErrorCategory;
 }
 export declare class NetworkError extends ApiError {
     constructor(message: string, context: ApiErrorContext, cause?: unknown);
+    get category(): ApiErrorCategory;
 }
 export declare class RequestAbortedError extends ApiError {
     constructor(context: ApiErrorContext, cause?: unknown);
+    get category(): ApiErrorCategory;
 }
 export declare class ConfigError extends ApiError {
     constructor(message: string, context: ApiErrorContext);
+    get category(): ApiErrorCategory;
+}
+/**
+ * Thrown when the client's `checkResponse` rejects a response that passed
+ * schema validation (e.g. HTTP 200 with `{ success: false }`).
+ */
+export declare class ApiResponseError extends ApiError {
+    readonly data: unknown;
+    constructor(message: string, data: unknown, context: ApiErrorContext, cause?: unknown);
+    get category(): ApiErrorCategory;
+    toJSON(): Record<string, unknown>;
 }
 export declare class ActionError extends ApiError {
     constructor(message: string, context: ApiErrorContext, cause?: unknown);
+    get category(): ApiErrorCategory;
 }
 export declare const isApiError: (e: unknown) => e is ApiError;
 export declare const isHttpResponseError: (e: unknown) => e is HttpResponseError;
@@ -61,4 +97,5 @@ export declare const isNetworkError: (e: unknown) => e is NetworkError;
 export declare const isRequestAbortedError: (e: unknown) => e is RequestAbortedError;
 export declare const isConfigError: (e: unknown) => e is ConfigError;
 export declare const isActionError: (e: unknown) => e is ActionError;
+export declare const isApiResponseError: (e: unknown) => e is ApiResponseError;
 export declare function isNonRetryableApiError(error: unknown): boolean;

package/dist/api-wrapper/index.d.ts

@@ -3,3 +3,8 @@ export * from './types';
 export * from './errors';
 export { createApiClient } from './create-client';
 export { defineAction } from './actions-impl';
+export { type PaginateOptions, paginate } from './paginate';
+export { defaultShouldRetry } from './transport';
+export { apiErrorLogAttributes, describeApiError } from './describe';
+export * from './otel';
+export { defineEndpoint } from './endpoint';

package/dist/api-wrapper/otel.d.ts

@@ -0,0 +1,44 @@
+import type { ApiMiddleware, ApiMiddlewareContext } from './types';
+export type OtelAttributes = Record<string, string | number | boolean | undefined>;
+export type OtelSpanLike = {
+    setAttributes(attributes: OtelAttributes): unknown;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): unknown;
+    recordException(exception: Error | string): unknown;
+    end(): void;
+};
+export type OtelTracerLike = {
+    startActiveSpan<F extends (span: OtelSpanLike) => unknown>(name: string, options: {
+        kind?: number;
+        attributes?: OtelAttributes;
+    }, fn: F): ReturnType<F>;
+};
+export type OtelMiddlewareOptions = {
+    /** Default: `client.endpoint`, or the endpoint key when the client has no `name`. */
+    spanName?: (context: ApiMiddlewareContext) => string;
+    /** Extra attributes set when the span starts. */
+    attributes?: (context: ApiMiddlewareContext) => OtelAttributes;
+    /**
+     * `url.full` keeps the query string with sensitive values redacted
+     * (default). Set `false` to drop the query string entirely.
+     */
+    includeQuery?: boolean;
+    /**
+     * Adds trace-context headers to the outgoing request, e.g.
+     * `(headers) => propagation.inject(context.active(), headers)`. Runs inside
+     * the active span. Not needed when fetch is already auto-instrumented.
+     */
+    inject?: (headers: Record<string, string>) => void;
+};
+/**
+ * One CLIENT span per logical request (all retries, validation and
+ * `checkResponse`), with OpenTelemetry HTTP semantic-convention attributes.
+ * It's the active span, so auto-instrumented fetch attempts become children.
+ *
+ * @example
+ * import { trace } from '@opentelemetry/api'
+ * createApiClient({ ...config, use: [otelMiddleware(trace.getTracer('app'))] })
+ */
+export declare function otelMiddleware(tracer: OtelTracerLike, options?: OtelMiddlewareOptions): ApiMiddleware;

package/dist/api-wrapper/paginate.d.ts

@@ -0,0 +1,12 @@
+export type PaginateOptions = {
+    /** Stop after this many pages (default: no limit). */
+    maxPages?: number;
+    /** Checked before each page fetch; throws `signal.reason` when aborted. */
+    signal?: AbortSignal;
+};
+/**
+ * Yields pages until `getNext` returns `null`/`undefined`. The first call to
+ * `fetchPage` gets `undefined` as cursor. Pages are fetched lazily, so
+ * breaking out of `for await` stops further requests.
+ */
+export declare function paginate<TPage, TCursor>(fetchPage: (cursor: TCursor | undefined) => Promise<TPage>, getNext: (page: TPage) => TCursor | null | undefined, options?: PaginateOptions): AsyncGenerator<TPage, void, undefined>;

package/dist/api-wrapper/redaction.d.ts

@@ -1,2 +1,4 @@
 import type { ApiErrorContext } from './shared';
+/** Replaces values of sensitive query parameters (`?api_key=…`) in a URL. */
+export declare function redactUrl(url: string): string;
 export declare function defaultRedactContext(ctx: ApiErrorContext): ApiErrorContext;

package/dist/api-wrapper/shared.d.ts

@@ -1,8 +1,22 @@
+import type { UrlQueryParams } from '../url';
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
 export type RequestBodyFormat = 'json' | 'form-data';
 export type BaseApiUrl = string | (() => string);
 export type PathParams = Record<string, string | number>;
-export type QueryParams = Record<string, string | number | boolean | undefined>;
+/** Array values repeat the key (`a=1&a=2`); `null`/`undefined` are skipped. */
+export type QueryParams = UrlQueryParams;
+/**
+ * Augment to type `meta` on requests, actions, hooks, middleware and errors:
+ *
+ * @example
+ * declare module 'hanzio/api-wrapper' {
+ *   interface ApiRequestMeta { traceId: string; tenantId?: string }
+ * }
+ */
+export interface ApiRequestMeta {
+}
+/** `ApiRequestMeta` once augmented, otherwise any record. */
+export type RequestMeta = keyof ApiRequestMeta extends never ? Record<string, unknown> : ApiRequestMeta;
 export type ApiErrorContext = {
     endpoint: string;
     method: HttpMethod;
@@ -12,5 +26,5 @@ export type ApiErrorContext = {
     elapsedMs: number;
     requestHeaders?: Record<string, string>;
     requestBody?: unknown;
-    meta?: Record<string, unknown>;
+    meta?: RequestMeta;
 };

package/dist/api-wrapper/testing.d.ts

@@ -0,0 +1,23 @@
+import type { FetchLike } from './types';
+export type MockFetch = FetchLike & {
+    /** Every request received, in order. Bodies are still readable. */
+    readonly calls: Request[];
+};
+/**
+ * A fetch stand-in for tests: pass it as the client's `fetch` option instead
+ * of replacing `globalThis.fetch`. Test-runner agnostic.
+ *
+ * @example
+ * const fetch = createMockFetch((request) =>
+ *   request.url.endsWith('/users/1')
+ *     ? jsonResponse({ id: 1 })
+ *     : jsonResponse({ error: 'not found' }, { status: 404 })
+ * )
+ * const api = createApiClient({ ...config, fetch })
+ */
+export declare function createMockFetch(handler: (request: Request, callIndex: number) => Response | Promise<Response>): MockFetch;
+/** A JSON `Response` with `content-type: application/json`. */
+export declare function jsonResponse(body: unknown, init?: {
+    status?: number;
+    headers?: Record<string, string>;
+}): Response;

package/dist/api-wrapper/transport.d.ts

@@ -1,18 +1,17 @@
 import { type z } from 'zod';
-import type { ApiEndpoint, OnResponseContext, OnRetryContext, RetryContext } from './types';
-import type { ApiErrorContext, HttpMethod } from './shared';
+import type { ApiEndpoint, FetchLike, OnResponseContext, OnRetryContext, RetryContext } from './types';
+import type { ApiErrorContext, HttpMethod, RequestMeta } from './shared';
 export type RequestConfig = {
     method: HttpMethod;
     fullUrl: string;
     body: unknown;
     headers: Record<string, string>;
     timeoutMs?: number;
-    fetchFn: typeof fetch;
+    fetchFn: FetchLike;
     userSignal?: AbortSignal;
 };
 export declare function validateResponse<T extends z.ZodType>(schema: T, data: unknown, ctx: (over?: Partial<ApiErrorContext>) => ApiErrorContext): Promise<z.infer<T>>;
 export declare function httpRequest(config: RequestConfig, ctx: (over?: Partial<ApiErrorContext>) => ApiErrorContext): Promise<Response>;
-export declare function mergeSignals(a: AbortSignal, b: AbortSignal | undefined): AbortSignal;
 export declare function readErrorResponse(response: Response): Promise<{
     body: string;
     headers: Record<string, string>;
@@ -38,7 +37,7 @@ type MakeRequestArgs<TValidated> = {
     endpointName: string;
     method: HttpMethod;
     fullUrl: string;
-    meta?: Record<string, unknown>;
+    meta?: RequestMeta;
     onResponse?: (context: OnResponseContext) => void | Promise<void>;
     onRetry?: (context: OnRetryContext) => void | Promise<void>;
 };

package/dist/api-wrapper/types.d.ts

@@ -1,6 +1,7 @@
 import type { z } from 'zod';
+import type { Result } from '../promise';
 import type { ApiError } from './errors';
-import type { ApiErrorContext, BaseApiUrl, HttpMethod, PathParams, QueryParams, RequestBodyFormat } from './shared';
+import type { ApiErrorContext, BaseApiUrl, HttpMethod, PathParams, QueryParams, RequestBodyFormat, RequestMeta } from './shared';
 export interface ApiEndpoint<TReqBody extends z.ZodType | undefined = z.ZodType | undefined, TReqParams extends z.ZodType | undefined = z.ZodType | undefined, TReqQuery extends z.ZodType | undefined = z.ZodType | undefined, TReqHeaders extends z.ZodType | undefined = z.ZodType | undefined, TResponse extends z.ZodType = z.ZodType> {
     method: HttpMethod;
     path: string | ((baseUrl: string) => string);
@@ -12,7 +13,8 @@ export interface ApiEndpoint<TReqBody extends z.ZodType | undefined = z.ZodType
     baseApiUrl?: string;
     reqBodyFormat?: RequestBodyFormat;
     defaultHeaders?: Record<string, string>;
-    resFormatter?: (data: unknown, headers: Record<string, string>) => z.infer<TResponse>;
+    /** Reshapes the raw body before `resSchema` parses it, so it returns the schema's input type. */
+    resFormatter?: (data: unknown, headers: Record<string, string>) => z.input<TResponse>;
     reqDefaultQueryParams?: QueryParams;
     doNotEncodeQueryParams?: boolean;
 }
@@ -47,7 +49,7 @@ export type OnRequestContext = {
     url: string;
     headers: Record<string, string>;
     body: unknown;
-    meta?: Record<string, unknown>;
+    meta?: RequestMeta;
 };
 export type OnResponseContext = {
     endpoint: string;
@@ -55,7 +57,7 @@ export type OnResponseContext = {
     url: string;
     response: Response;
     attempt: number;
-    meta?: Record<string, unknown>;
+    meta?: RequestMeta;
 };
 export type ActionCache = {
     <T>(key: string, fn: () => Promise<T> | T, options?: {
@@ -70,76 +72,159 @@ export type ActionCache = {
 };
 export type ActionInvokeOptions = {
     signal?: AbortSignal;
-    meta?: Record<string, unknown>;
+    meta?: RequestMeta;
 };
 export type ActionContext<TInput, TApi = any> = {
     input: TInput;
     api: TApi;
     signal?: AbortSignal;
-    meta?: Record<string, unknown>;
+    meta?: RequestMeta;
     logger?: Pick<Console, 'debug' | 'error'>;
     cache: ActionCache;
 };
 export interface ApiAction<TInput = any, TOutput = any> {
     handler: (ctx: ActionContext<TInput>) => Promise<TOutput> | TOutput;
+    /** Validates the caller's input at runtime; `handler` receives the parsed output. */
+    readonly input?: z.ZodType;
     /** When true, the action accepts only optional `{ signal, meta }`; input is always `undefined`. */
     readonly noRuntimeInput?: boolean;
 }
 type ActionDefinition<TInput, TOutput, TApi> = {
     handler: (ctx: ActionContext<TInput, TApi>) => Promise<TOutput> | TOutput;
 };
+type SchemaActionDefinition<TSchema extends z.ZodType, TOutput, TApi> = {
+    input: TSchema;
+    handler: (ctx: ActionContext<z.output<TSchema>, TApi>) => Promise<TOutput> | TOutput;
+};
 export type DefineAction<TApi> = {
+    /** Input validated by a Zod schema: callers pass `z.input`, the handler gets `z.output`. */
+    <TSchema extends z.ZodType, TOutput>(def: SchemaActionDefinition<TSchema, TOutput, TApi>): ApiAction<z.input<TSchema>, TOutput>;
     <TOutput>(def: ActionDefinition<undefined, TOutput, TApi>): ApiAction<undefined, TOutput>;
     <TInput>(): <TOutput>(def: ActionDefinition<TInput, TOutput, TApi>) => ApiAction<TInput, TOutput>;
 };
 type ActionInput<A> = A extends ApiAction<infer I, any> ? I : never;
 export type ActionOutput<A> = A extends ApiAction<any, infer O> ? O : never;
 export type ActionArgs<A> = [ActionInput<A>] extends [undefined] ? [options?: ActionInvokeOptions] : [input: ActionInput<A>, options?: ActionInvokeOptions];
-type SchemaInputKeys<TEndpoint extends ApiEndpoint> = (TEndpoint['reqBodySchema'] extends z.ZodType ? 'reqBody' : never) | (TEndpoint['reqParamsSchema'] extends z.ZodType ? 'reqParams' : never) | (TEndpoint['reqQuerySchema'] extends z.ZodType ? 'reqQuery' : never) | (TEndpoint['reqHeadersSchema'] extends z.ZodType ? 'reqHeaders' : never);
+type CharsOf<S extends string, Acc extends string = never> = S extends `${infer C}${infer Rest}` ? CharsOf<Rest, Acc | C> : Acc;
+type IdentStart = CharsOf<'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_'>;
+type WordChar = IdentStart | CharsOf<'0123456789'>;
+type TakeWord<S extends string, Acc extends string = ''> = S extends `${infer C}${infer Rest}` ? C extends WordChar ? TakeWord<Rest, `${Acc}${C}`> : Acc : Acc;
+/**
+ * `:name` placeholders in a literal path, matching the runtime rule (a letter
+ * or `_`, then word characters, so ports like `:8080` don't count).
+ * `never` for non-literal paths.
+ */
+export type PathParamNames<TPath> = TPath extends string ? string extends TPath ? never : TPath extends `${string}:${infer Rest}` ? (Rest extends `${IdentStart}${string}` ? TakeWord<Rest> : never) | PathParamNames<Rest> : never : never;
+type EndpointPathParamNames<TEndpoint extends ApiEndpoint> = PathParamNames<TEndpoint['path']>;
+type SchemaInputKeys<TEndpoint extends ApiEndpoint> = (TEndpoint['reqBodySchema'] extends z.ZodType ? 'reqBody' : never) | (TEndpoint['reqQuerySchema'] extends z.ZodType ? 'reqQuery' : never) | (TEndpoint['reqHeadersSchema'] extends z.ZodType ? 'reqHeaders' : never) | (TEndpoint['reqParamsSchema'] extends z.ZodType ? 'reqParams' : [EndpointPathParamNames<TEndpoint>] extends [never] ? never : 'reqParams');
 type SchemaInputs<TEndpoint extends ApiEndpoint> = {
-    reqBody: TEndpoint['reqBodySchema'] extends z.ZodType ? z.infer<TEndpoint['reqBodySchema']> : unknown;
-    reqParams: TEndpoint['reqParamsSchema'] extends z.ZodType ? z.infer<TEndpoint['reqParamsSchema']> : PathParams;
-    reqQuery: TEndpoint['reqQuerySchema'] extends z.ZodType ? z.infer<TEndpoint['reqQuerySchema']> : QueryParams;
-    reqHeaders: TEndpoint['reqHeadersSchema'] extends z.ZodType ? z.infer<TEndpoint['reqHeadersSchema']> : Record<string, string>;
+    reqBody: TEndpoint['reqBodySchema'] extends z.ZodType ? z.input<TEndpoint['reqBodySchema']> : unknown;
+    reqParams: TEndpoint['reqParamsSchema'] extends z.ZodType ? z.input<TEndpoint['reqParamsSchema']> : [EndpointPathParamNames<TEndpoint>] extends [never] ? PathParams : Record<EndpointPathParamNames<TEndpoint>, string | number>;
+    reqQuery: TEndpoint['reqQuerySchema'] extends z.ZodType ? z.input<TEndpoint['reqQuerySchema']> : QueryParams;
+    reqHeaders: TEndpoint['reqHeadersSchema'] extends z.ZodType ? z.input<TEndpoint['reqHeadersSchema']> : Record<string, string>;
 };
 type CommonRequestOptions = {
     url?: string;
     signal?: AbortSignal;
     timeoutMs?: number;
     retries?: number;
-    fetch?: typeof fetch;
-    meta?: Record<string, unknown>;
+    fetch?: FetchLike;
+    meta?: RequestMeta;
 };
 export type RequestInput<TEndpoint extends ApiEndpoint> = Pick<SchemaInputs<TEndpoint>, SchemaInputKeys<TEndpoint>> & Partial<Omit<SchemaInputs<TEndpoint>, SchemaInputKeys<TEndpoint>>> & CommonRequestOptions;
 type RequestArgs<TEndpoint extends ApiEndpoint> = SchemaInputKeys<TEndpoint> extends never ? [input?: RequestInput<TEndpoint>] : [input: RequestInput<TEndpoint>];
 export type ApiClient<T extends Record<string, ApiEndpoint>, A extends Record<string, ApiAction> = Record<string, never>> = {
     request: {
-        <K extends keyof T>(endpointKey: K, ...args: RequestArgs<T[K]>): Promise<ApiWrapperResponse<z.infer<T[K]['resSchema']>>>;
+        <K extends keyof T>(endpointKey: K, ...args: RequestArgs<T[K]>): Promise<ApiWrapperResponse<EndpointResponse<T[K]>>>;
         <K extends keyof A>(actionKey: K, ...args: ActionArgs<A[K]>): Promise<ActionOutput<A[K]>>;
     };
     cache: ActionCache;
+    /**
+     * The same endpoints and actions, resolving to `Result` instead of throwing
+     * `ApiError`s. Other errors (bugs in hooks or middleware) still throw.
+     */
+    safe: {
+        [K in keyof T]: (...args: RequestArgs<T[K]>) => Promise<Result<ApiWrapperResponse<EndpointResponse<T[K]>>, ApiError>>;
+    } & {
+        [K in keyof A]: (...args: ActionArgs<A[K]>) => Promise<Result<ActionOutput<A[K]>, ApiError>>;
+    };
 } & {
-    [K in keyof T]: (...args: RequestArgs<T[K]>) => Promise<ApiWrapperResponse<z.infer<T[K]['resSchema']>>>;
+    [K in keyof T]: (...args: RequestArgs<T[K]>) => Promise<ApiWrapperResponse<EndpointResponse<T[K]>>>;
 } & {
     [K in keyof A]: (...args: ActionArgs<A[K]>) => Promise<ActionOutput<A[K]>>;
 };
+/**
+ * Any client, for helpers that accept whichever client they're given. Call
+ * endpoints through `request` or `safe`; results are `unknown`.
+ */
+export type AnyApiClient = {
+    request(key: string, ...args: any[]): Promise<unknown>;
+    cache: ActionCache;
+    safe: Record<string, (...args: any[]) => Promise<Result<unknown, ApiError>>>;
+};
+/** Parsed response data of an endpoint definition (`z.output` of `resSchema`). */
+export type EndpointResponse<TEndpoint extends ApiEndpoint> = z.output<TEndpoint['resSchema']>;
+/** Request input for an endpoint definition (`reqBody`, `reqParams`, …). */
+export type EndpointRequest<TEndpoint extends ApiEndpoint> = RequestInput<TEndpoint>;
+/** Response data of a client method: `InferResponse<typeof api, 'usersGet'>`. */
+export type InferResponse<TClient, K extends keyof TClient> = TClient[K] extends (...args: never[]) => Promise<infer R> ? R extends ApiWrapperResponse<infer D> ? D : R : never;
+/** First argument of a client method: `InferRequest<typeof api, 'usersGet'>`. */
+export type InferRequest<TClient, K extends keyof TClient> = TClient[K] extends (...args: infer P) => unknown ? NonNullable<P[0]> : never;
 export type ActionsFactoryHelpers<T extends Record<string, ApiEndpoint>, A extends Record<string, ApiAction> = Record<string, never>> = {
     api: ApiClient<T, A>;
     defineAction: DefineAction<ApiClient<T, A>>;
 };
+/** Any fetch-compatible function; avoids Bun's `typeof fetch` extras like `preconnect`. */
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export type ApiMiddlewareContext = {
+    /** The client's `name`, when set. */
+    client?: string;
+    /** The endpoint key, e.g. `usersGet`. */
+    endpoint: string;
+    method: HttpMethod;
+    /** Full URL including the query string. */
+    url: string;
+    /** Outgoing headers. Mutate before `next()` to add headers (e.g. `traceparent`). */
+    headers: Record<string, string>;
+    meta?: RequestMeta;
+};
+/**
+ * Wraps one logical request: `onRequest`, every retry attempt, validation and
+ * `checkResponse`. Call `next()` to continue; errors it throws are `ApiError`s
+ * that were already redacted and passed to `onError`.
+ */
+export type ApiMiddleware = (context: ApiMiddlewareContext, next: () => Promise<ApiWrapperResponse<unknown>>) => Promise<ApiWrapperResponse<unknown>>;
+export type CheckResponseContext = {
+    endpoint: string;
+    method: HttpMethod;
+    url: string;
+    httpStatus: number;
+    attempt: number;
+    meta?: RequestMeta;
+};
+export type DefaultHeaders = Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
 export interface ApiClientConfig<T extends Record<string, ApiEndpoint>, A extends Record<string, ApiAction> = Record<string, never>> {
     name?: string;
     baseApiUrls: Record<string, BaseApiUrl>;
     defaultBaseApiUrl?: string;
     endpoints: T;
-    defaultHeaders?: Record<string, string>;
+    /** Static headers, or a function resolved on every request (e.g. auth from a secret store). */
+    defaultHeaders?: DefaultHeaders;
     timeoutMs?: number;
     retries?: number;
     retryDelayMs?: number | ((attempt: number) => number);
     maxRetryDelayMs?: number;
     shouldRetry?: (context: RetryContext) => boolean;
     logger?: Pick<Console, 'debug' | 'error'>;
-    fetch?: typeof fetch;
+    fetch?: FetchLike;
+    /** Middleware around each whole request, in array order (first is outermost). */
+    use?: ApiMiddleware[];
+    /**
+     * Runs after `resSchema` validation on every attempt. Throw to reject the
+     * response; non-`ApiError` throws become `ApiResponseError`, which the
+     * default retry policy does not retry.
+     */
+    checkResponse?: (data: unknown, context: CheckResponseContext) => void | Promise<void>;
     onRequest?: (context: OnRequestContext) => RequestInterceptorResult | Promise<RequestInterceptorResult>;
     onResponse?: (context: OnResponseContext) => void | Promise<void>;
     onError?: (error: ApiError) => void | Promise<void>;
@@ -151,4 +236,4 @@ export type ApiClientConfigNoActions<T extends Record<string, ApiEndpoint>> = Om
 export type ApiClientConfigWithActions<T extends Record<string, ApiEndpoint>, A extends Record<string, ApiAction>> = Omit<ApiClientConfig<T, Record<string, never>>, 'actions'> & {
     actions: A | ((helpers: ActionsFactoryHelpers<T, A>) => A);
 };
-export type { BaseApiUrl, HttpMethod, PathParams, QueryParams, RequestBodyFormat, ApiErrorContext } from './shared';
+export type { ApiRequestMeta, RequestMeta, BaseApiUrl, HttpMethod, PathParams, QueryParams, RequestBodyFormat, ApiErrorContext } from './shared';

package/dist/array/index.d.ts

@@ -1,22 +1,68 @@
 export interface ArrayDifference<TCurrent, TNext> {
     new: TNext[];
+    /** Items present in both arrays (`update` + `unchanged`). */
     upsert: TNext[];
     delete: TCurrent[];
 }
+export interface ArrayDifferenceWithChanges<TCurrent, TNext> extends ArrayDifference<TCurrent, TNext> {
+    /** Matched items where `isEqual` returned false. */
+    update: TNext[];
+    /** Matched items where `isEqual` returned true. */
+    unchanged: TNext[];
+}
 type PropertyKeyValue = string | number | symbol;
 type NonNullableValue<T> = T extends null | undefined ? never : T;
 type ItemsMatchingKeyValue<T, TKey extends keyof T, TValue> = [
     Extract<T, Record<TKey, TValue>>
 ] extends [never] ? T : Extract<T, Record<TKey, TValue>>;
 export declare function chunkArray<T>(array: readonly T[], chunkSize: number): T[][];
-export declare function findArrayDifferenceByKey<TCurrent, TNext, TKey extends keyof TCurrent & keyof TNext>(current: readonly TCurrent[], next: readonly TNext[], key: TKey): ArrayDifference<TCurrent, TNext>;
+type DifferenceKey<TCurrent, TNext> = (keyof TCurrent & keyof TNext) | ((item: TCurrent | TNext) => unknown);
+/**
+ * Splits `next` into items that are new or also in `current` (`upsert`), and
+ * lists the `current` items missing from `next` (`delete`). Items match by a
+ * shared key name or a key function; key values are compared as strings.
+ * Pass `isEqual` to also split `upsert` into `update` and `unchanged`.
+ */
+export declare function findArrayDifferenceByKey<TCurrent, TNext>(current: readonly TCurrent[], next: readonly TNext[], key: DifferenceKey<TCurrent, TNext>, options: {
+    isEqual: (current: TCurrent, next: TNext) => boolean;
+}): ArrayDifferenceWithChanges<TCurrent, TNext>;
+export declare function findArrayDifferenceByKey<TCurrent, TNext>(current: readonly TCurrent[], next: readonly TNext[], key: DifferenceKey<TCurrent, TNext>, options?: {
+    isEqual?: (current: TCurrent, next: TNext) => boolean;
+}): ArrayDifference<TCurrent, TNext>;
 export declare function getUniqueValues<T>(array: readonly T[]): T[];
 export declare function compact<T>(array: readonly T[]): NonNullableValue<T>[];
-export declare function getUniqueValuesByKey<T, TKey extends keyof T>(array: readonly T[], key: TKey): T[];
-export declare function groupBy<T, TKey extends keyof T, TGroupKey extends Extract<T[TKey], PropertyKeyValue>>(array: readonly T[], key: TKey): Record<TGroupKey, T[]>;
-export declare function groupBy<T, TGroupKey extends PropertyKeyValue>(array: readonly T[], keyFn: (item: T) => TGroupKey): Record<TGroupKey, T[]>;
+export declare function getUniqueValuesByKey<T>(array: readonly T[], keyOrFn: keyof T | ((item: T) => unknown)): T[];
+export declare function groupBy<T, TKey extends keyof T, TGroupKey extends Extract<T[TKey], PropertyKeyValue>>(array: readonly T[], key: TKey): Partial<Record<TGroupKey, T[]>>;
+export declare function groupBy<T, TGroupKey extends PropertyKeyValue>(array: readonly T[], keyFn: (item: T) => TGroupKey): Partial<Record<TGroupKey, T[]>>;
+export declare function countBy<T, TKey extends keyof T, TGroupKey extends Extract<T[TKey], PropertyKeyValue>>(array: readonly T[], key: TKey): Partial<Record<TGroupKey, number>>;
+export declare function countBy<T, TGroupKey extends PropertyKeyValue>(array: readonly T[], keyFn: (item: T) => TGroupKey): Partial<Record<TGroupKey, number>>;
 export declare function keyBy<T, TKey extends keyof T, TRecordKey extends Extract<T[TKey], PropertyKeyValue>>(array: readonly T[], key: TKey): Record<TRecordKey, T>;
 export declare function keyBy<T, TRecordKey extends PropertyKeyValue>(array: readonly T[], keyFn: (item: T) => TRecordKey): Record<TRecordKey, T>;
 export declare function partition<T>(array: readonly T[], predicate: (item: T, index: number) => boolean): [matched: T[], unmatched: T[]];
 export declare function pickItemsInArray<T, TKey extends keyof T, const TValue extends readonly T[TKey][]>(array: readonly T[], key: TKey, values: TValue): ItemsMatchingKeyValue<T, TKey, TValue[number]>[];
+/** Wraps a single value in an array; `null`/`undefined` become `[]`. Arrays are copied. */
+export declare function toArray<T>(value: T | readonly T[] | null | undefined): T[];
+type NumericKey<T> = {
+    [K in keyof T]: T[K] extends number | null | undefined ? K : never;
+}[keyof T];
+/** Sums a numeric property or callback result; nullish values count as 0. */
+export declare function sumBy<T>(array: readonly T[], fn: (item: T) => number | null | undefined): number;
+export declare function sumBy<T>(array: readonly T[], key: NumericKey<T>): number;
+type SortSelector<T> = keyof T | ((item: T) => unknown);
+export type SortCriterion<T> = SortSelector<T> | {
+    by: SortSelector<T>;
+    order: 'asc' | 'desc';
+};
+/**
+ * Returns a sorted copy. Each criterion is a key, a callback, or
+ * `{ by, order }`; later criteria break ties. The sort is stable, and
+ * `null`/`undefined` values always go last. Without criteria the items
+ * themselves are compared.
+ */
+export declare function sortBy<T>(array: readonly T[], ...criteria: SortCriterion<T>[]): T[];
+/**
+ * Numbers from `start` up to (not including) `end`. With one argument it
+ * counts from 0. `step` defaults to 1, or -1 when `end < start`.
+ */
+export declare function range(start: number, end?: number, step?: number): number[];
 export {};