@exabugs/dynamodb-client 1.15.0 → 1.16.0

package/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.16.0] - 2026-10-20
+
+### Added
+
+- **Records クライアントのヘルパー**（`@exabugs/dynamodb-client/client/iam`。ADR 0006 の段階 1）: `createRecordsClient`（`DynamoClient` の生成と `connect()`）、`withCollection`（作る → 使う → 確実に close）、`lazyCollection`（初回の使用時に 1 回だけ接続して再利用）。`url` / `region` は省略時に環境変数 `RECORDS_IAM_URL` / `AWS_REGION` から読む。使い方は `docs/RECORDS_CLIENT.md`
+- **`createAdminDirectory`**（`@exabugs/dynamodb-client/notify`）: `admins` の全件から通知の宛先を返す `AdminDirectory`。宛先のフィールドは `recipientFields`（既定 `['id']`。`['email','id']` で `email ?? id`）。あわせて `normalizeEmail` / `emailsOf` を公開
+
+### Changed
+
+- media の Records クライアント（`src/server/media/recordsClient.ts`）は、公開ヘルパー `lazyCollection` を使う。挙動は同じ（`connect()`、timeout 15 秒、`RECORDS_IAM_URL` の扱い、コールドスタートで 1 回の接続と再利用）。並行した初回の呼び出しが 1 つの接続を共有するようになった
+
+### Removed
+
+- **terraform/media**: 変数 `table_name`、`table_arn`、`shadow_created_at_field`、`shadow_updated_at_field`、`shadow_string_max_bytes`、`shadow_number_padding`（ADR 0005、issue #94。1.15.0 で deprecated）。利用側が渡していると、`terraform plan` が「宣言されていない変数」で失敗する。移行: 渡すのをやめる（1.15.0 以降、渡しても無視されていた）
+
 ## [1.15.0] - 2026-10-18
 
 ### Added

package/README.md

@@ -196,6 +196,7 @@ const article = await articles.findOne({ title: 'Hello DynamoDB' });
 - **[React Admin Integration](docs/react-admin-integration.md)** - Admin UI setup and many-to-many relationships
 - **[Authorization & Secure Setup](docs/AUTHORIZATION.md)** - 認可モデルと安全な構成（必読。JWT の有効性しか検証しない／管理者専用ユーザープール／`aud` 検証）
 - **[疎な検索の警告と対応](docs/SCAN_WARNING.md)** - 検索を打ち切らず、警告(SPARSE_SCAN)で気づいてインデックス・スキーマ・ロジックを見直す
+- **[Records クライアントのヘルパー](docs/RECORDS_CLIENT.md)** - Lambda から Records を呼ぶ定型（`createRecordsClient` / `withCollection` / `lazyCollection`）
 - **[運用通知](docs/NOTIFY.md)** - ログ・アラームを、Slack・メールで管理者へ通知する部品（`@exabugs/dynamodb-client/notify`）
 - **[Deployment](docs/DEPLOYMENT.md)** - Production deployment guide
 - **[Terraform Modules](terraform/README.md)** - Infrastructure as Code

package/dist/client/index.iam.d.ts

@@ -31,4 +31,5 @@ export interface ClientOptions extends Omit<BaseClientOptions<IAMAuthOptions>, '
 export declare class DynamoClient extends BaseDynamoClient<IAMAuthOptions> {
     constructor(endpoint: string, options: ClientOptions);
 }
+export { createRecordsClient, lazyCollection, withCollection, type LazyCollection, type RecordsClientOptions, type RecordsCollection, } from './recordsClient.js';
 //# sourceMappingURL=index.iam.d.ts.map

package/dist/client/index.iam.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.iam.d.ts","sourceRoot":"","sources":["../../src/client/index.iam.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,KAAK,aAAa,IAAI,iBAAiB,EACvC,YAAY,IAAI,gBAAgB,EACjC,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,aAAc,SAAQ,IAAI,CAAC,iBAAiB,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACpF,kBAAkB;IAClB,IAAI,EAAE,cAAc,CAAC;CACtB;AAED;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,gBAAgB,CAAC,cAAc,CAAC;gBACpD,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa;CAQrD"}
+{"version":3,"file":"index.iam.d.ts","sourceRoot":"","sources":["../../src/client/index.iam.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,KAAK,aAAa,IAAI,iBAAiB,EACvC,YAAY,IAAI,gBAAgB,EACjC,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,aAAc,SAAQ,IAAI,CAAC,iBAAiB,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACpF,kBAAkB;IAClB,IAAI,EAAE,cAAc,CAAC;CACtB;AAED;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,gBAAgB,CAAC,cAAc,CAAC;gBACpD,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa;CAQrD;AAED,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,GACvB,MAAM,oBAAoB,CAAC"}

package/dist/client/index.iam.js

@@ -25,4 +25,5 @@ export class DynamoClient extends BaseDynamoClient {
         });
     }
 }
