hanzio 1.1.0 → 1.2.0

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

@@ -15,6 +15,7 @@ import type { PathParams, QueryParams } from './shared'
 import type { ApiErrorContext } from './shared'
 import {
 	buildHeaders,
+	buildPathParams,
 	buildQueryParams,
 	buildRequestBody,
 	buildUrl
@@ -51,6 +52,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>
@@ -102,31 +136,12 @@ function createApiClientImpl<
 
 		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 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(
@@ -140,6 +155,25 @@ 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
 
@@ -163,11 +197,9 @@ function createApiClientImpl<
 
 		const config: RequestConfig = {
 			method: endpoint.method,
-			url: finalUrl,
-			queryParams,
+			fullUrl,
 			body,
 			headers,
-			doNotEncodeQueryParams: endpoint.doNotEncodeQueryParams,
 			timeoutMs: input.timeoutMs ?? apiConfig.timeoutMs,
 			fetchFn: input.fetch ?? apiConfig.fetch ?? fetch,
 			userSignal: input.signal
@@ -178,8 +210,11 @@ function createApiClientImpl<
 				config,
 				maxRetries,
 				retryDelay: apiConfig.retryDelayMs ?? 300,
-				validateFn: (response) =>
-					validateAndTransformResponse(endpoint, response, ctx),
+				maxRetryDelayMs: apiConfig.maxRetryDelayMs,
+				validateFn: (response, attempt) =>
+					validateAndTransformResponse(endpoint, response, (over) =>
+						ctx({ attempt, ...over })
+					),
 				shouldRetry: apiConfig.shouldRetry ?? defaultShouldRetry,
 				logger: apiConfig.logger,
 				ctx,
@@ -192,11 +227,12 @@ function createApiClientImpl<
 			})
 
 			const responseTimeMs = elapsed()
-			const responseSizeMb = calculateSizeInMb(result.validatedData)
+			const responseSizeMb =
+				result.validatedData.responseSizeBytes / (1024 * 1024)
 			const requestBodySizeMb = calculateSizeInMb(config.body)
 
 			return {
-				data: result.validatedData as z.infer<T[K]['resSchema']>,
+				data: result.validatedData.data as z.infer<T[K]['resSchema']>,
 				requestBodySizeMb,
 				responseSizeMb,
 				responseTimeMs,
@@ -264,26 +300,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,
@@ -305,26 +343,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
 		}

package/src/api-wrapper/errors.ts

@@ -219,3 +219,13 @@ export const isConfigError = (e: unknown): e is ConfigError =>
 	e instanceof ConfigError
 export const isActionError = (e: unknown): e is ActionError =>
 	e instanceof ActionError
+
+export function isNonRetryableApiError(error: unknown): boolean {
+	return (
+		error instanceof HttpResponseError ||
+		error instanceof ResponseValidationError ||
+		error instanceof RequestValidationError ||
+		error instanceof ConfigError ||
+		error instanceof RequestAbortedError
+	)
+}

package/src/api-wrapper/headers.ts

@@ -1,3 +1,5 @@
+import type { ConfigError } from './errors'
+
 const CANONICAL_HEADER_NAMES: Record<string, string> = {
 	'content-type': 'Content-Type',
 	authorization: 'Authorization',
@@ -49,11 +51,22 @@ export function hasJsonContentType(headers: Record<string, string>): boolean {
 
 export function buildFetchBody(
 	body: unknown,
-	headers: Record<string, string>
+	headers: Record<string, string>,
+	configError?: (msg: string) => ConfigError
 ): RequestInit['body'] {
 	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
+	) {
+		throw configError(
+			'Request body is a plain object but Content-Type is not application/json'
+		)
+	}
 	return body as RequestInit['body']
 }
 

package/src/api-wrapper/redaction.ts

@@ -17,6 +17,7 @@ const SENSITIVE_BODY_KEYS = new Set([
 	'refresh_token',
 	'secret',
 	'client_secret',
+	'clientsecret',
 	'apikey',
 	'api_key'
 ])

package/src/api-wrapper/transport.ts

@@ -9,10 +9,10 @@ import type { ApiErrorContext, HttpMethod } from './shared'
 import {
 	ConfigError,
 	HttpResponseError,
+	isNonRetryableApiError,
 	NetworkError,
 	RequestAbortedError,
 	RequestTimeoutError,
-	RequestValidationError,
 	ResponseValidationError
 } from './errors'
 import {
@@ -24,11 +24,9 @@ import { makeJsonParseZodError } from './zod-issues'
 
 export type RequestConfig = {
 	method: HttpMethod
-	url: string
-	queryParams: Record<string, string>
+	fullUrl: string
 	body: unknown
 	headers: Record<string, string>
-	doNotEncodeQueryParams?: boolean
 	timeoutMs?: number
 	fetchFn: typeof fetch
 	userSignal?: AbortSignal
@@ -53,13 +51,6 @@ export async function httpRequest(
 	config: RequestConfig,
 	ctx: (over?: Partial<ApiErrorContext>) => ApiErrorContext
 ): Promise<Response> {
-	const queryString = config.doNotEncodeQueryParams
-		? Object.entries(config.queryParams)
-				.map(([key, value]) => `${key}=${value}`)
-				.join('&')
-		: new URLSearchParams(config.queryParams).toString()
-	const fullUrl = queryString ? `${config.url}?${queryString}` : config.url
-
 	const timeoutController = new AbortController()
 	const timeout =
 		config.timeoutMs === undefined
@@ -69,10 +60,14 @@ export async function httpRequest(
 	const signal = mergeSignals(timeoutController.signal, config.userSignal)
 
 	try {
-		return await config.fetchFn(fullUrl, {
+		return await config.fetchFn(config.fullUrl, {
 			method: config.method,
 			headers: config.headers,
-			body: buildFetchBody(config.body, config.headers),
+			body: buildFetchBody(
+				config.body,
+				config.headers,
+				(msg) => new ConfigError(msg, ctx())
+			),
 			signal
 		})
 	} catch (error) {
@@ -85,6 +80,7 @@ export async function httpRequest(
 			}
 			throw new RequestAbortedError(ctx(), error)
 		}
+		if (error instanceof ConfigError) throw error
 		throw new NetworkError(
 			error instanceof Error ? error.message : String(error),
 			ctx(),
@@ -142,30 +138,30 @@ export function getRetryDelay(params: {
 	retryDelay: number | ((attempt: number) => number)
 	attempt: number
 	response?: Response
+	maxRetryDelayMs?: number
 }): number {
+	const maxDelay = params.maxRetryDelayMs ?? 30_000
 	const { retryDelay, attempt, response } = params
 	if (response && (response.status === 429 || response.status === 503)) {
 		const retryAfter = response.headers.get('retry-after')
 		if (retryAfter) {
 			const seconds = Number(retryAfter)
-			if (Number.isFinite(seconds)) return seconds * 1000
+			if (Number.isFinite(seconds)) {
+				return Math.min(Math.max(0, seconds * 1000), maxDelay)
+			}
 			const dateMs = Date.parse(retryAfter)
 			if (!Number.isNaN(dateMs)) {
-				return Math.max(0, dateMs - Date.now())
+				return Math.min(Math.max(0, dateMs - Date.now()), maxDelay)
 			}
 		}
 	}
-	if (typeof retryDelay === 'function') return retryDelay(attempt)
-	return retryDelay
+	const delayMs =
+		typeof retryDelay === 'function' ? retryDelay(attempt) : retryDelay
+	return Math.min(delayMs, maxDelay)
 }
 
 export function shouldAttemptRetryOnError(error: unknown): boolean {
-	if (error instanceof HttpResponseError) return false
-	if (error instanceof ResponseValidationError) return false
-	if (error instanceof RequestValidationError) return false
-	if (error instanceof ConfigError) return false
-	if (error instanceof RequestAbortedError) return false
-	return true
+	return !isNonRetryableApiError(error)
 }
 
 export function shouldAttemptRetryOnHttp(retryCtx: RetryContext): boolean {
@@ -178,7 +174,8 @@ type MakeRequestArgs<TValidated> = {
 	config: RequestConfig
 	maxRetries: number
 	retryDelay: number | ((attempt: number) => number)
-	validateFn: (response: Response) => Promise<TValidated>
+	maxRetryDelayMs?: number
+	validateFn: (response: Response, attempt: number) => Promise<TValidated>
 	shouldRetry: (context: RetryContext) => boolean
 	logger?: Pick<Console, 'debug'>
 	ctx: (over?: Partial<ApiErrorContext>) => ApiErrorContext
@@ -201,6 +198,7 @@ export async function makeRequestWithRetry<TValidated>(
 		config,
 		maxRetries,
 		retryDelay,
+		maxRetryDelayMs,
 		validateFn,
 		shouldRetry,
 		logger,
@@ -244,7 +242,8 @@ export async function makeRequestWithRetry<TValidated>(
 					const delayMs = getRetryDelay({
 						retryDelay,
 						attempt: retryCount,
-						response
+						response,
+						maxRetryDelayMs
 					})
 					await onRetry?.({
 						...retryCtx,
@@ -267,18 +266,12 @@ export async function makeRequestWithRetry<TValidated>(
 			}
 
 			return {
-				validatedData: await validateFn(response),
+				validatedData: await validateFn(response, retryCount),
 				retryCount,
 				httpStatus: response.status
 			}
 		} catch (error) {
-			if (
-				error instanceof HttpResponseError ||
-				error instanceof ResponseValidationError ||
-				error instanceof RequestValidationError ||
-				error instanceof ConfigError ||
-				error instanceof RequestAbortedError
-			) {
+			if (isNonRetryableApiError(error)) {
 				throw error
 			}
 
@@ -297,7 +290,8 @@ export async function makeRequestWithRetry<TValidated>(
 			const delayMs = getRetryDelay({
 				retryDelay,
 				attempt: retryCount,
-				response: undefined
+				response: undefined,
+				maxRetryDelayMs
 			})
 			await onRetry?.({
 				...retryCtx,
@@ -320,11 +314,12 @@ export async function validateAndTransformResponse<T extends z.ZodType>(
 	>,
 	response: Response,
 	ctx: (over?: Partial<ApiErrorContext>) => ApiErrorContext
-): Promise<z.infer<T>> {
+): Promise<{ data: z.infer<T>; responseSizeBytes: number }> {
 	const responseHeaders = getHeadersAsObject(response.headers)
+	const text = await response.text()
+	const responseSizeBytes = new TextEncoder().encode(text).length
 	let responseData: unknown
 	if (hasJsonContentType(responseHeaders)) {
-		const text = await response.text()
 		try {
 			responseData = text === '' ? undefined : JSON.parse(text)
 		} catch (error) {
@@ -335,13 +330,14 @@ export async function validateAndTransformResponse<T extends z.ZodType>(
 			)
 		}
 	} else {
-		responseData = await response.text()
+		responseData = text
 	}
 	const transformedData = endpoint.resFormatter
 		? endpoint.resFormatter(responseData, responseHeaders)
 		: responseData
 
-	return validateResponse(endpoint.resSchema, transformedData, ctx)
+	const data = await validateResponse(endpoint.resSchema, transformedData, ctx)
+	return { data, responseSizeBytes }
 }
 
 export function defaultShouldRetry(ctx: RetryContext): boolean {

package/src/api-wrapper/types.ts

@@ -225,6 +225,7 @@ export interface ApiClientConfig<
 	timeoutMs?: number
 	retries?: number
 	retryDelayMs?: number | ((attempt: number) => number)
+	maxRetryDelayMs?: number
 	shouldRetry?: (context: RetryContext) => boolean
 	logger?: Pick<Console, 'debug' | 'error'>
 	fetch?: typeof fetch