hanzio 2.1.0 → 3.0.0

package/src/api-wrapper/SKILL.md

@@ -0,0 +1,256 @@
+---
+name: hanzio-api-wrapper
+description: Building typed HTTP API wrappers with createApiClient and Zod in hanzio/api-wrapper. Covers folder layout, index factory, endpoint files with defineEndpoint, shared types, pagination with paginate, and common REST API integration patterns.
+---
+
+# AI Agent Guide: Building API Wrappers
+
+This guide is for AI assistants to follow when building API wrappers using the
+`createApiClient` utility from `hanzio/api-wrapper`. The API reference
+(configuration, errors, actions, retries, pagination) lives in
+[README.md](./README.md).
+
+## Folder Structure
+
+When creating a new API wrapper, follow this structure:
+
+```txt
+src/api-wrapper/{api-name}/
+├── index.ts
+├── types.ts
+├── {endpointName}.ts
+├── {anotherEndpoint}.ts
+└── utils/
+    ├── {utilName}.ts
+    └── ...
+```
+
+### Naming Conventions
+
+- Folder name: lowercase, kebab-case, for example `github-api`, `stripe`, `template-persona`.
+- Endpoint files: camelCase and action-oriented, for example `topicsGet.ts`, `usersCreate.ts`, `ordersUpdate.ts`.
+- Utility files: camelCase and descriptive, for example `paginateResults.ts`, `templateGetAll.ts`.
+
+## Step-By-Step Process
+
+### Step 1: Gather Information
+
+The user will typically provide one or more of:
+
+1. cURL command: extract method, URL, headers, and body.
+2. Request/response examples: use them to build Zod schemas.
+3. Chrome DevTools Network logs: extract request and response details.
+4. API documentation: reference schemas, auth, pagination, and endpoints.
+
+### Step 2: Create The Folder
+
+```bash
+mkdir -p src/api-wrapper/{api-name}/utils
+```
+
+### Step 3: Create The Index File
+
+The index file creates and exports the API client. When the token comes from
+a secret store, create the client at module level and resolve the header
+lazily with a `defaultHeaders` function; take the token as a parameter only
+when callers supply it per instance.
+
+```ts
+import { createApiClient } from 'hanzio/api-wrapper'
+import { endpointOne } from './endpointOne'
+import { endpointTwo } from './endpointTwo'
+
+export const exampleApi = createApiClient({
+	name: 'exampleApi',
+	baseApiUrls: {
+		default: 'https://api.example.com'
+	},
+	defaultHeaders: () => ({
+		Authorization: `Bearer ${getSecret('EXAMPLE_API_TOKEN')}`
+	}),
+	endpoints: {
+		endpointOne,
+		endpointTwo
+	}
+})
+```
+
+If the project uses OpenTelemetry, add
+`use: [otelMiddleware(trace.getTracer('app'))]`; for other shared middleware
+(metrics), pass it with `use: [...]` instead of wrapping `fetch`. Pass a
+`logger` so failures are logged with their category (server, input or output
+validation). If the API returns HTTP 200 with an
+error envelope (e.g. `{ success: false, errors }`), add a `checkResponse` that
+throws on failure rather than checking after every call. Endpoints without the
+envelope set `checkResponse: false` (or their own check). When the result is in
+response headers (e.g. a `Location`), read them in `resFormatter(body, headers)`.
+
+### Step 4: Create Shared Types
+
+If multiple endpoints share schemas, create a `types.ts` file.
+
+```ts
+import { z } from 'zod'
+
+export const ListQueryInput = z.object({
+	page: z.number().optional(),
+	page_size: z.number().optional()
+})
+export type ListQueryInput = z.infer<typeof ListQueryInput>
+
+export const ListQueryOutput = <T extends z.ZodType>(itemSchema: T) =>
+	z.object({
+		data: z.array(itemSchema),
+		current_page: z.number(),
+		last_page: z.number(),
+		per_page: z.number(),
+		total: z.number()
+	})
+
+export type ListQueryOutput<T> = {
+	data: T[]
+	current_page: number
+	last_page: number
+	per_page: number
+	total: number
+}
+```
+
+### Step 5: Create Endpoint Files
+
+Each endpoint gets its own file with request/response schemas and endpoint
+configuration.
+
+```ts
+import { defineEndpoint } from 'hanzio/api-wrapper'
+import { z } from 'zod'
+
+export const UserResponse = z.object({
+	id: z.number(),
+	name: z.string(),
+	email: z.string()
+})
+
+export const usersGet = defineEndpoint({
+	method: 'GET',
+	path: '/users/:userId',
+	reqQuerySchema: z.object({ includeInactive: z.boolean().optional() }),
+	resSchema: UserResponse
+})
+```
+
+`defineEndpoint` types `reqParams` from the `:params` in `path`, so add a
+`reqParamsSchema` only when params need validation or coercion.
+
+### Step 6: Create Utility Functions
+
+Place reusable helpers in `utils/`, e.g. response normalization or rate-limit
+handling. For pagination, use the built-in `paginate` instead of a hand-written
+loop:
+
+```ts
+import { paginate } from 'hanzio/api-wrapper'
+import type { GetExampleApi } from '../index'
+
+export const usersGetAll = (api: GetExampleApi) =>
+	Array.fromAsync(
+		paginate(
+			(page: number = 1) => api.usersList({ reqQuery: { page } }),
+			(res) =>
+				res.data.current_page < res.data.last_page
+					? res.data.current_page + 1
+					: null
+		)
+	)
+```
+
+## Extracting Information From User Input
+
+### From cURL Commands
+
+```bash
+curl -X POST 'https://api.example.com/users' \
+  -H 'Authorization: Bearer token123' \
+  -H 'Content-Type: application/json' \
+  -d '{"name": "John", "email": "john@example.com"}'
+```
+
+Extract:
+
+- Method: `POST`
+- Base URL: `https://api.example.com`
+- Path: `/users`
+- Headers: `Authorization`, `Content-Type`
+- Body schema: `{ name: string, email: string }`
+
+### From Chrome DevTools
+
+Look for:
+
+1. Request URL: base URL plus path.
+2. Request method: HTTP method.
+3. Request headers: auth and custom headers.
+4. Request payload: body schema.
+5. Response body: response schema.
+6. Query string parameters: query schema.
+
+### Building Zod Schemas From JSON
+
+Given this response:
+
+```json
+{
+	"id": 123,
+	"name": "John Doe",
+	"email": "john@example.com",
+	"created_at": "2024-01-15T10:30:00Z",
+	"roles": ["admin", "user"],
+	"profile": {
+		"avatar_url": "https://example.com/avatar.png",
+		"bio": "Developer"
+	},
+	"is_active": true
+}
+```
+
+Create this schema:
+
+```ts
+const UserResponse = z.object({
+	id: z.number(),
+	name: z.string(),
+	email: z.string(),
+	created_at: z.string(),
+	roles: z.array(z.string()),
+	profile: z.object({
+		avatar_url: z.string(),
+		bio: z.string()
+	}),
+	is_active: z.boolean()
+})
+```
+
+## Checklist
+
+- [ ] Create folder with API name in kebab-case.
+- [ ] Create `index.ts` with a `createApiClient` call.
+- [ ] Set `baseApiUrls` and `defaultHeaders` (a function when the token comes from a secret store).
+- [ ] Add `checkResponse` if the API returns errors inside 200 responses.
+- [ ] Create `types.ts` for shared schemas when needed.
+- [ ] Create one file per endpoint.
+- [ ] Define Zod schemas for all request and response data.
+- [ ] Use `defineEndpoint` for endpoint definitions.
+- [ ] Create helpers in `utils/` when needed.
+- [ ] Export the API type, for example `export type ExampleApi = typeof exampleApi`.
+- [ ] Test with `createMockFetch` from `hanzio/api-wrapper/testing` passed as `fetch`; don't replace `globalThis.fetch`.
+
+## Tips
+
+1. Always use `defineEndpoint` for endpoint definitions (it checks `resFormatter` and types path params).
+2. Import Zod from `zod`.
+3. Be strict with schemas and mark unstable fields as `.optional()` or `.nullish()`.
+4. Use descriptive endpoint names like `usersGet`, `usersCreate`, and `ordersListByStatus`.
+5. Keep files small by using one endpoint per file.
+6. Extract schemas to `types.ts` when used by two or more endpoints.
+7. Use `paginate` when APIs use pagination.
+8. Ask for sample responses if the user only provides cURL commands.

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

