@exabugs/dynamodb-client 1.21.0 → 1.23.0

package/docs/ADMINS.md

@@ -0,0 +1,57 @@
+# 管理者（admins）
+
+管理画面にログインできる人の正本は、Records の `admins` コレクションのレコードである（[ADR 0007](adr/0007-app-basic-features.md) §7）。このライブラリは、レコードの形・メールの正規化・存在確認つきの作成（`@exabugs/dynamodb-client/admins`）、管理画面（`adminsResource`。[react-admin-integration.md](react-admin-integration.md) の「管理者の画面」）、最初の 1 人の登録の CLI（`dynamodb-admins`）を持つ。通知の宛先（`createAdminDirectory`。[NOTIFY.md](NOTIFY.md)）も同じレコードを読む。
+
+## レコードの形
+
+```ts
+import type { AdminRecord } from '@exabugs/dynamodb-client/admins';
+
+interface AdminRecord {
+  id: string; // 不変。作成時の小文字のメール
+  name: string; // 表示名（必須）
+  email: string; // 不変。常に id と同じ値
+  createdAt?: string;
+  updatedAt?: string;
+}
+```
+
+- `id` が主キーなので、同じメールで 2 件はできない。ログインの判定（Pre Token Generation）は、正規化したメールで `id` を直接引く
+- `email` を持たない既存のレコード（asanowa の `{ id, name }`）は、`id` を `email` として扱う（`adminEmailOf(record)`）。補完の書き込みは任意
+- `name` は必須。ただし `name` を持たない既存のレコード（astro）も、画面は表示できる（「—」）
+- メールアドレスは変えられない。新しい管理者を作り、古い管理者を削除する
+
+## 関数
+
+| 関数                                   | 内容                                                                                                             |
+| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `normalizeAdminEmail(raw)`             | 前後の空白を除き小文字にする（形式は検査しない）。画面・CLI・`createAdminDirectory` が共有する                   |
+| `isAdminEmail(normalized)`             | メールの形式か                                                                                                   |
+| `adminEmailOf(record)`                 | `email`（無ければ `id`）                                                                                         |
+| `buildAdminRecord({ email, name })`    | 作るレコード `{ id, email, name }`。形式の誤り・空の名前は `AdminInputError`（`field` は `'email'` か `'name'`） |
+| `addAdmin(input, writer, { dryRun? })` | 存在確認つきの作成。`{ status: 'created' \| 'exists' \| 'dry-run', record }`。既にあれば書き込まない             |
+| `adminWriterOf(collection)`            | Records のコレクションでの存在確認（`findAdmin`）と `insertOne`                                                  |
+| `findAdmin(collection, id)`            | `find({ id })` + id の昇順 + 1 件（無ければ null）                                                               |
+
+**作成の前に、必ず `id` で存在を確かめる。** 同じ `id` で `insertOne` すると、Records は存在確認をせずに黙って上書きする（条件付き書き込みが無い既知の制約）。`findOne` は、無い `id` で 404 と `ITEM_NOT_FOUND` の警告を出すので、存在確認には使わない。
+
+## 最初の管理者の登録（CLI）
+
+管理画面には admins にいる人しかログインできないので、最初の 1 人は CLI で登録する（2 人目以降は管理画面の「管理者」から）。
+
+```bash
+AWS_PROFILE=<profile> npx dynamodb-admins add you@example.com --app <app> --env dev --name 山田 --dry-run
+AWS_PROFILE=<profile> npx dynamodb-admins add you@example.com --app <app> --env dev --name 山田
+```
+
+- 経路: Records の IAM 版 Function URL を、利用者の AWS の認証情報（SigV4）で呼ぶ。URL は SSM の `/<app>/<env>/infra/dynamodb-client-api-iam-url`（`terraform/modules/parameter-store` が作る）から読む（`--url` で直接も渡せる）。要る権限は、SSM の `GetParameter` と、Function URL の呼び出し
+- オプション: `--region`（既定 `AWS_REGION`、無ければ `ap-northeast-1`）、`--collection`（既定 `admins`）、`--dry-run`（存在確認だけして書き込まない）、`--confirm <env>`
+- **prd の確認**: `--env prd` で書き込むときは `--confirm prd` が要る（例: `… --env prd --name 山田 --confirm prd`。astro の `make … CONFIRM=prd` と同じ流儀）。無い・違う値なら、SSM も Records も呼ばずに終了コード 2。`--dry-run` は書き込まないので要らない
+- 出力には、宛先の `app/env`・コレクションと、Records の URL のホストを出す（`--url` を渡したときの食い違いに気づけるように）
+- 終了コード: 0 = 登録した（`--dry-run` では登録できる）、**3 = 既に登録されている（何も書いていない）**、2 = 引数の誤り・prd の確認の不足、1 = そのほかの失敗（メールの形式の誤りを含む）
+
+## アプリに残るもの
+
+- 管理画面: `<Resource {...adminsResource({ icon })} />`（アイコンはアプリが選ぶ）
+- 最初の管理者のメール（CLI の引数）
+- 誰を admins に入れるか（データ）

