hanzio 1.0.10 → 1.2.0

package/README.md

@@ -218,26 +218,51 @@ await promiseTimeout(250)
 `defineSecretSet` loads a typed set of required secrets from `process.env` or
 Infisical before the rest of the program starts.
 
+When both `INFISICAL_CLIENT_ID` and `INFISICAL_CLIENT_SECRET` are set, it uses
+Infisical's HTTP API. If either is missing, it uses your signed-in Infisical CLI
+session. For local development, install the CLI and run
+`infisical login --domain=https://eu.infisical.com` (or your configured
+`siteUrl`). See the [secrets documentation](src/secrets/README.md) for details.
+
 ```ts
 import { defineSecretSet } from 'hanzio/secrets'
 
 export const backendSecrets = await defineSecretSet(
 	['DATABASE_URL', 'APP_SECRET'] as const,
-	{ projectId: 'infisical-project-id' }
+	{
+		organizationId: 'infisical-organization-id',
+		projectId: 'infisical-project-id'
+	}
 )
 
 const databaseUrl = backendSecrets.secret('DATABASE_URL')
 ```
 
+The required `organizationId` scopes the CLI session per secret set, allowing projects
+in different organizations to run together without switching the active CLI
+organization. This flow reads the CLI user token and fetches secrets over HTTP;
+tokens remain in memory. Use `writeToProcessEnv: false` for multiple sets in one
+process. Both `organizationId` and `projectId` are required for Infisical loading.
+
 For Vite config, `viteSecretSetPlugin(secretSet)` exposes the loaded values as
 `import.meta.env.*` replacements. Use `getViteDefine(secretSet)` if you need the
