hanzio 1.0.10 → 1.2.0

package/src/api-wrapper/transport.ts

@@ -0,0 +1,350 @@
+import { ZodError, type z } from 'zod'
+import type {
+	ApiEndpoint,
+	OnResponseContext,
+	OnRetryContext,
+	RetryContext
+} from './types'
+import type { ApiErrorContext, HttpMethod } from './shared'
+import {
+	ConfigError,
+	HttpResponseError,
+	isNonRetryableApiError,
+	NetworkError,
+	RequestAbortedError,
+	RequestTimeoutError,
+	ResponseValidationError
+} from './errors'
+import {
+	buildFetchBody,
+	getHeadersAsObject,
+	hasJsonContentType
+} from './headers'
+import { makeJsonParseZodError } from './zod-issues'
+
+export type RequestConfig = {
+	method: HttpMethod
+	fullUrl: string
+	body: unknown
+	headers: Record<string, string>
+	timeoutMs?: number
+	fetchFn: typeof fetch
+	userSignal?: AbortSignal
+}
+
+export async function validateResponse<T extends z.ZodType>(
+	schema: T,
+	data: unknown,
+	ctx: (over?: Partial<ApiErrorContext>) => ApiErrorContext
+): Promise<z.infer<T>> {
+	try {
+		return await schema.parseAsync(data)
+	} catch (error) {
+		if (error instanceof ZodError) {
+			throw new ResponseValidationError(error, data, ctx())
+		}
+		throw error
+	}
+}
+
+export async function httpRequest(
+	config: RequestConfig,
+	ctx: (over?: Partial<ApiErrorContext>) => ApiErrorContext
+): Promise<Response> {
+	const timeoutController = new AbortController()
+	const timeout =
+		config.timeoutMs === undefined
+			? undefined
+			: setTimeout(() => timeoutController.abort(), config.timeoutMs)
+
+	const signal = mergeSignals(timeoutController.signal, config.userSignal)
+
+	try {
+		return await config.fetchFn(config.fullUrl, {
+			method: config.method,
+			headers: config.headers,
+			body: buildFetchBody(
+				config.body,
+				config.headers,
+				(msg) => new ConfigError(msg, ctx())
+			),
+			signal
+		})
+	} catch (error) {
+		if (isDomAbortError(error)) {
+			if (config.userSignal?.aborted) {
+				throw new RequestAbortedError(ctx(), error)
+			}
+			if (timeoutController.signal.aborted && config.timeoutMs !== undefined) {
+				throw new RequestTimeoutError(config.timeoutMs, ctx())
+			}
+			throw new RequestAbortedError(ctx(), error)
+		}
+		if (error instanceof ConfigError) throw error
+		throw new NetworkError(
+			error instanceof Error ? error.message : String(error),
+			ctx(),
+			error
+		)
+	} finally {
+		if (timeout) clearTimeout(timeout)
+	}
+}
+
+function isDomAbortError(error: unknown): boolean {
+	return (
+		typeof error === 'object' &&
+		error !== null &&
+		'name' in error &&
+		(error as { name: string }).name === 'AbortError'
+	)
+}
+
+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>
+	status: number
+}> {
+	const body = await response.text()
+	return {
+		body,
+		headers: getHeadersAsObject(response.headers),
+		status: response.status
+	}
+}
+
+export function getRetryDelay(params: {
+	retryDelay: number | ((attempt: number) => number)
+	attempt: number
+	response?: Response
+	maxRetryDelayMs?: number
+}): number {
+	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 delayMs =
+		typeof retryDelay === 'function' ? retryDelay(attempt) : retryDelay
+	return Math.min(delayMs, maxDelay)
+}
+
+export function shouldAttemptRetryOnError(error: unknown): boolean {
+	return !isNonRetryableApiError(error)
+}
+
+export function shouldAttemptRetryOnHttp(retryCtx: RetryContext): boolean {
+	const { error, response } = retryCtx
+	if (error) return shouldAttemptRetryOnError(error)
+	return response ? response.status >= 500 || response.status === 429 : false
+}
+
+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 async function makeRequestWithRetry<TValidated>(
+	args: MakeRequestArgs<TValidated>
+): Promise<{
+	validatedData: TValidated
+	retryCount: number
+	httpStatus: number
+}> {
+	const {
+		config,
+		maxRetries,
+		retryDelay,
+		maxRetryDelayMs,
+		validateFn,
+		shouldRetry,
+		logger,
+		ctx,
+		endpointName,
+		method,
+		fullUrl,
+		meta,
+		onResponse,
+		onRetry
+	} = args
+	let retryCount = 0
+
+	while (true) {
+		let response: Response | undefined
+		try {
+			logger?.debug?.('API request', config)
+			response = await httpRequest(config, (over) =>
+				ctx({ attempt: retryCount, ...over })
+			)
+
+			await onResponse?.({
+				endpoint: endpointName,
+				method,
+				url: fullUrl,
+				response: response.clone() as Response,
+				attempt: retryCount,
+				meta
+			})
+
+			if (response.status >= 400) {
+				const retryCtx: RetryContext = {
+					response,
+					retryCount,
+					maxRetries,
+					endpoint: endpointName,
+					method,
+					url: fullUrl
+				}
+				if (retryCount < maxRetries && shouldRetry(retryCtx)) {
+					const delayMs = getRetryDelay({
+						retryDelay,
+						attempt: retryCount,
+						response,
+						maxRetryDelayMs
+					})
+					await onRetry?.({
+						...retryCtx,
+						delayMs,
+						nextAttempt: retryCount + 1
+					})
+					retryCount++
+					await delay(delayMs)
+					continue
+				}
+
+				const { body, headers: responseHeaders } =
+					await readErrorResponse(response)
+				throw new HttpResponseError(
+					response.status,
+					body,
+					responseHeaders,
+					ctx({ attempt: retryCount })
+				)
+			}
+
+			return {
+				validatedData: await validateFn(response, retryCount),
+				retryCount,
+				httpStatus: response.status
+			}
+		} catch (error) {
+			if (isNonRetryableApiError(error)) {
+				throw error
+			}
+
+			const retryCtx: RetryContext = {
+				error,
+				retryCount,
+				maxRetries,
+				endpoint: endpointName,
+				method,
+				url: fullUrl
+			}
+			if (retryCount >= maxRetries || !shouldRetry(retryCtx)) {
+				throw error
+			}
+
+			const delayMs = getRetryDelay({
+				retryDelay,
+				attempt: retryCount,
+				response: undefined,
+				maxRetryDelayMs
+			})
+			await onRetry?.({
+				...retryCtx,
+				delayMs,
+				nextAttempt: retryCount + 1
+			})
+			retryCount++
+			await delay(delayMs)
+		}
+	}
+}
+
+export async 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 }> {
+	const responseHeaders = getHeadersAsObject(response.headers)
+	const text = await response.text()
+	const responseSizeBytes = new TextEncoder().encode(text).length
+	let responseData: unknown
+	if (hasJsonContentType(responseHeaders)) {
+		try {
+			responseData = text === '' ? undefined : JSON.parse(text)
+		} catch (error) {
+			throw new ResponseValidationError(
+				makeJsonParseZodError(error, text),
+				text,
+				ctx()
+			)
+		}
+	} else {
+		responseData = text
+	}
+	const transformedData = endpoint.resFormatter
+		? endpoint.resFormatter(responseData, responseHeaders)
+		: responseData
+
+	const data = await validateResponse(endpoint.resSchema, transformedData, ctx)
+	return { data, responseSizeBytes }
+}
+
+export function defaultShouldRetry(ctx: RetryContext): boolean {
+	if (ctx.error) return shouldAttemptRetryOnError(ctx.error)
+	return shouldAttemptRetryOnHttp(ctx)
+}
+
+function delay(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms))
+}

package/src/api-wrapper/types.ts

@@ -0,0 +1,259 @@
+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>
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: TApi defaults to any so plain ApiAction stays open
+export type ActionContext<TInput, TApi = any> = {
+	input: TInput
+	api: TApi
+	signal?: AbortSignal
+	meta?: Record<string, unknown>
+	logger?: Pick<Console, 'debug' | 'error'>
+	cache: ActionCache
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: variance-friendly bounds
+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>
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: variance-friendly inference
+type ActionInput<A> = A extends ApiAction<infer I, any> ? I : never
+// biome-ignore lint/suspicious/noExplicitAny: variance-friendly inference
+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'