+export { createRecordsClient, lazyCollection, withCollection, } from './recordsClient.js';
 //# sourceMappingURL=index.iam.js.map

package/dist/client/index.iam.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.iam.js","sourceRoot":"","sources":["../../src/client/index.iam.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAEL,YAAY,IAAI,gBAAgB,GACjC,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,UAAU,EAAmC,MAAM,iBAAiB,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAkB7C;;;;;GAKG;AACH,MAAM,OAAO,YAAa,SAAQ,gBAAgC;IAChE,YAAY,QAAgB,EAAE,OAAsB;QAClD,KAAK,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,GAAW,EAAE,IAAY,EAAE,IAAqB,EAAE,EAAE;YAClF,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;YACnD,CAAC;YACD,OAAO,MAAM,WAAW,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QACnD,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}
+{"version":3,"file":"index.iam.js","sourceRoot":"","sources":["../../src/client/index.iam.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAEL,YAAY,IAAI,gBAAgB,GACjC,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,UAAU,EAAmC,MAAM,iBAAiB,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAkB7C;;;;;GAKG;AACH,MAAM,OAAO,YAAa,SAAQ,gBAAgC;IAChE,YAAY,QAAgB,EAAE,OAAsB;QAClD,KAAK,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,GAAW,EAAE,IAAY,EAAE,IAAqB,EAAE,EAAE;YAClF,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;YACnD,CAAC;YACD,OAAO,MAAM,WAAW,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QACnD,CAAC,CAAC,CAAC;IACL,CAAC;CACF;AAED,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,cAAc,GAIf,MAAM,oBAAoB,CAAC"}

package/dist/client/recordsClient.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Records（IAM 版 Function URL）を呼ぶクライアントのヘルパー（ADR 0006）
+ *
+ * Lambda などのサーバー側が Records のコレクションを使うときの定型を持つ。
+ * - `createRecordsClient`: `DynamoClient` の生成と `connect()`（`connect()` 忘れの防止）
+ * - `withCollection`: 作る → 使う → 確実に close（Lambda の 1 回の呼び出しで使い切る用途）
+ * - `lazyCollection`: 初回の使用時に 1 回だけ接続して再利用（コールドスタートで共有する用途）
+ *
+ * `url` と `region` は、省略時に環境変数 `RECORDS_IAM_URL`、`AWS_REGION`（無ければ `REGION`）から読む。
+ */
+import { DynamoClient } from './index.iam.js';
+import type { Collection } from './index.iam.js';
+/** Records 用のコレクションの型（IAM 認証） */
+export type RecordsCollection<T extends {
+    id: string;
+    [key: string]: unknown;
+}> = Collection<T, {
+    region: string;
+}>;
+export interface RecordsClientOptions {
+    /** Records の IAM 版 Function URL。省略時は環境変数 RECORDS_IAM_URL */
+    url?: string;
+    /** AWS リージョン。省略時は環境変数 AWS_REGION（無ければ REGION） */
+    region?: string;
+    /** リクエストの timeout（ms）。省略時は DynamoClient の既定。Records の Lambda の timeout より短くする */
+    timeout?: number;
+}
+type RecordShape = {
+    id: string;
+    [key: string]: unknown;
+};
+/** `DynamoClient` を生成して接続する。IAM では接続は状態の更新だけ（`db()` の前に必須） */
+export declare function createRecordsClient(options?: RecordsClientOptions): Promise<DynamoClient>;
+/**
+ * 接続して、コレクションで `fn` を実行し、成功でも失敗でも close する。
+ * `fn` の例外はそのまま投げる（close の失敗で `fn` の例外を隠さない）。
+ */
+export declare function withCollection<T extends RecordShape = RecordShape, R = unknown>(name: string, fn: (collection: RecordsCollection<T>) => Promise<R>, options?: RecordsClientOptions): Promise<R>;
+/** `lazyCollection` の戻り値。呼ぶとコレクションを返す（初回に接続） */
+export interface LazyCollection<T extends RecordShape> {
+    (): Promise<RecordsCollection<T>>;
+    /** キャッシュを捨てる（テスト用。次の呼び出しで接続し直す） */
+    reset(): void;
+}
+/**
+ * 最初の使用時に接続し、以降は同じコレクションを再利用する（コールドスタートで 1 回だけ接続）。
+ * 並行した初回の呼び出しは 1 つの接続を共有する。失敗したらキャッシュせず、次の呼び出しでやり直す。
+ */
+export declare function lazyCollection<T extends RecordShape>(name: string, options?: RecordsClientOptions): LazyCollection<T>;
+export {};
+//# sourceMappingURL=recordsClient.d.ts.map

package/dist/client/recordsClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recordsClient.d.ts","sourceRoot":"","sources":["../../src/client/recordsClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,iCAAiC;AACjC,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,IAAI,UAAU,CAC1F,CAAC,EACD;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CACnB,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,4DAA4D;IAC5D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,KAAK,WAAW,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAC;AAE1D,8DAA8D;AAC9D,wBAAsB,mBAAmB,CACvC,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,YAAY,CAAC,CAevB;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAAE,CAAC,GAAG,OAAO,EACnF,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,CAAC,UAAU,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EACpD,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED,gDAAgD;AAChD,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,WAAW;IACnD,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;IAClC,mCAAmC;IACnC,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,WAAW,EAClD,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,oBAAyB,GACjC,cAAc,CAAC,CAAC,CAAC,CAkBnB"}

package/dist/client/recordsClient.js

@@ -0,0 +1,64 @@
+/**
+ * Records（IAM 版 Function URL）を呼ぶクライアントのヘルパー（ADR 0006）
+ *
+ * Lambda などのサーバー側が Records のコレクションを使うときの定型を持つ。
+ * - `createRecordsClient`: `DynamoClient` の生成と `connect()`（`connect()` 忘れの防止）
+ * - `withCollection`: 作る → 使う → 確実に close（Lambda の 1 回の呼び出しで使い切る用途）
+ * - `lazyCollection`: 初回の使用時に 1 回だけ接続して再利用（コールドスタートで共有する用途）
+ *
+ * `url` と `region` は、省略時に環境変数 `RECORDS_IAM_URL`、`AWS_REGION`（無ければ `REGION`）から読む。
+ */
+import { DynamoClient } from './index.iam.js';
+/** `DynamoClient` を生成して接続する。IAM では接続は状態の更新だけ（`db()` の前に必須） */
+export async function createRecordsClient(options = {}) {
+    const url = options.url ?? process.env.RECORDS_IAM_URL;
+    if (!url) {
+        throw new Error('RECORDS_IAM_URL environment variable is not set');
+    }
+    const region = options.region ?? process.env.AWS_REGION ?? process.env.REGION;
+    if (!region) {
+        throw new Error('AWS_REGION environment variable is not set');
+    }
+    const client = new DynamoClient(url, {
+        auth: { region },
+        ...(options.timeout !== undefined ? { timeout: options.timeout } : {}),
+    });
+    await client.connect();
+    return client;
+}
+/**
+ * 接続して、コレクションで `fn` を実行し、成功でも失敗でも close する。
+ * `fn` の例外はそのまま投げる（close の失敗で `fn` の例外を隠さない）。
+ */
+export async function withCollection(name, fn, options = {}) {
+    const client = await createRecordsClient(options);
+    try {
+        return await fn(client.db().collection(name));
+    }
+    finally {
+        await client.close();
+    }
+}
+/**
+ * 最初の使用時に接続し、以降は同じコレクションを再利用する（コールドスタートで 1 回だけ接続）。
+ * 並行した初回の呼び出しは 1 つの接続を共有する。失敗したらキャッシュせず、次の呼び出しでやり直す。
+ */
+export function lazyCollection(name, options = {}) {
+    let cached;
+    const get = (() => {
+        if (!cached) {
+            const attempt = createRecordsClient(options).then((client) => client.db().collection(name));
+            cached = attempt;
+            attempt.catch(() => {
+                if (cached === attempt)
+                    cached = undefined;
+            });
+        }
+        return cached;
+    });
+    get.reset = () => {
+        cached = undefined;
+    };
+    return get;
+}
+//# sourceMappingURL=recordsClient.js.map

package/dist/client/recordsClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recordsClient.js","sourceRoot":"","sources":["../../src/client/recordsClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAoB9C,8DAA8D;AAC9D,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,UAAgC,EAAE;IAElC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;IACvD,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACrE,CAAC;IACD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC;IAC9E,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAChE,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,GAAG,EAAE;QACnC,IAAI,EAAE,EAAE,MAAM,EAAE;QAChB,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACvE,CAAC,CAAC;IACH,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;IACvB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAAY,EACZ,EAAoD,EACpD,UAAgC,EAAE;IAElC,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAClD,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,UAAU,CAAI,IAAI,CAAC,CAAC,CAAC;IACnD,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;AACH,CAAC;AASD;;;GAGG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAY,EACZ,UAAgC,EAAE;IAElC,IAAI,MAAiD,CAAC;IACtD,MAAM,GAAG,GAAG,CAAC,GAAG,EAAE;QAChB,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,OAAO,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAC3D,MAAM,CAAC,EAAE,EAAE,CAAC,UAAU,CAAI,IAAI,CAAC,CAChC,CAAC;YACF,MAAM,GAAG,OAAO,CAAC;YACjB,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE;gBACjB,IAAI,MAAM,KAAK,OAAO;oBAAE,MAAM,GAAG,SAAS,CAAC;YAC7C,CAAC,CAAC,CAAC;QACL,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC,CAAsB,CAAC;IACxB,GAAG,CAAC,KAAK,GAAG,GAAG,EAAE;QACf,MAAM,GAAG,SAAS,CAAC;IACrB,CAAC,CAAC;IACF,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/notify/admins.d.ts

@@ -0,0 +1,44 @@
+import type { RecordsClientOptions } from '../client/recordsClient.js';
+import type { AdminDirectory } from './types.js';
+export interface AdminRecord {
+    id: string;
+    [key: string]: unknown;
+}
+/**
+ * 管理者の一覧を読む側（`authorizedCollection` の `list` と同じ形）。
+ * 自前で接続せず、呼び出し側が権限チェック層などを通した読み取りを渡すときに使う。
+ * `all.maxItems` を超える件数のときは、呼び出し側が例外にする（黙って切らない）
+ */
+export interface AdminsLister {
+    list(filter: Record<string, unknown>, options?: {
+        sort?: Record<string, 'asc' | 'desc'>;
+        all?: {
+            maxItems: number;
+        };
+    }): Promise<readonly AdminRecord[]>;
+}
+export interface AdminDirectoryOptions extends RecordsClientOptions {
+    /** 管理者のコレクション名（自前で接続するとき）。既定 `admins` */
+    collection?: string;
+    /**
+     * 管理者を読む側。指定すると自前で接続せず（url / region / timeout / collection は使わない）、
+     * これを通して読む。astro は `authorizedCollection` を渡す
+     */
+    source?: AdminsLister;
+    /** 管理者の数の上限。件数が上限を超えたら例外（ちょうど上限は成功）。通知先の設計を見直す。既定 200 */
+    maxAdmins?: number;
+    /**
+     * 宛先を取り出すフィールド。先頭から見て、最初に null / undefined でない値を使う。
+     * 既定 `['id']`（asanowa）。astro の現行は `['email', 'id']`
+     */
+    recipientFields?: readonly string[];
+    /** true なら id の昇順で読み、宛先の順序を固定する（astro の現行）。既定 false（順序は不定） */
+    sortById?: boolean;
+}
+/** メールアドレスの形式なら小文字・前後空白除去で返す。そうでなければ null */
+export declare function normalizeEmail(value: unknown): string | null;
+/** 管理者のレコード → 宛先（小文字・重複なし・不正な形式は除く）。id がメールアドレス */
+export declare function emailsOf(admins: readonly AdminRecord[], fields?: readonly string[]): string[];
+/** 管理者の宛先を、呼び出しごとに Records から読む（`createNotifyHandler` の `admins` に渡す） */
+export declare function createAdminDirectory(options?: AdminDirectoryOptions): AdminDirectory;
+//# sourceMappingURL=admins.d.ts.map

package/dist/notify/admins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admins.d.ts","sourceRoot":"","sources":["../../src/notify/admins.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAKjD,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,CACF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC,CAAC;QAAC,GAAG,CAAC,EAAE;YAAE,QAAQ,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAC9E,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,qBAAsB,SAAQ,oBAAoB;IACjE,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,6CAA6C;AAC7C,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAI5D;AAED,mDAAmD;AACnD,wBAAgB,QAAQ,CACtB,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,MAAM,GAAE,SAAS,MAAM,EAAW,GACjC,MAAM,EAAE,CAQV;AAED,yEAAyE;AACzE,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,qBAA0B,GAAG,cAAc,CAsCxF"}

package/dist/notify/admins.js

@@ -0,0 +1,55 @@
+/**
+ * 通知の宛先（管理者全員）の取得（ADR 0006）
+ *
+ * 管理者は `admins` レコード（管理画面で増減）が正本。レコードの id が小文字のメールアドレス。
+ * Records の IAM 版 Function URL 経由で全件を読み、正規化したメールアドレスを返す。
+ */
+import { withCollection } from '../client/recordsClient.js';
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const PAGE_SIZE = 50;
+/** メールアドレスの形式なら小文字・前後空白除去で返す。そうでなければ null */
+export function normalizeEmail(value) {
+    if (typeof value !== 'string')
+        return null;
+    const email = value.trim().toLowerCase();
+    return EMAIL_PATTERN.test(email) ? email : null;
+}
+/** 管理者のレコード → 宛先（小文字・重複なし・不正な形式は除く）。id がメールアドレス */
+export function emailsOf(admins, fields = ['id']) {
+    const set = new Set();
+    for (const a of admins) {
+        const key = fields.find((f) => a[f] !== undefined && a[f] !== null);
+        const email = normalizeEmail(key === undefined ? undefined : a[key]);
+        if (email)
+            set.add(email);
+    }
+    return [...set];
+}
+/** 管理者の宛先を、呼び出しごとに Records から読む（`createNotifyHandler` の `admins` に渡す） */
+export function createAdminDirectory(options = {}) {
+    const { collection = 'admins', source, maxAdmins = 200, recipientFields = ['id'], sortById = false, ...clientOptions } = options;
+    const sort = sortById ? { id: 'asc' } : undefined;
+    return {
+        async listEmails() {
+            if (source) {
+                const all = await source.list({}, { ...(sort ? { sort } : {}), all: { maxItems: maxAdmins } });
+                return emailsOf(all, recipientFields);
+            }
+            return await withCollection(collection, async (admins) => {
+                const cursor = admins.find({});
+                if (sort)
+                    cursor.sort(sort);
+                // 上限 + 1 件まで読めれば、超過を件数で判定できる（ちょうど上限は成功）
+                const all = await cursor.toArrayAll({
+                    pageSize: PAGE_SIZE,
+                    maxPages: Math.ceil((maxAdmins + 1) / PAGE_SIZE),
+                });
+                if (all.length > maxAdmins) {
+                    throw new Error(`Too many admins: more than ${maxAdmins} in "${collection}"`);
+                }
+                return emailsOf(all, recipientFields);
+            }, clientOptions);
+        },
+    };
+}
+//# sourceMappingURL=admins.js.map

package/dist/notify/admins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admins.js","sourceRoot":"","sources":["../../src/notify/admins.ts"],"names":[],"mappings":"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"}

package/dist/notify/index.d.ts

@@ -4,6 +4,8 @@
  * ログ（warn 以上）・CloudWatch アラーム・直接呼び出しを Notice にそろえ、重複抑制のうえ、
  * Slack・メールなどのチャネルへ配信する部品。配線（購読フィルタ・Lambda・Terraform）は各アプリが行う。
  */
+export { createAdminDirectory, emailsOf, normalizeEmail } from './admins.js';
+export type { AdminDirectoryOptions, AdminRecord, AdminsLister } from './admins.js';
 export { ALERTS_RESOURCE, ALERT_RETENTION_DAYS, alertKeyOf, cleanupAlerts, createAlertRecorder, } from './alerts.js';
 export type { AlertInput, AlertOccurrence, AlertRecord, AlertRecorder, AlertRecorderOptions, AlertsCleanupCollection, AlertsCollection, CleanupAlertsOptions, CleanupAlertsResult, } from './alerts.js';
 export { createEmailChannel, sesSender } from './channels/email.js';

package/dist/notify/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/notify/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,UAAU,EACV,aAAa,EACb,mBAAmB,GACpB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,UAAU,EACV,eAAe,EACf,WAAW,EACX,aAAa,EACb,oBAAoB,EACpB,uBAAuB,EACvB,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACpE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACjG,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,YAAY,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,EACrB,QAAQ,EACR,OAAO,GACR,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACjF,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC3E,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAClE,YAAY,EACV,cAAc,EACd,UAAU,EACV,eAAe,EACf,gBAAgB,EAChB,OAAO,EACP,MAAM,EACN,WAAW,EACX,MAAM,EACN,WAAW,EACX,WAAW,EACX,YAAY,GACb,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/notify/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,oBAAoB,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7E,YAAY,EAAE,qBAAqB,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACpF,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,UAAU,EACV,aAAa,EACb,mBAAmB,GACpB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,UAAU,EACV,eAAe,EACf,WAAW,EACX,aAAa,EACb,oBAAoB,EACpB,uBAAuB,EACvB,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACpE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACjG,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,YAAY,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,EACrB,QAAQ,EACR,OAAO,GACR,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACjF,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC3E,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAClE,YAAY,EACV,cAAc,EACd,UAAU,EACV,eAAe,EACf,gBAAgB,EAChB,OAAO,EACP,MAAM,EACN,WAAW,EACX,MAAM,EACN,WAAW,EACX,WAAW,EACX,YAAY,GACb,MAAM,YAAY,CAAC"}

package/dist/notify/index.js

@@ -4,6 +4,7 @@
  * ログ（warn 以上）・CloudWatch アラーム・直接呼び出しを Notice にそろえ、重複抑制のうえ、
  * Slack・メールなどのチャネルへ配信する部品。配線（購読フィルタ・Lambda・Terraform）は各アプリが行う。
  */
+export { createAdminDirectory, emailsOf, normalizeEmail } from './admins.js';
 export { ALERTS_RESOURCE, ALERT_RETENTION_DAYS, alertKeyOf, cleanupAlerts, createAlertRecorder, } from './alerts.js';
 export { createEmailChannel, sesSender } from './channels/email.js';
 export { createSlackChannel } from './channels/slack.js';

package/dist/notify/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/notify/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,UAAU,EACV,aAAa,EACb,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAYrB,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,EACrB,QAAQ,EACR,OAAO,GACR,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEjF,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC3E,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/notify/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,oBAAoB,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7E,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,UAAU,EACV,aAAa,EACb,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAYrB,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,EACrB,QAAQ,EACR,OAAO,GACR,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEjF,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC3E,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}

