hanzio 1.0.10 → 1.2.0

package/src/api-wrapper/builders.ts

@@ -0,0 +1,200 @@
+import { ZodError } from 'zod'
+import { type ConfigError, RequestValidationError } from './errors'
+import { normalizeHeaders } from './headers'
+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 function formatQueryString(
+	queryParams: Record<string, string>,
+	doNotEncode?: boolean
+): string {
+	if (Object.keys(queryParams).length === 0) return ''
+	return doNotEncode
+		? Object.entries(queryParams)
+				.map(([key, value]) => `${key}=${value}`)
+				.join('&')
+		: new URLSearchParams(queryParams).toString()
+}
+
+export function buildUrl(options: BuildUrlOptions) {
+	const {
+		endpoint,
+		params,
+		queryParams,
+		baseApiUrls,
+		defaultBaseApiUrl,
+		url,
+		doNotEncodeQueryParams,
+		configError
+	} = options
+
+	let finalUrl: string
+	if (url) {
+		finalUrl = replacePathParams(url, params, configError)
+	} else {
+		const defaultBaseUrl = defaultBaseApiUrl ?? Object.keys(baseApiUrls)[0]
+		if (!defaultBaseUrl) {
+			throw configError('At least one base API URL is required')
+		}
+
+		const baseUrlKey = endpoint.baseApiUrl ?? defaultBaseUrl
+		const configBaseUrl = baseApiUrls[baseUrlKey]
+		if (!configBaseUrl) {
+			throw configError(`Unknown base API URL: ${baseUrlKey}`)
+		}
+
+		const baseUrl =
+			typeof configBaseUrl === 'function' ? configBaseUrl() : configBaseUrl
+		const path =
+			typeof endpoint.path === 'function'
+				? endpoint.path(baseUrl)
+				: endpoint.path
+		// Substitute endpoint parameters without interpreting a port or IPv6 host as one.
+		finalUrl = `${baseUrl}${replacePathParams(path, params, configError)}`
+	}
+
+	const queryString = formatQueryString(queryParams, doNotEncodeQueryParams)
+	return {
+		finalUrl,
+		fullUrl: queryString ? `${finalUrl}?${queryString}` : finalUrl
+	}
+}
+
+export function buildPathParams(
+	endpoint: ApiEndpoint,
+	params: PathParams | undefined,
+	ctx: (over?: Partial<ApiErrorContext>) => ApiErrorContext
+): PathParams | undefined {
+	if (!endpoint.reqParamsSchema) return params
+
+	try {
+		return endpoint.reqParamsSchema.parse(params) as PathParams
+	} catch (error) {
+		if (error instanceof ZodError) {
+			throw new RequestValidationError(error, 'params', params, ctx())
+		}
+		throw error
+	}
+}
+
+export function buildQueryParams(
+	endpoint: ApiEndpoint,
+	query: QueryParams | undefined,
+	ctx: (over?: Partial<ApiErrorContext>) => ApiErrorContext
+): Record<string, string> {
+	const defaultParams = endpoint.reqDefaultQueryParams ?? {}
+	let parsedQuery: QueryParams
+	if (endpoint.reqQuerySchema) {
+		try {
+			parsedQuery = endpoint.reqQuerySchema.parse(query) as QueryParams
+		} catch (error) {
+			if (error instanceof ZodError) {
+				throw new RequestValidationError(error, 'query', query, ctx())
+			}
+			throw error
+		}
+	} else {
+		parsedQuery = query ?? {}
+	}
+	const merged = { ...defaultParams, ...parsedQuery }
+
+	return Object.fromEntries(
+		Object.entries(merged)
+			.filter(([, value]) => value !== undefined)
+			.map(([key, value]) => [key, String(value)])
+	)
+}
+
+export function buildRequestBody(
+	endpoint: ApiEndpoint,
+	body: unknown,
+	ctx: (over?: Partial<ApiErrorContext>) => ApiErrorContext
+): unknown {
+	if (!endpoint.reqBodySchema) return body
+
+	let parsedBody: Record<string, unknown>
+	try {
+		parsedBody = endpoint.reqBodySchema.parse(body) as Record<string, unknown>
+	} catch (error) {
+		if (error instanceof ZodError) {
+			throw new RequestValidationError(error, 'body', body, ctx())
+		}
+		throw error
+	}
+
+	if (endpoint.reqBodyFormat !== 'form-data') {
+		return parsedBody
+	}
+
+	const formData = new FormData()
+	for (const [key, value] of Object.entries(parsedBody)) {
+		if (value == null) continue
+		formData.set(key, value instanceof Blob ? value : String(value))
+	}
+
+	return formData
+}
+
+export function buildHeaders(
+	endpoint: ApiEndpoint,
+	headers: Record<string, string> | undefined,
+	defaultHeaders: Record<string, string>,
+	ctx: (over?: Partial<ApiErrorContext>) => ApiErrorContext
+): Record<string, string> {
+	const contentType =
+		endpoint.reqBodyFormat === 'json' ? 'application/json' : undefined
+
+	let parsedHeaders: Record<string, string>
+	if (endpoint.reqHeadersSchema) {
+		try {
+			parsedHeaders = endpoint.reqHeadersSchema.parse(headers) as Record<
+				string,
+				string
+			>
+		} catch (error) {
+			if (error instanceof ZodError) {
+				throw new RequestValidationError(error, 'headers', headers, ctx())
+			}
+			throw error
+		}
+	} else {
+		parsedHeaders = headers ?? {}
+	}
+
+	return normalizeHeaders({
+		...defaultHeaders,
+		...(contentType && { 'Content-Type': contentType }),
+		...endpoint.defaultHeaders,
+		...parsedHeaders
+	})
+}
+
+export function replacePathParams(
+	path: string,
+	params: PathParams | undefined,
+	configError: (msg: string) => ConfigError
+): string {
+	return path.replace(/:(\w+)/g, (_, key: string) => {
+		const value = params?.[key]
+		if (value === undefined) {
+			throw configError(`Missing required path parameter: ${key}`)
+		}
+		return encodeURIComponent(String(value))
+	})
+}