-raw `define` object. Import Vite helpers from `hanzio/secrets/vite` so browser
-bundles do not pull in the Infisical SDK.
+raw `define` object. Vite helpers accept only `VITE_` keys by default; use an
+explicit `publicKeys` list to select public values from a mixed set. Import
+these helpers from `hanzio/secrets/vite`.
+
+The helper supports `auth: 'auto' | 'http' | 'cli'`, `secretPath`, deadlines,
+cancellation, optional schema validation, per-key source metadata, and
+`writeToProcessEnv: false` for isolated sets. Use `hanzio/secrets/worker` for
+Cloudflare bindings without Node compatibility. See the
+[migration notes](src/secrets/README.md#migration-notes) for stricter environment
+validation and browser exposure rules.
 
 ### Cache
 
 `cacheFunction` wraps sync or async functions with TTL caching and request
-deduplication.
+deduplication. With `refreshInBackground: true`, stale entries are served
+immediately while a background refresh updates the cache
+(stale-while-revalidate).
 
 ```ts
 import { cacheFunction } from 'hanzio'
@@ -252,6 +277,47 @@ const user = await getUser('user_1')
 getUser.clearCache()
 ```
 
+#### External stores (e.g. Redis)
+
+By default entries live in an in-memory `Map`. Pass a `store` to keep entries
+in an external cache instead. A store implements `get`, `set`, and `delete`
+(plus an optional `clear`, used by `clearCache`); hanzio never imports the
+underlying client, so any backend works. Serialization is the adapter's
+responsibility, and the `ttlMs` passed to `set` maps to the store's native
+expiry. External stores are only supported for async functions.
+
+```ts
+import { cacheFunction, type CacheStore, type CacheStoreEntry } from 'hanzio'
+import Redis from 'ioredis'
+
+const redis = new Redis()
+
+const redisStore: CacheStore = {
+	get: async (key) => {
+		const raw = await redis.get(key)
+		return raw ? (JSON.parse(raw) as CacheStoreEntry) : undefined
+	},
+	set: async (key, entry, ttlMs) => {
+		await redis.set(key, JSON.stringify(entry), 'PX', ttlMs)
+	},
+	delete: async (key) => {
+		await redis.del(key)
+	}
+}
+
+const getUser = cacheFunction({
+	name: 'getUser',
+	fn: async (id: string) => ({ id, name: 'Ada' }),
+	cacheTimeMs: 60_000,
+	store: redisStore,
+	onStoreError: (error) => console.error('cache store failed', error)
+})
+```
+
+Store failures never break the cached function: on a failed `get` or `set`
+the wrapped function falls back to calling `fn` directly, and the optional
+`onStoreError` callback is invoked.
+
 ### State Machine
 
 `SimpleStateMachine` models typed states, actions, validation, and action

package/dist/api-wrapper/actions-impl.d.ts

@@ -0,0 +1,4 @@
+import type { ActionCache, DefineAction } from './types';
+export declare function createActionCache(): ActionCache;
+export declare function makeDefineAction<TApi>(): DefineAction<TApi>;
+export declare const defineAction: DefineAction<any>;

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

@@ -0,0 +1,23 @@
+import { type ConfigError } from './errors';
+import type { ApiErrorContext, BaseApiUrl, PathParams, QueryParams } from './shared';
+import type { ApiEndpoint } from './types';
+export type BuildUrlOptions = {
+    endpoint: ApiEndpoint;
+    params: PathParams | undefined;
+    queryParams: Record<string, string>;
+    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 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>;
+export declare function replacePathParams(path: string, params: PathParams | undefined, configError: (msg: string) => ConfigError): string;

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

@@ -0,0 +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>;
+}
+export declare const createApiClient: CreateApiClientFn;

package/dist/api-wrapper/error-reporting.d.ts

@@ -0,0 +1,7 @@
+import type { ApiError } from './errors';
+import type { ApiClientConfig } from './types';
+import type { ApiErrorContext } from './shared';
+type ErrorHookConfig = Pick<ApiClientConfig<never, never>, 'logger' | 'onError' | 'redact'>;
+export declare function applyErrorContextRedaction(ctx: ApiErrorContext, config: Pick<ApiClientConfig<never, never>, 'redact'>): ApiErrorContext;
+export declare function reportApiError(err: ApiError, config: ErrorHookConfig): Promise<ApiError>;
+export {};

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

@@ -0,0 +1,64 @@
+import type { ZodError } from 'zod';
+import type { ApiErrorContext } from './shared';
+import { type FormattedZodIssue } from './zod-issues';
+export declare class ApiError extends Error {
+    context: ApiErrorContext;
+    cause?: unknown;
+    constructor(message: string, context: ApiErrorContext, options?: {
+        cause?: unknown;
+    });
+    toJSON(): Record<string, unknown>;
+}
+export declare class HttpResponseError extends ApiError {
+    readonly status: number;
+    readonly body: string;
+    readonly bodyJson?: unknown;
+    readonly responseHeaders: Record<string, string>;
+    readonly requestId?: string;
+    constructor(status: number, body: string, responseHeaders: Record<string, string>, context: ApiErrorContext);
+    toJSON(): Record<string, unknown>;
+}
+export declare class ResponseValidationError extends ApiError {
+    readonly zodError: ZodError;
+    readonly rawResponse: unknown;
+    readonly issues: FormattedZodIssue[];
+    readonly validationIssues: string;
+    constructor(zodError: ZodError, rawResponse: unknown, context: ApiErrorContext);
+    toJSON(): Record<string, unknown>;
+}
+export type RequestValidationTarget = 'body' | 'query' | 'params' | 'headers';
+export declare class RequestValidationError extends ApiError {
+    readonly zodError: ZodError;
+    readonly target: RequestValidationTarget;
+    readonly rawInput: unknown;
+    readonly issues: FormattedZodIssue[];
+    readonly validationIssues: string;
+    constructor(zodError: ZodError, target: RequestValidationTarget, rawInput: unknown, context: ApiErrorContext);
+    toJSON(): Record<string, unknown>;
+}
+export declare class RequestTimeoutError extends ApiError {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number, context: ApiErrorContext);
+}
+export declare class NetworkError extends ApiError {
+    constructor(message: string, context: ApiErrorContext, cause?: unknown);
+}
+export declare class RequestAbortedError extends ApiError {
+    constructor(context: ApiErrorContext, cause?: unknown);
+}
+export declare class ConfigError extends ApiError {
+    constructor(message: string, context: ApiErrorContext);
+}
+export declare class ActionError extends ApiError {
+    constructor(message: string, context: ApiErrorContext, cause?: unknown);
+}
+export declare const isApiError: (e: unknown) => e is ApiError;
+export declare const isHttpResponseError: (e: unknown) => e is HttpResponseError;
+export declare const isResponseValidationError: (e: unknown) => e is ResponseValidationError;
+export declare const isRequestValidationError: (e: unknown) => e is RequestValidationError;
+export declare const isRequestTimeoutError: (e: unknown) => e is RequestTimeoutError;
+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 function isNonRetryableApiError(error: unknown): boolean;

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

