@h-ai/reach 1.0.0-beta.21 → 1.0.0-beta.23

package/README.en.md

@@ -175,7 +175,7 @@ Production rejects console providers and requires SMTP, SMS or an actual API ser
 
 Use `reach.send({ ..., sensitive: true, expiresAt, idempotencyKey })` for passwords, OTPs and reset tokens. expiresAt is Unix milliseconds; stable operation keys must contain no credentials. A shared ledger stores only metadata receipts/status and redacted destinations, never bodies, variables or credential hashes. There is no delayed credential queue. Success returns receiptId; DND/expired messages are not sent, and uncertain delivery is never automatically repeated. Explicit development console output is isolated from persistent observers. Production Console restrictions remain. Normal messages may use deferPolicy: reject to avoid a second queue.
 
-`migrateReach({ dryRun: true })` previews persistence preparation performed during repository initialization. Stop on failure, back up and stop conflicting writers first, preserve the sending ledger and never treat schema preparation as permission to replay credentials.
+`reach.init()` creates and validates the send log and its queue identifier constraint. Incompatible tables cause initialization to fail. Preserve send receipts and reconcile uncertain outcomes before attempting further credential delivery.
 
 ### API acknowledgements and destination boundaries
 

package/README.ja.md

@@ -175,7 +175,7 @@ if (state.data?.status === 'dead' && state.data.updatedAt !== undefined) {
 
 パスワード、OTP、リセットトークンは `reach.send({ ..., sensitive: true, expiresAt, idempotencyKey })` を使います。expiresAt は Unix ミリ秒、操作キーに秘密値を含めません。共有台帳は本文・変数・認証値のハッシュを保存せず、脱機密化した宛先と受領状態のみを保持します。遅延キューに入れず、DND/期限切れは送信せず、不明な配信を自動再送しません。成功時は receiptId を返します。明示した開発用コンソール出力は永続観測から分離し、本番 Console 制限は維持します。通常通知は deferPolicy: reject で二重キューを防げます。
 
-`migrateReach({ dryRun: true })` で永続構造を確認し、リポジトリ初期化で準備します。失敗時は停止し、事前バックアップと競合書込の停止を行い、送信台帳を保持します。構造準備を資格情報の再送許可と解釈しないでください。
+`reach.init()` は送信ログとキュー識別子の制約を作成・検証し、構造が一致しない場合は初期化に失敗します。送信台帳を保存し、結果が不明な資格情報通知は永続レシートで状態を確認してください。
 
 ### API 応答と送信先の境界
 

package/README.md

@@ -175,7 +175,7 @@ if (state.data?.status === 'dead' && state.data.updatedAt !== undefined) {
 
 发送密码、OTP 或重置令牌时使用 `reach.send({ ..., sensitive: true, expiresAt, idempotencyKey })`。expiresAt 是 Unix 毫秒，稳定操作键不可包含凭据。必须有共享发送账本：只持久化无载荷回执/状态，接收方脱敏，不存正文、变量或低熵凭据摘要，也不进入延迟队列。发送成功返回 receiptId；DND/过期不投递，异常或不明状态不自动重投。明确启用的开发控制台仍可显示业务允许的通知，持久采集观察器被隔离；生产 Console Provider 限制不变。普通通知可用 deferPolicy: reject 阻止二次排队。
 
-`migrateReach({ dryRun: true })` 预检持久结构，仓储初始化执行支持的准备步骤；失败时停止初始化。执行前备份并停止冲突写入，保留发送账本，不把结构准备作为重新发送凭据的理由。
+`reach.init()` 创建并校验发送日志表及队列标识约束，结构不符时返回初始化失败。保留发送账本，按持久回执核对状态，避免重发结果不明的凭据通知。
 
 ### API 回执与目标边界
 

package/dist/index.d.ts

@@ -1,8 +1,6 @@
 import { z } from 'zod';
 import * as _h_ai_core from '@h-ai/core';
 import { HaiResult } from '@h-ai/core';
-import * as _h_ai_reldb from '@h-ai/reldb';
-import { ReldbFunctions } from '@h-ai/reldb';
 
 /**
  * @h-ai/reach — 配置 Schema
@@ -1377,17 +1375,5 @@ interface ReachFunctions extends SendOperations {
  */
 declare const reach: ReachFunctions;
 
-/**
- * 预检或升级 Reach 队列。旧凭据相关载荷清除，待发凭据丢弃，保留发送状态和历史标识。
- * @example
- * ```ts
- * import { migrateReach } from '@h-ai/reach'
- * const plan = await migrateReach({ dryRun: true })
- * ```
- */
-declare function migrateReach(options?: {
-    dryRun?: boolean;
-}, db?: ReldbFunctions): Promise<_h_ai_core.HaiResult<_h_ai_reldb.SchemaMigrationPlan>>;
-
-export { AliyunSmsProviderConfigSchema, ApiProviderConfigSchema, ConsoleProviderConfigSchema, DndConfigSchema, HaiReachError, ProviderConfigSchema, ReachConfigSchema, ReachDeadRequeueSchema, ReachQueueConfigSchema, ReachQueueIdSchema, ReachQueueListSchema, ReachUnknownResolutionSchema, SmtpProviderConfigSchema, TemplateConfigSchema, migrateReach, reach };
+export { AliyunSmsProviderConfigSchema, ApiProviderConfigSchema, ConsoleProviderConfigSchema, DndConfigSchema, HaiReachError, ProviderConfigSchema, ReachConfigSchema, ReachDeadRequeueSchema, ReachQueueConfigSchema, ReachQueueIdSchema, ReachQueueListSchema, ReachUnknownResolutionSchema, SmtpProviderConfigSchema, TemplateConfigSchema, reach };
 export type { AliyunSmsProviderConfig, ApiProviderConfig, ConsoleProviderConfig, DndConfig, ProviderConfig, ReachChannel, ReachConfig, ReachConfigInput, ReachDeadRequeue, ReachFunctions, ReachGatewayHook, ReachInitOptions, ReachMessage, ReachQueueConfig, ReachQueueEntry, ReachQueueFailure, ReachQueueListOptions, ReachQueueOperations, ReachQueueStatus, ReachTemplate, ReachTemplateRegistry, ReachUnknownResolution, RenderedTemplate, SendOperations, SendResult, SmtpProviderConfig, TemplateConfig };

package/dist/index.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { core, err, ok } from '@h-ai/core';
 import process from 'process';
 import { reldb, BaseReldbCrudRepository } from '@h-ai/reldb';
-import { randomUUID, createHash, createHmac } from 'crypto';
+import { createHash, randomUUID, createHmac } from 'crypto';
 import { addAbortListener } from 'events';
 import { createRequire } from 'module';
 import { cache } from '@h-ai/cache';
@@ -11,6 +11,7 @@ import { cache } from '@h-ai/cache';
 
 // messages/en-US.json
 var en_US_default = {
+  reach_sendLogIndexRequired: "The send log table requires a unique index on receipt IDs",
   $schema: "https://inlang.com/schema/inlang-message-format",
   reach_notInitialized: "Reach module not initialized, call reach.init() first",
   reach_initFailed: "Reach module initialization failed: {error}",
@@ -70,6 +71,7 @@ var en_US_default = {
 
 // messages/ja-JP.json
 var ja_JP_default = {
+  reach_sendLogIndexRequired: "\u9001\u4FE1\u30ED\u30B0\u30C6\u30FC\u30D6\u30EB\u306B\u306F\u53D7\u4ED8 ID \u306E\u4E00\u610F\u30A4\u30F3\u30C7\u30C3\u30AF\u30B9\u304C\u5FC5\u8981\u3067\u3059",
   $schema: "https://inlang.com/schema/inlang-message-format",
   reach_notInitialized: "\u901A\u77E5\u30E2\u30B8\u30E5\u30FC\u30EB\u304C\u521D\u671F\u5316\u3055\u308C\u3066\u3044\u307E\u305B\u3093\u3002\u5148\u306Breach.init()\u3092\u547C\u3073\u51FA\u3057\u3066\u304F\u3060\u3055\u3044",
   reach_initFailed: "\u901A\u77E5\u30E2\u30B8\u30E5\u30FC\u30EB\u306E\u521D\u671F\u5316\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
@@ -129,6 +131,7 @@ var ja_JP_default = {
 
 // messages/zh-CN.json
 var zh_CN_default = {
+  reach_sendLogIndexRequired: "\u53D1\u9001\u65E5\u5FD7\u8868\u5FC5\u987B\u4E3A\u56DE\u6267\u7F16\u53F7\u5EFA\u7ACB\u552F\u4E00\u7D22\u5F15",
   $schema: "https://inlang.com/schema/inlang-message-format",
   reach_notInitialized: "\u89E6\u8FBE\u6A21\u5757\u5C1A\u672A\u521D\u59CB\u5316\uFF0C\u8BF7\u5148\u8C03\u7528 reach.init()",
   reach_initFailed: "\u89E6\u8FBE\u6A21\u5757\u521D\u59CB\u5316\u5931\u8D25: {error}",
@@ -483,7 +486,7 @@ function createAliyunSmsProvider(gatewayHook) {
       }
       const templateCode = message.extra?.templateCode;
       if (!config.gateway)
-        logger.debug("Sending SMS", { to: message.to, templateCode });
+        logger.debug("Sending SMS", { templateCode });
       try {
         const params = {
           AccessKeyId: config.accessKeyId,
@@ -525,14 +528,18 @@ function createAliyunSmsProvider(gatewayHook) {
             reachM("reach_smsSendFailed")
           );
         }
-        logger.info("SMS sent", { to: message.to, bizId: body.BizId });
+        logger.info("SMS sent", { bizId: body.BizId });
         return ok({ success: true, messageId: body.BizId });
       } catch (error) {
         if (config.gateway) {
-          logger.warn("SMS gateway request failed");
+          logger.warn("SMS gateway request failed", {
+            causeName: error instanceof Error ? error.name : void 0
+          });
           return err(HaiReachError.SEND_FAILED, reachM("reach_smsGatewayFailed"));
         }
-        logger.error("SMS send failed", { to: message.to, error });
+        logger.warn("SMS send failed", {
+          causeName: error instanceof Error ? error.name : void 0
+        });
         return err(toReachError());
       }
     }
@@ -713,7 +720,6 @@ function createConsoleProvider() {
     async send(message) {
       logger3.debug("Sending message via console", {
         provider: message.provider,
-        to: message.to,
         hasSubject: Boolean(message.subject),
         bodyLength: message.body?.length ?? 0,
         template: message.template,
@@ -725,6 +731,15 @@ function createConsoleProvider() {
   };
 }
 var logger4 = core.logger.child({ module: "reach", scope: "provider-smtp" });
+function smtpErrorDiagnostics(error) {
+  const code = error && typeof error === "object" && "code" in error ? error.code : void 0;
+  const responseCode = error && typeof error === "object" && "responseCode" in error ? error.responseCode : void 0;
+  return {
+    causeName: error instanceof Error ? error.name : void 0,
+    causeCode: typeof code === "string" && /^[A-Z0-9_]{1,64}$/.test(code) ? code : void 0,
+    responseCode: typeof responseCode === "number" ? responseCode : void 0
+  };
+}
 function toReachError3() {
   return {
     ...HaiReachError.SEND_FAILED,
@@ -759,7 +774,7 @@ function createSmtpProvider() {
         logger4.info("SMTP provider connected", { host: config.host, port: config.port });
         return ok(void 0);
       } catch (error) {
-        logger4.error("SMTP connection failed", { error });
+        logger4.error("SMTP connection failed", smtpErrorDiagnostics(error));
         return err(toReachError3());
       }
     },
@@ -781,7 +796,7 @@ function createSmtpProvider() {
           reachM("reach_notInitialized")
         );
       }
-      logger4.debug("Sending email", { to: message.to, subject: message.subject });
+      logger4.debug("Sending email");
       try {
         const sendMail = transporter.sendMail.bind(transporter);
         const info = await sendMail({
@@ -790,10 +805,10 @@ function createSmtpProvider() {
           subject: message.subject ?? "",
           html: message.body ?? ""
         });
-        logger4.info("Email sent", { to: message.to, messageId: info.messageId });
+        logger4.info("Email sent");
         return ok({ success: true, messageId: info.messageId });
       } catch (error) {
-        logger4.error("Email send failed", { to: message.to, error });
+        logger4.warn("Email send failed", smtpErrorDiagnostics(error));
         return err(toReachError3());
       }
     }
@@ -1313,7 +1328,7 @@ async function executeSend(message, providers2, templateRegistry2, dndConfig2, r
       logger6.info("Message persisted for DND delivery", { provider: providerName, queueId });
       return ok({ success: true, deferred: true, queueId });
     }
-    logger6.info("Message blocked by DND (discard strategy)", { provider: providerName, to: message.to });
+    logger6.info("Message blocked by DND (discard strategy)", { provider: providerName });
     return err(
       HaiReachError.DND_BLOCKED,
       reachM("reach_dndBlocked")
@@ -1322,14 +1337,12 @@ async function executeSend(message, providers2, templateRegistry2, dndConfig2, r
   const provider = providers2.get(providerName);
   logger6.debug("Sending message", {
     provider: providerName,
-    to: preprocessed.data.to,
     template: message.template
   });
   const result = await provider.send(preprocessed.data);
   if (!result.success) {
     logger6.warn("Message send failed", {
       provider: providerName,
-      to: message.to,
       error: result.error.code
     });
     return result;
@@ -1342,133 +1355,6 @@ async function executeSend(message, providers2, templateRegistry2, dndConfig2, r
   }
   return result;
 }
-function migrateReach(options = {}, db = reldb) {
-  const definitions = {
-    queue_id: db.config?.type === "mysql" ? "VARCHAR(255)" : "TEXT",
-    retry_safe: "BOOLEAN NOT NULL DEFAULT FALSE",
-    attempt_count: "BIGINT NOT NULL DEFAULT 0",
-    max_attempts: "BIGINT NOT NULL DEFAULT 5",
-    next_attempt_at: "BIGINT NOT NULL DEFAULT 0",
-    retry_delay_ms: "BIGINT NOT NULL DEFAULT 60000",
-    max_retry_delay_ms: "BIGINT NOT NULL DEFAULT 3600000",
-    last_failure: "TEXT"
-  };
-  const steps = [
-    {
-      version: 1,
-      name: "durable-delivery-ledger",
-      async needed(sql) {
-        const found = await db.schemaColumns("hai_reach_send_log", sql);
-        return found.success ? ok(found.data.length > 0 && Object.keys(definitions).some((name) => !found.data.includes(name))) : found;
-      },
-      async apply(sql) {
-        const found = await db.schemaColumns("hai_reach_send_log", sql);
-        if (!found.success)
-          return found;
-        for (const [name, definition] of Object.entries(definitions)) {
-          if (found.data.includes(name))
-            continue;
-          const added = await sql.execute(`ALTER TABLE hai_reach_send_log ADD COLUMN ${name} ${definition}`);
-          if (!added.success)
-            return added;
-        }
-        return ok(void 0);
-      }
-    },
-    {
-      version: 2,
-      name: "legacy-delivery-isolation",
-      async needed(sql) {
-        const found = await db.schemaColumns("hai_reach_send_log", sql);
-        if (!found.success || !found.data.length) {
-          return found.success ? ok(false) : found;
-        }
-        if (!found.data.includes("queue_id"))
-          return ok(true);
-        const row = await sql.get("SELECT id FROM hai_reach_send_log WHERE queue_id IS NULL AND status IN ('pending','processing','unknown') LIMIT 1");
-        return row.success ? ok(Boolean(row.data)) : row;
-      },
-      async apply(sql) {
-        const isolated = await sql.execute("UPDATE hai_reach_send_log SET status='unknown',processing_owner=NULL,locked_until=NULL WHERE status='processing' AND queue_id IS NULL");
-        if (!isolated.success)
-          return isolated;
-        while (true) {
-          const rows = await sql.query("SELECT id FROM hai_reach_send_log WHERE queue_id IS NULL AND status IN ('pending','unknown') ORDER BY id LIMIT 100");
-          if (!rows.success)
-            return rows;
-          for (const row of rows.data) {
-            const saved = await sql.execute("UPDATE hai_reach_send_log SET queue_id=? WHERE id=? AND queue_id IS NULL", [
-              randomUUID(),
-              row.id
-            ]);
-            if (!saved.success)
-              return saved;
-          }
-          if (rows.data.length < 100)
-            return ok(void 0);
-        }
-      }
-    },
-    {
-      version: 3,
-      name: "credential-payload-retirement",
-      async needed(sql) {
-        const found = await db.schemaColumns("hai_reach_send_log", sql);
-        if (!found.success || !found.data.length) {
-          return found.success ? ok(false) : found;
-        }
-        const ledger = await db.schemaColumns("hai_schema_migrations", sql);
-        if (!ledger.success)
-          return ledger;
-        const version = ledger.data.length ? await sql.get("SELECT version FROM hai_schema_migrations WHERE module=?", ["reach"]) : ok(null);
-        if (!version.success)
-          return version;
-        if (Number(version.data?.version ?? 0) >= 3)
-          return ok(false);
-        const row = await sql.get("SELECT id FROM hai_reach_send_log WHERE subject IS NOT NULL OR body IS NOT NULL OR template IS NOT NULL OR vars_json IS NOT NULL OR extra_json IS NOT NULL LIMIT 1");
-        return row.success ? ok(Boolean(row.data)) : row;
-      },
-      async apply(sql) {
-        return sql.execute("UPDATE hai_reach_send_log SET body=NULL,subject=NULL,vars_json=NULL,extra_json=NULL,template=NULL,status=CASE WHEN status IN ('pending','processing') THEN 'discarded' WHEN status='sending' THEN 'unknown' ELSE status END,processing_owner=NULL,locked_until=NULL WHERE subject IS NOT NULL OR body IS NOT NULL OR template IS NOT NULL OR vars_json IS NOT NULL OR extra_json IS NOT NULL");
-      }
-    },
-    {
-      version: 4,
-      name: "unique-operation-receipts",
-      async needed(sql) {
-        const columns = await db.schemaColumns("hai_reach_send_log", sql);
-        if (!columns.success || !columns.data.length) {
-          return columns.success ? ok(false) : columns;
-        }
-        if (!columns.data.includes("queue_id"))
-          return ok(true);
-        if (db.config?.type === "sqlite") {
-          const indexes = await sql.query("PRAGMA index_list(hai_reach_send_log)");
-          if (!indexes.success)
-            return indexes;
-          for (const index of indexes.data) {
-            if (!index.unique || !/^\w+$/.test(index.name))
-              continue;
-            const fields = await sql.query(`PRAGMA index_info(${index.name})`);
-            if (!fields.success)
-              return fields;
-            if (fields.data.length === 1 && fields.data[0]?.name === "queue_id")
-              return ok(false);
-          }
-          return ok(true);
-        }
-        const found = db.config?.type === "mysql" ? await sql.get("SELECT index_name FROM information_schema.statistics WHERE table_schema=DATABASE() AND table_name=? AND non_unique=0 GROUP BY index_name HAVING COUNT(*)=1 AND MAX(column_name)=?", ["hai_reach_send_log", "queue_id"]) : await sql.get("SELECT i.indexrelid FROM pg_index i JOIN pg_class t ON t.oid=i.indrelid JOIN pg_namespace n ON n.oid=t.relnamespace JOIN pg_attribute a ON a.attrelid=t.oid AND a.attnum=ANY(i.indkey) WHERE t.relname=? AND n.nspname=current_schema() AND i.indisunique AND i.indnatts=1 AND a.attname=?", ["hai_reach_send_log", "queue_id"]);
-        return found.success ? ok(!found.data) : found;
-      },
-      async apply(sql) {
-        return sql.execute("CREATE UNIQUE INDEX uq_hai_reach_queue_v1 ON hai_reach_send_log(queue_id)");
-      }
-    }
-  ];
-  return db.migrateSchema("reach", steps, options);
-}
-
-// src/repositories/reach-repository-send-log.ts
 var TABLE_NAME = "hai_reach_send_log";
 var DEFAULT_CLAIM_BATCH_SIZE = 100;
 var DEFAULT_CLAIM_LOCK_MS = 10 * 60 * 1e3;
@@ -1692,11 +1578,8 @@ function resetSendLogRepoSingleton() {
 async function createSendLogRepository(db) {
   if (sendLogRepoInstance && sendLogRepoSqlOps === db.sql)
     return ok(sendLogRepoInstance);
-  const migration = await migrateReach({}, db);
-  if (!migration.success)
-    return migration;
   const repo = new DbSendLogRepository(db);
-  const initResult = await repo.count();
+  const initResult = await repo.ready();
   if (!initResult.success) {
     return err(
       HaiReachError.SEND_FAILED,
@@ -1711,6 +1594,17 @@ async function createSendLogRepository(db) {
   return ok(repo);
 }
 var DbSendLogRepository = class extends BaseReldbCrudRepository {
+  /** 唯一回执约束保证多个节点不能为同一操作排入不同的发送记录。 */
+  async ready() {
+    const schema = await this.ensureSchema();
+    if (!schema.success)
+      return schema;
+    const type = this.db.config?.type;
+    const index = type === "sqlite" ? await this.db.sql.get('SELECT i.name FROM pragma_index_list(?) i JOIN pragma_index_info(i.name) f WHERE i."unique"=1 AND i.partial=0 GROUP BY i.name HAVING COUNT(*)=1 AND MAX(f.name)=?', [TABLE_NAME, "queue_id"]) : type === "mysql" ? await this.db.sql.get("SELECT index_name FROM information_schema.statistics WHERE table_schema=DATABASE() AND table_name=? AND non_unique=0 GROUP BY index_name HAVING COUNT(*)=1 AND MAX(column_name)=?", [TABLE_NAME, "queue_id"]) : await this.db.sql.get("SELECT i.indexrelid FROM pg_index i JOIN pg_class t ON t.oid=i.indrelid JOIN pg_namespace n ON n.oid=t.relnamespace JOIN pg_attribute a ON a.attrelid=t.oid AND a.attnum=i.indkey[0] WHERE t.relname=? AND n.nspname=current_schema() AND i.indisunique AND i.indisvalid AND i.indpred IS NULL AND i.indnkeyatts=1 AND a.attname=?", [TABLE_NAME, "queue_id"]);
+    if (!index.success)
+      return index;
+    return index.data ? ok(void 0) : err(HaiReachError.SEND_FAILED, reachM("reach_sendLogIndexRequired"));
+  }
   /** 共享后端取真正执行时钟；本地 SQLite 保留可控的单进程测试时钟。 */
   clockSql(localNow) {
     if (this.db.config?.type === "postgresql")
@@ -2587,6 +2481,6 @@ var reach = {
   }
 };
 
-export { AliyunSmsProviderConfigSchema, ApiProviderConfigSchema, ConsoleProviderConfigSchema, DndConfigSchema, HaiReachError, ProviderConfigSchema, ReachConfigSchema, ReachDeadRequeueSchema, ReachQueueConfigSchema, ReachQueueIdSchema, ReachQueueListSchema, ReachUnknownResolutionSchema, SmtpProviderConfigSchema, TemplateConfigSchema, migrateReach, reach };
+export { AliyunSmsProviderConfigSchema, ApiProviderConfigSchema, ConsoleProviderConfigSchema, DndConfigSchema, HaiReachError, ProviderConfigSchema, ReachConfigSchema, ReachDeadRequeueSchema, ReachQueueConfigSchema, ReachQueueIdSchema, ReachQueueListSchema, ReachUnknownResolutionSchema, SmtpProviderConfigSchema, TemplateConfigSchema, reach };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map