hanzio 1.0.9 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hanzio",
-  "version": "1.0.9",
+  "version": "1.1.0",
   "description": "A lightweight set of utility functions for TypeScript",
   "type": "module",
   "module": "./dist/src/index.js",
@@ -50,7 +50,7 @@
   },
   "scripts": {
     "build": "bun run build:js && bun run build:types",
-    "build:js": "bun build ./src/index.ts ./src/zod/index.ts ./src/api-wrapper/index.ts ./src/jwt/index.ts ./src/sitemap/index.ts ./src/p-queue/index.ts ./src/secrets/index.ts ./src/secrets/infisical.ts ./src/secrets/vite.ts --outdir ./dist --target node --packages external",
+    "build:js": "bun build ./src/index.ts ./src/zod/index.ts ./src/api-wrapper/index.ts ./src/jwt/index.ts ./src/sitemap/index.ts ./src/p-queue/index.ts ./src/secrets/index.ts ./src/secrets/infisical.ts ./src/secrets/loaders.ts ./src/secrets/vite.ts --outdir ./dist --target node --packages external",
     "build:types": "tsgo -p tsconfig.build.json",
     "prepublishOnly": "bun run build",
     "publish:patch": "npm version patch && npm publish",

package/src/api-wrapper/actions-impl.ts

@@ -0,0 +1,100 @@
+import type { ActionCache, DefineAction } from './types'
+
+type CacheEntry = {
+	value?: unknown
+	hasValue: boolean
+	expiresAt?: number
+	inflight?: Promise<unknown>
+}
+
+export function createActionCache(): ActionCache {
+	const store = new Map<string, CacheEntry>()
+
+	const isExpired = (entry: CacheEntry) =>
+		entry.expiresAt !== undefined && entry.expiresAt <= Date.now()
+
+	const cache = (async <T>(
+		key: string,
+		fn: () => Promise<T> | T,
+		options?: { ttlMs?: number }
+	): Promise<T> => {
+		const existing = store.get(key)
+		if (existing && !isExpired(existing)) {
+			if (existing.inflight) return existing.inflight as Promise<T>
+			if (existing.hasValue) return existing.value as T
+		}
+
+		const promise = (async () => fn())()
+		const entry: CacheEntry = {
+			hasValue: false,
+			inflight: promise,
+			expiresAt:
+				options?.ttlMs !== undefined ? Date.now() + options.ttlMs : undefined
+		}
+		store.set(key, entry)
+
+		try {
+			const value = await promise
+			entry.value = value
+			entry.hasValue = true
+			entry.inflight = undefined
+			return value
+		} catch (error) {
+			store.delete(key)
+			throw error
+		}
+	}) as ActionCache
+
+	cache.get = <T>(key: string): T | undefined => {
+		const entry = store.get(key)
+		if (!entry || !entry.hasValue) return undefined
+		if (isExpired(entry)) {
+			store.delete(key)
+			return undefined
+		}
+		return entry.value as T
+	}
+
+	cache.set = <T>(
+		key: string,
+		value: T,
+		options?: { ttlMs?: number }
+	): void => {
+		store.set(key, {
+			value,
+			hasValue: true,
+			expiresAt:
+				options?.ttlMs !== undefined ? Date.now() + options.ttlMs : undefined
+		})
+	}
+
+	cache.invalidate = (key: string): void => {
+		store.delete(key)
+	}
+
+	cache.clear = (): void => {
+		store.clear()
+	}
+
+	return cache
+}
+
+export function makeDefineAction<TApi>(): DefineAction<TApi> {
+	function defineAction(...args: unknown[]): unknown {
+		if (args.length === 0) {
+			return (def: { handler: unknown }) => ({
+				...def,
+				noRuntimeInput: false as const
+			})
+		}
+		const def = args[0] as { handler: unknown }
+		return {
+			...def,
+			noRuntimeInput: true as const
+		}
+	}
+	return defineAction as DefineAction<TApi>
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: top-level form keeps ctx.api as any
+export const defineAction: DefineAction<any> = makeDefineAction<any>()

package/src/api-wrapper/builders.ts

@@ -0,0 +1,175 @@
+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 function buildUrl(
+	endpoint: ApiEndpoint,
+	params: PathParams | undefined,
+	reqQuery: QueryParams | undefined,
+	baseApiUrls: Record<string, BaseApiUrl>,
+	defaultBaseApiUrl: string | undefined,
+	url: string | undefined,
+	configError: (msg: string) => ConfigError
+) {
+	if (url) {
+		const finalUrl = replacePathParams(url, params, configError)
+		const queryString = new URLSearchParams(
+			buildQueryParamsRaw(endpoint, reqQuery)
+		).toString()
+		return {
+			finalUrl,
+			fullUrl: queryString ? `${finalUrl}?${queryString}` : finalUrl
+		}
+	}
+
+	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
+	const finalUrl = replacePathParams(`${baseUrl}${path}`, params, configError)
+	const queryString = new URLSearchParams(
+		buildQueryParamsRaw(endpoint, reqQuery)
+	).toString()
+
+	return {
+		finalUrl,
+		fullUrl: queryString ? `${finalUrl}?${queryString}` : finalUrl
+	}
+}
+
+export function buildQueryParamsRaw(
+	endpoint: ApiEndpoint,
+	query: QueryParams | undefined
+): Record<string, string> {
+	const defaultParams = endpoint.reqDefaultQueryParams ?? {}
+	const merged = { ...defaultParams, ...(query ?? {}) }
+	return Object.fromEntries(
+		Object.entries(merged)
+			.filter(([, value]) => value !== undefined)
+			.map(([key, value]) => [key, String(value)])
+	)
+}
+
+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,373 @@
+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,
+	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 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 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 body: unknown
+		let headers: Record<string, string>
+		try {
+			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
+		}
+
+		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,
+			url: finalUrl,
+			queryParams,
+			body,
+			headers,
+			doNotEncodeQueryParams: endpoint.doNotEncodeQueryParams,
+			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),
+				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 = calculateSizeInMb(result.validatedData)
+			const requestBodySizeMb = calculateSizeInMb(config.body)
+
+			return {
+				data: result.validatedData 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)
+		}
+	}
+
+	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 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) {
+				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 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
+}