@@ -0,0 +1,10 @@
+import type { ConfigError } from './errors';
+/**
+ * Normalize headers to canonical case so lookups are deterministic. Later
+ * occurrences of the same header (case-insensitive) win.
+ */
+export declare function normalizeHeaders(headers: Record<string, string>): Record<string, string>;
+export declare function getHeader(headers: Record<string, string>, name: string): string | undefined;
+export declare function hasJsonContentType(headers: Record<string, string>): boolean;
+export declare function buildFetchBody(body: unknown, headers: Record<string, string>, configError?: (msg: string) => ConfigError): RequestInit['body'];
+export declare function getHeadersAsObject(headers: Headers): Record<string, string>;

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

@@ -1,84 +1,5 @@
-import { type z, ZodError } from 'zod';
-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>;
-export declare class ResponseValidationError extends Error {
-    readonly zodError: ZodError;
-    readonly rawResponse: unknown;
-    readonly validationIssues: string;
-    constructor(zodError: ZodError, rawResponse: unknown);
-}
-export declare class HttpResponseError extends Error {
-    readonly status: number;
-    readonly body: string;
-    constructor(status: number, body: string);
-}
-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);
-    reqBodySchema?: TReqBody;
-    reqParamsSchema?: TReqParams;
-    reqQuerySchema?: TReqQuery;
-    reqHeadersSchema?: TReqHeaders;
-    resSchema: TResponse;
-    baseApiUrl?: string;
-    reqBodyFormat?: RequestBodyFormat;
-    defaultHeaders?: Record<string, string>;
-    resFormatter?: (data: unknown, headers: Record<string, string>) => z.infer<TResponse>;
-    reqDefaultQueryParams?: QueryParams;
-    doNotEncodeQueryParams?: boolean;
-}
-export interface ApiWrapperResponse<T> {
-    data: T;
-    requestSizeMb: number;
-    responseSizeMb: number;
-    requestSizeTotalMb: number;
-    responseTimeMs: number;
-    httpStatus: number;
-    retryCount: number;
-}
-export type RetryContext = {
-    error?: unknown;
-    response?: Response;
-    retryCount: number;
-    maxRetries: number;
-};
-export interface ApiClientConfig<T extends Record<string, ApiEndpoint>> {
-    name?: string;
-    baseApiUrls: Record<string, BaseApiUrl>;
-    defaultBaseApiUrl?: string;
-    endpoints: T;
-    defaultHeaders?: Record<string, string>;
-    timeoutMs?: number;
-    retries?: number;
-    retryDelayMs?: number;
-    shouldRetry?: (context: RetryContext) => boolean;
-    logger?: Pick<Console, 'debug' | 'error'>;
-    fetch?: typeof fetch;
-    onRequestStart?: (context: {
-        endpoint: string;
-        url: string;
-    }) => void;
-    onRequestEnd?: (context: {
-        endpoint: string;
-        url: string;
-        status: number;
-        retryCount: number;
-        responseTimeMs: number;
-    }) => void;
-}
-type RequestInput<TEndpoint extends ApiEndpoint> = {
-    reqBody?: InferOptionalSchema<TEndpoint['reqBodySchema']>;
-    reqParams?: InferOptionalSchema<TEndpoint['reqParamsSchema']>;
-    reqQuery?: InferOptionalSchema<TEndpoint['reqQuerySchema']>;
-    reqHeaders?: InferOptionalSchema<TEndpoint['reqHeadersSchema']>;
-    url?: string;
-};
-type InferOptionalSchema<TSchema> = TSchema extends z.ZodType ? z.infer<TSchema> : undefined;
-export declare function createApiClient<T extends Record<string, ApiEndpoint>>(apiConfig: ApiClientConfig<T>): {
-    request: <K extends keyof T>(endpointKey: K, input?: RequestInput<T[K]>) => Promise<ApiWrapperResponse<z.TypeOf<T[K]["resSchema"]>>>;
-};
-export declare const createApiWrapper: typeof createApiClient;
-export {};
+export type { FormattedZodIssue } from './zod-issues';
+export * from './types';
+export * from './errors';
+export { createApiClient } from './create-client';
+export { defineAction } from './actions-impl';

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

