hanzio 1.2.0 → 2.0.0

package/src/api-wrapper/errors.ts

@@ -11,10 +11,38 @@ import {
 
 const MAX_BODY_PREVIEW = 500
 
+/**
+ * Where a request failed, for logs and alerts:
+ * - `server_error`: the API returned 5xx
+ * - `client_error`: the API rejected the request (4xx: auth, params, body)
+ * - `input_validation`: the caller's data failed a request schema; nothing was sent
+ * - `output_validation`: the response wasn't JSON or didn't match `resSchema`
+ * - `response_rejected`: `checkResponse` rejected a valid response
+ * - `network` / `timeout` / `aborted`: the request didn't complete
+ * - `config`: the client or call is misconfigured
+ * - `action`: a composite action handler threw
+ */
+export type ApiErrorCategory =
+	| 'server_error'
+	| 'client_error'
+	| 'input_validation'
+	| 'output_validation'
+	| 'response_rejected'
+	| 'network'
+	| 'timeout'
+	| 'aborted'
+	| 'config'
+	| 'action'
+	| 'unknown'
+
 export class ApiError extends Error {
 	public context: ApiErrorContext
 	public override cause?: unknown
 
+	get category(): ApiErrorCategory {
+		return 'unknown'
+	}
+
 	constructor(
 		message: string,
 		context: ApiErrorContext,
@@ -29,6 +57,7 @@ export class ApiError extends Error {
 	toJSON(): Record<string, unknown> {
 		return {
 			name: this.name,
+			category: this.category,
 			message: this.message,
 			context: this.context
 		}
@@ -66,6 +95,10 @@ export class HttpResponseError extends ApiError {
 		this.bodyJson = tryParseJson(body)
 	}
 
+	override get category(): ApiErrorCategory {
+		return this.status >= 500 ? 'server_error' : 'client_error'
+	}
+
 	override toJSON(): Record<string, unknown> {
 		return {
 			...super.toJSON(),
@@ -83,11 +116,14 @@ export class ResponseValidationError extends ApiError {
 	public readonly rawResponse: unknown
 	public readonly issues: FormattedZodIssue[]
 	public readonly validationIssues: string
+	/** True when the body wasn't valid JSON (rather than failing `resSchema`). */
+	public readonly invalidJson: boolean
 
 	constructor(
 		zodError: ZodError,
 		rawResponse: unknown,
-		context: ApiErrorContext
+		context: ApiErrorContext,
+		options: { invalidJson?: boolean } = {}
 	) {
 		const issues = formatZodIssues(zodError, rawResponse)
 		const summary = renderIssueSummary(issues)
@@ -97,6 +133,7 @@ export class ResponseValidationError extends ApiError {
 			{ cause: zodError }
 		)
 		this.name = 'ResponseValidationError'
+		this.invalidJson = options.invalidJson ?? false
 		this.zodError = zodError
 		this.rawResponse = rawResponse
 		this.issues = issues
@@ -105,9 +142,14 @@ export class ResponseValidationError extends ApiError {
 			.join('; ')
 	}
 
+	override get category(): ApiErrorCategory {
+		return 'output_validation'
+	}
+
 	override toJSON(): Record<string, unknown> {
 		return {
 			...super.toJSON(),
+			invalidJson: this.invalidJson,
 			issues: this.issues,
 			validationIssues: this.validationIssues,
 			rawResponsePreview: previewValue(this.rawResponse, 1000)
@@ -115,7 +157,13 @@ export class ResponseValidationError extends ApiError {
 	}
 }
 
-export type RequestValidationTarget = 'body' | 'query' | 'params' | 'headers'
+/** Which request schema failed; `input` is an action's input schema. */
+export type RequestValidationTarget =
+	| 'body'
+	| 'query'
+	| 'params'
+	| 'headers'
+	| 'input'
 
 export class RequestValidationError extends ApiError {
 	public readonly zodError: ZodError
@@ -147,6 +195,10 @@ export class RequestValidationError extends ApiError {
 			.join('; ')
 	}
 
+	override get category(): ApiErrorCategory {
+		return 'input_validation'
+	}
+
 	override toJSON(): Record<string, unknown> {
 		return {
 			...super.toJSON(),
@@ -168,6 +220,10 @@ export class RequestTimeoutError extends ApiError {
 		this.name = 'RequestTimeoutError'
 		this.timeoutMs = timeoutMs
 	}
+
+	override get category(): ApiErrorCategory {
+		return 'timeout'
+	}
 }
 
 export class NetworkError extends ApiError {
@@ -175,6 +231,10 @@ export class NetworkError extends ApiError {
 		super(message, context, { cause })
 		this.name = 'NetworkError'
 	}
+
+	override get category(): ApiErrorCategory {
+		return 'network'
+	}
 }
 
 export class RequestAbortedError extends ApiError {
@@ -184,6 +244,10 @@ export class RequestAbortedError extends ApiError {
 		})
 		this.name = 'RequestAbortedError'
 	}
+
+	override get category(): ApiErrorCategory {
+		return 'aborted'
+	}
 }
 
 export class ConfigError extends ApiError {
@@ -191,6 +255,40 @@ export class ConfigError extends ApiError {
 		super(message, context)
 		this.name = 'ConfigError'
 	}
+
+	override get category(): ApiErrorCategory {
+		return 'config'
+	}
+}
+
+/**
+ * Thrown when the client's `checkResponse` rejects a response that passed
+ * schema validation (e.g. HTTP 200 with `{ success: false }`).
+ */
+export class ApiResponseError extends ApiError {
+	public readonly data: unknown
+
+	constructor(
+		message: string,
+		data: unknown,
+		context: ApiErrorContext,
+		cause?: unknown
+	) {
+		super(message, context, { cause })
+		this.name = 'ApiResponseError'
+		this.data = data
+	}
+
+	override get category(): ApiErrorCategory {
+		return 'response_rejected'
+	}
+
+	override toJSON(): Record<string, unknown> {
+		return {
+			...super.toJSON(),
+			dataPreview: previewValue(this.data, 1000)
+		}
+	}
 }
 
 export class ActionError extends ApiError {
@@ -198,6 +296,10 @@ export class ActionError extends ApiError {
 		super(message, context, { cause })
 		this.name = 'ActionError'
 	}
+
+	override get category(): ApiErrorCategory {
+		return 'action'
+	}
 }
 
 export const isApiError = (e: unknown): e is ApiError => e instanceof ApiError
@@ -219,11 +321,14 @@ export const isConfigError = (e: unknown): e is ConfigError =>
 	e instanceof ConfigError
 export const isActionError = (e: unknown): e is ActionError =>
 	e instanceof ActionError
+export const isApiResponseError = (e: unknown): e is ApiResponseError =>
+	e instanceof ApiResponseError
 
 export function isNonRetryableApiError(error: unknown): boolean {
 	return (
 		error instanceof HttpResponseError ||
 		error instanceof ResponseValidationError ||
+		error instanceof ApiResponseError ||
 		error instanceof RequestValidationError ||
 		error instanceof ConfigError ||
 		error instanceof RequestAbortedError

package/src/api-wrapper/headers.ts

@@ -57,12 +57,17 @@ export function buildFetchBody(
 	if (body === undefined || body === null) return undefined
 	if (body instanceof FormData || body instanceof Blob) return body
 	if (hasJsonContentType(headers)) return JSON.stringify(body)
-	if (
-		typeof body === 'object' &&
-		(Object.getPrototypeOf(body) === Object.prototype ||
-			Object.getPrototypeOf(body) === null) &&
-		configError
-	) {
+	const isJsonLike =
+		Array.isArray(body) ||
+		(typeof body === 'object' &&
+			(Object.getPrototypeOf(body) === Object.prototype ||
+				Object.getPrototypeOf(body) === null))
+	// Objects and arrays default to JSON when no Content-Type was chosen.
+	if (isJsonLike && getHeader(headers, 'content-type') === undefined) {
+		headers['Content-Type'] = 'application/json'
+		return JSON.stringify(body)
+	}
+	if (isJsonLike && configError) {
 		throw configError(
 			'Request body is a plain object but Content-Type is not application/json'
 		)

package/src/api-wrapper/index.ts

@@ -3,3 +3,8 @@ export * from './types'
 export * from './errors'
 export { createApiClient } from './create-client'
 export { defineAction } from './actions-impl'
+export { type PaginateOptions, paginate } from './paginate'
+export { defaultShouldRetry } from './transport'
+export { apiErrorLogAttributes, describeApiError } from './describe'
+export * from './otel'
+export { defineEndpoint } from './endpoint'

package/src/api-wrapper/otel.ts

@@ -0,0 +1,139 @@
+import { ApiError, HttpResponseError } from './errors'
+import { redactUrl } from './redaction'
+import type { ApiMiddleware, ApiMiddlewareContext } from './types'
+
+// Structural subsets of @opentelemetry/api, so hanzio never imports it. The
+// app passes its own tracer (`trace.getTracer('app')`); a type test keeps
+// these compatible with the real `Tracer`.
+export type OtelAttributes = Record<
+	string,
+	string | number | boolean | undefined
+>
+
+export type OtelSpanLike = {
+	setAttributes(attributes: OtelAttributes): unknown
+	setStatus(status: { code: number; message?: string }): unknown
+	recordException(exception: Error | string): unknown
+	end(): void
+}
+
+export type OtelTracerLike = {
+	startActiveSpan<F extends (span: OtelSpanLike) => unknown>(
+		name: string,
+		options: { kind?: number; attributes?: OtelAttributes },
+		fn: F
+	): ReturnType<F>
+}
+
+export type OtelMiddlewareOptions = {
+	/** Default: `client.endpoint`, or the endpoint key when the client has no `name`. */
+	spanName?: (context: ApiMiddlewareContext) => string
+	/** Extra attributes set when the span starts. */
+	attributes?: (context: ApiMiddlewareContext) => OtelAttributes
+	/**
+	 * `url.full` keeps the query string with sensitive values redacted
+	 * (default). Set `false` to drop the query string entirely.
+	 */
+	includeQuery?: boolean
+	/**
+	 * Adds trace-context headers to the outgoing request, e.g.
+	 * `(headers) => propagation.inject(context.active(), headers)`. Runs inside
+	 * the active span. Not needed when fetch is already auto-instrumented.
+	 */
+	inject?: (headers: Record<string, string>) => void
+}
+
+// Frozen numeric values from the OpenTelemetry API.
+const SPAN_KIND_CLIENT = 2
+const SPAN_STATUS_ERROR = 2
+
+/**
+ * One CLIENT span per logical request (all retries, validation and
+ * `checkResponse`), with OpenTelemetry HTTP semantic-convention attributes.
+ * It's the active span, so auto-instrumented fetch attempts become children.
+ *
+ * @example
+ * import { trace } from '@opentelemetry/api'
+ * createApiClient({ ...config, use: [otelMiddleware(trace.getTracer('app'))] })
+ */
+export function otelMiddleware(
+	tracer: OtelTracerLike,
+	options: OtelMiddlewareOptions = {}
+): ApiMiddleware {
+	const { spanName, attributes, includeQuery = true, inject } = options
+
+	return (context, next) => {
+		const url = includeQuery
+			? redactUrl(context.url)
+			: context.url.split(/[?#]/, 1)[0]!
+		const name =
+			spanName?.(context) ??
+			(context.client
+				? `${context.client}.${context.endpoint}`
+				: context.endpoint)
+
+		return tracer.startActiveSpan(
+			name,
+			{
+				kind: SPAN_KIND_CLIENT,
+				attributes: {
+					'http.request.method': context.method,
+					'url.full': url,
+					'server.address': hostOf(context.url),
+					'api.client': context.client,
+					'api.endpoint': context.endpoint,
+					...attributes?.(context)
+				}
+			},
+			async (span) => {
+				inject?.(context.headers)
+				try {
+					const result = await next()
+					span.setAttributes({
+						'http.response.status_code': result.httpStatus,
+						'http.request.resend_count': result.retryCount || undefined,
+						'http.response.body.size': Math.round(
+							result.responseSizeMb * 1024 * 1024
+						)
+					})
+					return result
+				} catch (error) {
+					recordFailure(span, error)
+					throw error
+				} finally {
+					span.end()
+				}
+			}
+		)
+	}
+}
+
+function recordFailure(span: OtelSpanLike, error: unknown): void {
+	if (error instanceof ApiError) {
+		const isHttp = error instanceof HttpResponseError
+		span.setAttributes({
+			'error.type': isHttp ? String(error.status) : error.name,
+			'api.error.category': error.category,
+			'http.response.status_code': isHttp ? error.status : undefined,
+			'http.request.resend_count': error.context.attempt || undefined
+		})
+	} else {
+		span.setAttributes({
+			'error.type': error instanceof Error ? error.name : 'unknown'
+		})
+	}
+	span.recordException(error instanceof Error ? error : String(error))
+	span.setStatus({
+		code: SPAN_STATUS_ERROR,
+		message:
+			error instanceof Error ? error.message.split('\n', 1)[0] : String(error)
+	})
+}
+
+function hostOf(url: string): string | undefined {
+	try {
+		return new URL(url).hostname
+	} catch {
+		return undefined
+	}
+}

package/src/api-wrapper/paginate.ts

@@ -0,0 +1,28 @@
+export type PaginateOptions = {
+	/** Stop after this many pages (default: no limit). */
+	maxPages?: number
+	/** Checked before each page fetch; throws `signal.reason` when aborted. */
+	signal?: AbortSignal
+}
+
+/**
+ * Yields pages until `getNext` returns `null`/`undefined`. The first call to
+ * `fetchPage` gets `undefined` as cursor. Pages are fetched lazily, so
+ * breaking out of `for await` stops further requests.
+ */
+export async function* paginate<TPage, TCursor>(
+	fetchPage: (cursor: TCursor | undefined) => Promise<TPage>,
+	getNext: (page: TPage) => TCursor | null | undefined,
+	options: PaginateOptions = {}
+): AsyncGenerator<TPage, void, undefined> {
+	const { maxPages = Number.POSITIVE_INFINITY, signal } = options
+	let cursor: TCursor | undefined
+	for (let count = 0; count < maxPages; count++) {
+		signal?.throwIfAborted()
+		const page = await fetchPage(cursor)
+		yield page
+		const next = getNext(page)
+		if (next == null) return
+		cursor = next
+	}
+}

package/src/api-wrapper/redaction.ts

@@ -22,6 +22,18 @@ const SENSITIVE_BODY_KEYS = new Set([
 	'api_key'
 ])
 
+// Query strings also carry API keys and presigned-URL signatures.
+const SENSITIVE_QUERY_KEYS = new Set([
+	...SENSITIVE_BODY_KEYS,
+	'key',
+	'code',
+	'sig',
+	'signature',
+	'x-amz-signature',
+	'x-amz-credential',
+	'x-amz-security-token'
+])
+
 function redactHeaders(
 	headers: Record<string, string> | undefined
 ): Record<string, string> | undefined {
@@ -52,9 +64,39 @@ function redactBody(body: unknown): unknown {
 	return out
 }
 
+/** Replaces values of sensitive query parameters (`?api_key=…`) in a URL. */
+export function redactUrl(url: string): string {
+	const queryStart = url.indexOf('?')
+	if (queryStart === -1) return url
+	const hashStart = url.indexOf('#', queryStart)
+	const query = url.slice(
+		queryStart + 1,
+		hashStart === -1 ? undefined : hashStart
+	)
+	const redacted = query
+		.split('&')
+		.map((pair) => {
+			const [key = ''] = pair.split('=', 1)
+			return SENSITIVE_QUERY_KEYS.has(decodeKey(key).toLowerCase())
+				? `${key}=[REDACTED]`
+				: pair
+		})
+		.join('&')
+	return `${url.slice(0, queryStart + 1)}${redacted}${hashStart === -1 ? '' : url.slice(hashStart)}`
+}
+
+function decodeKey(key: string): string {
+	try {
+		return decodeURIComponent(key.replace(/\+/g, ' '))
+	} catch {
+		return key
+	}
+}
+
 export function defaultRedactContext(ctx: ApiErrorContext): ApiErrorContext {
 	return {
 		...ctx,
+		url: redactUrl(ctx.url),
 		requestHeaders: redactHeaders(ctx.requestHeaders),
 		requestBody: redactBody(ctx.requestBody),
 		meta: ctx.meta

package/src/api-wrapper/shared.ts

@@ -1,3 +1,5 @@
+import type { UrlQueryParams } from '../url'
+
 export type HttpMethod =
 	| 'GET'
 	| 'POST'
@@ -10,7 +12,24 @@ export type HttpMethod =
 export type RequestBodyFormat = 'json' | 'form-data'
 export type BaseApiUrl = string | (() => string)
 export type PathParams = Record<string, string | number>
-export type QueryParams = Record<string, string | number | boolean | undefined>
+/** Array values repeat the key (`a=1&a=2`); `null`/`undefined` are skipped. */
+export type QueryParams = UrlQueryParams
+
+/**
+ * Augment to type `meta` on requests, actions, hooks, middleware and errors:
+ *
+ * @example
+ * declare module 'hanzio/api-wrapper' {
+ *   interface ApiRequestMeta { traceId: string; tenantId?: string }
+ * }
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: augmentation target
+export interface ApiRequestMeta {}
+
+/** `ApiRequestMeta` once augmented, otherwise any record. */
+export type RequestMeta = keyof ApiRequestMeta extends never
+	? Record<string, unknown>
+	: ApiRequestMeta
 
 export type ApiErrorContext = {
 	endpoint: string
@@ -21,5 +40,5 @@ export type ApiErrorContext = {
 	elapsedMs: number
 	requestHeaders?: Record<string, string>
 	requestBody?: unknown
-	meta?: Record<string, unknown>
+	meta?: RequestMeta
 }

package/src/api-wrapper/testing.ts

@@ -0,0 +1,48 @@
+import type { FetchLike } from './types'
+
+export type MockFetch = FetchLike & {
+	/** Every request received, in order. Bodies are still readable. */
+	readonly calls: Request[]
+}
+
+/**
+ * A fetch stand-in for tests: pass it as the client's `fetch` option instead
+ * of replacing `globalThis.fetch`. Test-runner agnostic.
+ *
+ * @example
+ * const fetch = createMockFetch((request) =>
+ *   request.url.endsWith('/users/1')
+ *     ? jsonResponse({ id: 1 })
+ *     : jsonResponse({ error: 'not found' }, { status: 404 })
+ * )
+ * const api = createApiClient({ ...config, fetch })
+ */
+export function createMockFetch(
+	handler: (request: Request, callIndex: number) => Response | Promise<Response>
+): MockFetch {
+	const calls: Request[] = []
+	const mockFetch = async (
+		input: string | URL | Request,
+		init?: RequestInit
+	): Promise<Response> => {
+		const request: Request =
+			input instanceof Request
+				? new Request(input, init)
+				: new Request(input.toString(), init)
+		// Bun types clone() as the undici Request; it is the same runtime object.
+		calls.push(request.clone() as Request)
+		return handler(request, calls.length - 1)
+	}
+	return Object.assign(mockFetch, { calls })
+}
+
+/** A JSON `Response` with `content-type: application/json`. */
+export function jsonResponse(
+	body: unknown,
+	init: { status?: number; headers?: Record<string, string> } = {}
+): Response {
+	return new Response(JSON.stringify(body), {
+		status: init.status ?? 200,
+		headers: { 'content-type': 'application/json', ...init.headers }
+	})
+}