hanzio 2.1.0 → 2.2.0

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.

package/src/i18n/README.md

@@ -0,0 +1,65 @@
+---
+description: Typed `{name}` placeholders, interpolation and a small typed translator.
+---
+
+# hanzio/i18n
+
+A typed helper for `{name}` message templates, not an i18n framework: no
+plurals, ICU, locale negotiation or escaping.
+
+```ts
+import { createTranslator, extractPlaceholders, interpolate } from 'hanzio/i18n'
+
+interpolate('Hi {name}, you have {count} messages', { name: 'Ada', count: 3 })
+// 'Hi Ada, you have 3 messages'
+
+interpolate('Hi {name}') // type error: params required
+interpolate('Hi {name}', { nam: 'Ada' }) // type error: misspelled
+
+extractPlaceholders('{name} has {count} items, {name}') // ['name', 'count']
+```
+
+## Placeholders
+
+A placeholder is `{` + word characters (`[A-Za-z0-9_]`) + `}`. Anything else is
+plain text: `{ name }`, `{}`, `{count, plural, ...}`. The types and the runtime
+use the same rule.
+
+- A placeholder without a param (or with `null`/`undefined`) stays as `{name}`.
+- Only own properties of `params` are used, so `{toString}` is never filled from
+  `Object.prototype`.
+- Values are `string | number`, converted with `String()`.
+
+Types:
+
+| Type                     | `'Hi {name}, {count}'`                       |
+| ------------------------ | -------------------------------------------- |
+| `PlaceholderNames<S>`    | `'name' \| 'count'`                          |
+| `PlaceholderParams<S>`   | `{ name: string \| number; count: ... }`     |
+| `PlaceholderArgs<S>`     | `[params: PlaceholderParams<S>]`, `[]` if none |
+
+For a non-literal `string` template, names are `string` and params are optional.
+
+## Translator
+
+```ts
+const messages = {
+	common: { save: 'Save' },
+	greeting: 'Hi {name}'
+} as const
+
+const t = createTranslator(messages)
+
+t('common.save') // 'Save'
+t('greeting', { name: 'Ada' }) // 'Hi Ada'
+t('greeting') // type error: params required
+t('common.save', { name: 'Ada' }) // type error: no placeholders
+t('common.missing') // type error: unknown key
+```
+
+Keys are the dot paths of the string leaves (`MessageKeys<T>`). Pass the
+messages inline or `as const` so the templates stay literal; with plain
+`Record<string, string>` messages (for example JSON imports) keys are `string`
+and params are optional. A key that is missing at runtime returns the key.
+
+`flattenMessages(messages)` gives the flat map: `{ 'common.save': 'Save', greeting: 'Hi {name}' }`.

package/src/jwt/README.md

@@ -0,0 +1,70 @@
+---
+description: JWT sign/verify/decode using built-in Web Crypto HMAC (HS256/HS384/HS512).
+---
+
+# hanzio/jwt
+
+```ts
+import { jwtDecode, jwtSign, jwtVerify, jwtVerifyResult } from 'hanzio/jwt'
+
+const token = await jwtSign({ sub: 'user-1' }, secret, {
+	expiresIn: 60 * 60, // seconds
+	issuer: 'api',
+	audience: 'web'
+})
+
+// Payload or null
+const payload = await jwtVerify<{ sub: string }>(token, secret)
+
+// Result with a reason
+const result = await jwtVerifyResult(token, secret, {
+	issuer: 'api',
+	audience: 'web',
+	leewaySec: 30
+})
+if (!result.ok) console.log(result.error.code) // 'expired', 'invalid_signature', …
+
+// Unverified: for reading claims client-side, never for auth
+const decoded = jwtDecode(token) // { header, payload } | null
+```
+
+## Signing
+
+`jwtSign(payload, secret, options?)`
+
+| Option       | Claim | Notes                               |
+| ------------ | ----- | ----------------------------------- |
+| `expiresIn`  | `exp` | seconds from now                    |
+| `notBefore`  | `nbf` | seconds from now                    |
+| `issuer`     | `iss` |                                     |
+| `audience`   | `aud` | `string \| string[]`                |
+| `algorithm`  | —     | `'HS256'` (default), `'HS384'`, `'HS512'` |
+
+- `iat` is always set to the current time.
+- Options win: a claim set through an option replaces the same claim in `payload`.
+  Payload claims are kept when the option is omitted.
+- Non-finite `expiresIn`/`notBefore` throw a `TypeError`.
+- The header is `{ alg, typ: 'JWT' }`.
+
+## Verifying
+
+`jwtVerifyResult(token, secret, options?)` returns
+`Result<Payload, JwtVerifyError>` (see `hanzio` promise helpers). `error.code` is one of
+`'malformed' | 'unsupported_alg' | 'invalid_signature' | 'expired' | 'not_yet_valid' | 'invalid_issuer' | 'invalid_audience'`.
+
+| Option       | Default                 | Notes                                      |
+| ------------ | ----------------------- | ------------------------------------------ |
+| `leewaySec`  | `0`                     | clock skew tolerance for `exp` / `nbf`     |
+| `issuer`     | —                       | required `iss`                             |
+| `audience`   | —                       | must equal `aud` or be one of its entries  |
+| `algorithms` | `['HS256','HS384','HS512']` | the header `alg` must be in this list |
+
+- The signature is checked before any claim, so unsigned claims never decide the error code.
+- `alg: 'none'` and anything outside `algorithms` is rejected as `unsupported_alg`.
+- Configuration errors (no Web Crypto, empty secret) throw. `jwtVerify` swallows them
+  and returns `null`, like any other failure.
+
+Imported `CryptoKey`s are cached per secret, algorithm and usage (up to 100 entries).
+
+The base64url and UTF-8 helpers this module uses are public in
+[`hanzio/crypto`](../crypto/README.md) (`encodeBase64Url`, `decodeBase64Url`, …).