hanzio 1.2.0 → 2.1.0

package/src/api-wrapper/builders.ts

@@ -1,4 +1,5 @@
 import { ZodError } from 'zod'
+import { buildQueryString } from '../url'
 import { type ConfigError, RequestValidationError } from './errors'
 import { normalizeHeaders } from './headers'
 import type {
@@ -12,7 +13,7 @@ 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
@@ -20,18 +21,6 @@ export type BuildUrlOptions = {
 	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,
@@ -46,7 +35,7 @@ export function buildUrl(options: BuildUrlOptions) {
 
 	let finalUrl: string
 	if (url) {
-		finalUrl = replacePathParams(url, params, configError)
+		finalUrl = replaceUrlPathParams(url, params, configError)
 	} else {
 		const defaultBaseUrl = defaultBaseApiUrl ?? Object.keys(baseApiUrls)[0]
 		if (!defaultBaseUrl) {
@@ -66,10 +55,15 @@ export function buildUrl(options: BuildUrlOptions) {
 				? endpoint.path(baseUrl)
 				: endpoint.path
 		// Substitute endpoint parameters without interpreting a port or IPv6 host as one.
-		finalUrl = `${baseUrl}${replacePathParams(path, params, configError)}`
+		finalUrl = joinUrlPath(
+			baseUrl,
+			replacePathParams(path, params, configError)
+		)
 	}
 
-	const queryString = formatQueryString(queryParams, doNotEncodeQueryParams)
+	const queryString = buildQueryString(queryParams, {
+		encode: !doNotEncodeQueryParams
+	})
 	return {
 		finalUrl,
 		fullUrl: queryString ? `${finalUrl}?${queryString}` : finalUrl
@@ -97,7 +91,7 @@ export function buildQueryParams(
 	endpoint: ApiEndpoint,
 	query: QueryParams | undefined,
 	ctx: (over?: Partial<ApiErrorContext>) => ApiErrorContext
-): Record<string, string> {
+): QueryParams {
 	const defaultParams = endpoint.reqDefaultQueryParams ?? {}
 	let parsedQuery: QueryParams
 	if (endpoint.reqQuerySchema) {
@@ -112,13 +106,7 @@ export function buildQueryParams(
 	} else {
 		parsedQuery = query ?? {}
 	}
-	const merged = { ...defaultParams, ...parsedQuery }
-
-	return Object.fromEntries(
-		Object.entries(merged)
-			.filter(([, value]) => value !== undefined)
-			.map(([key, value]) => [key, String(value)])
-	)
+	return { ...defaultParams, ...parsedQuery }
 }
 
 export function buildRequestBody(
@@ -185,12 +173,31 @@ export function buildHeaders(
 	})
 }
 
+/** Joins with exactly one `/`; empty paths and query-only paths are appended as-is. */
+export function joinUrlPath(base: string, path: string): string {
+	if (!path || path.startsWith('?')) return `${base}${path}`
+	return `${base.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`
+}
+
+/** Substitutes `:params` in the path of a full URL only, so ports are left alone. */
+function replaceUrlPathParams(
+	url: string,
+	params: PathParams | undefined,
+	configError: (msg: string) => ConfigError
+): string {
+	const origin = url.match(/^[a-z][a-z\d+.-]*:\/\/[^/?#]*/i)?.[0] ?? ''
+	const rest = url.slice(origin.length)
+	const suffixIndex = rest.search(/[?#]/)
+	const path = suffixIndex === -1 ? rest : rest.slice(0, suffixIndex)
+	return `${origin}${replacePathParams(path, params, configError)}${rest.slice(path.length)}`
+}
+
 export function replacePathParams(
 	path: string,
 	params: PathParams | undefined,
 	configError: (msg: string) => ConfigError
 ): string {
-	return path.replace(/:(\w+)/g, (_, key: string) => {
+	return path.replace(/:([A-Za-z_]\w*)/g, (_, key: string) => {
 		const value = params?.[key]
 		if (value === undefined) {
 			throw configError(`Missing required path parameter: ${key}`)

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

@@ -8,6 +8,7 @@ import type {
 	ApiClientConfigNoActions,
 	ApiClientConfigWithActions,
 	ApiEndpoint,
+	ApiMiddlewareContext,
 	ApiWrapperResponse,
 	RequestInput
 } from './types'
@@ -20,9 +21,16 @@ import {
 	buildRequestBody,
 	buildUrl
 } from './builders'
+import { err, exponentialBackoff, ok } from '../promise'
 import { createActionCache, makeDefineAction } from './actions-impl'
 import { reportApiError } from './error-reporting'
-import { ActionError, ApiError, ConfigError } from './errors'
+import {
+	ActionError,
+	ApiError,
+	ApiResponseError,
+	ConfigError,
+	RequestValidationError
+} from './errors'
 import { calculateSizeInMb } from './size'
 import {
 	defaultShouldRetry,
@@ -33,13 +41,15 @@ import {
 
 type AnyApiAction = ApiAction<unknown, unknown>
 
+// The actions overload comes first: TypeScript fixes a context-sensitive
+// `actions` factory's parameter types on the first overload it tries.
 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>>
 }
 
 function isActionInvokeOptionsOnly(
@@ -135,19 +145,25 @@ function createApiClientImpl<
 		}
 
 		baseContext.method = endpoint.method
+		// Until the full URL is built, errors (e.g. input validation) show the path template.
+		if (typeof endpoint.path === 'string') baseContext.url = endpoint.path
 
 		let pathParams: PathParams | undefined
-		let queryParams: Record<string, string>
+		let queryParams: QueryParams
 		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)
+			const defaultHeaders =
+				typeof apiConfig.defaultHeaders === 'function'
+					? await apiConfig.defaultHeaders()
+					: apiConfig.defaultHeaders
 			headers = buildHeaders(
 				endpoint,
 				rawInput.reqHeaders,
-				apiConfig.defaultHeaders ?? {},
+				defaultHeaders ?? {},
 				ctx
 			)
 		} catch (e) {
@@ -177,8 +193,10 @@ function createApiClientImpl<
 		baseContext.requestHeaders = headers
 		baseContext.requestBody = body
 
-		if (apiConfig.onRequest) {
-			try {
+		const execute = async (): Promise<
+			ApiWrapperResponse<z.infer<T[K]['resSchema']>>
+		> => {
+			if (apiConfig.onRequest) {
 				const result = await apiConfig.onRequest({
 					endpoint: endpointName,
 					method: endpoint.method,
@@ -189,32 +207,38 @@ function createApiClientImpl<
 				})
 				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
-		}
+			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,
+				retryDelay:
+					apiConfig.retryDelayMs ??
+					((attempt) =>
+						exponentialBackoff(attempt + 1, {
+							baseMs: 300,
+							maxMs: apiConfig.maxRetryDelayMs
+						})),
 				maxRetryDelayMs: apiConfig.maxRetryDelayMs,
-				validateFn: (response, attempt) =>
-					validateAndTransformResponse(endpoint, response, (over) =>
-						ctx({ attempt, ...over })
-					),
+				validateFn: async (response, attempt) => {
+					const validated = await validateAndTransformResponse(
+						endpoint,
+						response,
+						(over) => ctx({ attempt, ...over })
+					)
+					await runCheckResponse(validated.data, response.status, attempt)
+					return validated
+				},
 				shouldRetry: apiConfig.shouldRetry ?? defaultShouldRetry,
 				logger: apiConfig.logger,
 				ctx,
@@ -226,24 +250,76 @@ function createApiClientImpl<
 				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,
+				requestBodySizeMb: calculateSizeInMb(config.body),
+				responseSizeMb: result.validatedData.responseSizeBytes / (1024 * 1024),
+				responseTimeMs: elapsed(),
 				httpStatus: result.httpStatus,
 				retryCount: result.retryCount
 			}
-		} catch (error) {
-			if (error instanceof ApiError)
-				throw await reportApiError(error, apiConfig)
-			throw error
 		}
+
+		const runCheckResponse = async (
+			data: unknown,
+			httpStatus: number,
+			attempt: number
+		) => {
+			if (!apiConfig.checkResponse) return
+			try {
+				await apiConfig.checkResponse(data, {
+					endpoint: endpointName,
+					method: endpoint.method,
+					url: fullUrl,
+					httpStatus,
+					attempt,
+					meta: input.meta
+				})
+			} catch (error) {
+				if (error instanceof ApiError) throw error
+				throw new ApiResponseError(
+					error instanceof Error ? error.message : String(error),
+					data,
+					ctx({ attempt }),
+					error
+				)
+			}
+		}
+
+		// Innermost step: errors are redacted and passed to onError before any
+		// middleware sees them.
+		const run = async () => {
+			try {
+				return await execute()
+			} catch (error) {
+				if (error instanceof ApiError) {
+					throw await reportApiError(error, apiConfig)
+				}
+				throw error
+			}
+		}
+
+		const middleware = apiConfig.use ?? []
+		if (middleware.length === 0) return run()
+
+		const middlewareContext: ApiMiddlewareContext = {
+			client: apiConfig.name,
+			endpoint: String(endpointKey),
+			method: endpoint.method,
+			url: fullUrl,
+			headers,
+			meta: input.meta
+		}
+		const dispatch = (
+			index: number
+		): Promise<ApiWrapperResponse<z.infer<T[K]['resSchema']>>> => {
+			const current = middleware[index]
+			if (!current) return run()
+			return current(middlewareContext, () => dispatch(index + 1)) as Promise<
+				ApiWrapperResponse<z.infer<T[K]['resSchema']>>
+			>
+		}
+		return dispatch(0)
 	}
 
 	async function invokeAction(
@@ -273,9 +349,21 @@ function createApiClientImpl<
 
 		apiConfig.logger?.debug?.('Action start', { action: actionName })
 
+		let parsedInput = inputForHandler
+		if (action.input) {
+			const parsed = await action.input.safeParseAsync(rawInput)
+			if (!parsed.success) {
+				throw await reportApiError(
+					new RequestValidationError(parsed.error, 'input', rawInput, ctx()),
+					apiConfig
+				)
+			}
+			parsedInput = parsed.data
+		}
+
 		try {
 			const result = await action.handler({
-				input: inputForHandler,
+				input: parsedInput,
 				api: proxy,
 				signal: options.signal,
 				meta: options.meta,
@@ -329,7 +417,31 @@ function createApiClientImpl<
 		)
 	}) as unknown as ApiClient<T, A>['request']
 
-	const client = { request, cache } as ApiClient<T, A>
+	// Resolves to `Result` instead of throwing ApiErrors; other errors still throw.
+	const safe = new Proxy(
+		{},
+		{
+			get(_target, prop) {
+				if (typeof prop !== 'string') return undefined
+				if (!(prop in apiConfig.endpoints) && !(prop in actions)) {
+					return undefined
+				}
+				return async (...args: unknown[]) => {
+					try {
+						const method = Reflect.get(proxy, prop) as (
+							...a: unknown[]
+						) => Promise<unknown>
+						return ok(await method(...args))
+					} catch (error) {
+						if (error instanceof ApiError) return err(error)
+						throw error
+					}
+				}
+			}
+		}
+	)
+
+	const client = { request, cache, safe } as unknown as ApiClient<T, A>
 	const proxy: ApiClient<T, A> = new Proxy(client, {
 		get(target, prop, receiver) {
 			if (prop in target || typeof prop !== 'string') {
@@ -364,6 +476,24 @@ function createApiClientImpl<
 		actions = rawActions as Record<string, AnyApiAction>
 	}
 
+	const reserved = [
+		...Object.keys(apiConfig.endpoints),
+		...Object.keys(actions)
+	].filter((key) => key in client)
+	if (reserved.length > 0) {
+		throw new ConfigError(
+			`Endpoint/action name(s) are reserved by the client: ${reserved.join(', ')}`,
+			{
+				endpoint: reserved[0]!,
+				method: 'GET',
+				url: '',
+				attempt: 0,
+				maxRetries: 0,
+				elapsedMs: 0
+			}
+		)
+	}
+
 	const collisions = Object.keys(actions).filter(
 		(key) => key in apiConfig.endpoints
 	)

package/src/api-wrapper/describe.ts

@@ -0,0 +1,157 @@
+import {
+	ActionError,
+	type ApiError,
+	type ApiErrorCategory,
+	ApiResponseError,
+	HttpResponseError,
+	RequestTimeoutError,
+	RequestValidationError,
+	ResponseValidationError
+} from './errors'
+import { previewValue, renderIssueSummary } from './zod-issues'
+
+const BODY_PREVIEW = 500
+
+const schemaByTarget = {
+	body: 'reqBodySchema',
+	query: 'reqQuerySchema',
+	params: 'reqParamsSchema',
+	headers: 'reqHeadersSchema',
+	input: 'the action input schema'
+} as const
+
+function headline(error: ApiError): string {
+	if (error instanceof HttpResponseError) {
+		const status = `HTTP ${error.status}`
+		if (error.status >= 500) {
+			return `server error (${status}): the API failed while handling the request`
+		}
+		if (error.status === 401 || error.status === 403) {
+			return `request rejected (${status}): check credentials and permissions`
+		}
+		if (error.status === 404) {
+			return `request rejected (${status}): check the path and the IDs in it`
+		}
+		if (error.status === 429) return `rate limited (${status})`
+		return `request rejected (${status}): check params, query and body`
+	}
+	if (error instanceof RequestValidationError) {
+		return `input validation failed: the caller's ${error.target} doesn't match ${schemaByTarget[error.target]} (nothing was sent)`
+	}
+	if (error instanceof ResponseValidationError) {
+		return error.invalidJson
+			? 'output validation failed: the response body is not valid JSON'
+			: "output validation failed: the response doesn't match resSchema"
+	}
+	if (error instanceof ApiResponseError) {
+		return `response rejected by checkResponse: ${error.message}`
+	}
+	if (error instanceof RequestTimeoutError) {
+		return `timed out after ${error.timeoutMs}ms`
+	}
+	const labels: Partial<Record<ApiErrorCategory, string>> = {
+		network: `network error: couldn't reach the API (${error.message})`,
+		aborted: 'aborted by the caller',
+		config: `configuration error: ${error.message}`,
+		action: `action failed: ${error.message}`
+	}
+	return labels[error.category] ?? error.message
+}
+
+function details(error: ApiError): string[] {
+	if (error instanceof HttpResponseError) {
+		const body =
+			error.bodyJson === undefined
+				? error.body
+				: previewValue(error.bodyJson, BODY_PREVIEW)
+		return body
+			? [
+					`  response: ${body.length > BODY_PREVIEW ? `${body.slice(0, BODY_PREVIEW)}…` : body}`
+				]
+			: []
+	}
+	if (
+		error instanceof ResponseValidationError ||
+		error instanceof RequestValidationError
+	) {
+		const lines = [renderIssueSummary(error.issues)]
+		if (error instanceof ResponseValidationError && !error.invalidJson) {
+			lines.push(
+				'  fix: update resSchema (or resFormatter), or mark changed fields optional'
+			)
+		}
+		return lines
+	}
+	if (error instanceof ApiResponseError) {
+		return [`  response: ${previewValue(error.data, BODY_PREVIEW)}`]
+	}
+	if (error instanceof ActionError && error.cause instanceof Error) {
+		return error.cause.stack ? [`  cause: ${error.cause.stack}`] : []
+	}
+	return []
+}
+
+/**
+ * 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 function describeApiError(error: ApiError): string {
+	const { context } = error
+	const sent =
+		error.category !== 'input_validation' && error.category !== 'config'
+	const meta = [
+		context.url ? `${context.method} ${context.url}` : context.method,
+		...(sent
+			? [`attempt ${context.attempt + 1}/${context.maxRetries + 1}`]
+			: []),
+		`${context.elapsedMs}ms`
+	]
+	if (error instanceof HttpResponseError && error.requestId) {
+		meta.push(`request id ${error.requestId}`)
+	}
+	return [
+		`✗ ${context.endpoint} failed: ${headline(error)}`,
+		`  ${meta.join(' · ')}`,
+		...details(error)
+	].join('\n')
+}
+
+/** Flat, primitive attributes for structured loggers and log processors. */
+export function apiErrorLogAttributes(
+	error: ApiError
+): Record<string, string | number | boolean> {
+	const { context } = error
+	const attributes: Record<string, string | number | boolean> = {
+		errorName: error.name,
+		category: error.category,
+		endpoint: context.endpoint,
+		method: context.method,
+		url: context.url,
+		attempt: context.attempt,
+		maxRetries: context.maxRetries,
+		elapsedMs: context.elapsedMs
+	}
+	if (error instanceof HttpResponseError) {
+		attributes.status = error.status
+		if (error.requestId) attributes.requestId = error.requestId
+	}
+	if (
+		error instanceof ResponseValidationError ||
+		error instanceof RequestValidationError
+	) {
+		attributes.issueCount = error.issues.length
+		attributes.issues = error.validationIssues
+	}
+	if (error instanceof RequestValidationError) attributes.target = error.target
+	if (error instanceof RequestTimeoutError)
+		attributes.timeoutMs = error.timeoutMs
+	return attributes
+}

package/src/api-wrapper/endpoint.ts

@@ -0,0 +1,26 @@
+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 function defineEndpoint<const TEndpoint extends ApiEndpoint>(
+	endpoint: TEndpoint & {
+		resFormatter?: (
+			data: unknown,
+			headers: Record<string, string>
+		) => z.input<TEndpoint['resSchema']>
+	}
+): TEndpoint {
+	return endpoint
+}

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

@@ -1,6 +1,7 @@
 import type { ApiError } from './errors'
 import type { ApiClientConfig } from './types'
 import type { ApiErrorContext } from './shared'
+import { apiErrorLogAttributes, describeApiError } from './describe'
 import { defaultRedactContext } from './redaction'
 
 type ErrorHookConfig = Pick<
@@ -20,12 +21,17 @@ export async function reportApiError(
 	err: ApiError,
 	config: ErrorHookConfig
 ): Promise<ApiError> {
+	const rawUrl = err.context.url
 	err.context = applyErrorContextRedaction(err.context, config)
+	// Messages were built from the raw URL; keep redacted query values out of them.
+	if (rawUrl && rawUrl !== err.context.url) {
+		err.message = err.message.split(rawUrl).join(err.context.url)
+	}
 	try {
 		await config.onError?.(err)
 	} catch {
 		// ignore hook errors
 	}
-	config.logger?.error?.(err)
+	config.logger?.error?.(describeApiError(err), apiErrorLogAttributes(err))
 	return err
 }