@@ -256,7 +256,8 @@ function createApiClientImpl<
 				responseSizeMb: result.validatedData.responseSizeBytes / (1024 * 1024),
 				responseTimeMs: elapsed(),
 				httpStatus: result.httpStatus,
-				retryCount: result.retryCount
+				retryCount: result.retryCount,
+				headers: result.validatedData.headers
 			}
 		}
 
@@ -265,9 +266,14 @@ function createApiClientImpl<
 			httpStatus: number,
 			attempt: number
 		) => {
-			if (!apiConfig.checkResponse) return
+			// An endpoint's own check (or `false`) replaces the client's.
+			const checkResponse =
+				endpoint.checkResponse === undefined
+					? apiConfig.checkResponse
+					: endpoint.checkResponse
+			if (!checkResponse) return
 			try {
-				await apiConfig.checkResponse(data, {
+				await checkResponse(data, {
 					endpoint: endpointName,
 					method: endpoint.method,
 					url: fullUrl,

package/src/api-wrapper/endpoint.ts

@@ -1,11 +1,12 @@
 import type { z } from 'zod'
-import type { ApiEndpoint } from './types'
+import type { ApiEndpoint, CheckResponseContext } 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`).
+ * accepts, `checkResponse` receives the parsed `resSchema` output, and a
+ * literal `path` types its `:params` (making `reqParams` required when
+ * there's no `reqParamsSchema`).
  *
  * @example
  * export const usersGet = defineEndpoint({
@@ -14,12 +15,25 @@ import type { ApiEndpoint } from './types'
  *   resSchema: User
  * })
  */
-export function defineEndpoint<const TEndpoint extends ApiEndpoint>(
+// `TRes` is inferred from `resSchema` before the callbacks are typed, and the
+// constraint omits `checkResponse` so its untyped `ApiEndpoint` signature
+// doesn't override the one below.
+export function defineEndpoint<
+	const TEndpoint extends Omit<ApiEndpoint, 'checkResponse'>,
+	TRes extends z.ZodType = TEndpoint['resSchema']
+>(
 	endpoint: TEndpoint & {
+		resSchema: TRes
 		resFormatter?: (
 			data: unknown,
 			headers: Record<string, string>
-		) => z.input<TEndpoint['resSchema']>
+		) => z.input<TRes>
+		checkResponse?:
+			| ((
+					data: z.output<TRes>,
+					context: CheckResponseContext
+			  ) => void | Promise<void>)
+			| false
 	}
 ): TEndpoint {
 	return endpoint

package/src/api-wrapper/transport.ts

@@ -303,7 +303,11 @@ export async function validateAndTransformResponse<T extends z.ZodType>(
 	>,
 	response: Response,
 	ctx: (over?: Partial<ApiErrorContext>) => ApiErrorContext
-): Promise<{ data: z.infer<T>; responseSizeBytes: number }> {
+): Promise<{
+	data: z.infer<T>
+	responseSizeBytes: number
+	headers: Record<string, string>
+}> {
 	const responseHeaders = getHeadersAsObject(response.headers)
 	const text = await response.text()
 	const responseSizeBytes = new TextEncoder().encode(text).length
@@ -327,7 +331,7 @@ export async function validateAndTransformResponse<T extends z.ZodType>(
 		: responseData
 
 	const data = await validateResponse(endpoint.resSchema, transformedData, ctx)
-	return { data, responseSizeBytes }
+	return { data, responseSizeBytes, headers: responseHeaders }
 }
 
 export function defaultShouldRetry(ctx: RetryContext): boolean {

package/src/api-wrapper/types.ts

@@ -35,6 +35,17 @@ export interface ApiEndpoint<
 	) => z.input<TResponse>
 	reqDefaultQueryParams?: QueryParams
 	doNotEncodeQueryParams?: boolean
+	/**
+	 * Replaces the client's `checkResponse` for this endpoint; `false` skips it.
+	 * `defineEndpoint` types `data` as the parsed `resSchema` output.
+	 */
+	checkResponse?:
+		| ((
+				// biome-ignore lint/suspicious/noExplicitAny: typed per endpoint by defineEndpoint
+				data: any,
+				context: CheckResponseContext
+		  ) => void | Promise<void>)
+		| false
 }
 
 export interface ApiWrapperResponse<T> {
@@ -44,6 +55,8 @@ export interface ApiWrapperResponse<T> {
 	responseTimeMs: number
 	httpStatus: number
 	retryCount: number
+	/** Response headers of the final attempt, keyed by lowercase name. */
+	headers: Record<string, string>
 }
 
 export type RetryContext = {

package/src/crypto/README.md

@@ -0,0 +1,144 @@
+---
+description: Web Crypto helpers - base64/hex encoding, constant-time compare, random tokens, SHA-256, HMAC and webhook signatures, AES-GCM sealing.
+---
+
+# hanzio/crypto
+
+Built only on `globalThis.crypto` (Web Crypto), so it runs in browsers, Workers,
+Bun and Node ≥ 19. On Node 18, `globalThis.crypto` may be missing; fix that with
+`globalThis.crypto ??= (await import('node:crypto')).webcrypto`. Nothing here
+imports `node:crypto`. Hashing and HMAC are async because Web Crypto is; keep
+synchronous Node hashing (`createHash`) in apps that need it.
+
+```ts
+import {
+	createSealer,
+	randomToken,
+	safeEqual,
+	sha256Hex,
+	verifyHmacSignature,
+	verifySvixSignature
+} from 'hanzio/crypto'
+```
+
+## Encoding
+
+| Function | Notes |
+| --- | --- |
+| `encodeBase64(bytes)` / `decodeBase64(value)` | standard alphabet, padded output; decoding accepts missing padding |
+| `encodeBase64Url(bytes)` / `decodeBase64Url(value)` | URL-safe, unpadded output; decoding accepts padding |
+| `bytesToHex(bytes)` / `hexToBytes(value)` | lowercase output; decoding accepts either case |
+| `utf8Encode(string)` / `utf8Decode(bytes)` | invalid UTF-8 decodes to U+FFFD |
+
+`bytes` may be a `Uint8Array` or an `ArrayBuffer`. Decoders throw a `TypeError` on
+invalid input, and the message never contains the input.
+
+## Compare and random
+
+```ts
+safeEqual(providedToken, expectedToken) // string | Uint8Array, strings compared as UTF-8
+randomToken() // 32 random bytes as base64url (43 chars)
+randomToken(16) // 22 chars
+randomBytes(12) // Uint8Array
+```
+
+`safeEqual` always loops over the longer input and never exits early, so timing
+can reveal the **lengths** of the inputs but not where they differ. That is fine
+for comparing against fixed-length secrets or digests. If the length itself is
+sensitive, hash both sides first (`safeEqual(await sha256(a), await sha256(b))`).
+
+## Hashing and HMAC
+
+```ts
+await sha256('abc') // Uint8Array
+await sha256Hex('abc') // 'ba7816bf…'
+
+await hmacSign(secret, body) // hex HMAC-SHA-256
+await hmacSign(secret, body, { algorithm: 'SHA-512', encoding: 'base64url' })
+
+// Meta / GitHub style: `x-hub-signature-256: sha256=<hex>`
+await verifyHmacSignature(appSecret, rawBody, request.headers.get('x-hub-signature-256') ?? '', {
+	prefix: 'sha256='
+})
+```
+
+| Option | Default | Values |
+| --- | --- | --- |
+| `algorithm` | `'SHA-256'` | `'SHA-256' \| 'SHA-384' \| 'SHA-512'` |
+| `encoding` | `'hex'` | `'hex' \| 'base64' \| 'base64url'` |
+| `prefix` (verify only) | none | stripped before decoding; if it is missing, the result is `false` |
+
+`verifyHmacSignature` decodes the signature and checks it with
+`crypto.subtle.verify`, which compares in constant time. A malformed, truncated
+or wrongly prefixed signature returns `false`. Configuration errors throw: an
+empty secret, or an unknown algorithm or encoding.
+
+## Svix / Standard Webhooks
+
+Resend, Clerk and other Svix-based providers sign
+`${id}.${timestamp}.${body}` with HMAC-SHA-256, using the base64 key inside the
+`whsec_` secret.
+
+```ts
+const ok = await verifySvixSignature({
+	secret: env.RESEND_WEBHOOK_SECRET, // 'whsec_…'
+	payload: rawBody, // the exact raw body, not re-serialized JSON
+	headers: request.headers, // Headers or a plain record
+	toleranceSec: 300, // default
+	now: Date.now() // default, in milliseconds
+})
+```
+
+- Reads the `svix-id`, `svix-timestamp` and `svix-signature` headers. If they are
+  missing, it reads `webhook-id`, `webhook-timestamp` and `webhook-signature`.
+  Header lookup ignores case, also for plain records.
+- The signature header is a space-separated list. Every `v1,<base64>` entry is
+  checked, so verification keeps working while the provider rotates the secret.
+- Returns `false` for missing headers, a non-integer timestamp, a timestamp more
+  than `toleranceSec` from `now` in either direction, or no matching signature.
+  An invalid secret throws a `TypeError`.
+
+## Sealing (AES-256-GCM)
+
+```ts
+const sealer = createSealer({
+	secret: env.APP_SECRET,
+	info: 'myapp.oauth-tokens.v1' // use a different value for each purpose
+})
+
+const sealed = await sealer.sealJson({ accessToken }) // 'enc:v1:…'
+const tokens = await sealer.openJson<{ accessToken: string }>(sealed)
+
+await sealer.seal('plain text')
+await sealer.open(sealed)
+```
+
+- The key is derived from `secret` with HKDF-SHA-256 (`salt`, default empty;
+  `info`, default `'hanzio.sealer.aes-256-gcm.v1'`). Derivation runs once per
+  sealer, and the resulting `CryptoKey` cannot be exported.
+- Each value gets a random 96-bit IV.
+- The envelope is `enc:v1:<b64url(iv)>.<b64url(tag)>.<b64url(ciphertext)>`.
+- `open` throws a `SealerError` with one of these codes:
+  - `'malformed'`
+  - `'unsupported_version'`, for `enc:vN:` values other than v1
+  - `'decrypt_failed'`, for a wrong key, salt or info, or tampered data
+
+  Error messages never contain the secret or the plaintext.
+- `sealJson` stores `JSON.stringify(value)`. It throws for `undefined` and for
+  functions.
+
+### Migrating lullu `secret-json.ts`
+
+The envelope and key derivation match `apps/backend/src/lib/crypto/secret-json.ts`,
+so values already stored keep opening and don't need to be re-encrypted:
+
+```ts
+const sealer = createSealer({
+	secret: getSecret('APP_SECRET'),
+	salt: 'lullu.secret-json.salt.v1',
+	info: 'lullu.secret-json.aes-256-gcm.v1'
+})
+```
+
+lullu's `openSecretJson` returns non-sealed values unchanged. `open` throws on
+them instead, so keep the `value.startsWith('enc:')` check in the app.

package/src/format/README.md

@@ -0,0 +1,120 @@
+# hanzio/format
+
+Locale-aware formatting on top of `Intl`, with no dependencies. Every function
+takes the locale (a BCP-47 tag such as `'en-US'` or `'da-DK'`) explicitly, and
+every function that reads the clock accepts a `now` for tests.
+
+```ts
+import { formatRelativeTime, formatBytes } from 'hanzio/format'
+```
+
+## Cached formatters
+
+Creating an `Intl` formatter is slow; these return one shared instance per
+(locale, options), keyed on a stable JSON of the options (key order does not
+matter). Each cache holds the 100 most recently used formatters.
+
+```ts
+getNumberFormat('en-US', { style: 'currency', currency: 'EUR' }).format(5) // '€5.00'
+getDateTimeFormat('en-GB', { dateStyle: 'medium' }).format(date) // '28 Sep 2026'
+getRelativeTimeFormat('en-US', { numeric: 'auto' }).format(-1, 'day') // 'yesterday'
+getListFormat('en-US', { type: 'disjunction' }).format(['a', 'b']) // 'a or b'
+getPluralRules('en-US').select(1) // 'one'
+```
+
+## Numbers
+
+```ts
+formatNumber(1234567.891, 'da-DK') // '1.234.567,891'
+formatPercent(0.25, 'en-US') // '25%' (takes a fraction, not 25)
+formatCurrency(12.5, 'USD', 'en-US') // '$12.50' (whole units, not cents)
+formatCurrency(2500, 'DKK', 'da-DK', { maximumFractionDigits: 0 }) // '2.500 kr.'
+formatCompactNumber(1234, 'en-US') // '1.2K'
+```
+
+### `formatBytes(bytes, { locale?, decimals?, binary? })`
+
+Unit labels (B, KB, MB, GB, TB, PB) are not localized; the number is. 1 KB is
+1024 B by default (`binary: false` for 1000). Whole numbers up to KB, one
+decimal from MB up, unless `decimals` is set. `locale` defaults to `'en-US'`.
+
+```ts
+formatBytes(3.45 * 1024 * 1024) // '3.5 MB'
+```
+
+## Durations
+
+```ts
+splitDuration(93_784_005) // { days: 1, hours: 2, minutes: 3, seconds: 4, milliseconds: 5 }
+formatClockDuration(3_909_000) // '1:05:09' ('5:09' under an hour)
+```
+
+### `formatDuration(ms, locale, { style?, maxUnits? })`
+
+Truncates, never rounds up. Shows up to `maxUnits` (default 2) adjacent units
+starting at the largest non-zero one, so 1 day 0 h 5 min reads `'1 day'`.
+`style` is `'short'` by default.
+
+```ts
+formatDuration(3_930_000, 'en-US') // '1 hr, 5 min'
+formatDuration(3_930_000, 'en-US', { style: 'narrow' }) // '1h 5m'
+formatDuration(3_930_000, 'en-US', { style: 'long' }) // '1 hour, 5 minutes'
+```
+
+## Relative time
+
+### `formatRelativeTime(date, locale, { now?, numeric?, style?, withSuffix? })`
+
+Picks seconds, minutes, hours, days (< 30), months (30-day) or years.
+`numeric` defaults to `'auto'` ("yesterday"). `withSuffix: false` returns the
+bare amount ("5 minutes") for use next to a label that already says when.
+Unparseable input returns `''`.
+
+```ts
+formatRelativeTime('2026-09-28T11:00:00Z', 'en-US', { now: new Date('2026-09-28T12:00:00Z') }) // '1 hour ago'
+```
+
+### `formatWait(value, locale, { now? })`
+
+Compact "how long has this waited" for a status pill: floors, never below
+`1 min`, a future timestamp counts as no waiting. A `number` is a duration in
+milliseconds; a `Date` or string is a start time measured against `now`.
+
+```ts
+formatWait(14 * 60_000 + 50_000, 'en-US') // '14 min'
+```
+
+## Dates and lists
+
+### `formatDateRange(start, end, locale, options?)`
+
+Uses `Intl.DateTimeFormat#formatRange`, which collapses the shared parts. When
+`options` has no date/time fields, it uses day + short month + year (and still
+applies `timeZone` and similar options).
+
+```ts
+formatDateRange('2026-08-24', '2026-08-30', 'en-GB', { timeZone: 'UTC' }) // '24–30 Aug 2026'
+```
+
+### `formatList(items, locale, options?)`
+
+```ts
+formatList(['a', 'b', 'c'], 'en-US') // 'a, b, and c'
+```
+
+## Counts
+
+```ts
+formatCappedCount(150) // '99+' (a negative number or NaN gives '0')
+formatCappedCount(12, 9) // '9+'
+pluralize(1234, { one: '{count} item', other: '{count} items' }, 'en-US') // '1,234 items'
+```
+
+`pluralize` picks the form with `Intl.PluralRules` and falls back to `other`.
+
+## Runtime support
+
+Works in browsers, Node, Bun, Workers and React Native. On Hermes, polyfill
+`Intl.RelativeTimeFormat` and `Intl.PluralRules` if your Hermes build does not
+have them. `formatList`, `formatDuration` and `formatDateRange` fall back to
+plain separators when `Intl.ListFormat` or `formatRange` is missing.