@rdlabo/workers-hono-kit 0.1.0 → 0.2.1

package/dist/testing/fakes.js

@@ -1,14 +1,37 @@
-import { databaseFrom } from '../db/database';
+import { databaseFrom } from '../db/database.js';
 /**
- * オフライン route テスト用の in-memory FirebaseVerifier（4 repo 同一実装を集約）。
- * `register(token, { uid })` で偽 ID を仕込む。
+ * In-memory {@link FirebaseVerifier} implementation for offline route tests.
+ *
+ * Seed fake identities with {@link FakeFirebaseVerifier.register | register(token, { uid })}, then
+ * verification resolves the registered decoded token instead of calling a real Firebase backend.
+ *
+ * @example
+ * ```ts
+ * const firebase = new FakeFirebaseVerifier();
+ * firebase.register('tok-1', { uid: 'uid-1' });
+ * const decoded = await firebase.verifyIdToken('tok-1'); // { uid: 'uid-1' }
+ * ```
  */
 export class FakeFirebaseVerifier {
     tokens = new Map();
+    /** UIDs passed to {@link FakeFirebaseVerifier.deleteUser}, in call order, for assertions. */
     deleted = [];
+    /**
+     * Register a fake decoded token so that {@link FakeFirebaseVerifier.verifyIdToken} resolves it.
+     *
+     * @param token - Token string clients will present.
+     * @param record - Decoded token returned on verification (must include `uid`).
+     */
     register(token, record) {
         this.tokens.set(token, record);
     }
+    /**
+     * Resolve the decoded token previously registered for `idToken`.
+     *
+     * @param idToken - Token string to verify.
+     * @returns The registered decoded token.
+     * @throws Error if the token was never registered.
+     */
     async verifyIdToken(idToken) {
         const record = this.tokens.get(idToken);
         if (!record) {
@@ -16,16 +39,42 @@ export class FakeFirebaseVerifier {
         }
         return record;
     }
+    /**
+     * Return a minimal user record echoing the requested UID.
+     *
+     * @param uid - UID to look up.
+     * @returns An object containing the `uid` (never `null` in this fake).
+     */
     async getUser(uid) {
         return { uid };
     }
+    /**
+     * Record a user deletion by appending the UID to {@link FakeFirebaseVerifier.deleted}.
+     *
+     * @param uid - UID being deleted.
+     */
     async deleteUser(uid) {
         this.deleted.push(uid);
     }
 }
 /**
- * テスト用にプール 1 本を primary/replica 兼用にした Database（foodlabel の PoolDatabase 相当）。
- * `dispose()` はプールを閉じる。orm は消費側が自分の drizzle-orm で作って渡す（型同一性の分離）。
+ * Create a `Database` backed by a single pool used as both primary and replica, suitable for tests.
+ *
+ * @remarks
+ * `dispose()` ends the pool. The `orm` is provided by the caller (rather than constructed here) so
+ * the returned database uses the consumer's own `drizzle-orm` types, avoiding type-identity clashes
+ * across duplicated `drizzle-orm` installs.
+ *
+ * @typeParam TDrizzle - The Drizzle instance type provided by the consumer.
+ * @param options - Pool and Drizzle instance. See {@link CreatePoolDatabaseOptions}.
+ * @returns A {@link DisposableDatabase} whose `dispose()` closes the pool.
+ * @example
+ * ```ts
+ * const pool = testDb.createTestPool();
+ * const db = createPoolDatabase({ pool, orm: drizzle(pool, { schema }) });
+ * // ... run tests ...
+ * await db.dispose();
+ * ```
  */
 export function createPoolDatabase(options) {
     const { pool, orm } = options;
@@ -38,9 +87,22 @@ export function createPoolDatabase(options) {
     };
 }
 /**
- * DB に触れない route（GET / 等）用の Database スタブ。write/transaction は誤用検知のため throw。
- * dispose は no-op（Hyperdrive/Pool 背面の DisposableDatabase を期待する repo でもそのまま使える）。
- * orm 型は呼び出し側が指定（既定 unknown）。
+ * Create a no-op `Database` stub for routes that never touch the database (e.g. plain GET handlers).
+ *
+ * @remarks
+ * `read` resolves to an empty array, while `write` and `transaction` throw so that any unexpected
+ * database access is caught as a misuse. `dispose` is a no-op, so this can stand in for a
+ * {@link DisposableDatabase} backing (e.g. a Hyperdrive- or pool-based one) without changes.
+ *
+ * @typeParam TDrizzle - The Drizzle instance type the consumer expects (defaults to `unknown`).
+ * @returns A {@link DisposableDatabase} that reads empty and throws on writes/transactions.
+ * @throws Error from `write`/`transaction` if they are accessed.
+ * @example
+ * ```ts
+ * const db = createNoopDatabase();
+ * await db.read('SELECT 1'); // []
+ * await db.write(async (dz) => dz); // throws: noopDatabase.write accessed unexpectedly
+ * ```
  */
 export function createNoopDatabase() {
     return {

package/dist/testing/index.d.ts

@@ -1,8 +1,15 @@
-export { createTestDb } from './db';
-export type { TestDb, CreateTestDbOptions, TestDbConnection } from './db';
-export { FakeFirebaseVerifier, createPoolDatabase, createNoopDatabase } from './fakes';
-export type { CreatePoolDatabaseOptions } from './fakes';
-export type { Database, DisposableDatabase, QueryRunner, TxOf } from '../db/database';
-export { authHeaders, registerFirebaseToken, provisionUser } from './auth';
-export { configurableFake } from './configurable-fake';
-export { fakeApiList, fakePaymentIntent, fakeStripeEvent, fakeCheckoutSession, fakeCustomer, fakePrice, fakeSubscription, } from './stripe-fixtures';
+/**
+ * Shared test infrastructure for Hono on Cloudflare Workers projects (depends on `mysql2`/`drizzle-orm`).
+ *
+ * Test-only helpers that are never loaded at runtime. This subpath consolidates the duplicated
+ * test boilerplate (test DB setup, in-memory fakes, auth header builders, Stripe fixtures) that
+ * tends to be copy-pasted across projects into a single, importable surface.
+ */
+export { createTestDb } from './db.js';
+export type { TestDb, CreateTestDbOptions, TestDbConnection } from './db.js';
+export { FakeFirebaseVerifier, createPoolDatabase, createNoopDatabase } from './fakes.js';
+export type { CreatePoolDatabaseOptions } from './fakes.js';
+export type { Database, DisposableDatabase, QueryRunner, TxOf } from '../db/database.js';
+export { authHeaders, registerFirebaseToken, provisionUser } from './auth.js';
+export { configurableFake } from './configurable-fake.js';
+export { fakeApiList, fakePaymentIntent, fakeStripeEvent, fakeCheckoutSession, fakeCustomer, fakePrice, fakeSubscription, } from './stripe-fixtures.js';

package/dist/testing/index.js

@@ -1,10 +1,15 @@
-// @rdlabo/workers-hono-kit/testing — フリート共通のテスト基盤（mysql2/drizzle 依存）。
-// 実行時には読み込まれないテスト専用ヘルパ。各 repo の testing/db.ts・fakes.ts を集約。
-export { createTestDb } from './db';
-export { FakeFirebaseVerifier, createPoolDatabase, createNoopDatabase } from './fakes';
-// 認証テストヘルパ（route spec のヘッダ生成・ユーザ provision を集約）。
-export { authHeaders, registerFirebaseToken, provisionUser } from './auth';
-// test double ヘルパ（未設定メソッドで明示 throw する部分実装 fake）。
-export { configurableFake } from './configurable-fake';
-// Stripe オブジェクトの test fixture factory。
-export { fakeApiList, fakePaymentIntent, fakeStripeEvent, fakeCheckoutSession, fakeCustomer, fakePrice, fakeSubscription, } from './stripe-fixtures';
+/**
+ * Shared test infrastructure for Hono on Cloudflare Workers projects (depends on `mysql2`/`drizzle-orm`).
+ *
+ * Test-only helpers that are never loaded at runtime. This subpath consolidates the duplicated
+ * test boilerplate (test DB setup, in-memory fakes, auth header builders, Stripe fixtures) that
+ * tends to be copy-pasted across projects into a single, importable surface.
+ */
+export { createTestDb } from './db.js';
+export { FakeFirebaseVerifier, createPoolDatabase, createNoopDatabase } from './fakes.js';
+// Authentication test helpers (route-spec header builders and user provisioning).
+export { authHeaders, registerFirebaseToken, provisionUser } from './auth.js';
+// Test double helper (partial-implementation fake that throws explicitly on unconfigured members).
+export { configurableFake } from './configurable-fake.js';
+// Test fixture factories for Stripe objects.
+export { fakeApiList, fakePaymentIntent, fakeStripeEvent, fakeCheckoutSession, fakeCustomer, fakePrice, fakeSubscription, } from './stripe-fixtures.js';

package/dist/testing/stripe-fixtures.d.ts

@@ -1,13 +1,103 @@
 import type Stripe from 'stripe';
 /**
- * Stripe オブジェクトの test fixture factory。実 SDK 型は巨大なので、テストが参照する範囲だけを
- * 妥当な既定値で組み、`over` で上書きする（最後に 1 度だけ Stripe 型へキャスト）。fleet 各 repo の
- * 課金テストで同じダミー PaymentIntent/Event/... を手組みしていた重複を集約する。
+ * Test fixture factories for Stripe objects.
+ *
+ * The real SDK types are enormous, so each factory builds only the fields tests typically read,
+ * fills them with reasonable defaults, lets you override via `over`, and casts to the Stripe type
+ * once at the end. This consolidates the duplicated hand-built dummy `PaymentIntent`/`Event`/... that
+ * billing tests tend to reconstruct in every project.
+ */
+/**
+ * Build a fake Stripe `ApiList` wrapping the given data.
+ *
+ * @remarks Defaults: `object: 'list'`, `has_more: false`, `url: '/v1/_test'`.
+ * @typeParam T - Element type of the list.
+ * @param data - Items to place in `data`.
+ * @param over - Field overrides merged last.
+ * @returns A `Stripe.ApiList<T>` fixture.
+ * @example
+ * ```ts
+ * const list = fakeApiList([fakePaymentIntent()]);
+ * ```
  */
 export declare function fakeApiList<T>(data: T[], over?: Partial<Stripe.ApiList<T>>): Stripe.ApiList<T>;
+/**
+ * Build a fake Stripe `PaymentIntent`.
+ *
+ * @remarks Defaults: `id: 'pi_test_1'`, `object: 'payment_intent'`, `amount: 1000`, `currency: 'jpy'`,
+ * `status: 'succeeded'`, `created: 1_700_000_000`.
+ * @param over - Field overrides merged last.
+ * @returns A `Stripe.PaymentIntent` fixture.
+ * @example
+ * ```ts
+ * const pi = fakePaymentIntent({ status: 'requires_payment_method' });
+ * ```
+ */
 export declare function fakePaymentIntent(over?: Partial<Stripe.PaymentIntent>): Stripe.PaymentIntent;
+/**
+ * Build a fake Stripe webhook `Event` wrapping the given payload.
+ *
+ * @remarks Defaults: `id: 'evt_test_1'`, `object: 'event'`, `api_version: '2024-06-20'`,
+ * `created: 1_700_000_000`, `livemode: false`. The payload is placed at `data.object`.
+ * @param type - Event type (e.g. `'payment_intent.succeeded'`), assigned to `type`.
+ * @param dataObject - The object placed at `data.object`.
+ * @param over - Field overrides merged last.
+ * @returns A `Stripe.Event` fixture.
+ * @example
+ * ```ts
+ * const event = fakeStripeEvent('payment_intent.succeeded', fakePaymentIntent());
+ * ```
+ */
 export declare function fakeStripeEvent(type: string, dataObject: unknown, over?: Partial<Stripe.Event>): Stripe.Event;
+/**
+ * Build a fake Stripe `Checkout.Session`.
+ *
+ * @remarks Defaults: `id: 'cs_test_1'`, `object: 'checkout.session'`,
+ * `url: 'https://checkout.stripe.test/cs_test_1'`, `mode: 'subscription'`, `status: 'open'`.
+ * @param over - Field overrides merged last.
+ * @returns A `Stripe.Checkout.Session` fixture.
+ * @example
+ * ```ts
+ * const session = fakeCheckoutSession({ status: 'complete' });
+ * ```
+ */
 export declare function fakeCheckoutSession(over?: Partial<Stripe.Checkout.Session>): Stripe.Checkout.Session;
+/**
+ * Build a fake Stripe `Customer`.
+ *
+ * @remarks Defaults: `id: 'cus_test_1'`, `object: 'customer'`, `created: 1_700_000_000`,
+ * `livemode: false`.
+ * @param over - Field overrides merged last.
+ * @returns A `Stripe.Customer` fixture.
+ * @example
+ * ```ts
+ * const customer = fakeCustomer({ email: 'a@example.com' });
+ * ```
+ */
 export declare function fakeCustomer(over?: Partial<Stripe.Customer>): Stripe.Customer;
+/**
+ * Build a fake Stripe `Price`.
+ *
+ * @remarks Defaults: `id: 'price_test_1'`, `object: 'price'`, `active: true`, `currency: 'jpy'`,
+ * `unit_amount: 1000`.
+ * @param over - Field overrides merged last.
+ * @returns A `Stripe.Price` fixture.
+ * @example
+ * ```ts
+ * const price = fakePrice({ unit_amount: 2000 });
+ * ```
+ */
 export declare function fakePrice(over?: Partial<Stripe.Price>): Stripe.Price;
+/**
+ * Build a fake Stripe `Subscription`.
+ *
+ * @remarks Defaults: `id: 'sub_test_1'`, `object: 'subscription'`, `status: 'active'`,
+ * `customer: 'cus_test_1'`, `created: 1_700_000_000`.
+ * @param over - Field overrides merged last.
+ * @returns A `Stripe.Subscription` fixture.
+ * @example
+ * ```ts
+ * const sub = fakeSubscription({ status: 'canceled' });
+ * ```
+ */
 export declare function fakeSubscription(over?: Partial<Stripe.Subscription>): Stripe.Subscription;

package/dist/testing/stripe-fixtures.js

@@ -1,7 +1,23 @@
 /**
- * Stripe オブジェクトの test fixture factory。実 SDK 型は巨大なので、テストが参照する範囲だけを
- * 妥当な既定値で組み、`over` で上書きする（最後に 1 度だけ Stripe 型へキャスト）。fleet 各 repo の
- * 課金テストで同じダミー PaymentIntent/Event/... を手組みしていた重複を集約する。
+ * Test fixture factories for Stripe objects.
+ *
+ * The real SDK types are enormous, so each factory builds only the fields tests typically read,
+ * fills them with reasonable defaults, lets you override via `over`, and casts to the Stripe type
+ * once at the end. This consolidates the duplicated hand-built dummy `PaymentIntent`/`Event`/... that
+ * billing tests tend to reconstruct in every project.
+ */
+/**
+ * Build a fake Stripe `ApiList` wrapping the given data.
+ *
+ * @remarks Defaults: `object: 'list'`, `has_more: false`, `url: '/v1/_test'`.
+ * @typeParam T - Element type of the list.
+ * @param data - Items to place in `data`.
+ * @param over - Field overrides merged last.
+ * @returns A `Stripe.ApiList<T>` fixture.
+ * @example
+ * ```ts
+ * const list = fakeApiList([fakePaymentIntent()]);
+ * ```
  */
 export function fakeApiList(data, over = {}) {
     return {
@@ -12,6 +28,18 @@ export function fakeApiList(data, over = {}) {
         ...over,
     };
 }
+/**
+ * Build a fake Stripe `PaymentIntent`.
+ *
+ * @remarks Defaults: `id: 'pi_test_1'`, `object: 'payment_intent'`, `amount: 1000`, `currency: 'jpy'`,
+ * `status: 'succeeded'`, `created: 1_700_000_000`.
+ * @param over - Field overrides merged last.
+ * @returns A `Stripe.PaymentIntent` fixture.
+ * @example
+ * ```ts
+ * const pi = fakePaymentIntent({ status: 'requires_payment_method' });
+ * ```
+ */
 export function fakePaymentIntent(over = {}) {
     return {
         id: 'pi_test_1',
@@ -23,6 +51,20 @@ export function fakePaymentIntent(over = {}) {
         ...over,
     };
 }
+/**
+ * Build a fake Stripe webhook `Event` wrapping the given payload.
+ *
+ * @remarks Defaults: `id: 'evt_test_1'`, `object: 'event'`, `api_version: '2024-06-20'`,
+ * `created: 1_700_000_000`, `livemode: false`. The payload is placed at `data.object`.
+ * @param type - Event type (e.g. `'payment_intent.succeeded'`), assigned to `type`.
+ * @param dataObject - The object placed at `data.object`.
+ * @param over - Field overrides merged last.
+ * @returns A `Stripe.Event` fixture.
+ * @example
+ * ```ts
+ * const event = fakeStripeEvent('payment_intent.succeeded', fakePaymentIntent());
+ * ```
+ */
 export function fakeStripeEvent(type, dataObject, over = {}) {
     return {
         id: 'evt_test_1',
@@ -35,6 +77,18 @@ export function fakeStripeEvent(type, dataObject, over = {}) {
         ...over,
     };
 }
+/**
+ * Build a fake Stripe `Checkout.Session`.
+ *
+ * @remarks Defaults: `id: 'cs_test_1'`, `object: 'checkout.session'`,
+ * `url: 'https://checkout.stripe.test/cs_test_1'`, `mode: 'subscription'`, `status: 'open'`.
+ * @param over - Field overrides merged last.
+ * @returns A `Stripe.Checkout.Session` fixture.
+ * @example
+ * ```ts
+ * const session = fakeCheckoutSession({ status: 'complete' });
+ * ```
+ */
 export function fakeCheckoutSession(over = {}) {
     return {
         id: 'cs_test_1',
@@ -45,6 +99,18 @@ export function fakeCheckoutSession(over = {}) {
         ...over,
     };
 }
+/**
+ * Build a fake Stripe `Customer`.
+ *
+ * @remarks Defaults: `id: 'cus_test_1'`, `object: 'customer'`, `created: 1_700_000_000`,
+ * `livemode: false`.
+ * @param over - Field overrides merged last.
+ * @returns A `Stripe.Customer` fixture.
+ * @example
+ * ```ts
+ * const customer = fakeCustomer({ email: 'a@example.com' });
+ * ```
+ */
 export function fakeCustomer(over = {}) {
     return {
         id: 'cus_test_1',
@@ -54,6 +120,18 @@ export function fakeCustomer(over = {}) {
         ...over,
     };
 }
+/**
+ * Build a fake Stripe `Price`.
+ *
+ * @remarks Defaults: `id: 'price_test_1'`, `object: 'price'`, `active: true`, `currency: 'jpy'`,
+ * `unit_amount: 1000`.
+ * @param over - Field overrides merged last.
+ * @returns A `Stripe.Price` fixture.
+ * @example
+ * ```ts
+ * const price = fakePrice({ unit_amount: 2000 });
+ * ```
+ */
 export function fakePrice(over = {}) {
     return {
         id: 'price_test_1',
@@ -64,6 +142,18 @@ export function fakePrice(over = {}) {
         ...over,
     };
 }
+/**
+ * Build a fake Stripe `Subscription`.
+ *
+ * @remarks Defaults: `id: 'sub_test_1'`, `object: 'subscription'`, `status: 'active'`,
+ * `customer: 'cus_test_1'`, `created: 1_700_000_000`.
+ * @param over - Field overrides merged last.
+ * @returns A `Stripe.Subscription` fixture.
+ * @example
+ * ```ts
+ * const sub = fakeSubscription({ status: 'canceled' });
+ * ```
+ */
 export function fakeSubscription(over = {}) {
     return {
         id: 'sub_test_1',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rdlabo/workers-hono-kit",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -68,7 +68,11 @@
     "lint": "eslint \"src/**/*.ts\"",
     "lint:fix": "eslint \"src/**/*.ts\" --fix",
     "format": "prettier --write \"src/**/*.ts\"",
-    "format:check": "prettier --check \"src/**/*.ts\""
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "release": "np --no-tests --no-publish"
+  },
+  "dependencies": {
+    "stripe": "^20.4.1"
   },
   "peerDependencies": {
     "@hono/zod-validator": "^0.8.0",
@@ -79,15 +83,21 @@
     "hono": "^4.6.0",
     "jose": "^6.2.0",
     "mysql2": "^3.14.0",
-    "stripe": ">=15",
     "zod": "^4.4.0"
   },
   "peerDependenciesMeta": {
-    "ai": { "optional": true },
-    "ai-gateway-provider": { "optional": true },
-    "stripe": { "optional": true },
-    "drizzle-orm": { "optional": true },
-    "mysql2": { "optional": true }
+    "ai": {
+      "optional": true
+    },
+    "ai-gateway-provider": {
+      "optional": true
+    },
+    "drizzle-orm": {
+      "optional": true
+    },
+    "mysql2": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.84",
@@ -103,8 +113,8 @@
     "hono": "^4.6.0",
     "jose": "^6.2.3",
     "mysql2": "3.22.5",
+    "np": "^8.0.4",
     "prettier": "^3.8.4",
-    "stripe": "^20.4.1",
     "typescript": "~5.6.2",
     "typescript-eslint": "^8.61.1",
     "vitest": "^2.1.0",

package/src/ai/gateway.ts

@@ -1,61 +1,100 @@
 /**
- * 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';
 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 function createAiGatewayProvider(config: AiGatewayConfig): AiGatewayProvider {
   if ('binding' in config) {
@@ -63,13 +102,13 @@ export function createAiGatewayProvider(config: AiGatewayConfig): AiGatewayProvi
   }
 
   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,