@rdlabo/workers-hono-kit 0.2.0 → 0.2.1

package/README.md

@@ -7,8 +7,11 @@ It provides the building blocks a NestJS-style API needs but that don't run on `
 - **Firebase ID-token verification** on Workers via [`jose`](https://github.com/panva/jose) (RS256 against Google's securetoken JWKS), with optional Identity Toolkit REST for `getUser` / `deleteUser`.
 - **AWS Secrets Manager** via SigV4-signed `fetch` ([`aws4fetch`](https://github.com/mhart/aws4fetch)) — no AWS SDK.
 - **Middleware**: `finalizeResponse` (Express-compatible weak ETag + JSON charset), `validate` (NestJS `ValidationPipe`-shaped 400), and zod number-coercion helpers.
-- **Deadlock retry** (`ER_LOCK_DEADLOCK` exponential backoff).
-- **HTTP helpers**: `getUserProtocol`, `getAppInfo`, `HttpStatus`.
+- **NestJS-shaped errors**: `createNestErrorHandler` / `nestNotFoundHandler` / `HttpStatus`.
+- **Deadlock retry** (`ER_LOCK_DEADLOCK` exponential backoff) and an optional **MySQL data layer** (`@rdlabo/workers-hono-kit/db`) for Hyperdrive + Drizzle.
+- **AI Gateway**: route `@ai-sdk` models through the Cloudflare AI Gateway.
+- **Stripe** Workers-native client + async webhook verification.
+- **Testing helpers** (`@rdlabo/workers-hono-kit/testing`): a Drizzle-migration-backed test database, in-memory Firebase fake, configurable test doubles, and Stripe fixtures.
 
 ## Install
 
@@ -19,17 +22,36 @@ npm install @rdlabo/workers-hono-kit
 Peer dependencies — install the ones you use:
 
 ```bash
+# Core (root export)
 npm install hono zod @hono/zod-validator jose aws4fetch
+
+# Optional, only if you use the corresponding feature:
+npm install drizzle-orm mysql2        # ./db and ./testing
+npm install ai ai-gateway-provider    # createAiGatewayProvider
 ```
 
-> **TypeScript sources, no build step.** The package is published as `.ts` via the `exports` field and is meant to be consumed by a bundler that compiles TypeScript — wrangler/esbuild, Vite, etc. — targeting `workerd` or another edge runtime. It relies only on Web-standard APIs (`fetch`, `crypto.subtle`, `Response`) available on Cloudflare Workers.
+`stripe` is bundled as a direct dependency, so the Stripe helpers work without an extra install.
+
+> **Compiled ESM, with types.** The package is published as compiled ES modules (`./dist/*.js`) plus
+> declaration files (`./dist/*.d.ts`) via the `exports` field. It depends only on Web-standard APIs
+> (`fetch`, `crypto.subtle`, `Response`) available on Cloudflare Workers (`workerd`) and other edge
+> runtimes, and requires Node.js ≥ 20 for tooling. Three entry points are exposed:
+>
+> | Subpath | Import | Use |
+> | --- | --- | --- |
+> | `.` | `@rdlabo/workers-hono-kit` | Web-standard helpers (middleware, HTTP, Firebase, AWS, AI, Stripe, KV). |
+> | `./db` | `@rdlabo/workers-hono-kit/db` | MySQL data layer (mysql2 + Drizzle). |
+> | `./testing` | `@rdlabo/workers-hono-kit/testing` | Test helpers (mysql2 + Drizzle + fakes/fixtures). |
 
 ## API
 
+### Root — `@rdlabo/workers-hono-kit`
+
 | Export | Description |
 | --- | --- |
 | `finalizeResponse()` | Middleware that adds an Express-compatible weak `ETag` and JSON `charset=utf-8`. |
 | `validate(target, schema, options?)` | Zod validator → NestJS `ValidationPipe`-shaped `400` (`{ statusCode, message[], error }`). `options.onValidationError(err, c)` to report (e.g. Sentry). |
+| `createSentryValidate(sentry)` | Returns a `validate` variant that reports validation failures to an injected Sentry-like client (tags + context), avoiding a hard `@sentry/cloudflare` dependency. |
 | `zNum` / `zNumWithDefault` / `zNumOptional` / `zNumNullable` | Number-coercion zod schemas (mirror class-transformer `@Transform`). |
 | `getAuthenticationSecret<T>(options, secretId)` / `AwsSecretsOptions` | Fetch a secret from AWS Secrets Manager (SigV4 `fetch`, per-isolate cache). |
 | `getCloudFrontSignedUrl(url, privateKeyPem, keyPairId, dateLessThan)` | CloudFront signed URL (canned policy, RSA-SHA1, URL-safe base64) — Web Crypto reimpl of `@aws-sdk/cloudfront-signer`, byte-identical query order. |
@@ -40,14 +62,48 @@ npm install hono zod @hono/zod-validator jose aws4fetch
 | `retryWhenDeadlock(fn, retries?, delay?)` | Retry on MySQL `ER_LOCK_DEADLOCK` with exponential backoff. |
 | `getUserProtocol(c)` / `IUserProtocol` | Read client IP / UA (`CF-Connecting-IP` → `X-Forwarded-For`). |
 | `getAppInfo(c)` / `AppInfo` | Read `x-amz-meta-version` / `x-amz-meta-uuid`. |
+| `resolveAppEnv(env)` / `isProductionEnv(env)` / `AppEnv` | Resolve `'development'` / `'production'` from `env.APP_ENV` (defaults to `'production'` for safety). |
 | `HttpStatus` | HTTP status enum identical to NestJS `@nestjs/common`. |
 | `createNestErrorHandler(options?)` / `NestErrorHandlerOptions` | `app.onError()` handler that maps a thrown `HTTPException` to the NestJS exception-filter body (`{ statusCode, message, error? }`; `401` omits `error`). Configurable field order, reason phrases, error predicate, and unhandled-error report hook. |
 | `nestNotFoundHandler(c)` | `app.notFound()` handler with the Express/Nest default `{ message: 'Cannot METHOD path', error, statusCode }` 404 body. |
 | `NEST_REASON_PHRASES` | `{ 400, 401, 403, 404 }` → NestJS reason phrases. |
 | `createAuthMiddleware(options)` / `AuthMiddlewareOptions` | Factory for a Firebase-token auth middleware: reads the token header, verifies, resolves the DB user id, and stashes the result on the context. Omit `resolveUserId` for a token-only (login) guard. |
-| `ErrorReporter` / `ErrorReportContext` | Types for a `container.reportError`-style unhandled-error reporter (e.g. wired to Sentry), paired with `createNestErrorHandler`'s `onUnhandledError`. |
-| `KVCache` / `KVNamespace` / `KVCacheOptions` | Workers-KV cache-aside helper (key `appName+version+table_type_column`, sha256 for string ids, TTL clamped ≥60s). `appName`/`version` per repo. |
-| `createStripeClient(secret, opts?)` / `verifyStripeWebhook(...)` / `CreateStripeClientOptions` | Workers-native Stripe client (fetch transport) + async webhook verification (SubtleCrypto). `apiVersion` optional (pin per `/api` parity). |
+| `ErrorReporter` / `ErrorReportContext` | Types for a `reportError`-style unhandled-error reporter (e.g. wired to Sentry), paired with `createNestErrorHandler`'s `onUnhandledError`. |
+| `createAiGatewayProvider(config)` / `AiGatewayConfig` / `AiGatewayProvider` | Route `@ai-sdk` models through the Cloudflare AI Gateway, via either a Workers `AI` binding or REST credentials (`accountId` / `gateway` / `token`). |
+| `KVCache` / `KVNamespace` / `KVCacheOptions` | Workers-KV cache-aside helper (key `appName+version+table_type_column`, sha256 for string ids, TTL clamped ≥60s). Set `appName` / `version` per application. |
+| `createStripeClient(secret, opts?)` / `verifyStripeWebhook(...)` / `CreateStripeClientOptions` | Workers-native Stripe client (fetch transport) + async webhook verification (SubtleCrypto). `apiVersion` optional (pin to a fixed Stripe API version). |
+
+### Data layer — `@rdlabo/workers-hono-kit/db`
+
+Requires the `drizzle-orm` and `mysql2` peers. Reads run against a replica via raw SQL; writes/transactions run against the primary through the Drizzle ORM with deadlock retry. The kit deliberately does not depend on the ORM's type identity — you pass the Drizzle instance in.
+
+| Export | Description |
+| --- | --- |
+| `createHyperdriveDatabase(options)` | `DisposableDatabase` that lazily opens primary/replica connections from Hyperdrive bindings per request; `dispose()` closes them. |
+| `createMysqlDatabase(options)` | Assemble a `Database` from an already-connected Drizzle ORM + replica `QueryRunner`. |
+| `Database` / `DisposableDatabase` / `QueryRunner` / `TxOf` | The `read` / `write` / `transaction` API and its supporting types. |
+| `hyperdriveConnectionOptions(hyperdrive, overrides?)` / `HyperdriveLike` / `ExecutionContextLike` | Build mysql2 `createConnection` options from a Hyperdrive binding (`disableEval`, `decimalNumbers`, `timezone '+09:00'` by default). |
+| `withMysqlConnections(...)` | Open primary/replica connections, run a function, close them in `finally` (via `ctx.waitUntil`). |
+| `retryWhenDeadlock(fn, retries?, delay?)` | Same deadlock-retry helper as the root export. |
+| `insertIdOf` / `affectedRowsOf` / `insertedIdsOf` / `DzWriteResult` | Extract `insertId` / `affectedRows` (and derive contiguous bulk-insert ids) from a mysql2 write result. |
+| `toJstDate` / `jstTimestampParams` / `jstDatetimeParams` / `jstDateParams` | JST date/time normalization applied at the Drizzle `customType` column boundary. |
+| `DRIZZLE_ORM_OPTIONS` / `honoDrizzleConfig(options)` / `HonoDrizzleConfigOptions` | Shared Drizzle casing (`snake_case`) for both the runtime `drizzle()` call and `drizzle.config.ts`, keeping config ↔ runtime in sync. |
+
+### Testing — `@rdlabo/workers-hono-kit/testing`
+
+Requires the `drizzle-orm` and `mysql2` peers. Consolidates duplicated test boilerplate.
+
+| Export | Description |
+| --- | --- |
+| `createTestDb(options)` / `TestDb` / `CreateTestDbOptions` / `TestDbConnection` | Test database built from committed Drizzle migrations as the single source of truth: `resetSchema` / `createTestPool` / `truncateAll` / `seed` / `mysqlReachable`. |
+| `FakeFirebaseVerifier` | In-memory `FirebaseVerifier` for offline route tests (`register` / `verifyIdToken` / `getUser` / `deleteUser`). |
+| `createPoolDatabase(options)` / `CreatePoolDatabaseOptions` | A `Database` backed by a single pool used as both primary and replica. |
+| `createNoopDatabase()` | A `Database` stub that throws on `write` / `transaction` to catch accidental DB use in DB-less routes. |
+| `authHeaders(token, opts?)` | Build interceptor-compatible auth headers for requests. |
+| `registerFirebaseToken(firebase, uid, record?, token?)` | Register a token in a `FakeFirebaseVerifier` (no DB). |
+| `provisionUser(pool, firebase, opts)` | Register a token and provision a conventional `users(id, firebase_uid, agree)` row; returns the user id (idempotent). |
+| `configurableFake(impl, name?)` | Build a test double from a partial implementation; un-stubbed members throw `"${name}.${method} not configured"`. |
+| `fakeApiList` / `fakePaymentIntent` / `fakeStripeEvent` / `fakeCheckoutSession` / `fakeCustomer` / `fakePrice` / `fakeSubscription` | Stripe object fixtures with sensible defaults, overridable per test. |
 
 ## Usage
 
@@ -144,8 +200,8 @@ return c.json(body, HttpStatus.CREATED);
 
 `createNestErrorHandler()` renders a thrown `HTTPException` as the NestJS exception-filter
 body, and `nestNotFoundHandler` gives the Express/Nest default 404. The defaults match the
-NestJS canonical shape (`{ statusCode, message, error? }`, `401` omits `error`); each repo
-keeps its own byte-parity via options.
+NestJS canonical shape (`{ statusCode, message, error? }`, `401` omits `error`); the options
+let you reproduce any byte-for-byte variation an existing API expects.
 
 ```ts
 import { createNestErrorHandler, nestNotFoundHandler } from '@rdlabo/workers-hono-kit';
@@ -153,7 +209,7 @@ import { createNestErrorHandler, nestNotFoundHandler } from '@rdlabo/workers-hon
 app.notFound(nestNotFoundHandler);
 app.onError(createNestErrorHandler());
 
-// Repo-specific parity deltas:
+// Application-specific parity deltas:
 app.onError(
   createNestErrorHandler({
     fieldOrder: 'message-first', // emit { message, error, statusCode } instead of statusCode-first
@@ -166,7 +222,7 @@ app.onError(
 ### Auth middleware
 
 Encodes the shared skeleton (read token header → verify → `getAppInfo` → resolve user id →
-set context, with `console.error` + a configurable failure on error). Inject the repo's
+set context, with `console.error` + a configurable failure on error). Inject your own
 verify/resolver, context-variable names, and failure mode.
 
 `createAuthMiddleware<Env, Verified, Id>` is generic over your Hono `Env`, so `c.set(...)` in
@@ -195,12 +251,55 @@ const tokenAuth = createAuthMiddleware<AppEnv, UserRecord>({
 });
 ```
 
+### AI Gateway
+
+Route `@ai-sdk` models through the Cloudflare AI Gateway — either with a Workers `AI` binding
+(production / `wrangler dev`) or with REST credentials (non-Workers contexts).
+
+```ts
+import { createAiGatewayProvider } from '@rdlabo/workers-hono-kit';
+import { openai } from '@ai-sdk/openai';
+
+// Binding form (Workers):
+const provider = createAiGatewayProvider({ binding: env.AI.gateway('my-gateway') });
+
+// REST form (anywhere):
+const rest = createAiGatewayProvider({
+  accountId: env.CF_ACCOUNT_ID,
+  gateway: 'my-gateway',
+  token: env.CF_AIG_TOKEN,
+});
+
+const model = provider.aigateway(openai('gpt-4o-mini'));
+```
+
+### MySQL data layer (Hyperdrive + Drizzle)
+
+```ts
+import { createHyperdriveDatabase, hyperdriveConnectionOptions } from '@rdlabo/workers-hono-kit/db';
+import { drizzle } from 'drizzle-orm/mysql2';
+import { DRIZZLE_ORM_OPTIONS } from '@rdlabo/workers-hono-kit/db';
+
+const db = createHyperdriveDatabase({
+  primaryHyperdrive: env.HYPERDRIVE,
+  replicaHyperdrive: env.HYPERDRIVE_REPLICA,
+  createOrm: (conn) => drizzle(conn, { ...DRIZZLE_ORM_OPTIONS, schema }),
+});
+
+try {
+  const rows = await db.read('SELECT * FROM users WHERE id = ?', [id]); // replica, raw SQL
+  await db.write((dz) => dz.insert(users).values({ name })); // primary, deadlock-retried
+} finally {
+  await db.dispose();
+}
+```
+
 ### KV cache
 
 ```ts
 import { KVCache } from '@rdlabo/workers-hono-kit';
 
-const cache = new KVCache(env.CACHE, { appName: 'myapp' }); // version defaults to 'v8_'
+const cache = new KVCache(env.CACHE, { appName: 'myapp' }); // version prefix defaults to 'v8_'
 await cache.set('users', 'byId', userId, user, 600);
 const hit = await cache.get<User>('users', 'byId', userId);
 ```
@@ -214,6 +313,21 @@ const stripe = createStripeClient(secret); // or { apiVersion: '2024-04-10' } to
 const event = await verifyStripeWebhook(secret, webhookSecret, rawBody, c.req.header('stripe-signature') ?? '');
 ```
 
+### Testing
+
+```ts
+import { createTestDb, FakeFirebaseVerifier, configurableFake } from '@rdlabo/workers-hono-kit/testing';
+
+const testDb = createTestDb({ dbName: 'myapp_test', migrationsFolder: './drizzle' });
+await testDb.resetSchema();
+const pool = testDb.createTestPool();
+
+const firebase = new FakeFirebaseVerifier();
+firebase.register('uid-1', { email: 'a@example.com' });
+
+const gateway = configurableFake<PaymentGateway>({ charge: async () => ({ ok: true }) }, 'PaymentGateway');
+```
+
 ## Local development / linking
 
 If you consume this package via a local path (e.g. `"@rdlabo/workers-hono-kit": "../../hono-kit"`) rather than from npm, TypeScript and esbuild resolve the package's bare imports from *its own* `node_modules`, which can create a second `zod` instance. That breaks types where your zod-inferred values flow into other libraries (e.g. Drizzle inserts). Dedupe with tsconfig `paths`:
@@ -240,6 +354,7 @@ npm install
 npm run typecheck   # tsc --noEmit
 npm run lint        # eslint
 npm test            # vitest
+npm run build       # tsc -p tsconfig.build.json → dist/
 ```
 
 ## License

package/dist/ai/gateway.d.ts

@@ -1,40 +1,78 @@
 import type { AiGateway, AiGatewayBindingSettings, AiGatewayOptions } from 'ai-gateway-provider';
 export type { AiGateway, AiGatewayOptions } from 'ai-gateway-provider';
-/** Workers の AI binding（`env.AI.gateway(name)`）の最小形。Cloudflare の `AiGateway` が構造的に適合する。 */
+/**
+ * Minimal shape of a Workers AI binding (`env.AI.gateway(name)`).
+ *
+ * @remarks
+ * Cloudflare's runtime `AiGateway` type is structurally compatible with this binding shape.
+ */
 export type AiGatewayBinding = AiGatewayBindingSettings['binding'];
 /**
- * AI Gateway 設定。2 系統:
- *  - binding 形: Workers ランタイム（本番 / `wrangler dev`）。`env.AI.gateway(name)` を渡す。
- *    binding 経由は同一アカウント内で事前認証されるため Gateway トークン不要。
- *  - REST 形: Workers 外（Node の eval ハーネス等、binding 不可）。accountId + gateway + token で REST。
+ * Configuration for the AI Gateway provider. This is a union with two mutually exclusive forms.
+ *
+ * @remarks
+ * - **Binding form** — for the Workers runtime (production and `wrangler dev`). Pass the
+ *   `env.AI.gateway(name)` binding. Requests through a binding are pre-authenticated within the same
+ *   Cloudflare account, so no Gateway token is required.
+ * - **REST form** — for non-Workers contexts where a binding is unavailable (e.g. a Node evaluation
+ *   harness). Supply `accountId`, `gateway`, and (for authenticated Gateways) `token` to reach the
+ *   Gateway over REST.
  */
 export type AiGatewayConfig = {
-    /** `env.AI.gateway(name)` 等の AI Gateway binding。 */
+    /** The AI Gateway binding, typically obtained via `env.AI.gateway(name)`. */
     binding: AiGatewayBinding;
-    /** キャッシュ / リトライ / メタデータ等の Gateway オプション（任意）。 */
+    /** Optional Gateway options such as caching, retries, and request metadata. */
     options?: AiGatewayOptions;
 } | {
-    /** Cloudflare アカウント ID。 */
+    /** Cloudflare account ID that owns the Gateway. */
     accountId: string;
-    /** AI Gateway 名。 */
+    /** AI Gateway name. */
     gateway: string;
     /**
-     * `cf-aig-authorization` に載せる Gateway 認証トークン。Authenticated Gateway のときだけ必要。
-     * unauthenticated Gateway では省略可（プロバイダの API キーではなく Gateway 自体への認証）。
+     * Gateway authentication token sent in the `cf-aig-authorization` header. Required only for an
+     * Authenticated Gateway; omit it for an unauthenticated Gateway. This authenticates the request to
+     * the Gateway itself and is distinct from any provider API key.
      */
     token?: string;
-    /** キャッシュ / リトライ / メタデータ等の Gateway オプション（任意）。 */
+    /** Optional Gateway options such as caching, retries, and request metadata. */
     options?: AiGatewayOptions;
 };
+/** Provider object exposing the AI Gateway model wrapper. */
 export interface AiGatewayProvider {
     /**
-     * `@ai-sdk/*` のモデルを包んで AI Gateway 経由にする。
-     * 例: `aigateway(createAnthropic({ apiKey }).('claude-...'))`。
-     * 配列を渡すとフォールバック（先頭から順に試行）になる。
+     * Wraps an `@ai-sdk/*` model so its requests are routed through the AI Gateway.
+     *
+     * @remarks
+     * Example invocation: `aigateway(createAnthropic({ apiKey })('claude-...'))`. Passing an array of
+     * models enables fallback behavior — each model is attempted in order from the start of the array.
      */
     aigateway: AiGateway;
 }
 /**
- * AI Gateway 用のプロバイダを生成する。binding 形 / REST 形のどちらでも可（欠落時は fail-fast）。
+ * Create an AI Gateway provider from either the binding form or the REST form of the configuration.
+ *
+ * @param config - The Gateway configuration; either the binding form or the REST form.
+ * @returns A provider whose `aigateway` wrapper routes models through the AI Gateway.
+ * @throws Error When the REST form is used and `accountId` or `gateway` is missing (fail-fast).
+ * @example
+ * ```ts
+ * // Binding form (Workers runtime: production / wrangler dev)
+ * import { createAnthropic } from '@ai-sdk/anthropic';
+ *
+ * const { aigateway } = createAiGatewayProvider({ binding: env.AI.gateway('my-gateway') });
+ * const model = aigateway(createAnthropic({ apiKey: env.ANTHROPIC_API_KEY })('claude-3-5-sonnet-latest'));
+ * ```
+ * @example
+ * ```ts
+ * // REST form (non-Workers context, e.g. a Node evaluation harness)
+ * import { createOpenAI } from '@ai-sdk/openai';
+ *
+ * const { aigateway } = createAiGatewayProvider({
+ *   accountId: process.env.CF_ACCOUNT_ID!,
+ *   gateway: 'my-gateway',
+ *   token: process.env.CF_AIG_TOKEN, // only for an Authenticated Gateway
+ * });
+ * const model = aigateway(createOpenAI({ apiKey: process.env.OPENAI_API_KEY })('gpt-4o'));
+ * ```
  */
 export declare function createAiGatewayProvider(config: AiGatewayConfig): AiGatewayProvider;

package/dist/ai/gateway.js

@@ -1,30 +1,55 @@
 /**
- * Cloudflare AI Gateway のプロバイダ生成（`ai` SDK + `ai-gateway-provider`）。
- * フリート共通 = foodlabel / winecode / receptray hono の AI 呼び出しを必ず Gateway 経由にする。
+ * Cloudflare AI Gateway provider factory built on the Vercel AI SDK and `ai-gateway-provider`.
  *
- * `createAiGateway` が返す wrapper で `@ai-sdk/*` のモデルを包むと、SDK が組み立てた
- * プロバイダ宛リクエスト（api.openai.com / api.anthropic.com / *-aiplatform.googleapis.com 等）を
- * AI Gateway の Universal Endpoint 経由に差し替える。OpenAI / Anthropic / Google Vertex(SA) の
- * いずれも同じ `aigateway(model)` で透過的にルーティングされる（Vertex も対応）。
+ * Routes OpenAI, Anthropic, and Google Vertex `@ai-sdk/*` models through the AI Gateway Universal
+ * Endpoint. The wrapper returned by `createAiGateway` intercepts the provider-bound requests the SDK
+ * assembles (`api.openai.com`, `api.anthropic.com`, `*-aiplatform.googleapis.com`, etc.) and redirects
+ * them through the Gateway. Every provider is routed transparently via the same `aigateway(model)` call.
  *
- * ここはインフラ層（Gateway 識別子と認証トークンの注入だけ）。プロバイダの API キーや
- * Vertex の SA 認証情報は各 repo 側でモデル生成時に渡す（pass-through）。
+ * @remarks
+ * This module is purely the infrastructure layer: it injects only the Gateway identifier and (optionally)
+ * the Gateway authentication token. Provider API keys and Vertex service-account credentials are supplied
+ * by the caller at model-construction time and passed through untouched.
  */
 import { createAiGateway } from 'ai-gateway-provider';
 /**
- * AI Gateway 用のプロバイダを生成する。binding 形 / REST 形のどちらでも可（欠落時は fail-fast）。
+ * Create an AI Gateway provider from either the binding form or the REST form of the configuration.
+ *
+ * @param config - The Gateway configuration; either the binding form or the REST form.
+ * @returns A provider whose `aigateway` wrapper routes models through the AI Gateway.
+ * @throws Error When the REST form is used and `accountId` or `gateway` is missing (fail-fast).
+ * @example
+ * ```ts
+ * // Binding form (Workers runtime: production / wrangler dev)
+ * import { createAnthropic } from '@ai-sdk/anthropic';
+ *
+ * const { aigateway } = createAiGatewayProvider({ binding: env.AI.gateway('my-gateway') });
+ * const model = aigateway(createAnthropic({ apiKey: env.ANTHROPIC_API_KEY })('claude-3-5-sonnet-latest'));
+ * ```
+ * @example
+ * ```ts
+ * // REST form (non-Workers context, e.g. a Node evaluation harness)
+ * import { createOpenAI } from '@ai-sdk/openai';
+ *
+ * const { aigateway } = createAiGatewayProvider({
+ *   accountId: process.env.CF_ACCOUNT_ID!,
+ *   gateway: 'my-gateway',
+ *   token: process.env.CF_AIG_TOKEN, // only for an Authenticated Gateway
+ * });
+ * const model = aigateway(createOpenAI({ apiKey: process.env.OPENAI_API_KEY })('gpt-4o'));
+ * ```
  */
 export function createAiGatewayProvider(config) {
     if ('binding' in config) {
         return { aigateway: createAiGateway({ binding: config.binding, options: config.options }) };
     }
     if (!config.accountId) {
-        throw new Error('AI Gateway: accountId が未設定です');
+        throw new Error('AI Gateway: accountId is not set');
     }
     if (!config.gateway) {
-        throw new Error('AI Gateway: gateway 名が未設定です');
+        throw new Error('AI Gateway: gateway name is not set');
     }
-    // token は Authenticated Gateway のときだけ apiKey として送る。unauthenticated では undefined で可。
+    // The token is sent as apiKey only for an Authenticated Gateway; undefined is fine when unauthenticated.
     return {
         aigateway: createAiGateway({
             accountId: config.accountId,

package/dist/aws/cloudfront.d.ts

@@ -1,9 +1,27 @@
 /**
- * CloudFront 署名付き URL 生成（`@aws-sdk/cloudfront-signer` の getSignedUrl を Web Crypto で再実装）。
- * Cloudflare Workers ネイティブ（aws-sdk 不要）。フリート共通 = tipsys/winecode hono。
+ * Generate a CloudFront signed URL using a canned policy, implemented natively for Cloudflare Workers.
  *
- * canned policy を RSASSA-PKCS1-v1_5 + SHA-1 で署名し、AWS の URL-safe base64 変換
- *   '+' -> '-' , '/' -> '~' , '=' -> '_'
- * を施して `Expires` / `Key-Pair-Id` / `Signature` の順でクエリを付与する（aws-sdk の出力とバイト一致）。
+ * Reimplements `getSignedUrl` from `@aws-sdk/cloudfront-signer` on top of the Web Crypto API, so no
+ * `@aws-sdk` dependency is required. The canned policy is signed with RSASSA-PKCS1-v1_5 and SHA-1, the
+ * signature is converted to AWS URL-safe base64 (`+` -> `-`, `/` -> `~`, `=` -> `_`), and the query
+ * parameters are appended in the order `Expires`, `Key-Pair-Id`, `Signature`.
+ *
+ * @remarks
+ * The output is byte-for-byte identical to that of `@aws-sdk/cloudfront-signer`.
+ *
+ * @param url - The resource URL to sign.
+ * @param privateKeyPem - The CloudFront key group private key in PKCS#8 PEM format.
+ * @param keyPairId - The CloudFront public key (key pair) ID associated with the private key.
+ * @param dateLessThan - Expiry time, accepted as a `Date`, epoch-millisecond number, or date string.
+ * @returns The signed URL with the `Expires`, `Key-Pair-Id`, and `Signature` query parameters appended.
+ * @example
+ * ```ts
+ * const signedUrl = await getCloudFrontSignedUrl(
+ *   'https://cdn.example.com/private/video.mp4',
+ *   env.CLOUDFRONT_PRIVATE_KEY,
+ *   env.CLOUDFRONT_KEY_PAIR_ID,
+ *   Date.now() + 60 * 60 * 1000, // valid for one hour
+ * );
+ * ```
  */
 export declare function getCloudFrontSignedUrl(url: string, privateKeyPem: string, keyPairId: string, dateLessThan: string | number | Date): Promise<string>;

package/dist/aws/cloudfront.js

@@ -1,10 +1,28 @@
 /**
- * CloudFront 署名付き URL 生成（`@aws-sdk/cloudfront-signer` の getSignedUrl を Web Crypto で再実装）。
- * Cloudflare Workers ネイティブ（aws-sdk 不要）。フリート共通 = tipsys/winecode hono。
+ * Generate a CloudFront signed URL using a canned policy, implemented natively for Cloudflare Workers.
  *
- * canned policy を RSASSA-PKCS1-v1_5 + SHA-1 で署名し、AWS の URL-safe base64 変換
- *   '+' -> '-' , '/' -> '~' , '=' -> '_'
- * を施して `Expires` / `Key-Pair-Id` / `Signature` の順でクエリを付与する（aws-sdk の出力とバイト一致）。
+ * Reimplements `getSignedUrl` from `@aws-sdk/cloudfront-signer` on top of the Web Crypto API, so no
+ * `@aws-sdk` dependency is required. The canned policy is signed with RSASSA-PKCS1-v1_5 and SHA-1, the
+ * signature is converted to AWS URL-safe base64 (`+` -> `-`, `/` -> `~`, `=` -> `_`), and the query
+ * parameters are appended in the order `Expires`, `Key-Pair-Id`, `Signature`.
+ *
+ * @remarks
+ * The output is byte-for-byte identical to that of `@aws-sdk/cloudfront-signer`.
+ *
+ * @param url - The resource URL to sign.
+ * @param privateKeyPem - The CloudFront key group private key in PKCS#8 PEM format.
+ * @param keyPairId - The CloudFront public key (key pair) ID associated with the private key.
+ * @param dateLessThan - Expiry time, accepted as a `Date`, epoch-millisecond number, or date string.
+ * @returns The signed URL with the `Expires`, `Key-Pair-Id`, and `Signature` query parameters appended.
+ * @example
+ * ```ts
+ * const signedUrl = await getCloudFrontSignedUrl(
+ *   'https://cdn.example.com/private/video.mp4',
+ *   env.CLOUDFRONT_PRIVATE_KEY,
+ *   env.CLOUDFRONT_KEY_PAIR_ID,
+ *   Date.now() + 60 * 60 * 1000, // valid for one hour
+ * );
+ * ```
  */
 export async function getCloudFrontSignedUrl(url, privateKeyPem, keyPairId, dateLessThan) {
     const epochSeconds = Math.round(new Date(dateLessThan).getTime() / 1000);
@@ -15,12 +33,26 @@ export async function getCloudFrontSignedUrl(url, privateKeyPem, keyPairId, date
     const signatureBuffer = await crypto.subtle.sign({ name: 'RSASSA-PKCS1-v1_5' }, key, new TextEncoder().encode(policy));
     const signature = toUrlSafeBase64(arrayBufferToBase64(signatureBuffer));
     const separator = url.includes('?') ? '&' : '?';
-    // @aws-sdk/cloudfront-signer のクエリ順: Expires -> Key-Pair-Id -> Signature
+    // Query order used by @aws-sdk/cloudfront-signer: Expires -> Key-Pair-Id -> Signature
     return `${url}${separator}Expires=${epochSeconds}&Key-Pair-Id=${keyPairId}&Signature=${signature}`;
 }
+/**
+ * Convert standard base64 to the URL-safe alphabet expected in CloudFront signatures.
+ *
+ * @param value - A standard base64 string.
+ * @returns The base64 string with `+` -> `-`, `=` -> `_`, and `/` -> `~`.
+ * @internal
+ */
 function toUrlSafeBase64(value) {
     return value.replace(/\+/g, '-').replace(/=/g, '_').replace(/\//g, '~');
 }
+/**
+ * Encode an `ArrayBuffer` to standard base64.
+ *
+ * @param buffer - The raw bytes to encode.
+ * @returns The standard base64 representation of the buffer.
+ * @internal
+ */
 function arrayBufferToBase64(buffer) {
     const bytes = new Uint8Array(buffer);
     let binary = '';
@@ -29,6 +61,13 @@ function arrayBufferToBase64(buffer) {
     }
     return btoa(binary);
 }
+/**
+ * Decode a PKCS#8 PEM private key into its DER `ArrayBuffer`.
+ *
+ * @param pem - The PEM-encoded key, including the BEGIN/END armor.
+ * @returns The decoded DER bytes, suitable for `crypto.subtle.importKey('pkcs8', ...)`.
+ * @internal
+ */
 function pemToDer(pem) {
     const base64 = pem
         .replace(/-----BEGIN [^-]+-----/, '')

package/dist/aws/secrets-manager.d.ts

@@ -1,14 +1,48 @@
 /**
- * AWS Secrets Manager の GetSecretValue を aws4fetch（SigV4 署名 fetch）で叩く汎用ヘルパ。
- * Cloudflare Workers には AWS SDK も IAM ロールも無いため、AWS の静的キーを Workers secrets として
- * 渡して署名する（移植元 `api/src/secrets-manager.ts` 相当）。DB 認証情報は Hyperdrive 側に持つので対象外。
+ * AWS credentials used to sign Secrets Manager requests.
  *
- * Secret の中身（スキーマ）と secretId は repo ごとに異なるため、`<T>` と `secretId` を呼び出し側が渡す。
+ * @remarks
+ * Cloudflare Workers have neither the AWS SDK nor IAM role credentials, so static AWS keys are supplied
+ * as Workers secrets and used to produce a SigV4 signature.
  */
 export interface AwsSecretsOptions {
+    /** AWS access key ID. */
     accessKeyId: string;
+    /** AWS secret access key. */
     secretAccessKey: string;
+    /** Optional STS session token, required when using temporary credentials. */
     sessionToken?: string;
+    /** AWS region of the Secrets Manager endpoint, e.g. `ap-northeast-1`. */
     region: string;
 }
+/**
+ * Fetch and parse a secret from AWS Secrets Manager, caching the result per isolate.
+ *
+ * Issues a `GetSecretValue` call to Secrets Manager via a SigV4-signed `fetch` (using aws4fetch), with no
+ * AWS SDK involved. The parsed `SecretString` is cached per isolate keyed by region, access key ID, and
+ * secret ID; concurrent first-time callers share one in-flight request, and a rejected fetch clears the
+ * cache entry so the next call retries.
+ *
+ * @typeParam T - The shape of the JSON-parsed secret payload, supplied by the caller.
+ * @param options - AWS credentials and region used to sign the request.
+ * @param secretId - The Secrets Manager secret ID or ARN to retrieve.
+ * @returns The parsed secret value cast to `T`.
+ * @throws Error When the Secrets Manager response is not OK, or when it contains no `SecretString`.
+ * @example
+ * ```ts
+ * interface DbSecret {
+ *   username: string;
+ *   password: string;
+ * }
+ *
+ * const secret = await getAuthenticationSecret<DbSecret>(
+ *   {
+ *     accessKeyId: env.AWS_ACCESS_KEY_ID,
+ *     secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
+ *     region: 'ap-northeast-1',
+ *   },
+ *   'prod/db/credentials',
+ * );
+ * ```
+ */
 export declare function getAuthenticationSecret<T>(options: AwsSecretsOptions, secretId: string): Promise<T>;

package/dist/aws/secrets-manager.js

@@ -1,10 +1,46 @@
 import { AwsClient } from 'aws4fetch';
 /**
- * Per-isolate cache: Secrets Manager は isolate ごと 1 回だけ叩く。region+accessKeyId+secretId を
- * キーにし、資格情報ローテーション時は再取得する。promise をキャッシュして同時初回リクエストが 1 回の
- * 呼び出しを共有する。reject 時はキャッシュをクリアして retry を許す。
+ * Per-isolate cache for the fetched secret.
+ *
+ * @remarks
+ * Secrets Manager is queried at most once per isolate. The entry is keyed by
+ * `region:accessKeyId:secretId`, so rotating credentials triggers a fresh fetch. The in-flight promise
+ * itself is cached so that concurrent first-time callers share a single request. On rejection the cache
+ * is cleared so a failed fetch can be retried.
+ *
+ * @internal
  */
 let cache = null;
+/**
+ * Fetch and parse a secret from AWS Secrets Manager, caching the result per isolate.
+ *
+ * Issues a `GetSecretValue` call to Secrets Manager via a SigV4-signed `fetch` (using aws4fetch), with no
+ * AWS SDK involved. The parsed `SecretString` is cached per isolate keyed by region, access key ID, and
+ * secret ID; concurrent first-time callers share one in-flight request, and a rejected fetch clears the
+ * cache entry so the next call retries.
+ *
+ * @typeParam T - The shape of the JSON-parsed secret payload, supplied by the caller.
+ * @param options - AWS credentials and region used to sign the request.
+ * @param secretId - The Secrets Manager secret ID or ARN to retrieve.
+ * @returns The parsed secret value cast to `T`.
+ * @throws Error When the Secrets Manager response is not OK, or when it contains no `SecretString`.
+ * @example
+ * ```ts
+ * interface DbSecret {
+ *   username: string;
+ *   password: string;
+ * }
+ *
+ * const secret = await getAuthenticationSecret<DbSecret>(
+ *   {
+ *     accessKeyId: env.AWS_ACCESS_KEY_ID,
+ *     secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
+ *     region: 'ap-northeast-1',
+ *   },
+ *   'prod/db/credentials',
+ * );
+ * ```
+ */
 export function getAuthenticationSecret(options, secretId) {
     const key = `${options.region}:${options.accessKeyId}:${secretId}`;
     if (cache?.key !== key) {
@@ -16,6 +52,15 @@ export function getAuthenticationSecret(options, secretId) {
     }
     return cache.value;
 }
+/**
+ * Perform the SigV4-signed `GetSecretValue` request and parse the returned `SecretString`.
+ *
+ * @param options - AWS credentials and region used to sign the request.
+ * @param secretId - The Secrets Manager secret ID or ARN to retrieve.
+ * @returns The JSON-parsed secret payload.
+ * @throws Error When the response is not OK, or when it contains no `SecretString`.
+ * @internal
+ */
 async function fetchSecret(options, secretId) {
     const aws = new AwsClient({
         accessKeyId: options.accessKeyId,