hanzio 2.2.0 → 3.1.0

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "hanzio",
-  "version": "2.2.0",
+  "version": "3.1.0",
   "description": "A lightweight set of utility functions for TypeScript",
   "type": "module",
   "module": "./dist/src/index.js",
   "main": "./dist/src/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "hanzio-i18n": "./dist/src/i18n/cli.js"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -26,6 +29,7 @@
   "files": [
     "src/**/*.ts",
     "src/**/README.md",
+    "src/api-wrapper/SKILL.md",
     "dist",
     "!src/**/*.test.ts"
   ],
@@ -55,6 +59,12 @@
       "import": "./dist/src/api-wrapper/testing.js",
       "default": "./dist/src/api-wrapper/testing.js"
     },
+    "./api-wrapper/connection-auth": {
+      "types": "./dist/api-wrapper/connection-auth.d.ts",
+      "bun": "./src/api-wrapper/connection-auth.ts",
+      "import": "./dist/src/api-wrapper/connection-auth.js",
+      "default": "./dist/src/api-wrapper/connection-auth.js"
+    },
     "./jwt": {
       "types": "./dist/jwt/index.d.ts",
       "bun": "./src/jwt/index.ts",
@@ -85,6 +95,12 @@
       "import": "./dist/src/format/index.js",
       "default": "./dist/src/format/index.js"
     },
+    "./format/phone": {
+      "types": "./dist/format/phone.d.ts",
+      "bun": "./src/format/phone.ts",
+      "import": "./dist/src/format/phone.js",
+      "default": "./dist/src/format/phone.js"
+    },
     "./crypto": {
       "types": "./dist/crypto/index.d.ts",
       "bun": "./src/crypto/index.ts",
@@ -103,6 +119,36 @@
       "import": "./dist/src/i18n/index.js",
       "default": "./dist/src/i18n/index.js"
     },
+    "./i18n/vue": {
+      "types": "./dist/i18n/vue.d.ts",
+      "bun": "./src/i18n/vue.ts",
+      "import": "./dist/src/i18n/vue.js",
+      "default": "./dist/src/i18n/vue.js"
+    },
+    "./i18n/i18next": {
+      "types": "./dist/i18n/i18next.d.ts",
+      "bun": "./src/i18n/i18next.ts",
+      "import": "./dist/src/i18n/i18next.js",
+      "default": "./dist/src/i18n/i18next.js"
+    },
+    "./i18n/vite": {
+      "types": "./dist/i18n/vite.d.ts",
+      "bun": "./src/i18n/vite.ts",
+      "import": "./dist/src/i18n/vite.js",
+      "default": "./dist/src/i18n/vite.js"
+    },
+    "./i18n/check": {
+      "types": "./dist/i18n/check.d.ts",
+      "bun": "./src/i18n/check.ts",
+      "import": "./dist/src/i18n/check.js",
+      "default": "./dist/src/i18n/check.js"
+    },
+    "./iso": {
+      "types": "./dist/iso/index.d.ts",
+      "bun": "./src/iso/index.ts",
+      "import": "./dist/src/iso/index.js",
+      "default": "./dist/src/iso/index.js"
+    },
     "./secrets": {
       "types": "./dist/secrets/index.d.ts",
       "bun": "./src/secrets/index.ts",
@@ -120,11 +166,35 @@
       "bun": "./src/secrets/worker.ts",
       "import": "./dist/src/secrets/worker.js",
       "default": "./dist/src/secrets/worker.js"
+    },
+    "./redis": {
+      "types": "./dist/redis/index.d.ts",
+      "bun": "./src/redis/index.ts",
+      "import": "./dist/src/redis/index.js",
+      "default": "./dist/src/redis/index.js"
+    },
+    "./http": {
+      "types": "./dist/http/index.d.ts",
+      "bun": "./src/http/index.ts",
+      "import": "./dist/src/http/index.js",
+      "default": "./dist/src/http/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli/index.d.ts",
+      "bun": "./src/cli/index.ts",
+      "import": "./dist/src/cli/index.js",
+      "default": "./dist/src/cli/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "bun": "./src/testing/index.ts",
+      "import": "./dist/src/testing/index.js",
+      "default": "./dist/src/testing/index.js"
     }
   },
   "scripts": {
     "build": "rm -rf dist && 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/api-wrapper/testing.ts ./src/jwt/index.ts ./src/sitemap/index.ts ./src/p-queue/index.ts ./src/cool-console-log/index.ts ./src/format/index.ts ./src/crypto/index.ts ./src/storage/index.ts ./src/i18n/index.ts ./src/secrets/index.ts ./src/secrets/vite.ts ./src/secrets/worker.ts --outdir ./dist --target node --packages external --splitting",
+    "build:js": "bun build ./src/index.ts ./src/zod/index.ts ./src/api-wrapper/index.ts ./src/api-wrapper/testing.ts ./src/api-wrapper/connection-auth.ts ./src/jwt/index.ts ./src/sitemap/index.ts ./src/p-queue/index.ts ./src/cool-console-log/index.ts ./src/format/index.ts ./src/format/phone.ts ./src/crypto/index.ts ./src/storage/index.ts ./src/i18n/index.ts ./src/i18n/vue.ts ./src/i18n/i18next.ts ./src/i18n/vite.ts ./src/i18n/check.ts ./src/i18n/cli.ts ./src/iso/index.ts ./src/secrets/index.ts ./src/secrets/vite.ts ./src/secrets/worker.ts ./src/redis/index.ts ./src/http/index.ts ./src/cli/index.ts ./src/testing/index.ts --outdir ./dist --target node --packages external --splitting",
     "build:types": "tsgo -p tsconfig.build.json",
     "prepublishOnly": "bun run build",
     "test": "bun test",
@@ -138,19 +208,44 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.6",
+    "@intlify/message-compiler": "^11.4.16",
     "@opentelemetry/api": "^1.9.1",
     "@types/bun": "latest",
     "@typescript/native-preview": "^7.0.0-dev.20260306.1",
     "husky": "^9.1.7",
+    "i18next": "^25.10.10",
+    "libphonenumber-js": "^1.13.15",
     "miniflare": "^4.20260730.0",
     "typescript": "^5.7.0",
     "vite": "^8.2.2",
+    "vue": "^3.5.44",
+    "vue-i18n": "^11.4.16",
     "zod": "^4.3.6"
   },
   "peerDependencies": {
+    "@intlify/message-compiler": ">=10.0.0",
+    "i18next": ">=23.0.0",
+    "libphonenumber-js": "^1.10.0",
+    "vite": ">=6.0.0",
+    "vue-i18n": ">=10.0.0",
     "zod": "^4.3.6"
   },
   "peerDependenciesMeta": {
+    "@intlify/message-compiler": {
+      "optional": true
+    },
+    "i18next": {
+      "optional": true
+    },
+    "libphonenumber-js": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    },
+    "vue-i18n": {
+      "optional": true
+    },
     "zod": {
       "optional": true
     }