package/dist/server/handler.cjs

@@ -1,5 +1,5 @@
-// @exabugs/dynamodb-client v1.15.0
-// Built: 2026-10-18T10:11:26.658Z
+// @exabugs/dynamodb-client v1.16.0
+// Built: 2026-10-20T00:50:17.412Z
 "use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -38980,7 +38980,7 @@ async function handler(event) {
       return createCorsResponse(HTTP_STATUS.OK);
     }
     if (event.requestContext.http.method === "GET" && event.requestContext.http.path === "/version") {
-      const version = "1.15.0";
+      const version = "1.16.0";
       return createSuccessResponse({ version, timestamp: (/* @__PURE__ */ new Date()).toISOString() }, requestId);
     }
     if (event.requestContext.http.method !== "POST") {

package/dist/server/media/recordsClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"recordsClient.d.ts","sourceRoot":"","sources":["../../../src/server/media/recordsClient.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,0EAA0E;AAC1E,eAAO,MAAM,0BAA0B,QAAS,CAAC;AAiCjD,uCAAuC;AACvC,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAGtF;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,IAAI,CAAC,CASf;AAED,8BAA8B;AAC9B,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD"}
+{"version":3,"file":"recordsClient.d.ts","sourceRoot":"","sources":["../../../src/server/media/recordsClient.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,0EAA0E;AAC1E,eAAO,MAAM,0BAA0B,QAAS,CAAC;AASjD,uCAAuC;AACvC,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAGtF;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,IAAI,CAAC,CASf;AAED,8BAA8B;AAC9B,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD"}

package/dist/server/media/recordsClient.js

@@ -2,42 +2,22 @@
  * media の Lambda（process-handler / process-handler-dlq）が Records を呼ぶための共通部品
  *
  * DynamoDB には直接触れず、Records の IAM 版 Function URL を `DynamoClient`（SigV4 署名）で
- * 呼ぶ（詳細: docs/adr/0005-writes-through-records.md）。
+ * 呼ぶ（詳細: docs/adr/0005-writes-through-records.md）。接続の定型は公開ヘルパー
+ * `lazyCollection`（src/client/recordsClient.ts。ADR 0006）に任せる。
  * 失敗は握りつぶさず、そのまま例外にする（呼び出し側が再スローして、Lambda の非同期再試行と
  * DLQ に乗せる）。
  */
-import { DynamoClient } from '../../client/index.iam.js';
+import { lazyCollection } from '../../client/recordsClient.js';
 /** Records へのリクエストの timeout（ms）。Records の Lambda の timeout（30 秒）より短くする */
 export const RECORDS_REQUEST_TIMEOUT_MS = 15_000;
 const MEDIA_COLLECTION = 'media';
-let mediaCollection;
-/**
- * コールドスタートで 1 回だけ生成・接続して再利用する。
- * `db()` は `connect()` の前に呼ぶと例外になるため、接続を待つ（IAM では接続は状態の更新だけ）。
- * 失敗したらキャッシュせず、次の呼び出しでやり直す。
- */
-async function getMediaCollection() {
-    if (!mediaCollection) {
-        const endpoint = process.env.RECORDS_IAM_URL;
-        if (!endpoint) {
-            throw new Error('RECORDS_IAM_URL environment variable is not set');
-        }
-        const region = process.env.AWS_REGION ?? process.env.REGION;
-        if (!region) {
-            throw new Error('AWS_REGION environment variable is not set');
-        }
-        const client = new DynamoClient(endpoint, {
-            auth: { region },
-            timeout: RECORDS_REQUEST_TIMEOUT_MS,
-        });
-        await client.connect();
-        mediaCollection = client.db().collection(MEDIA_COLLECTION);
-    }
-    return mediaCollection;
-}
+/** コールドスタートで 1 回だけ接続して再利用する。環境変数は初回の使用時に読む */
+const mediaCollection = lazyCollection(MEDIA_COLLECTION, {
+    timeout: RECORDS_REQUEST_TIMEOUT_MS,
+});
 /** media レコードを 1 件読む。無ければ undefined */
 export async function findMediaRecord(fileId) {
-    const records = await (await getMediaCollection()).findMany([fileId]);
+    const records = await (await mediaCollection()).findMany([fileId]);
     return records[0];
 }
 /**
@@ -46,10 +26,10 @@ export async function findMediaRecord(fileId) {
  */
 export async function writeMediaRecord(fileId, fields) {
     const now = new Date().toISOString();
-    await (await getMediaCollection()).updateOne({ id: fileId }, { $set: { ...fields, updatedAt: now }, $setOnInsert: { createdAt: now } }, { upsert: true });
+    await (await mediaCollection()).updateOne({ id: fileId }, { $set: { ...fields, updatedAt: now }, $setOnInsert: { createdAt: now } }, { upsert: true });
 }
 /** テスト用: キャッシュしたクライアントを捨てる */
 export function resetRecordsClientForTest() {
-    mediaCollection = undefined;
+    mediaCollection.reset();
 }
 //# sourceMappingURL=recordsClient.js.map

package/dist/server/media/recordsClient.js.map

@@ -1 +1 @@
-{"version":3,"file":"recordsClient.js","sourceRoot":"","sources":["../../../src/server/media/recordsClient.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAIzD,0EAA0E;AAC1E,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAM,CAAC;AAEjD,MAAM,gBAAgB,GAAG,OAAO,CAAC;AAIjC,IAAI,eAA4C,CAAC;AAEjD;;;;GAIG;AACH,KAAK,UAAU,kBAAkB;IAC/B,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;QAC7C,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;QACrE,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC;QAC5D,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;QAChE,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,QAAQ,EAAE;YACxC,IAAI,EAAE,EAAE,MAAM,EAAE;YAChB,OAAO,EAAE,0BAA0B;SACpC,CAAC,CAAC;QACH,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;QACvB,eAAe,GAAG,MAAM,CAAC,EAAE,EAAE,CAAC,UAAU,CAA+B,gBAAgB,CAAC,CAAC;IAC3F,CAAC;IACD,OAAO,eAAe,CAAC;AACzB,CAAC;AAED,uCAAuC;AACvC,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,MAAc;IAClD,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,kBAAkB,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IACtE,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,MAAc,EACd,MAA+B;IAE/B,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACrC,MAAM,CACJ,MAAM,kBAAkB,EAAE,CAC3B,CAAC,SAAS,CACT,EAAE,EAAE,EAAE,MAAM,EAAE,EACd,EAAE,IAAI,EAAE,EAAE,GAAG,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE,YAAY,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE,EACzE,EAAE,MAAM,EAAE,IAAI,EAAE,CACjB,CAAC;AACJ,CAAC;AAED,8BAA8B;AAC9B,MAAM,UAAU,yBAAyB;IACvC,eAAe,GAAG,SAAS,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"recordsClient.js","sourceRoot":"","sources":["../../../src/server/media/recordsClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAG/D,0EAA0E;AAC1E,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAM,CAAC;AAEjD,MAAM,gBAAgB,GAAG,OAAO,CAAC;AAEjC,8CAA8C;AAC9C,MAAM,eAAe,GAAG,cAAc,CAA+B,gBAAgB,EAAE;IACrF,OAAO,EAAE,0BAA0B;CACpC,CAAC,CAAC;AAEH,uCAAuC;AACvC,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,MAAc;IAClD,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,eAAe,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IACnE,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,MAAc,EACd,MAA+B;IAE/B,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACrC,MAAM,CACJ,MAAM,eAAe,EAAE,CACxB,CAAC,SAAS,CACT,EAAE,EAAE,EAAE,MAAM,EAAE,EACd,EAAE,IAAI,EAAE,EAAE,GAAG,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE,YAAY,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE,EACzE,EAAE,MAAM,EAAE,IAAI,EAAE,CACjB,CAAC;AACJ,CAAC;AAED,8BAA8B;AAC9B,MAAM,UAAU,yBAAyB;IACvC,eAAe,CAAC,KAAK,EAAE,CAAC;AAC1B,CAAC"}

package/dist/server/media-handler.cjs

@@ -1,5 +1,5 @@
-// @exabugs/dynamodb-client v1.15.0
-// Built: 2026-10-18T10:11:26.658Z
+// @exabugs/dynamodb-client v1.16.0
+// Built: 2026-10-20T00:50:17.412Z
 "use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;

package/dist/server/media-process-handler-dlq.cjs

@@ -1,5 +1,5 @@
-// @exabugs/dynamodb-client v1.15.0
-// Built: 2026-10-18T10:11:26.658Z
+// @exabugs/dynamodb-client v1.16.0
+// Built: 2026-10-20T00:50:17.412Z
 "use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -45859,38 +45859,59 @@ var DynamoClient2 = class extends DynamoClient {
   }
 };
 
+// src/client/recordsClient.ts
+async function createRecordsClient(options = {}) {
+  const url = options.url ?? process.env.RECORDS_IAM_URL;
+  if (!url) {
+    throw new Error("RECORDS_IAM_URL environment variable is not set");
+  }
+  const region = options.region ?? process.env.AWS_REGION ?? process.env.REGION;
+  if (!region) {
+    throw new Error("AWS_REGION environment variable is not set");
+  }
+  const client = new DynamoClient2(url, {
+    auth: { region },
+    ...options.timeout !== void 0 ? { timeout: options.timeout } : {}
+  });
+  await client.connect();
+  return client;
+}
+__name(createRecordsClient, "createRecordsClient");
+function lazyCollection(name, options = {}) {
+  let cached;
+  const get2 = /* @__PURE__ */ __name((() => {
+    if (!cached) {
+      const attempt = createRecordsClient(options).then(
+        (client) => client.db().collection(name)
+      );
+      cached = attempt;
+      attempt.catch(() => {
+        if (cached === attempt) cached = void 0;
+      });
+    }
+    return cached;
+  }), "get");
+  get2.reset = () => {
+    cached = void 0;
+  };
+  return get2;
+}
+__name(lazyCollection, "lazyCollection");
+
 // src/server/media/recordsClient.ts
 var RECORDS_REQUEST_TIMEOUT_MS = 15e3;
 var MEDIA_COLLECTION = "media";
-var mediaCollection;
-async function getMediaCollection() {
-  if (!mediaCollection) {
-    const endpoint = process.env.RECORDS_IAM_URL;
-    if (!endpoint) {
-      throw new Error("RECORDS_IAM_URL environment variable is not set");
-    }
-    const region = process.env.AWS_REGION ?? process.env.REGION;
-    if (!region) {
-      throw new Error("AWS_REGION environment variable is not set");
-    }
-    const client = new DynamoClient2(endpoint, {
-      auth: { region },
-      timeout: RECORDS_REQUEST_TIMEOUT_MS
-    });
-    await client.connect();
-    mediaCollection = client.db().collection(MEDIA_COLLECTION);
-  }
-  return mediaCollection;
-}
-__name(getMediaCollection, "getMediaCollection");
+var mediaCollection = lazyCollection(MEDIA_COLLECTION, {
+  timeout: RECORDS_REQUEST_TIMEOUT_MS
+});
 async function findMediaRecord(fileId) {
-  const records = await (await getMediaCollection()).findMany([fileId]);
+  const records = await (await mediaCollection()).findMany([fileId]);
   return records[0];
 }
 __name(findMediaRecord, "findMediaRecord");
 async function writeMediaRecord(fileId, fields) {
   const now = (/* @__PURE__ */ new Date()).toISOString();
-  await (await getMediaCollection()).updateOne(
+  await (await mediaCollection()).updateOne(
     { id: fileId },
     { $set: { ...fields, updatedAt: now }, $setOnInsert: { createdAt: now } },
     { upsert: true }