@rdlabo/workers-hono-kit 0.2.0 → 0.3.0

package/dist/db/orm-config.d.ts

@@ -1,47 +1,89 @@
 /**
- * Drizzle の列名 casing をフリートで一元管理する（標準: snake_case を「config」と「runtime」の両方で固定）。
+ * Centralizes Drizzle column-name casing so it is fixed (standard: `snake_case`) in both the
+ * config and the runtime ORM.
  *
- * casing は2か所にあり別物:
- *   ① drizzle.config.ts の top-level `casing` … `db:generate` が **作る列名** を決める（→ honoDrizzleConfig）
- *   ② database.ts の `drizzle(conn, { …casing })` … **実行時の書き込みビルダが参照する列名** を決める（→ DRIZZLE_ORM_OPTIONS）
+ * @remarks
+ * Casing is configured in two distinct places:
  *
- * この2つが食い違うと、明示列名を書き忘れた camelCase 複数単語列で generate と実行時がズレて実行時
- * `Unknown column` になる（typecheck もマイグレーションも正常に見えるので発覚が遅い）。両方ここから取れば
- * ズレが構造的に起きない。明示列名がある列では casing は無視されるので、既存挙動は変えない純粋な安全網。
+ * 1. The top-level `casing` in `drizzle.config.ts` decides the column names that `db:generate`
+ *    **creates** (see {@link honoDrizzleConfig}).
+ * 2. The `drizzle(conn, { …casing })` call decides the column names the **runtime write builder**
+ *    resolves to (see {@link DRIZZLE_ORM_OPTIONS}).
  *
- * 注: runtime の `drizzle()` 呼び出し自体は **消費側 repo が自分の drizzle-orm で行う**（kit が drizzle() を
- * 呼ぶと kit と repo で drizzle-orm が別コピーになり型同一性が壊れるため）。kit は「値」だけを提供する。
+ * If these two disagree, a multi-word camelCase column without an explicit column name will be
+ * generated with one name but queried with another, producing a runtime `Unknown column` error —
+ * something neither the type-check nor the migration surface, so it is caught late. Sourcing both
+ * from here makes the mismatch structurally impossible. Casing is ignored for columns that declare
+ * an explicit name, so this is a pure safety net that does not change existing behavior.
+ *
+ * The runtime `drizzle()` call itself is made by the consuming app with its own `drizzle-orm`; the
+ * kit only ever provides values, never the ORM instance, to avoid splitting `drizzle-orm` into two
+ * copies and breaking type identity.
  */
 /**
- * runtime 用。消費側 repo の database.ts で `drizzle(conn, { schema, ...DRIZZLE_ORM_OPTIONS })` と spread して使う。
- * mode/casing を kit が固定し、書き込みビルダの列名解決を snake_case に揃える。
+ * Runtime ORM options shared by the consuming app's `drizzle()` call.
+ *
+ * Spread into the runtime ORM as `drizzle(conn, { schema, ...DRIZZLE_ORM_OPTIONS })` so the write
+ * builder resolves column names as `snake_case`, matching what `db:generate` creates.
+ *
+ * @remarks
+ * Fixes `mode: 'default'` and `casing: 'snake_case'`. See the module-level documentation for why
+ * the same casing must be used by both the config and the runtime ORM.
  */
 export declare const DRIZZLE_ORM_OPTIONS: {
     readonly mode: "default";
     readonly casing: "snake_case";
 };