package/src/api-wrapper/README.md

@@ -3,8 +3,11 @@
 Typed HTTP clients from Zod schemas: `createApiClient` validates requests and
 responses, retries with exponential backoff, and throws structured errors.
 
-Building a new wrapper with an AI agent? See [AGENTS.md](./AGENTS.md) for the
-step-by-step workflow and folder conventions.
+Building a new wrapper with an AI agent? [SKILL.md](./SKILL.md) has the
+step-by-step workflow and folder conventions. It ships with the package: copy
+`node_modules/hanzio/src/api-wrapper/SKILL.md` to
+`.claude/skills/hanzio-api-wrapper/SKILL.md` (or `.agents/skills/…`), or point
+your agent at it.
 
 ## Quick Start
 
@@ -645,6 +648,58 @@ Cache API:
 The cache is also exposed on the client itself as `api.cache` for use outside
 of action handlers (e.g. clearing auth on logout).
 
+### Sharing a login across clients
+
+`ctx.cache` lives for one client. When every request builds its own client
+(one per tenant or per connection, from stored credentials), use
+`ConnectionAuthCache` from `hanzio/api-wrapper/connection-auth` instead: one
+module-level cache shares a single token exchange per connection across all
+of them. It needs `node:crypto` (Bun, Node, Deno, or Workers with
+`nodejs_compat`), so it is not part of `hanzio/api-wrapper`.
+
+```ts
+import { ConnectionAuthCache } from 'hanzio/api-wrapper/connection-auth'
+
+const authCache = new ConnectionAuthCache() // keeps at most 1,000 connections
+
+export function createShopClient(connection: { id: string; apiKey: string; secret: string }) {
+	const auth = authCache.bind({
+		connectionId: connection.id,
+		authInputs: [connection.apiKey, connection.secret],
+		refreshMarginMs: 60_000,
+		exchange: () => login(connection) // resolves { token, expiresAt }
+	})
+
+	return {
+		async get(path: string, signal?: AbortSignal) {
+			for (let attempt = 0; ; attempt++) {
+				const current = await auth.get({ signal })
+				const response = await fetch(`https://shop.example.com${path}`, {
+					headers: { authorization: `Bearer ${current.token}` },
+					signal
+				})
+				// One retry with a new login when the token was refused.
+				if (response.status !== 401 || attempt > 0) return response
+				auth.reject(current)
+			}
+		}
+	}
+}
+```
+
+- Concurrent callers share one exchange, and aborting one caller's wait leaves
+  it running for the others.
+- Changing any `authInputs` value (a rotated secret) retires the old token: a
+  client still using the old credentials can finish its request but cannot
+  store its token. The inputs are kept only as an HMAC under a random key.
+- `reject(token)` drops a token the API refused, unless a newer login has
+  already replaced it. `get({ fresh: true })` always exchanges, for an explicit
+  credential check, and never falls back to the old token when it fails.
+- `clear()` forgets everything, including exchanges still in flight.
+
+`connectionAuthContract` in [`hanzio/testing`](../testing/README.md#connection-auth-contract)
+runs these races against your client.
+
 ## Endpoint Configuration Reference
 
 | Option | Required | Description |

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/connection-auth.ts

@@ -0,0 +1,142 @@
+import { createHmac, randomBytes } from 'node:crypto'
+import { raceAbort } from '../promise'
+
+export type ConnectionAuthToken = { token: string; expiresAt: number }
+
+type Entry = {
+	identity: string
+	token?: ConnectionAuthToken
+	pending?: Promise<ConnectionAuthToken>
+}
+
+/**
+ * Shares one login per connection across every client instance in the process,
+ * for APIs that exchange credentials for a short-lived token.
+ *
+ * - Concurrent callers share one exchange; aborting one caller's wait leaves the
+ *   exchange running for the others.
+ * - Changing any of `authInputs` (rotated password, new client id) retires the
+ *   old token: a retired client may finish its request but cannot store its
+ *   token. Inputs are kept only as an HMAC under a random per-cache key, so
+ *   the cache never holds, and cannot be used to guess, the credentials.
+ * - On a 401, `reject(token)` drops the refused token, unless a newer one has
+ *   already replaced it, and the next `get()` exchanges again.
+ * - `get({ fresh: true })` always exchanges, for an explicit credential check;
+ *   its failure never falls back to the previous token.
+ * - At most `maxEntries` connections are kept, least recently used first;
+ *   connections with an exchange in flight are never evicted.
+ *
+ * @example
+ * const auth = new ConnectionAuthCache()
+ *
+ * class ShopApi {
+ *   private readonly token
+ *   constructor(credentials: { connectionId: string; apiKey: string; secret: string }) {
+ *     this.token = auth.bind({
+ *       connectionId: credentials.connectionId,
+ *       authInputs: [credentials.apiKey, credentials.secret],
+ *       refreshMarginMs: 60_000,
+ *       exchange: () => login(credentials) // resolves { token, expiresAt }
+ *     })
+ *   }
+ *   async read(signal?: AbortSignal) {
+ *     const current = await this.token.get({ signal })
+ *     // On a 401: this.token.reject(current), then retry once with this.token.get().
+ *   }
+ * }
+ */
+export class ConnectionAuthCache {
+	private readonly key = randomBytes(32)
+	private readonly entries = new Map<string, Entry>()
+
+	constructor(private readonly maxEntries = 1_000) {}
+
+	get size() {
+		return this.entries.size
+	}
+
+	clear() {
+		for (const entry of this.entries.values()) entry.token = undefined
+		this.entries.clear()
+	}
+
+	private prune(protectedEntry?: Entry) {
+		for (const [connectionId, entry] of this.entries) {
+			if (this.entries.size <= this.maxEntries) break
+			// In-flight work must remain discoverable by identical callers. Its
+			// ownership ends on settlement, when pruning runs again.
+			if (entry.pending || entry === protectedEntry) continue
+			entry.token = undefined
+			this.entries.delete(connectionId)
+		}
+	}
+
+	bind(input: {
+		connectionId: string
+		authInputs: readonly (string | number)[]
+		refreshMarginMs: number
+		exchange: () => Promise<ConnectionAuthToken>
+	}) {
+		const identity = createHmac('sha256', this.key)
+			.update(JSON.stringify(input.authInputs))
+			.digest('hex')
+		let entry = this.entries.get(input.connectionId)
+
+		if (!entry || entry.identity !== identity) {
+			if (entry) entry.token = undefined
+			entry = { identity }
+		}
+
+		// Map order is LRU. Eviction never cancels an exchange already in use.
+		this.entries.delete(input.connectionId)
+		this.entries.set(input.connectionId, entry)
+		this.prune(entry)
+
+		const state = entry
+		const get = (options?: { fresh?: boolean; signal?: AbortSignal }) => {
+			if (options?.signal?.aborted) {
+				return Promise.reject<ConnectionAuthToken>(options.signal.reason)
+			}
+
+			if (this.entries.get(input.connectionId) === state) {
+				this.entries.delete(input.connectionId)
+				this.entries.set(input.connectionId, state)
+			}
+
+			// Aborting cancels only this wait; the exchange belongs to every waiter.
+			if (state.pending) return raceAbort(state.pending, options?.signal)
+			if (
+				!options?.fresh &&
+				state.token &&
+				state.token.expiresAt - Date.now() > input.refreshMarginMs
+			) {
+				return Promise.resolve(state.token)
+			}
+
+			// A fresh check cannot leave the previous token usable after failure.
+			state.token = undefined
+			const pending = input
+				.exchange()
+				.then((token) => {
+					if (this.entries.get(input.connectionId) === state) {
+						state.token = token
+					}
+					return token
+				})
+				.finally(() => {
+					if (state.pending === pending) state.pending = undefined
+					this.prune()
+				})
+			state.pending = pending
+
+			return raceAbort(pending, options?.signal)
+		}
+
+		return {
+			get,
+			reject(token: ConnectionAuthToken) {
+				if (state.token === token) state.token = undefined
+			}
+		}
+	}
+}