hanzio 1.2.0 → 2.0.0

package/src/api-wrapper/transport.ts

@@ -1,12 +1,16 @@
 import { ZodError, type z } from 'zod'
+import { anySignal, promiseTimeout } from '../promise'
+import { parseRetryAfter } from '../url'
 import type {
 	ApiEndpoint,
+	FetchLike,
 	OnResponseContext,
 	OnRetryContext,
 	RetryContext
 } from './types'
-import type { ApiErrorContext, HttpMethod } from './shared'
+import type { ApiErrorContext, HttpMethod, RequestMeta } from './shared'
 import {
+	ApiResponseError,
 	ConfigError,
 	HttpResponseError,
 	isNonRetryableApiError,
@@ -20,6 +24,7 @@ import {
 	getHeadersAsObject,
 	hasJsonContentType
 } from './headers'
+import { redactUrl } from './redaction'
 import { makeJsonParseZodError } from './zod-issues'
 
 export type RequestConfig = {
@@ -28,7 +33,7 @@ export type RequestConfig = {
 	body: unknown
 	headers: Record<string, string>
 	timeoutMs?: number
-	fetchFn: typeof fetch
+	fetchFn: FetchLike
 	userSignal?: AbortSignal
 }
 
@@ -57,7 +62,7 @@ export async function httpRequest(
 			? undefined
 			: setTimeout(() => timeoutController.abort(), config.timeoutMs)
 
-	const signal = mergeSignals(timeoutController.signal, config.userSignal)
+	const signal = anySignal(timeoutController.signal, config.userSignal)
 
 	try {
 		return await config.fetchFn(config.fullUrl, {
@@ -100,27 +105,6 @@ function isDomAbortError(error: unknown): boolean {
 	)
 }
 
-export function mergeSignals(
-	a: AbortSignal,
-	b: AbortSignal | undefined
-): AbortSignal {
-	if (!b) return a
-	const anyFn = (
-		AbortSignal as unknown as {
-			any?: (signals: AbortSignal[]) => AbortSignal
-		}
-	).any
-	if (typeof anyFn === 'function') return anyFn([a, b])
-
-	const controller = new AbortController()
-	const onAbort = () => controller.abort()
-	if (a.aborted) controller.abort()
-	else a.addEventListener('abort', onAbort, { once: true })
-	if (b.aborted) controller.abort()
-	else b.addEventListener('abort', onAbort, { once: true })
-	return controller.signal
-}
-
 export async function readErrorResponse(response: Response): Promise<{
 	body: string
 	headers: Record<string, string>
@@ -143,17 +127,8 @@ export function getRetryDelay(params: {
 	const maxDelay = params.maxRetryDelayMs ?? 30_000
 	const { retryDelay, attempt, response } = params
 	if (response && (response.status === 429 || response.status === 503)) {
-		const retryAfter = response.headers.get('retry-after')
-		if (retryAfter) {
-			const seconds = Number(retryAfter)
-			if (Number.isFinite(seconds)) {
-				return Math.min(Math.max(0, seconds * 1000), maxDelay)
-			}
-			const dateMs = Date.parse(retryAfter)
-			if (!Number.isNaN(dateMs)) {
-				return Math.min(Math.max(0, dateMs - Date.now()), maxDelay)
-			}
-		}
+		const retryAfterMs = parseRetryAfter(response.headers.get('retry-after'))
+		if (retryAfterMs !== undefined) return Math.min(retryAfterMs, maxDelay)
 	}
 	const delayMs =
 		typeof retryDelay === 'function' ? retryDelay(attempt) : retryDelay
@@ -182,7 +157,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>
 }
@@ -215,7 +190,13 @@ export async function makeRequestWithRetry<TValidated>(
 	while (true) {
 		let response: Response | undefined
 		try {
-			logger?.debug?.('API request', config)
+			// Headers and body stay out of debug logs; they may carry credentials.
+			logger?.debug?.('API request', {
+				endpoint: endpointName,
+				method,
+				url: redactUrl(fullUrl),
+				attempt: retryCount
+			})
 			response = await httpRequest(config, (over) =>
 				ctx({ attempt: retryCount, ...over })
 			)
@@ -250,8 +231,10 @@ export async function makeRequestWithRetry<TValidated>(
 						delayMs,
 						nextAttempt: retryCount + 1
 					})
+					await sleepBeforeRetry(delayMs, config.userSignal, () =>
+						ctx({ attempt: retryCount })
+					)
 					retryCount++
-					await delay(delayMs)
 					continue
 				}
 
@@ -271,7 +254,11 @@ export async function makeRequestWithRetry<TValidated>(
 				httpStatus: response.status
 			}
 		} catch (error) {
-			if (isNonRetryableApiError(error)) {
+			// ApiResponseError is not retried by default, but a custom shouldRetry may opt in.
+			if (
+				isNonRetryableApiError(error) &&
+				!(error instanceof ApiResponseError)
+			) {
 				throw error
 			}
 
@@ -298,8 +285,10 @@ export async function makeRequestWithRetry<TValidated>(
 				delayMs,
 				nextAttempt: retryCount + 1
 			})
+			await sleepBeforeRetry(delayMs, config.userSignal, () =>
+				ctx({ attempt: retryCount })
+			)
 			retryCount++
-			await delay(delayMs)
 		}
 	}
 }
@@ -326,7 +315,8 @@ export async function validateAndTransformResponse<T extends z.ZodType>(
 			throw new ResponseValidationError(
 				makeJsonParseZodError(error, text),
 				text,
-				ctx()
+				ctx(),
+				{ invalidJson: true }
 			)
 		}
 	} else {
@@ -345,6 +335,14 @@ export function defaultShouldRetry(ctx: RetryContext): boolean {
 	return shouldAttemptRetryOnHttp(ctx)
 }
 
-function delay(ms: number): Promise<void> {
-	return new Promise((resolve) => setTimeout(resolve, ms))
+async function sleepBeforeRetry(
+	ms: number,
+	signal: AbortSignal | undefined,
+	ctx: () => ApiErrorContext
+): Promise<void> {
+	try {
+		await promiseTimeout(ms, { signal })
+	} catch (error) {
+		throw new RequestAbortedError(ctx(), error)
+	}
 }

package/src/api-wrapper/types.ts

@@ -1,4 +1,5 @@
 import type { z } from 'zod'
+import type { Result } from '../promise'
 import type { ApiError } from './errors'
 import type {
 	ApiErrorContext,
@@ -6,7 +7,8 @@ import type {
 	HttpMethod,
 	PathParams,
 	QueryParams,
-	RequestBodyFormat
+	RequestBodyFormat,
+	RequestMeta
 } from './shared'
 
 export interface ApiEndpoint<
@@ -26,10 +28,11 @@ export interface ApiEndpoint<
 	baseApiUrl?: string
 	reqBodyFormat?: RequestBodyFormat
 	defaultHeaders?: Record<string, string>
+	/** Reshapes the raw body before `resSchema` parses it, so it returns the schema's input type. */
 	resFormatter?: (
 		data: unknown,
 		headers: Record<string, string>
-	) => z.infer<TResponse>
+	) => z.input<TResponse>
 	reqDefaultQueryParams?: QueryParams
 	doNotEncodeQueryParams?: boolean
 }
@@ -72,7 +75,7 @@ export type OnRequestContext = {
 	url: string
 	headers: Record<string, string>
 	body: unknown
-	meta?: Record<string, unknown>
+	meta?: RequestMeta
 }
 
 export type OnResponseContext = {
@@ -81,7 +84,7 @@ export type OnResponseContext = {
 	url: string
 	response: Response
 	attempt: number
-	meta?: Record<string, unknown>
+	meta?: RequestMeta
 }
 
 export type ActionCache = {
@@ -98,7 +101,7 @@ export type ActionCache = {
 
 export type ActionInvokeOptions = {
 	signal?: AbortSignal
-	meta?: Record<string, unknown>
+	meta?: RequestMeta
 }
 
 // biome-ignore lint/suspicious/noExplicitAny: TApi defaults to any so plain ApiAction stays open
@@ -106,7 +109,7 @@ 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
 }
@@ -114,6 +117,8 @@ export type ActionContext<TInput, TApi = any> = {
 // biome-ignore lint/suspicious/noExplicitAny: variance-friendly bounds
 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
 }
@@ -122,7 +127,18 @@ 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>
@@ -140,24 +156,68 @@ export type ActionArgs<A> = [ActionInput<A>] extends [undefined]
 	? [options?: ActionInvokeOptions]
 	: [input: ActionInput<A>, options?: ActionInvokeOptions]
 
+// Tail-recursive (accumulator) to stay under TypeScript's recursion limit.
+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['reqParamsSchema'] extends z.ZodType ? 'reqParams' : 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')
 
+// Callers pass what the schemas accept (`z.input`): fields with `.default()`
+// are optional and transforms take their pre-transform type.
 type SchemaInputs<TEndpoint extends ApiEndpoint> = {
 	reqBody: TEndpoint['reqBodySchema'] extends z.ZodType
-		? z.infer<TEndpoint['reqBodySchema']>
+		? z.input<TEndpoint['reqBodySchema']>
 		: unknown
 	reqParams: TEndpoint['reqParamsSchema'] extends z.ZodType
-		? z.infer<TEndpoint['reqParamsSchema']>
-		: PathParams
+		? z.input<TEndpoint['reqParamsSchema']>
+		: [EndpointPathParamNames<TEndpoint>] extends [never]
+			? PathParams
+			: Record<EndpointPathParamNames<TEndpoint>, string | number>
 	reqQuery: TEndpoint['reqQuerySchema'] extends z.ZodType
-		? z.infer<TEndpoint['reqQuerySchema']>
+		? z.input<TEndpoint['reqQuerySchema']>
 		: QueryParams
 	reqHeaders: TEndpoint['reqHeadersSchema'] extends z.ZodType
-		? z.infer<TEndpoint['reqHeadersSchema']>
+		? z.input<TEndpoint['reqHeadersSchema']>
 		: Record<string, string>
 }
 
@@ -166,8 +226,8 @@ type CommonRequestOptions = {
 	signal?: AbortSignal
 	timeoutMs?: number
 	retries?: number
-	fetch?: typeof fetch
-	meta?: Record<string, unknown>
+	fetch?: FetchLike
+	meta?: RequestMeta
 }
 
 export type RequestInput<TEndpoint extends ApiEndpoint> = Pick<
@@ -190,21 +250,72 @@ export type ApiClient<
 		<K extends keyof T>(
 			endpointKey: K,
 			...args: RequestArgs<T[K]>
-		): Promise<ApiWrapperResponse<z.infer<T[K]['resSchema']>>>
+		): 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']>>>
+	) => 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 = {
+	// Method syntax keeps the key parameter bivariant, so any client fits.
+	// biome-ignore lint/suspicious/noExplicitAny: accepts every client's argument shapes
+	request(key: string, ...args: any[]): Promise<unknown>
+	cache: ActionCache
+	// biome-ignore lint/suspicious/noExplicitAny: accepts every client's argument shapes
+	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>
@@ -213,6 +324,48 @@ export type ActionsFactoryHelpers<
 	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>
@@ -221,14 +374,26 @@ export interface ApiClientConfig<
 	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>
@@ -250,6 +415,8 @@ export type ApiClientConfigWithActions<
 }
 
 export type {
+	ApiRequestMeta,
+	RequestMeta,
 	BaseApiUrl,
 	HttpMethod,
 	PathParams,