package/docs/NOTIFY.md

@@ -119,6 +119,57 @@ export const handler = createNotifyHandler({
 });
 ```
 
+### 通知 Lambda のエントリ（`createOpsNotifyHandler`。1.22.0）
+
+`terraform/ops-notify` の Lambda のエントリは、ハンドラのファクトリを export するだけでよい。上の組み立て（環境変数の読み取り、Slack〔SSM の Webhook〕・メール〔SES v2〕のチャネル、通知ストア、管理者の一覧、alerts の記録）をライブラリが行う。asanowa・astro のエントリ（`functions/ops-notify/src/index.ts`・`apps/server/src/notify.ts`）を 1 つにしたもの:
+
+```ts
+import { createOpsNotifyHandler } from '@exabugs/dynamodb-client/notify/ops';
+
+export const handler = createOpsNotifyHandler();
+```
+
+- 環境変数（`terraform/ops-notify` が設定する。`readOpsNotifyConfig` が読む）: `PROJECT_NAME`・`ENV_NAME`・`RECORDS_IAM_URL`・`NOTICE_TABLE`（必須。無ければ `<名前> environment variable is required`）、`SLACK_WEBHOOK_PARAM`・`MAIL_FROM`（空なら、そのチャネルを作らない）、`SES_REGION`（既定 `us-east-1`）、`DRY_RUN=true`、`ADMIN_BASE_URL`（あるときだけ alerts に記録する）、`SKIP_RECORD_LOG_GROUPS`（カンマ区切り。`ADMIN_BASE_URL` があって空なら warn `ALERTS_SKIP_LOG_GROUPS_EMPTY`）。リージョンは `AWS_REGION`（無ければ `REGION`。どちらも無ければ例外）
+- ハンドラは最初の呼び出しで組み立て、コンテナの中で使い回す（遮断・管理者の一覧のキャッシュを保つ）。組み立てに失敗したら、次の呼び出しでやり直す
+- 既定: `failOnAnyChannelError: true`（一部のチャネルの失敗も Lambda の失敗先へ）、記録の上限 `OPS_NOTIFY_RECORD_LIMITS`（3000 ms・50 件・並列 5）、遮断 `OPS_NOTIFY_RECORD_BREAKER`（3 回・60 秒）、alerts の書き込みの HTTP の時間切れ `OPS_NOTIFY_RECORD_HTTP_TIMEOUT_MS`（2500 ms。記録の上限より短く）
+- Webhook の URL は SSM（SecureString）から最初の送信で読み、実行環境の間はキャッシュする
+- **サブパスは `notify/ops`**（`notify` 本体と分ける）。SSM・SES の SDK（`@aws-sdk/client-ssm`・`@aws-sdk/client-sesv2`。どちらもライブラリの依存）を静的に import するので、`notify` 本体（alerts-cleanup など）は SDK を読まないまま。メールの送信は、ライブラリが既定で SES v2 を使う（`sesSender` に SDK を渡す形は、`createNotifyHandler` を直接使うときのもの）
+- バンドル（どちらも CJS。`src/notify/ops/__tests__/bundle.test.ts` で固定）:
+  - SDK を外部にする（asanowa: `esbuild --bundle --platform=node --format=cjs --external:@aws-sdk/*`）: SDK は `require("@aws-sdk/…")` のまま残り、Lambda の実行環境の SDK（NODE_PATH）で解決される。動的 `import()` は残らない
+  - SDK も同梱する（astro: `--external` なし）: ライブラリの依存の版の SDK がバンドルに入る
+- alerts の書き込み先は Records のコレクション（`lazyCollection`。最初の書き込みで接続し、使い回す）。管理者の一覧は呼び出しごとに接続して閉じる（`withCollection`）
+
+オプション（どれも任意）:
+
+| オプション            | 既定                          | 内容                                                                                                                                                                                                    |
+| --------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `app`                 | `PROJECT_NAME`                | 通知の `app`。渡せば `PROJECT_NAME` は不要                                                                                                                                                              |
+| `region`              | `AWS_REGION`                  | 通知ストア・SSM・Records・ログ参照のリージョン                                                                                                                                                          |
+| `admins`              | 宛先は `id`、生のコレクション | `createAdminDirectory` の設定（`recipientFields`・`sortById`・`maxAdmins`・`collection`・`timeout`）と、`lister: (raw) => AdminsLister`（読み取りを権限チェック層で包む）。url・region はハンドラが渡す |
+| `alertsCollection`    | 生のコレクション              | `(raw) => AlertsCollection`。alerts の書き込みを自分の層で包むアプリが使う                                                                                                                              |
+| `recordHttpTimeoutMs` | 2500                          | alerts の書き込みの HTTP の時間切れ                                                                                                                                                                     |
+| `log`                 | `logJson`                     | 設定の誤りの警告（`ALERTS_SKIP_LOG_GROUPS_EMPTY`）の出力先                                                                                                                                              |
+| `notify`              | 上の既定                      | `createNotifyHandler` に渡す設定（`windows`・`rate`・`adminCacheSec`・`failOnAnyChannelError`・`now`・`logger`・`skipRecordEvents`・`recordLimits`・`recordBreaker`）                                   |
+| `overrides`           | なし                          | テスト用の差し替え（`store`・`channels`・`admins`・`alertsCollection`・`ssmClient`・`emailSender`）                                                                                                     |
+
+アプリごとの書き方（現行の挙動を再現する）:
+
+```ts
+// asanowa: 既定のまま（管理者は id、生のコレクション）
+export const handler = createOpsNotifyHandler();
+
+// astro: 管理者は email ?? id・id の昇順で、読み取りを権限チェック層に通す
+export const handler = createOpsNotifyHandler({
+  admins: {
+    recipientFields: ['email', 'id'],
+    sortById: true,
+    lister: (raw) => authorizedCollection(ADMINS, raw, PERMISSION_MATRIX, { role: 'system' }),
+  },
+});
+```
+
+アプリに残るもの: エントリの数行（と、権限チェック層を通すアプリの包み方）、バンドルの作成、`terraform/ops-notify` の module ブロック。IAM は `terraform/ops-notify` が付けるもの（notices の UpdateItem、Records の IAM URL、SSM の GetParameter、SES の送信）で足りる。
+
 ## 配線の注意（各アプリ）
 
 - **通知ハンドラのロググループは購読しない**（自分のログで無限ループになる）。失敗は Lambda の失敗先（SNS など）→ 固定の運用者のアドレスへ届ける

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exabugs/dynamodb-client",
-  "version": "1.21.0",
+  "version": "1.23.0",
   "description": "DynamoDB Single-Table Client SDK with MongoDB-like API, Shadow Records, and Lambda implementation for serverless applications",
   "author": "exabugs",
   "license": "MIT",
@@ -9,6 +9,7 @@
   "types": "./dist/index.d.ts",
   "bin": {
     "dynamodb-access-check": "./bin/dynamodb-access-check.js",
+    "dynamodb-admins": "./bin/dynamodb-admins.js",
     "dynamodb-system-change": "./bin/dynamodb-system-change.js"
   },
   "keywords": [
@@ -46,7 +47,8 @@
     "docs/NOTIFY.md",
     "docs/DYNAMODB_ACCESS.md",
     "docs/RECORDS_CLIENT.md",
-    "docs/SYSTEM_CHANGES.md"
+    "docs/SYSTEM_CHANGES.md",
+    "docs/ADMINS.md"
   ],
   "exports": {
     ".": {
@@ -89,6 +91,10 @@
       "import": "./dist/integrations/react-admin/index.js",
       "types": "./dist/integrations/react-admin/index.d.ts"
     },
+    "./integrations/react-admin/i18n": {
+      "import": "./dist/integrations/react-admin/i18n/index.js",
+      "types": "./dist/integrations/react-admin/i18n/index.d.ts"
+    },
     "./server/media/presign": {
       "import": "./dist/server/media/presign.js",
       "types": "./dist/server/media/presign.d.ts"
@@ -127,6 +133,10 @@
       "import": "./dist/notify/index.js",
       "types": "./dist/notify/index.d.ts"
     },
+    "./notify/ops": {
+      "import": "./dist/notify/ops/index.js",
+      "types": "./dist/notify/ops/index.d.ts"
+    },
     "./system-changes": {
       "import": "./dist/system-changes/index.js",
       "types": "./dist/system-changes/index.d.ts"
@@ -134,11 +144,17 @@
     "./system-changes/cli": {
       "import": "./dist/tools/dynamodb-system-change/index.js",
       "types": "./dist/tools/dynamodb-system-change/index.d.ts"
+    },
+    "./admins": {
+      "import": "./dist/admins/index.js",
+      "types": "./dist/admins/index.d.ts"
     }
   },
   "peerDependencies": {
     "@mui/material": "^5.16.12 || ^6.0.0 || ^7.0.0",
-    "react-admin": "^5.0.0"
+    "react-admin": "^5.0.0",
+    "ra-i18n-polyglot": "^5.0.0",
+    "ra-language-english": "^5.0.0"
   },
   "peerDependenciesMeta": {
     "@mui/material": {
@@ -146,6 +162,12 @@
     },
     "react-admin": {
       "optional": true
+    },
+    "ra-i18n-polyglot": {
+      "optional": true
+    },
+    "ra-language-english": {
+      "optional": true
     }
   },
   "scripts": {
@@ -173,6 +195,7 @@
     "@aws-crypto/sha256-js": "5.2.0",
     "@aws-sdk/client-dynamodb": "3.946.0",
     "@aws-sdk/client-s3": "3.946.0",
+    "@aws-sdk/client-sesv2": "3.946.0",
     "@aws-sdk/client-ssm": "3.946.0",
     "@aws-sdk/cloudfront-signer": "3.946.0",
     "@aws-sdk/credential-provider-node": "3.946.0",
@@ -205,6 +228,8 @@
     "jsdom": "^26.1.0",
     "orval": "^8.2.0",
     "prettier": "^3.0.0",
+    "ra-i18n-polyglot": "^5.0.0",
+    "ra-language-english": "^5.0.0",
     "react-admin": "^5.0.0",
     "sharp": "^0.35.5",
     "tsx": "^4.21.0",

package/terraform/ops-notify/README.md

@@ -16,7 +16,7 @@ ADR 0006 の (b)（1.21.0）。asanowa・astro の `infra/modules/ops-notify`
 ## 前提
 
 - 参照は `node_modules` のパス（版は npm の版で固定される。git の `ref` ではない）。例: アプリの infra が `infra/` なら `source = "../node_modules/@exabugs/dynamodb-client/terraform/ops-notify"`、`infra/apps/<app>/` なら `"../../../node_modules/..."`
-- **Lambda の成果物はアプリが作り、`source_file`（バンドル済みの 1 ファイル）と `handler` で渡す**。エントリはアプリの数行（`createNotifyHandler` などの notify の部品。アプリ名や、権限チェック層を通すアプリの包み方を渡す）なので、ライブラリの dist は使わない
+- **Lambda の成果物はアプリが作り、`source_file`（バンドル済みの 1 ファイル）と `handler` で渡す**。エントリはアプリの数行（1.22.0 からは `@exabugs/dynamodb-client/notify/ops` の `createOpsNotifyHandler()`。権限チェック層を通すアプリは包み方を渡す。[docs/NOTIFY.md](../../docs/NOTIFY.md) の「通知 Lambda のエントリ」）なので、ライブラリの dist は使わない
 - zip は `${path.root}/.terraform/archives/notify.zip` に作る（`path.module` を使わない。pnpm の版つきのパスが state に入ると、版を上げるたびに差分が出るため）
 - pnpm では、版を上げた後に `.terraform/modules` を消してから `terraform init` する（[../README.md](../README.md) の注意）
 - モジュール全体の `depends_on` は使わない（依存先に変更があると、中のデータソースが apply 時の読み取りになり、既存のリソースが作り直しになる）。依存は、出力の値（`log_group_name` など）で渡す
@@ -95,7 +95,7 @@ provider "aws" {
 ## アプリに残るもの
 
 - 上の module ブロック（`source`・`providers`・`source_file`・`handler` と設定の値）
-- Lambda のエントリ（`createNotifyHandler` などの notify の部品 を呼ぶ数行）とバンドルの作成（esbuild など）
+- Lambda のエントリ（`createOpsNotifyHandler` を export する数行）とバンドルの作成（esbuild など）
 - 秘密（webhook の URL など）の SSM パラメータの作成
 
 ## アプリのモジュールからの移行（置き換えを起こさない）