@@ -0,0 +1,2 @@
+import type { ApiErrorContext } from './shared';
+export declare function defaultRedactContext(ctx: ApiErrorContext): ApiErrorContext;

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

@@ -0,0 +1,16 @@
+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>;
+export type ApiErrorContext = {
+    endpoint: string;
+    method: HttpMethod;
+    url: string;
+    attempt: number;
+    maxRetries: number;
+    elapsedMs: number;
+    requestHeaders?: Record<string, string>;
+    requestBody?: unknown;
+    meta?: Record<string, unknown>;
+};

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

@@ -0,0 +1 @@
+export declare function calculateSizeInMb(data: unknown): number;

package/dist/api-wrapper/test-helpers.d.ts

@@ -0,0 +1,6 @@
+export declare const originalFetch: typeof fetch;
+export declare const createMockResponse: (body: unknown, options?: {
+    status?: number | undefined;
+    contentType?: string | undefined;
+}) => Response;
+export declare const mockFetch: (fn: (url: string, options?: RequestInit | undefined) => Promise<Response>) => void;

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

@@ -0,0 +1,55 @@
+import { type z } from 'zod';
+import type { ApiEndpoint, OnResponseContext, OnRetryContext, RetryContext } from './types';
+import type { ApiErrorContext, HttpMethod } from './shared';
+export type RequestConfig = {
+    method: HttpMethod;
+    fullUrl: string;
+    body: unknown;
+    headers: Record<string, string>;
+    timeoutMs?: number;
+    fetchFn: typeof fetch;
+    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>;
+    status: number;
+}>;
+export declare function getRetryDelay(params: {
+    retryDelay: number | ((attempt: number) => number);
+    attempt: number;
+    response?: Response;
+    maxRetryDelayMs?: number;
+}): number;
+export declare function shouldAttemptRetryOnError(error: unknown): boolean;
+export declare function shouldAttemptRetryOnHttp(retryCtx: RetryContext): boolean;
+type MakeRequestArgs<TValidated> = {
+    config: RequestConfig;
+    maxRetries: number;
+    retryDelay: number | ((attempt: number) => number);
+    maxRetryDelayMs?: number;
+    validateFn: (response: Response, attempt: number) => Promise<TValidated>;
+    shouldRetry: (context: RetryContext) => boolean;
+    logger?: Pick<Console, 'debug'>;
+    ctx: (over?: Partial<ApiErrorContext>) => ApiErrorContext;
+    endpointName: string;
+    method: HttpMethod;
+    fullUrl: string;
+    meta?: Record<string, unknown>;
+    onResponse?: (context: OnResponseContext) => void | Promise<void>;
+    onRetry?: (context: OnRetryContext) => void | Promise<void>;
+};
+export declare function makeRequestWithRetry<TValidated>(args: MakeRequestArgs<TValidated>): Promise<{
+    validatedData: TValidated;
+    retryCount: number;
+    httpStatus: number;
+}>;
+export declare function validateAndTransformResponse<T extends z.ZodType>(endpoint: ApiEndpoint<z.ZodType | undefined, z.ZodType | undefined, z.ZodType | undefined, z.ZodType | undefined, T>, response: Response, ctx: (over?: Partial<ApiErrorContext>) => ApiErrorContext): Promise<{
+    data: z.infer<T>;
+    responseSizeBytes: number;
+}>;
+export declare function defaultShouldRetry(ctx: RetryContext): boolean;
+export {};

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