+/**
+ * Options for {@link honoDrizzleConfig}.
+ */
 export interface HonoDrizzleConfigOptions {
-    /** drizzle-kit の dbCredentials.database（localConnectionString とは別）。 */
+    /** drizzle-kit `dbCredentials.database` — the database name to connect to. */
     database: string;
+    /** Database host; defaults to `process.env.DB_HOST` then `127.0.0.1`. */
     host?: string;
+    /** Database port; defaults to `process.env.DB_PORT` then `3306`. */
     port?: number;
+    /** Database user; defaults to `process.env.DB_USER` then `root`. */
     user?: string;
+    /** Database password; defaults to `process.env.DB_PASSWORD` then `root`. */
     password?: string;
-    /** 既定 './src/db/schemes'。 */
+    /** Path to the schema directory; defaults to `'./src/db/schemes'`. */
     schema?: string;
-    /** 既定 './drizzle'。 */
+    /** Output directory for generated migrations; defaults to `'./drizzle'`. */
     out?: string;
-    /** /api と DB を共有する repo は schema 由来テーブルに限定する（省略可）。 */
+    /**
+     * Optional table allow-list. Use this to restrict drizzle-kit to the schema's own tables when the
+     * database is shared with another application.
+     */
     tablesFilter?: string[];
-    /** db:introspect（DB→JS）の casing。生成方向の `casing:'snake_case'` とは別軸（省略可）。 */
+    /**
+     * Optional `db:introspect` (DB → JS) casing. This is an independent axis from the generation-side
+     * `casing: 'snake_case'` and only affects introspection output.
+     */
     introspect?: {
         casing: 'camel' | 'preserve';
     };
 }
 /**
- * drizzle.config.ts 用ファクトリ。`export default honoDrizzleConfig({ database })` で使う。
- * casing:'snake_case'・schema/out・dbCredentials（env 既定）を kit が owner として固定する。
- * drizzle-kit を kit の依存にしないため plain object を返す（drizzle-kit CLI は default export を読むだけ）。
+ * Build a `drizzle.config.ts` configuration object with the kit's standard defaults.
+ *
+ * Fixes `casing: 'snake_case'`, the `schema`/`out` paths, and `dbCredentials` (with env-based
+ * defaults), while leaving `tablesFilter` and `introspect` opt-in.
+ *
+ * @remarks
+ * Returns a plain object rather than a typed drizzle-kit config so that `drizzle-kit` need not be a
+ * dependency of the kit; the drizzle-kit CLI only reads the default export.
+ *
+ * @param options - configuration overrides; only `database` is required.
+ * @returns a plain configuration object suitable for `export default` in `drizzle.config.ts`.
+ * @example
+ * ```ts
+ * // drizzle.config.ts
+ * import { honoDrizzleConfig } from '@rdlabo/workers-hono-kit/db';
+ *
+ * export default honoDrizzleConfig({ database: 'app' });
+ * ```
  */
 export declare function honoDrizzleConfig(options: HonoDrizzleConfigOptions): {
     dbCredentials: {

package/dist/db/orm-config.js

@@ -1,26 +1,55 @@
 /**
- * Drizzle の列名 casing をフリートで一元管理する（標準: snake_case を「config」と「runtime」の両方で固定）。
+ * Centralizes Drizzle column-name casing so it is fixed (standard: `snake_case`) in both the
+ * config and the runtime ORM.
  *
- * casing は2か所にあり別物:
- *   ① drizzle.config.ts の top-level `casing` … `db:generate` が **作る列名** を決める（→ honoDrizzleConfig）
- *   ② database.ts の `drizzle(conn, { …casing })` … **実行時の書き込みビルダが参照する列名** を決める（→ DRIZZLE_ORM_OPTIONS）
+ * @remarks
+ * Casing is configured in two distinct places:
  *
- * この2つが食い違うと、明示列名を書き忘れた camelCase 複数単語列で generate と実行時がズレて実行時
- * `Unknown column` になる（typecheck もマイグレーションも正常に見えるので発覚が遅い）。両方ここから取れば
- * ズレが構造的に起きない。明示列名がある列では casing は無視されるので、既存挙動は変えない純粋な安全網。
+ * 1. The top-level `casing` in `drizzle.config.ts` decides the column names that `db:generate`
+ *    **creates** (see {@link honoDrizzleConfig}).
+ * 2. The `drizzle(conn, { …casing })` call decides the column names the **runtime write builder**
+ *    resolves to (see {@link DRIZZLE_ORM_OPTIONS}).
  *
- * 注: runtime の `drizzle()` 呼び出し自体は **消費側 repo が自分の drizzle-orm で行う**（kit が drizzle() を
- * 呼ぶと kit と repo で drizzle-orm が別コピーになり型同一性が壊れるため）。kit は「値」だけを提供する。
+ * If these two disagree, a multi-word camelCase column without an explicit column name will be
+ * generated with one name but queried with another, producing a runtime `Unknown column` error —
+ * something neither the type-check nor the migration surface, so it is caught late. Sourcing both
+ * from here makes the mismatch structurally impossible. Casing is ignored for columns that declare
+ * an explicit name, so this is a pure safety net that does not change existing behavior.
+ *
+ * The runtime `drizzle()` call itself is made by the consuming app with its own `drizzle-orm`; the
+ * kit only ever provides values, never the ORM instance, to avoid splitting `drizzle-orm` into two
+ * copies and breaking type identity.
  */
 /**
- * runtime 用。消費側 repo の database.ts で `drizzle(conn, { schema, ...DRIZZLE_ORM_OPTIONS })` と spread して使う。
- * mode/casing を kit が固定し、書き込みビルダの列名解決を snake_case に揃える。
+ * Runtime ORM options shared by the consuming app's `drizzle()` call.
+ *
+ * Spread into the runtime ORM as `drizzle(conn, { schema, ...DRIZZLE_ORM_OPTIONS })` so the write
+ * builder resolves column names as `snake_case`, matching what `db:generate` creates.
+ *
+ * @remarks
+ * Fixes `mode: 'default'` and `casing: 'snake_case'`. See the module-level documentation for why
+ * the same casing must be used by both the config and the runtime ORM.
  */
 export const DRIZZLE_ORM_OPTIONS = { mode: 'default', casing: 'snake_case' };
 /**
- * drizzle.config.ts 用ファクトリ。`export default honoDrizzleConfig({ database })` で使う。
- * casing:'snake_case'・schema/out・dbCredentials（env 既定）を kit が owner として固定する。
- * drizzle-kit を kit の依存にしないため plain object を返す（drizzle-kit CLI は default export を読むだけ）。
+ * Build a `drizzle.config.ts` configuration object with the kit's standard defaults.
+ *
+ * Fixes `casing: 'snake_case'`, the `schema`/`out` paths, and `dbCredentials` (with env-based
+ * defaults), while leaving `tablesFilter` and `introspect` opt-in.
+ *
+ * @remarks
+ * Returns a plain object rather than a typed drizzle-kit config so that `drizzle-kit` need not be a
+ * dependency of the kit; the drizzle-kit CLI only reads the default export.
+ *
+ * @param options - configuration overrides; only `database` is required.
+ * @returns a plain configuration object suitable for `export default` in `drizzle.config.ts`.
+ * @example
+ * ```ts
+ * // drizzle.config.ts
+ * import { honoDrizzleConfig } from '@rdlabo/workers-hono-kit/db';
+ *
+ * export default honoDrizzleConfig({ database: 'app' });
+ * ```
  */
 export function honoDrizzleConfig(options) {
     const { database, host, port, user, password, schema = './src/db/schemes', out = './drizzle', tablesFilter, introspect, } = options;

package/dist/db/retry.d.ts

@@ -1,6 +1,28 @@
 /**
- * ER_LOCK_DEADLOCK を指数バックオフで retry する（NestJS/TypeORM の retryWhenDeadlock 相当）。
- * MySQL はデッドロック時にトランザクション全体をロールバックするため、同じ作業単位の再実行は安全。
- * `fn` は単一文（write）またはトランザクション全体（transaction）であること — retry は `fn` 全体を再実行する。
+ * Run an async unit of work, retrying it on MySQL deadlock errors with exponential backoff.
+ *
+ * Retries are triggered only by the `ER_LOCK_DEADLOCK` error code. Each failed attempt waits
+ * `delay * attempt` milliseconds (linear growth of the base delay) before the next try, and any
+ * non-deadlock error is rethrown immediately without retrying.
+ *
+ * @remarks
+ * MySQL rolls back the entire transaction when it detects a deadlock, so re-running the same unit
+ * of work is safe. Pass a `fn` that represents one complete unit — a single statement or an entire
+ * transaction — because the whole `fn` is re-executed on each retry.
+ *
+ * @typeParam T - resolved value produced by `fn`.
+ * @param fn - the unit of work to execute; it is invoked again from scratch on each retry.
+ * @param retries - maximum number of attempts (default `3`).
+ * @param delay - base backoff in milliseconds; attempt N waits `delay * N` (default `100`).
+ * @returns the value resolved by the first successful call to `fn`.
+ * @throws the last error thrown by `fn` once retries are exhausted, or any non-deadlock error on
+ * the first occurrence.
+ * @example
+ * ```ts
+ * await retryWhenDeadlock(() => db.transaction(async (tx) => {
+ *   await tx.insert(orders).values(order);
+ *   await tx.update(stock).set({ qty: sql`qty - 1` }).where(eq(stock.id, order.itemId));
+ * }));
+ * ```
  */
 export declare function retryWhenDeadlock<T>(fn: () => Promise<T>, retries?: number, delay?: number): Promise<T>;

package/dist/db/retry.js

@@ -1,7 +1,29 @@
 /**
- * ER_LOCK_DEADLOCK を指数バックオフで retry する（NestJS/TypeORM の retryWhenDeadlock 相当）。
- * MySQL はデッドロック時にトランザクション全体をロールバックするため、同じ作業単位の再実行は安全。
- * `fn` は単一文（write）またはトランザクション全体（transaction）であること — retry は `fn` 全体を再実行する。
+ * Run an async unit of work, retrying it on MySQL deadlock errors with exponential backoff.
+ *
+ * Retries are triggered only by the `ER_LOCK_DEADLOCK` error code. Each failed attempt waits
+ * `delay * attempt` milliseconds (linear growth of the base delay) before the next try, and any
+ * non-deadlock error is rethrown immediately without retrying.
+ *
+ * @remarks
+ * MySQL rolls back the entire transaction when it detects a deadlock, so re-running the same unit
+ * of work is safe. Pass a `fn` that represents one complete unit — a single statement or an entire
+ * transaction — because the whole `fn` is re-executed on each retry.
+ *
+ * @typeParam T - resolved value produced by `fn`.
+ * @param fn - the unit of work to execute; it is invoked again from scratch on each retry.
+ * @param retries - maximum number of attempts (default `3`).
+ * @param delay - base backoff in milliseconds; attempt N waits `delay * N` (default `100`).
+ * @returns the value resolved by the first successful call to `fn`.
+ * @throws the last error thrown by `fn` once retries are exhausted, or any non-deadlock error on
+ * the first occurrence.
+ * @example
+ * ```ts
+ * await retryWhenDeadlock(() => db.transaction(async (tx) => {
+ *   await tx.insert(orders).values(order);
+ *   await tx.update(stock).set({ qty: sql`qty - 1` }).where(eq(stock.id, order.itemId));
+ * }));
+ * ```
  */
 export async function retryWhenDeadlock(fn, retries = 3, delay = 100) {
     for (let attempt = 0; attempt < retries; attempt++) {

package/dist/db/write-result.d.ts

@@ -1,16 +1,39 @@
 /**
- * Drizzle(mysql2) の write 結果から insertId / affectedRows を型安全に取り出すヘルパ。
- * 生の builder/ResultSetHeader を repo 側に晒さずに、よく使う値だけを取り出す。
+ * Shape of a Drizzle (mysql2) write result, narrowed to the fields callers actually read.
  *
- * mysql2 の INSERT/UPDATE/DELETE 結果は `[ResultSetHeader, FieldPacket[]]` 形。
+ * @remarks
+ * A mysql2 INSERT/UPDATE/DELETE result is the tuple `[ResultSetHeader, FieldPacket[]]`. Typing the
+ * result this way lets repositories extract the common values without exposing the raw query
+ * builder or the full `ResultSetHeader` to the rest of the codebase.
  */
 export type DzWriteResult = readonly [{
     insertId: number;
     affectedRows: number;
 }, ...unknown[]];
+/**
+ * Extract the auto-increment `insertId` from a write result.
+ *
+ * @param result - the result of a Drizzle (mysql2) INSERT/UPDATE/DELETE.
+ * @returns the `insertId` reported by mysql2 (the id of the first inserted row).
+ */
 export declare function insertIdOf(result: DzWriteResult): number;
+/**
+ * Extract the number of affected rows from a write result.
+ *
+ * @param result - the result of a Drizzle (mysql2) INSERT/UPDATE/DELETE.
+ * @returns the `affectedRows` count reported by mysql2.
+ */
 export declare function affectedRowsOf(result: DzWriteResult): number;
 /**
- * 一括 INSERT で連番採番された行の id 群を返す（mysql2 は先頭 insertId のみ返すため count 分を生成）。
+ * Reconstruct the auto-increment ids assigned by a bulk INSERT.
+ *
+ * @remarks
+ * mysql2 reports only the first `insertId` for a multi-row INSERT, so the remaining ids are derived
+ * by assuming a contiguous sequence (`base`, `base + 1`, …). This holds for tables with a standard
+ * `AUTO_INCREMENT` column and the default `innodb_autoinc_lock_mode`.
+ *
+ * @param result - the result of a bulk INSERT.
+ * @param count - the number of rows that were inserted.
+ * @returns an array of the `count` auto-increment ids, starting at the reported `insertId`.
  */
 export declare function insertedIdsOf(result: DzWriteResult, count: number): number[];

package/dist/db/write-result.js

@@ -1,11 +1,32 @@
+/**
+ * Extract the auto-increment `insertId` from a write result.
+ *
+ * @param result - the result of a Drizzle (mysql2) INSERT/UPDATE/DELETE.
+ * @returns the `insertId` reported by mysql2 (the id of the first inserted row).
+ */
 export function insertIdOf(result) {
     return result[0].insertId;
 }
+/**
+ * Extract the number of affected rows from a write result.
+ *
+ * @param result - the result of a Drizzle (mysql2) INSERT/UPDATE/DELETE.
+ * @returns the `affectedRows` count reported by mysql2.
+ */
 export function affectedRowsOf(result) {
     return result[0].affectedRows;
 }
 /**
- * 一括 INSERT で連番採番された行の id 群を返す（mysql2 は先頭 insertId のみ返すため count 分を生成）。
+ * Reconstruct the auto-increment ids assigned by a bulk INSERT.
+ *
+ * @remarks
+ * mysql2 reports only the first `insertId` for a multi-row INSERT, so the remaining ids are derived
+ * by assuming a contiguous sequence (`base`, `base + 1`, …). This holds for tables with a standard
+ * `AUTO_INCREMENT` column and the default `innodb_autoinc_lock_mode`.
+ *
+ * @param result - the result of a bulk INSERT.
+ * @param count - the number of rows that were inserted.
+ * @returns an array of the `count` auto-increment ids, starting at the reported `insertId`.
  */
 export function insertedIdsOf(result, count) {
     const base = result[0].insertId;

package/dist/firebase/firebase-verifier.d.ts

@@ -1,17 +1,66 @@
-/** Firebase boundary replacing the firebase-admin Auth surface used by `/api`. */
+/**
+ * Decoded Firebase ID token payload.
+ *
+ * Shaped to match the subset of `firebase-admin`'s `DecodedIdToken` that consumers
+ * typically rely on: a stable `uid` plus an optional `email`. The index signature keeps
+ * every other JWT claim (e.g. `name`, `picture`, custom claims) accessible without
+ * enumerating them here.
+ *
+ * @remarks
+ * This is the return type of {@link FirebaseVerifier.verifyIdToken}. The `uid` is derived
+ * from the token's `sub` claim.
+ */
 export interface DecodedIdToken {
+    /** The authenticated user's unique id, taken from the token's `sub` claim. */
     uid: string;
+    /** The user's email address, when present on the token. */
     email?: string;
+    /** Any additional JWT claim carried by the token (custom claims, `name`, `picture`, ...). */
     [claim: string]: unknown;
 }
+/**
+ * Abstract authentication boundary that replaces the `firebase-admin` Auth surface
+ * (`verifyIdToken` / `getUser` / `deleteUser`) for environments where the Node SDK cannot
+ * run, such as Cloudflare Workers.
+ *
+ * @remarks
+ * Implementations verify Firebase ID tokens and look up or delete accounts without the
+ * `firebase-admin` Node dependency. See `JoseFirebaseVerifier` for the `jose`-based
+ * implementation and the `createRemoteFirebaseVerifier` / `createServiceAccountVerifier`
+ * factories for ready-made instances.
+ */
 export interface FirebaseVerifier {
-    /** Mirrors firebase-admin getAuth().verifyIdToken(). Throws on invalid token. */
+    /**
+     * Verify a Firebase ID token and return its decoded payload.
+     *
+     * Mirrors `firebase-admin` `getAuth().verifyIdToken()`.
+     *
+     * @param idToken - The raw Firebase ID token (JWT) to verify.
+     * @returns The decoded token payload.
+     * @throws If the token signature, issuer, audience, expiry, or other required claims are invalid.
+     */
     verifyIdToken(idToken: string): Promise<DecodedIdToken>;
-    /** Mirrors getAuth().getUser(); returns null when the user is absent. */
+    /**
+     * Look up a user record by uid.
+     *
+     * Mirrors `firebase-admin` `getAuth().getUser()`.
+     *
+     * @param uid - The user's unique id.
+     * @returns The user's `uid` and optional `email`, or `null` when the user does not exist.
+     * @throws If the backing user-management service is not configured or the lookup fails.
+     */
     getUser(uid: string): Promise<{
         uid: string;
         email?: string;
     } | null>;
-    /** Mirrors getAuth().deleteUser(). */
+    /**
+     * Delete a user by uid.
+     *
+     * Mirrors `firebase-admin` `getAuth().deleteUser()`.
+     *
+     * @param uid - The user's unique id.
+     * @returns A promise that resolves once the user has been deleted.
+     * @throws If the backing user-management service is not configured or the deletion fails.
+     */
     deleteUser(uid: string): Promise<void>;
 }

package/dist/firebase/identity-toolkit.d.ts

@@ -1,24 +1,73 @@
 /**
- * Minimal Google Identity Toolkit client for the operations firebase-admin performed
- * that aren't token verification: accounts:lookup (getUser) and accounts:delete
- * (deleteUser). Replaces the firebase-admin Node SDK, which won't run on workerd.
+ * Minimal service-account credential consumed by {@link IdentityToolkit}.
  *
- * Auth: sign a JWT assertion with the service-account private key (jose), exchange it for
- * an OAuth2 access token, then call the REST API. Tokens are cached in-process.
+ * @remarks
+ * Corresponds to the relevant fields of a Google service-account JSON key file.
  */
 export interface ServiceAccount {
+    /** The service account's email, used as the JWT assertion issuer and subject. */
     client_email: string;
+    /** The PEM-encoded PKCS#8 RSA private key used to sign the OAuth2 assertion. */
     private_key: string;
+    /** The Google/Firebase project id the Identity Toolkit calls target. */
     project_id: string;
 }
+/**
+ * Minimal Google Identity Toolkit REST client for the user-management operations that token
+ * verification does not cover: `accounts:lookup` (getUser) and `accounts:delete` (deleteUser).
+ *
+ * This replaces the parts of the `firebase-admin` Node SDK that cannot run on Cloudflare
+ * Workers (workerd).
+ *
+ * @remarks
+ * Authentication follows the JWT-bearer flow: a JWT assertion is signed with the service
+ * account's private key (via `jose`), exchanged at the OAuth2 token endpoint for an access
+ * token, and that token is then used to call the REST API. Access tokens are cached in-process
+ * and reused until shortly before they expire.
+ */
 export declare class IdentityToolkit {
     private readonly sa;
+    /** Cached OAuth2 access token and its absolute expiry (Unix seconds), or `null` when none. */
     private accessToken;
+    /**
+     * Create a client bound to a single service account.
+     *
+     * @param sa - The service-account credential used to authenticate REST calls.
+     */
     constructor(sa: ServiceAccount);
+    /**
+     * Return a valid OAuth2 access token, minting a new one when the cache is empty or expiring.
+     *
+     * Signs a short-lived JWT assertion with the service-account key and exchanges it at the
+     * Google OAuth2 token endpoint. The result is cached and reused while it remains valid
+     * (with a 60-second safety margin).
+     *
+     * @param nowSeconds - The current Unix time in seconds, used for cache validity and JWT timestamps.
+     * @returns A bearer access token for the Identity Toolkit API.
+     * @throws If the token exchange request fails.
+     * @internal
+     */
     private getAccessToken;
+    /**
+     * Look up a user record by uid via the `accounts:lookup` endpoint.
+     *
+     * @param uid - The user's unique id (`localId`).
+     * @param nowSeconds - The current Unix time in seconds, used for access-token caching.
+     * @returns The user's `uid` and optional `email`, or `null` when the request is unsuccessful
+     *   or no matching user is returned.
+     * @throws If acquiring an access token fails.
+     */
     lookup(uid: string, nowSeconds: number): Promise<{
         uid: string;
         email?: string;
     } | null>;
+    /**
+     * Delete a user by uid via the `accounts:delete` endpoint.
+     *
+     * @param uid - The user's unique id (`localId`).
+     * @param nowSeconds - The current Unix time in seconds, used for access-token caching.
+     * @returns A promise that resolves once the user has been deleted.
+     * @throws If acquiring an access token fails or the delete request is unsuccessful.
+     */
     remove(uid: string, nowSeconds: number): Promise<void>;
 }

package/dist/firebase/identity-toolkit.js

@@ -1,13 +1,47 @@
 import { SignJWT, importPKCS8 } from 'jose';
+/** Google OAuth2 token endpoint used to exchange a signed JWT assertion for an access token. */
 const TOKEN_URL = 'https://oauth2.googleapis.com/token';
+/** Base URL of the Google Identity Toolkit v1 REST API. */
 const IDENTITY_TOOLKIT = 'https://identitytoolkit.googleapis.com/v1';
+/** OAuth2 scopes required for Identity Toolkit account lookup and deletion. */
 const SCOPE = 'https://www.googleapis.com/auth/identitytoolkit https://www.googleapis.com/auth/firebase';
+/**
+ * Minimal Google Identity Toolkit REST client for the user-management operations that token
+ * verification does not cover: `accounts:lookup` (getUser) and `accounts:delete` (deleteUser).
+ *
+ * This replaces the parts of the `firebase-admin` Node SDK that cannot run on Cloudflare
+ * Workers (workerd).
+ *
+ * @remarks
+ * Authentication follows the JWT-bearer flow: a JWT assertion is signed with the service
+ * account's private key (via `jose`), exchanged at the OAuth2 token endpoint for an access
+ * token, and that token is then used to call the REST API. Access tokens are cached in-process
+ * and reused until shortly before they expire.
+ */
 export class IdentityToolkit {
     sa;
+    /** Cached OAuth2 access token and its absolute expiry (Unix seconds), or `null` when none. */
     accessToken = null;
+    /**
+     * Create a client bound to a single service account.
+     *
+     * @param sa - The service-account credential used to authenticate REST calls.
+     */
     constructor(sa) {
         this.sa = sa;
     }
+    /**
+     * Return a valid OAuth2 access token, minting a new one when the cache is empty or expiring.
+     *
+     * Signs a short-lived JWT assertion with the service-account key and exchanges it at the
+     * Google OAuth2 token endpoint. The result is cached and reused while it remains valid
+     * (with a 60-second safety margin).
+     *
+     * @param nowSeconds - The current Unix time in seconds, used for cache validity and JWT timestamps.
+     * @returns A bearer access token for the Identity Toolkit API.
+     * @throws If the token exchange request fails.
+     * @internal
+     */
     async getAccessToken(nowSeconds) {
         if (this.accessToken && this.accessToken.expiresAt > nowSeconds + 60) {
             return this.accessToken.value;
@@ -36,6 +70,15 @@ export class IdentityToolkit {
         this.accessToken = { value: json.access_token, expiresAt: nowSeconds + json.expires_in };
         return json.access_token;
     }
+    /**
+     * Look up a user record by uid via the `accounts:lookup` endpoint.
+     *
+     * @param uid - The user's unique id (`localId`).
+     * @param nowSeconds - The current Unix time in seconds, used for access-token caching.
+     * @returns The user's `uid` and optional `email`, or `null` when the request is unsuccessful
+     *   or no matching user is returned.
+     * @throws If acquiring an access token fails.
+     */
     async lookup(uid, nowSeconds) {
         const token = await this.getAccessToken(nowSeconds);
         const res = await fetch(`${IDENTITY_TOOLKIT}/projects/${this.sa.project_id}/accounts:lookup`, {
@@ -50,6 +93,14 @@ export class IdentityToolkit {
         const user = json.users?.[0];
         return user ? { uid: user.localId, email: user.email } : null;
     }
+    /**
+     * Delete a user by uid via the `accounts:delete` endpoint.
+     *
+     * @param uid - The user's unique id (`localId`).
+     * @param nowSeconds - The current Unix time in seconds, used for access-token caching.
+     * @returns A promise that resolves once the user has been deleted.
+     * @throws If acquiring an access token fails or the delete request is unsuccessful.
+     */
     async remove(uid, nowSeconds) {
         const token = await this.getAccessToken(nowSeconds);
         const res = await fetch(`${IDENTITY_TOOLKIT}/projects/${this.sa.project_id}/accounts:delete`, {