package/src/api-wrapper/create-client.ts

@@ -0,0 +1,393 @@
+import type { z } from 'zod'
+import type {
+	ActionInvokeOptions,
+	ActionsFactoryHelpers,
+	ApiAction,
+	ApiClient,
+	ApiClientConfig,
+	ApiClientConfigNoActions,
+	ApiClientConfigWithActions,
+	ApiEndpoint,
+	ApiWrapperResponse,
+	RequestInput
+} from './types'
+import type { PathParams, QueryParams } from './shared'
+import type { ApiErrorContext } from './shared'
+import {
+	buildHeaders,
+	buildPathParams,
+	buildQueryParams,
+	buildRequestBody,
+	buildUrl
+} from './builders'
+import { createActionCache, makeDefineAction } from './actions-impl'
+import { reportApiError } from './error-reporting'
+import { ActionError, ApiError, ConfigError } from './errors'
+import { calculateSizeInMb } from './size'
+import {
+	defaultShouldRetry,
+	makeRequestWithRetry,
+	type RequestConfig,
+	validateAndTransformResponse
+} from './transport'
+
+type AnyApiAction = ApiAction<unknown, unknown>
+
+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>
+}
+
+function isActionInvokeOptionsOnly(
+	value: unknown
+): value is ActionInvokeOptions {
+	if (value === null || value === undefined) return false
+	if (typeof value !== 'object' || Array.isArray(value)) return false
+	return Object.keys(value as object).every(
+		(k) => k === 'signal' || k === 'meta'
+	)
+}
+
+function resolveActionInvocation(
+	action: AnyApiAction,
+	actionName: string,
+	first: unknown,
+	second?: ActionInvokeOptions
+): { input: unknown; options: ActionInvokeOptions } {
+	if (!action.noRuntimeInput) {
+		return { input: first, options: second ?? {} }
+	}
+
+	if (first === undefined || first === null) {
+		return { input: undefined, options: second ?? {} }
+	}
+	if (second !== undefined) {
+		return { input: undefined, options: second }
+	}
+	if (isActionInvokeOptionsOnly(first)) {
+		return { input: undefined, options: first }
+	}
+
+	throw new ConfigError(
+		`Action "${actionName}" does not accept input; pass only optional { signal, meta }`,
+		{
+			endpoint: actionName,
+			method: 'GET',
+			url: '',
+			attempt: 0,
+			maxRetries: 0,
+			elapsedMs: 0
+		}
+	)
+}
+
+function createApiClientImpl<
+	T extends Record<string, ApiEndpoint>,
+	A extends Record<string, ApiAction> = Record<string, never>
+>(apiConfig: ApiClientConfig<T, A>): ApiClient<T, A> {
+	let actions: Record<string, AnyApiAction> = {}
+
+	const cache = createActionCache()
+
+	const invokeEndpoint = async <K extends keyof T>(
+		endpointKey: K,
+		input: RequestInput<T[K]> = {} as RequestInput<T[K]>
+	): Promise<ApiWrapperResponse<z.infer<T[K]['resSchema']>>> => {
+		const endpoint = apiConfig.endpoints[endpointKey]
+		const rawInput = input as RequestInput<T[K]> & {
+			reqBody?: unknown
+			reqParams?: PathParams
+			reqQuery?: QueryParams
+			reqHeaders?: Record<string, string>
+		}
+		const endpointName = apiConfig.name
+			? `${apiConfig.name}.${String(endpointKey)}`
+			: String(endpointKey)
+		const startedAt = Date.now()
+		const maxRetries = input.retries ?? apiConfig.retries ?? 3
+
+		const baseContext: ApiErrorContext = {
+			endpoint: endpointName,
+			method: endpoint?.method ?? 'GET',
+			url: '',
+			attempt: 0,
+			maxRetries,
+			elapsedMs: 0,
+			meta: input.meta
+		}
+
+		const elapsed = () => Date.now() - startedAt
+		const ctx = (over: Partial<ApiErrorContext> = {}): ApiErrorContext => ({
+			...baseContext,
+			elapsedMs: elapsed(),
+			...over
+		})
+
+		if (!endpoint) {
+			throw await reportApiError(
+				new ConfigError(`Unknown API endpoint: ${String(endpointKey)}`, ctx()),
+				apiConfig
+			)
+		}
+
+		baseContext.method = endpoint.method
+
+		let pathParams: PathParams | undefined
+		let queryParams: Record<string, string>
+		let body: unknown
+		let headers: Record<string, string>
+		try {
+			pathParams = buildPathParams(endpoint, rawInput.reqParams, ctx)
+			queryParams = buildQueryParams(endpoint, rawInput.reqQuery, ctx)
+			body = buildRequestBody(endpoint, rawInput.reqBody, ctx)
+			headers = buildHeaders(
+				endpoint,
+				rawInput.reqHeaders,
+				apiConfig.defaultHeaders ?? {},
+				ctx
+			)
+		} catch (e) {
+			if (e instanceof ApiError) throw await reportApiError(e, apiConfig)
+			throw e
+		}
+
+		let fullUrl: string
+		try {
+			const built = buildUrl({
+				endpoint,
+				params: pathParams,
+				queryParams,
+				baseApiUrls: apiConfig.baseApiUrls,
+				defaultBaseApiUrl: apiConfig.defaultBaseApiUrl,
+				url: input.url,
+				doNotEncodeQueryParams: endpoint.doNotEncodeQueryParams,
+				configError: (msg) => new ConfigError(msg, ctx())
+			})
+			fullUrl = built.fullUrl
+		} catch (e) {
+			if (e instanceof ApiError) throw await reportApiError(e, apiConfig)
+			throw e
+		}
+
+		baseContext.url = fullUrl
+		baseContext.requestHeaders = headers
+		baseContext.requestBody = body
+
+		if (apiConfig.onRequest) {
+			try {
+				const result = await apiConfig.onRequest({
+					endpoint: endpointName,
+					method: endpoint.method,
+					url: fullUrl,
+					headers,
+					body,
+					meta: input.meta
+				})
+				if (result?.headers) headers = result.headers
+				if (result && 'body' in result) body = result.body
+			} catch (e) {
+				if (e instanceof ApiError) throw await reportApiError(e, apiConfig)
+				throw e
+			}
+		}
+
+		const config: RequestConfig = {
+			method: endpoint.method,
+			fullUrl,
+			body,
+			headers,
+			timeoutMs: input.timeoutMs ?? apiConfig.timeoutMs,
+			fetchFn: input.fetch ?? apiConfig.fetch ?? fetch,
+			userSignal: input.signal
+		}
+
+		try {
+			const result = await makeRequestWithRetry({
+				config,
+				maxRetries,
+				retryDelay: apiConfig.retryDelayMs ?? 300,
+				maxRetryDelayMs: apiConfig.maxRetryDelayMs,
+				validateFn: (response, attempt) =>
+					validateAndTransformResponse(endpoint, response, (over) =>
+						ctx({ attempt, ...over })
+					),
+				shouldRetry: apiConfig.shouldRetry ?? defaultShouldRetry,
+				logger: apiConfig.logger,
+				ctx,
+				endpointName,
+				method: endpoint.method,
+				fullUrl,
+				meta: input.meta,
+				onResponse: apiConfig.onResponse,
+				onRetry: apiConfig.onRetry
+			})
+
+			const responseTimeMs = elapsed()
+			const responseSizeMb =
+				result.validatedData.responseSizeBytes / (1024 * 1024)
+			const requestBodySizeMb = calculateSizeInMb(config.body)
+
+			return {
+				data: result.validatedData.data as z.infer<T[K]['resSchema']>,
+				requestBodySizeMb,
+				responseSizeMb,
+				responseTimeMs,
+				httpStatus: result.httpStatus,
+				retryCount: result.retryCount
+			}
+		} catch (error) {
+			if (error instanceof ApiError)
+				throw await reportApiError(error, apiConfig)
+			throw error
+		}
+	}
+
+	async function invokeAction(
+		name: string,
+		rawInput: unknown,
+		options: ActionInvokeOptions = {}
+	): Promise<unknown> {
+		const action = actions[name]!
+		const inputForHandler = action.noRuntimeInput ? undefined : rawInput
+		const actionName = apiConfig.name ? `${apiConfig.name}.${name}` : name
+		const startedAt = Date.now()
+		const baseContext: ApiErrorContext = {
+			endpoint: actionName,
+			method: 'GET',
+			url: '',
+			attempt: 0,
+			maxRetries: 0,
+			elapsedMs: 0,
+			meta: options.meta,
+			requestBody: action.noRuntimeInput ? undefined : rawInput
+		}
+		const ctx = (over: Partial<ApiErrorContext> = {}): ApiErrorContext => ({
+			...baseContext,
+			elapsedMs: Date.now() - startedAt,
+			...over
+		})
+
+		apiConfig.logger?.debug?.('Action start', { action: actionName })
+
+		try {
+			const result = await action.handler({
+				input: inputForHandler,
+				api: proxy,
+				signal: options.signal,
+				meta: options.meta,
+				logger: apiConfig.logger,
+				cache
+			})
+			apiConfig.logger?.debug?.('Action end', {
+				action: actionName,
+				elapsedMs: Date.now() - startedAt
+			})
+			return result
+		} catch (error) {
+			if (error instanceof ApiError) {
+				throw await reportApiError(error, apiConfig)
+			}
+			const wrapped = new ActionError(
+				`Action ${actionName} failed: ${error instanceof Error ? error.message : String(error)}`,
+				ctx(),
+				error
+			)
+			throw await reportApiError(wrapped, apiConfig)
+		}
+	}
+
+	async function dispatchAction(
+		name: string,
+		first?: unknown,
+		second?: ActionInvokeOptions
+	): Promise<unknown> {
+		const action = actions[name]!
+		const { input, options } = resolveActionInvocation(
+			action,
+			name,
+			first,
+			second
+		)
+		return invokeAction(name, input, options)
+	}
+
+	const request = (async (
+		key: string,
+		input?: unknown,
+		options?: ActionInvokeOptions
+	): Promise<unknown> => {
+		if (key in actions) {
+			return dispatchAction(key, input, options)
+		}
+		return invokeEndpoint(
+			key as keyof T,
+			(input ?? {}) as RequestInput<T[keyof T]>
+		)
+	}) as unknown as ApiClient<T, A>['request']
+
+	const client = { request, cache } as ApiClient<T, A>
+	const proxy: ApiClient<T, A> = new Proxy(client, {
+		get(target, prop, receiver) {
+			if (prop in target || typeof prop !== 'string') {
+				return Reflect.get(target, prop, receiver)
+			}
+			if (prop in apiConfig.endpoints) {
+				return (input?: RequestInput<T[keyof T]>) =>
+					invokeEndpoint(
+						prop as keyof T,
+						input ?? ({} as RequestInput<T[keyof T]>)
+					)
+			}
+			if (prop in actions) {
+				return (first?: unknown, second?: ActionInvokeOptions) =>
+					dispatchAction(prop, first, second)
+			}
+			return undefined
+		}
+	})
+
+	const rawActions = apiConfig.actions
+	if (typeof rawActions === 'function') {
+		actions = (
+			rawActions as (
+				helpers: ActionsFactoryHelpers<T, A>
+			) => Record<string, AnyApiAction>
+		)({
+			api: proxy,
+			defineAction: makeDefineAction<ApiClient<T, A>>()
+		}) as Record<string, AnyApiAction>
+	} else if (rawActions) {
+		actions = rawActions as Record<string, AnyApiAction>
+	}
+
+	const collisions = Object.keys(actions).filter(
+		(key) => key in apiConfig.endpoints
+	)
+	if (collisions.length > 0) {
+		throw new ConfigError(
+			`Action name(s) collide with endpoint name(s): ${collisions.join(', ')}`,
+			{
+				endpoint: collisions[0]!,
+				method: 'GET',
+				url: '',
+				attempt: 0,
+				maxRetries: 0,
+				elapsedMs: 0
+			}
+		)
+	}
+
+	return proxy
+}
+
+export const createApiClient: CreateApiClientFn = ((apiConfig: unknown) =>
+	createApiClientImpl(
+		apiConfig as ApiClientConfig<
+			Record<string, ApiEndpoint>,
+			Record<string, ApiAction>
+		>
+	)) as CreateApiClientFn

package/src/api-wrapper/error-reporting.ts

@@ -0,0 +1,31 @@
+import type { ApiError } from './errors'
+import type { ApiClientConfig } from './types'
+import type { ApiErrorContext } from './shared'
+import { defaultRedactContext } from './redaction'
+
+type ErrorHookConfig = Pick<
+	ApiClientConfig<never, never>,
+	'logger' | 'onError' | 'redact'
+>
+
+export function applyErrorContextRedaction(
+	ctx: ApiErrorContext,
+	config: Pick<ApiClientConfig<never, never>, 'redact'>
+): ApiErrorContext {
+	const base = defaultRedactContext(ctx)
+	return config.redact ? config.redact(base) : base
+}
+
+export async function reportApiError(
+	err: ApiError,
+	config: ErrorHookConfig
+): Promise<ApiError> {
+	err.context = applyErrorContextRedaction(err.context, config)
+	try {
+		await config.onError?.(err)
+	} catch {
+		// ignore hook errors
+	}
+	config.logger?.error?.(err)
+	return err
+}