@@ -0,0 +1,154 @@
+import type { z } from 'zod';
+import type { ApiError } from './errors';
+import type { ApiErrorContext, BaseApiUrl, HttpMethod, PathParams, QueryParams, RequestBodyFormat } 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);
+    reqBodySchema?: TReqBody;
+    reqParamsSchema?: TReqParams;
+    reqQuerySchema?: TReqQuery;
+    reqHeadersSchema?: TReqHeaders;
+    resSchema: TResponse;
+    baseApiUrl?: string;
+    reqBodyFormat?: RequestBodyFormat;
+    defaultHeaders?: Record<string, string>;
+    resFormatter?: (data: unknown, headers: Record<string, string>) => z.infer<TResponse>;
+    reqDefaultQueryParams?: QueryParams;
+    doNotEncodeQueryParams?: boolean;
+}
+export interface ApiWrapperResponse<T> {
+    data: T;
+    requestBodySizeMb: number;
+    responseSizeMb: number;
+    responseTimeMs: number;
+    httpStatus: number;
+    retryCount: number;
+}
+export type RetryContext = {
+    error?: unknown;
+    response?: Response;
+    retryCount: number;
+    maxRetries: number;
+    endpoint?: string;
+    method?: HttpMethod;
+    url?: string;
+};
+export type OnRetryContext = RetryContext & {
+    delayMs: number;
+    nextAttempt: number;
+};
+export type RequestInterceptorResult = {
+    headers?: Record<string, string>;
+    body?: unknown;
+} | void | undefined;
+export type OnRequestContext = {
+    endpoint: string;
+    method: HttpMethod;
+    url: string;
+    headers: Record<string, string>;
+    body: unknown;
+    meta?: Record<string, unknown>;
+};
+export type OnResponseContext = {
+    endpoint: string;
+    method: HttpMethod;
+    url: string;
+    response: Response;
+    attempt: number;
+    meta?: Record<string, unknown>;
+};
+export type ActionCache = {
+    <T>(key: string, fn: () => Promise<T> | T, options?: {
+        ttlMs?: number;
+    }): Promise<T>;
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T, options?: {
+        ttlMs?: number;
+    }): void;
+    invalidate(key: string): void;
+    clear(): void;
+};
+export type ActionInvokeOptions = {
+    signal?: AbortSignal;
+    meta?: Record<string, unknown>;
+};
+export type ActionContext<TInput, TApi = any> = {
+    input: TInput;
+    api: TApi;
+    signal?: AbortSignal;
+    meta?: Record<string, unknown>;
+    logger?: Pick<Console, 'debug' | 'error'>;
+    cache: ActionCache;
+};
+export interface ApiAction<TInput = any, TOutput = any> {
+    handler: (ctx: ActionContext<TInput>) => Promise<TOutput> | TOutput;
+    /** 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;
+};
+export type DefineAction<TApi> = {
+    <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 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>;
+};
+type CommonRequestOptions = {
+    url?: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    retries?: number;
+    fetch?: typeof fetch;
+    meta?: Record<string, unknown>;
+};
+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 A>(actionKey: K, ...args: ActionArgs<A[K]>): Promise<ActionOutput<A[K]>>;
+    };
+    cache: ActionCache;
+} & {
+    [K in keyof T]: (...args: RequestArgs<T[K]>) => Promise<ApiWrapperResponse<z.infer<T[K]['resSchema']>>>;
+} & {
+    [K in keyof A]: (...args: ActionArgs<A[K]>) => Promise<ActionOutput<A[K]>>;
+};
+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>>;
+};
+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>;
+    timeoutMs?: number;
+    retries?: number;
+    retryDelayMs?: number | ((attempt: number) => number);
+    maxRetryDelayMs?: number;
+    shouldRetry?: (context: RetryContext) => boolean;
+    logger?: Pick<Console, 'debug' | 'error'>;
+    fetch?: typeof fetch;
+    onRequest?: (context: OnRequestContext) => RequestInterceptorResult | Promise<RequestInterceptorResult>;
+    onResponse?: (context: OnResponseContext) => void | Promise<void>;
+    onError?: (error: ApiError) => void | Promise<void>;
+    onRetry?: (context: OnRetryContext) => void | Promise<void>;
+    redact?: (context: ApiErrorContext) => ApiErrorContext;
+    actions?: A | ((helpers: ActionsFactoryHelpers<T, A>) => A);
+}
+export type ApiClientConfigNoActions<T extends Record<string, ApiEndpoint>> = Omit<ApiClientConfig<T, Record<string, never>>, 'actions'>;
+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';

package/dist/api-wrapper/zod-issues.d.ts

@@ -0,0 +1,17 @@
+import { ZodError } from 'zod';
+export type FormattedZodIssue = {
+    path: string;
+    pathArray: (string | number)[];
+    code: string;
+    message: string;
+    expected?: string;
+    received?: string;
+    value?: unknown;
+    valuePreview?: string;
+    extra?: Record<string, unknown>;
+};
+export declare function formatZodIssues(error: ZodError, rawData: unknown): FormattedZodIssue[];
+export declare function renderIssueSummary(issues: FormattedZodIssue[]): string;
+export declare function previewValue(value: unknown, maxLen?: number): string;
+export declare function makeJsonParseZodError(error: unknown, text: string): ZodError;
+export declare function tryParseJson(body: string): unknown;

package/dist/cache/index.d.ts

@@ -3,6 +3,23 @@ type CachedFunction<T extends AnyFunction> = {
     (...args: Parameters<T>): ReturnType<T>;
     clearCache: () => void;
 };
+export type CacheStoreEntry = {
+    value: unknown;
+    timestamp: number;
+};
+/**
+ * Contract for external cache stores (e.g. a Redis adapter).
+ * Serialization is the adapter's responsibility; this library never imports
+ * the underlying client.
+ */
+export type CacheStore = {
+    get: (key: string) => Promise<CacheStoreEntry | undefined>;
+    /** `ttlMs` maps to the store's native expiry (e.g. Redis `PX`). */
+    set: (key: string, entry: CacheStoreEntry, ttlMs: number) => Promise<void>;
+    delete: (key: string) => Promise<void>;
+    /** Optional; called by clearCache when defined. */
+    clear?: () => Promise<void>;
+};
 export type CacheFunctionOptions<T extends AnyFunction> = {
     name: string;
     fn: T;
@@ -14,6 +31,15 @@ export type CacheFunctionOptions<T extends AnyFunction> = {
     onBackgroundRefreshError?: (error: unknown, context: {
         name: string;
     }) => void;
+    /**
+     * External cache store (e.g. a Redis adapter). Only supported for async
+     * functions; when omitted the built-in in-memory cache is used.
+     */
+    store?: ReturnType<T> extends Promise<unknown> ? CacheStore : never;
+    /** Called when a store get/set/delete/clear fails (default: silent). */
+    onStoreError?: (error: unknown, context: {
+        name: string;
+    }) => void;
 };
 export declare function cacheFunction<T extends AnyFunction>(options: CacheFunctionOptions<T>): CachedFunction<T>;
 export {};