hanzio 1.1.0 → 2.0.0

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

@@ -8,6 +8,7 @@ import type {
 	ApiClientConfigNoActions,
 	ApiClientConfigWithActions,
 	ApiEndpoint,
+	ApiMiddlewareContext,
 	ApiWrapperResponse,
 	RequestInput
 } from './types'
@@ -15,13 +16,21 @@ import type { PathParams, QueryParams } from './shared'
 import type { ApiErrorContext } from './shared'
 import {
 	buildHeaders,
+	buildPathParams,
 	buildQueryParams,
 	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,
@@ -32,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(
@@ -51,6 +62,39 @@ function isActionInvokeOptionsOnly(
 	)
 }
 
+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>
@@ -101,38 +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 finalUrl: string
-		let fullUrl: string
-		try {
-			const built = buildUrl(
-				endpoint,
-				rawInput.reqParams,
-				rawInput.reqQuery,
-				apiConfig.baseApiUrls,
-				apiConfig.defaultBaseApiUrl,
-				input.url,
-				(msg) => new ConfigError(msg, ctx())
-			)
-			finalUrl = built.finalUrl
-			fullUrl = built.fullUrl
-		} catch (e) {
-			if (e instanceof ApiError) throw await reportApiError(e, apiConfig)
-			throw e
-		}
-
-		baseContext.url = fullUrl
-
-		let queryParams: Record<string, string>
+		let pathParams: PathParams | undefined
+		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) {
@@ -140,11 +171,32 @@ function createApiClientImpl<
 			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 execute = async (): Promise<
+			ApiWrapperResponse<z.infer<T[K]['resSchema']>>
+		> => {
+			if (apiConfig.onRequest) {
 				const result = await apiConfig.onRequest({
 					endpoint: endpointName,
 					method: endpoint.method,
@@ -155,31 +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,
-			url: finalUrl,
-			queryParams,
-			body,
-			headers,
-			doNotEncodeQueryParams: endpoint.doNotEncodeQueryParams,
-			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,
-				validateFn: (response) =>
-					validateAndTransformResponse(endpoint, response, ctx),
+				retryDelay:
+					apiConfig.retryDelayMs ??
+					((attempt) =>
+						exponentialBackoff(attempt + 1, {
+							baseMs: 300,
+							maxMs: apiConfig.maxRetryDelayMs
+						})),
+				maxRetryDelayMs: apiConfig.maxRetryDelayMs,
+				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,
@@ -191,23 +250,76 @@ function createApiClientImpl<
 				onRetry: apiConfig.onRetry
 			})
 
-			const responseTimeMs = elapsed()
-			const responseSizeMb = calculateSizeInMb(result.validatedData)
-			const requestBodySizeMb = calculateSizeInMb(config.body)
-
 			return {
-				data: result.validatedData as z.infer<T[K]['resSchema']>,
-				requestBodySizeMb,
-				responseSizeMb,
-				responseTimeMs,
+				data: result.validatedData.data as z.infer<T[K]['resSchema']>,
+				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(
@@ -237,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,
@@ -264,26 +388,28 @@ function createApiClientImpl<
 		}
 	}
 
+	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) {
-			const action = actions[key]!
-			if (action.noRuntimeInput) {
-				if (input === undefined || input === null) {
-					return invokeAction(key, undefined, options ?? {})
-				}
-				if (options !== undefined) {
-					return invokeAction(key, undefined, options)
-				}
-				if (isActionInvokeOptionsOnly(input)) {
-					return invokeAction(key, undefined, input)
-				}
-				return invokeAction(key, undefined, {})
-			}
-			return invokeAction(key, input, options)
+			return dispatchAction(key, input, options)
 		}
 		return invokeEndpoint(
 			key as keyof T,
@@ -291,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') {
@@ -305,26 +455,8 @@ function createApiClientImpl<
 					)
 			}
 			if (prop in actions) {
-				const action = actions[prop]!
-				if (action.noRuntimeInput) {
-					return (
-						first?: unknown,
-						second?: ActionInvokeOptions
-					): Promise<unknown> => {
-						if (first === undefined || first === null) {
-							return invokeAction(prop, undefined, second ?? {})
-						}
-						if (second !== undefined) {
-							return invokeAction(prop, undefined, second)
-						}
-						if (isActionInvokeOptionsOnly(first)) {
-							return invokeAction(prop, undefined, first)
-						}
-						return invokeAction(prop, undefined, {})
-					}
-				}
-				return (input?: unknown, opt?: ActionInvokeOptions) =>
-					invokeAction(prop, input, opt)
+				return (first?: unknown, second?: ActionInvokeOptions) =>
+					dispatchAction(prop, first, second)
 			}
 			return undefined
 		}
@@ -344,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
 }