@rei-standard/amsg-server 2.6.0-next.13 → 2.6.0-next.15

package/dist/lib/client-state-store.d.ts

@@ -12,6 +12,13 @@ export function stateValueBytes(value: any): number;
  * 两者都受同一套 last-write-wins 约束：`updatedAt` 比库里已有值旧的写入
  * （或删除）不生效，陈旧批次盖不掉新数据。
  *
+ * 条件写护栏：条目可带可选的 `version`（毫秒时间戳或单调递增整数）。带了它，
+ * 比较用的就是这个值而不是 `updatedAt`——同一个 key 有多个写入方时（例如
+ * fire_pack 由常规 flush 和 instant-chat 两条路径写），谁的**内容**新谁赢，
+ * 而不是谁的请求后到谁赢：慢网下晚到的旧包带着旧 `version`，盖不掉先到的新
+ * 包。护栏值落在行的 updated_at 列上（client_state 的比较列本来就是它），
+ * 没带 `version` 的写入照旧按 `updatedAt` 比。
+ *
  * 条目本身的合法性（namespace / key 字符、value 大小）由调用方先校验好：
  * HTTP handler 逐条拒绝并把原因回给客户端，`writeState()` 直接抛错给 hook。
  *
@@ -19,10 +26,13 @@ export function stateValueBytes(value: any): number;
  * @param {{ upsertClientState: Function }} args.db
  * @param {string} args.userId
  * @param {CryptoKey|string} args.userKey - 该用户的存储密钥（value 用它加密）
- * @param {Array<{ namespace: string, key: string, value: string|null, updatedAt: number }>} args.entries
- * @returns {Promise<{ upserted: number, skipped: number, deleted: number }>}
+ * @param {Array<{ namespace: string, key: string, value: string|null, updatedAt: number, version?: number }>} args.entries
+ *   `version`（可选）：条件写护栏值，见文件头。带了它，这条的 last-write-wins
+ *   比较用它（写进行的 updated_at 列）；没带照旧用 `updatedAt`。
+ * @returns {Promise<{ upserted: number, skipped: number, deleted: number, skippedEntries: Array<{ namespace: string, key: string }> }>}
  *   `upserted` / `skipped` 按逻辑条目计（切片行不计）；`deleted` 是请求删除的
- *   key 数，不代表这些 key 原本一定存在。
+ *   key 数，不代表这些 key 原本一定存在。`skippedEntries` 逐条列出被
+ *   last-write-wins 拦下的 key（适配器不回 outcomes 时为空数组——分不清是哪条）。
  */
 export function writeClientStateEntries({ db, userId, userKey, entries }: {
     db: {
@@ -35,11 +45,16 @@ export function writeClientStateEntries({ db, userId, userKey, entries }: {
         key: string;
         value: string | null;
         updatedAt: number;
+        version?: number;
     }>;
 }): Promise<{
     upserted: number;
     skipped: number;
     deleted: number;
+    skippedEntries: Array<{
+        namespace: string;
+        key: string;
+    }>;
 }>;
 export const MAX_STATE_ENTRIES_PER_BATCH: 200;
 export const MAX_NAMESPACE_CHARS: 128;

package/dist/lib/errors.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 这个错误是不是「重试也好不了」。认 NonRetryableError，也认任何自带
+ * `permanent: true` 的错误对象（跨包/跨版本安全）。
+ *
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+export function isNonRetryableError(error: unknown): boolean;
+/**
+ * 把错误原因脱敏成能明文落库（任务行 last_error 列）的摘要。
+ *
+ * 任务内容一律密文落库，last_error 是唯一一列明文的「为什么没发出去」——
+ * 错误消息偶尔会回显请求细节（上游 API 的报错带 URL、header 片段），所以
+ * 长得像凭据的 token 一律遮掉，再截断到 500 字符。
+ *
+ * @param {unknown} reason
+ * @returns {string}
+ */
+export function sanitizeErrorSummary(reason: unknown): string;
+/**
+ * 错误类型：宿主 hook 与库内部共用的失败语义标注。
+ */
+/**
+ * 确定性失败——重试必然同败，别再排退避阶梯。
+ *
+ * 典型场景全在 fire-time hook 里：onBeforeFire 发现 fire_pack 缺失、解析失
+ * 败、缺必要的段……这类错误不会因为过两分钟再跑一次就好，按普通投递失败重
+ * 试三轮只是让用户多白等十几分钟，还把 hook 里的计费调用（情绪评估之类）
+ * 重复烧三遍。hook 抛这个类（或任何带 `permanent: true` 的错误），run-tick
+ * 收到后跳过退避：一次性任务直接标 failed（原因进 last_error / payload 的
+ * lastError），循环任务直接作废本次 occurrence。
+ *
+ * `code`（可选）会透传到 processSingleMessage 的 errorCode，宿主想按错误类
+ * 别分流时用它。
+ *
+ * 用 `permanent` 属性而不是 instanceof 做判定：宿主的 worker 里可能打包了另
+ * 一份本库（版本错开、bundler 双实例），跨 realm 的 instanceof 靠不住。
+ */
+export class NonRetryableError extends Error {
+    /**
+     * @param {string} message
+     * @param {{ code?: string, cause?: unknown }} [options]
+     */
+    constructor(message: string, options?: {
+        code?: string;
+        cause?: unknown;
+    });
+    permanent: boolean;
+    code: string;
+}

package/dist/lib/message-processor.d.ts

@@ -10,12 +10,18 @@
  * @param {import('../adapters/interface.js').TaskRow} task
  * @param {ProcessorContext} ctx
  * @param {string} [providedMasterKey]
- * @returns {Promise<{ success: boolean, messagesSent: number, error?: string }>}
+ * @param {{ userKey: string, payload: Object } | null} [predecrypted] - 调用方
+ *   （run-tick 的预扫描）已经解好的 payload；传了就不再解第二遍。
+ * @returns {Promise<{ success: boolean, messagesSent: number, error?: string, errorCode?: string|null }>}
  */
-export function processSingleMessage(task: import("../adapters/interface.js").TaskRow, ctx: ProcessorContext, providedMasterKey?: string): Promise<{
+export function processSingleMessage(task: import("../adapters/interface.js").TaskRow, ctx: ProcessorContext, providedMasterKey?: string, predecrypted?: {
+    userKey: string;
+    payload: any;
+} | null): Promise<{
     success: boolean;
     messagesSent: number;
     error?: string;
+    errorCode?: string | null;
 }>;
 /**
  * Process a single message identified by UUID (used for instant type).

package/dist/lib/outbox-store.d.ts

@@ -0,0 +1,33 @@
+/** 适配器支持 outbox 吗（写入侧要用的两个方法都在才算）。 */
+export function supportsOutbox(db: any): boolean;
+/**
+ * 发送前把这一批 push 落进 outbox。push 对象须已定稿（messageId / sessionId /
+ * messageIndex / totalMessages / 任务身份都已补齐）——落进去的密文就是客户端
+ * 补收时拿到的那一份。
+ *
+ * @param {Object} args
+ * @param {Object} args.db
+ * @param {string} args.userId
+ * @param {CryptoKey|string} args.userKey - per-user 存储密钥
+ * @param {Object[]} args.pushes - 定稿后的 push 对象
+ * @returns {Promise<boolean>} 是否真的落了行（适配器不支持 / 落行失败 → false）
+ */
+export function appendPushesToOutbox({ db, userId, userKey, pushes }: {
+    db: any;
+    userId: string;
+    userKey: CryptoKey | string;
+    pushes: any[];
+}): Promise<boolean>;
+/**
+ * 把发出去的那部分标成 delivered（发送半途失败时只标已发出的段）。
+ *
+ * @param {Object} args
+ * @param {Object} args.db
+ * @param {string} args.userId
+ * @param {string[]} args.messageIds
+ */
+export function markPushesDelivered({ db, userId, messageIds }: {
+    db: any;
+    userId: string;
+    messageIds: string[];
+}): Promise<void>;

package/dist/lib/push-subscription-store.d.ts

@@ -48,16 +48,24 @@ export function loadPushSubscription({ db, userId, userKey }: {
 /**
  * 投递前取订阅。取不到就抛——静默不发会让任务「成功」地什么都没做，用户
  * 只看到消息凭空消失。抛出去走既有的重试 / 标记逻辑，原因也会记进 payload
- * 的 lastError，`GET /messages` 上看得见。
+ * 的 lastError，`GET /messages` 上看得见。抛出的错误带稳定的 `code` 属性
+ * （'PUSH_SUBSCRIPTION_MISSING' / 'PUSH_SUBSCRIPTION_STORE_UNSUPPORTED'），
+ * 按类别分支请用它，别匹配 message 文案。
+ *
+ * `legacyFallback`：用户级存储里没有订阅时的兜底（升级前创建的任务把订阅
+ * 冻结在自己的 payload 里，这份订阅仍然有效）。存储里有订阅时永远用存储的
+ * 那份——它是用户最近一次登记的。
  *
  * @param {Object} args
  * @param {import('../adapters/interface.js').DbAdapter} args.db
  * @param {string} args.userId
  * @param {string} args.userKey
+ * @param {unknown} [args.legacyFallback] - 旧任务 payload 里内嵌的订阅（可选）
  * @returns {Promise<Object>} 明文订阅对象
  */
-export function resolvePushSubscription({ db, userId, userKey }: {
+export function resolvePushSubscription({ db, userId, userKey, legacyFallback }: {
     db: import("../adapters/interface.js").DbAdapter;
     userId: string;
     userKey: string;
+    legacyFallback?: unknown;
 }): Promise<any>;

package/dist/lib/request.d.ts

@@ -56,6 +56,42 @@ export function isEncryptedEnvelope(payload: unknown): payload is {
  * @returns {ParseBodyResult}
  */
 export function parseEncryptedBody(body: unknown): ParseBodyResult;
+/**
+ * 标准错误信封：{ status, body: { success: false, error: { code, message, details? } } }。
+ *
+ * @param {number} status
+ * @param {string} code
+ * @param {string} message
+ * @param {Object} [details]
+ */
+export function errorResponse(status: number, code: string, message: string, details?: any): {
+    status: number;
+    body: {
+        success: boolean;
+        error: {
+            code: string;
+            message: string;
+            details?: undefined;
+        } | {
+            code: string;
+            message: string;
+            details: any;
+        };
+    };
+};
+/**
+ * X-User-Id 门禁。所有按用户读写的端点共用这一份：规则（必填 + UUID v4）和
+ * 文案只此一处，改口径不用挨个 handler 找复制粘贴的副本。
+ *
+ * @param {Record<string, any>} headers
+ * @returns {{ userId: string, error?: undefined } | { error: ReturnType<typeof errorResponse> }}
+ */
+export function requireUserId(headers: Record<string, any>): {
+    userId: string;
+    error?: undefined;
+} | {
+    error: ReturnType<typeof errorResponse>;
+};
 /**
  * Read a header value case-insensitively.
  *

package/dist/lib/run-tick.d.ts

@@ -27,8 +27,35 @@ export function runScheduledTick(ctx: any): Promise<{
         failedTasks: any[];
     };
 }>;
+/**
+ * 只跑一条任务的官方入口，给「fetch 里只来得及 enqueue、真正的 fire 交给
+ * CF Queue 消费者（15 分钟预算）跑」这类宿主用——不用再依赖 cron 恰好捞到。
+ *
+ * 与 cron tick 走完全同一条投递链：占位（含心跳续租）、过期守卫、分组串行
+ * （单任务场景下退化为占位时的跨 tick 分组门）、失败重试/终态、hook 全套。
+ * 行没到点（next_send_at 在未来）或正处在退避窗口（retry_after 未到点）时不
+ * 跑——这个入口只是换了个触发器，不是绕过排期的后门。
+ *
+ * @param {Object} ctx - 与 runScheduledTick 同一份 ctx
+ * @param {string} uuid - 任务 uuid（pending 行）
+ * @returns {Promise<{ ran: false, reason: 'not_found'|'not_due'|'retry_pending', nextSendAt?: string, retryAfter?: string }
+ *   | { ran: true, summary: Object }>} summary 与 runScheduledTick 的返回同构
+ *   （totalTasks 恒为 1）；任务被别的执行者占着时体现在 summary.details.claimSkippedTasks。
+ */
+export function runTask(ctx: any, uuid: string): Promise<{
+    ran: false;
+    reason: "not_found" | "not_due" | "retry_pending";
+    nextSendAt?: string;
+    retryAfter?: string;
+} | {
+    ran: true;
+    summary: any;
+}>;
 export const DEFAULT_CLAIM_LEASE_MS: number;
+export const DEFAULT_LEASE_HEARTBEAT_MS: number;
+export const DEFAULT_HEARTBEAT_LEASE_TTL_MS: number;
 export const STALE_AFTER_MS: number;
+export { sanitizeErrorSummary };
 export type StaleSkipInfo = {
     reason: "stale";
     /**
@@ -66,3 +93,4 @@ export type StaleSkipInfo = {
     readState: (namespace: string) => Promise<any[]>;
     writeState: (namespace: string, entries: any[]) => Promise<any>;
 };
+import { sanitizeErrorSummary } from './errors.js';

package/dist/lib/validation.d.ts

@@ -4,12 +4,6 @@
  * @returns {boolean}
  */
 export function isValidISO8601(dateString: string): boolean;
-/**
- * Validate URL format.
- * @param {string} urlString
- * @returns {boolean}
- */
-export function isValidUrl(urlString: string): boolean;
 /**
  * Validate UUID format.
  * @param {string} uuid
@@ -65,4 +59,4 @@ export function validateScheduleMessagePayload(payload: any): {
     details?: any;
 };
 import { isValidTimeZoneId } from './recurrence.js';
-export { isValidTimeZoneId, validateAvatarUrl };
+export { isValidTimeZoneId, isValidUrl, validateAvatarUrl };

package/dist/{neon-CUIGAB2T.mjs → neon-XLWK27RL.mjs}

@@ -1,3 +1,11 @@
+import {
+  claimTask,
+  deletePushSubscription,
+  getPushSubscription,
+  getTaskStatusInfo,
+  renewTaskLease,
+  upsertPushSubscription
+} from "./chunk-UYROU4L3.mjs";
 import {
   COLUMNS_SQL,
   INDEXES,
@@ -6,7 +14,7 @@ import {
   TABLE_SQL,
   UPDATABLE_COLUMNS,
   VERIFY_TABLE_SQL
-} from "./chunk-B2FDV7YK.mjs";
+} from "./chunk-34I2YSWE.mjs";
 
 // src/server/adapters/neon.js
 import { neon } from "@neondatabase/serverless";
@@ -91,7 +99,7 @@ var NeonAdapter = class {
   async getTaskByUuid(uuid, userId) {
     const sql = this._getSql();
     const rows = await sql.query(
-      `SELECT id, user_id, uuid, encrypted_payload, message_type, next_send_at, status, retry_count, created_at, updated_at
+      `SELECT id, user_id, uuid, encrypted_payload, message_type, next_send_at, status, retry_count, last_error, created_at, updated_at
        FROM scheduled_messages
        WHERE uuid = $1 AND user_id = $2 AND status = 'pending'
        LIMIT 1`,
@@ -171,7 +179,7 @@ var NeonAdapter = class {
   async getPendingTasks(limit = 50) {
     const sql = this._getSql();
     return sql.query(
-      `SELECT id, user_id, uuid, encrypted_payload, message_type, next_send_at, status, retry_count
+      `SELECT id, user_id, uuid, encrypted_payload, message_type, next_send_at, retry_after, status, retry_count
        FROM scheduled_messages
        WHERE status = 'pending' AND next_send_at <= NOW()
          AND (lease_until IS NULL OR lease_until <= NOW())
@@ -181,65 +189,16 @@ var NeonAdapter = class {
       [limit]
     );
   }
-  /**
-   * 领取一条到点的任务：在 lease_until 上写下「这条归我管到什么时候」，
-   * 本次投递期间别的 tick 领不走它。
-   *
-   * 租约写在自己的列上，next_send_at 全程不动——那一列是用户设的触发时刻，
-   * 任务列表要读它、循环任务推进下一次也要拿它当基准。
-   *
-   * 两个 tick 抢同一行时只有一个改得动，另一个拿不到 RETURNING 行，据此跳
-   * 过。WHERE 里的两个条件各管一件事：
-   *   - lease_until 为空或已过期：没人正在跑这条。领了任务的 tick 中途没了
-   *     也不会把行焊死，租约到期后自然可以被接手。
-   *   - next_send_at 等于读这行时看到的值：读出来之后用户又改了排期的话，
-   *     这一跳就不该再按旧时刻发。
-   *
-   * 不加一个 'sending' 状态来表达「正在跑」：status 上有 CHECK 约束，加值
-   * 要改表。
-   *
-   * 比 next_send_at 时两边都截到毫秒：列是 timestamptz（微秒精度），驱动读
-   * 出来是 JS Date（毫秒精度），原值送回去可能因为亚毫秒差对不上。
-   *
-   * 带 serializeGroup 时多一道分组门：同一分组里已经有别的行拿着未到期的租
-   * 约，这条就领不走（同一分组同时只跑一条）。判定和写租约在同一条 UPDATE
-   * 里完成，「先查再占」的空档天然不存在。分组门只看租约，不看
-   * `retry_after`：等着重试的任务其实闲着，不该把同分组的其他任务一起堵住。
-   *
-   * @param {number} taskId
-   * @param {string|Date} expectedNextSendAt - 读这行时拿到的 next_send_at 原值
-   * @param {string|Date} leaseUntil - 租期末尾
-   * @param {string|null} [serializeGroup] - 串行分组标识；空表示不参与分组串行
-   * @returns {Promise<boolean>} true = 领到了；false = 别人正拿着租约、同分组
-   *   有任务正在跑、排期被改过、或行已不是 pending
-   */
+  // 领取一条到点的任务。SQL 与并发语义在 pg-shared.js（pg / neon 共用一份，
+  // 语义说明也在那里）。
   async claimTask(taskId, expectedNextSendAt, leaseUntil, serializeGroup = null) {
     const sql = this._getSql();
-    const grouped = typeof serializeGroup === "string" && serializeGroup.length > 0;
-    const params = [leaseUntil, taskId, expectedNextSendAt];
-    let setClause = "lease_until = $1, updated_at = NOW()";
-    let groupGuard = "";
-    if (grouped) {
-      params.push(serializeGroup);
-      setClause = "lease_until = $1, serialize_group = $4, updated_at = NOW()";
-      groupGuard = `
-          AND NOT EXISTS (
-            SELECT 1 FROM scheduled_messages busy
-             WHERE busy.serialize_group = $4 AND busy.id <> $2
-               AND busy.status = 'pending' AND busy.lease_until > NOW()
-          )`;
-    }
-    const rows = await sql.query(
-      `UPDATE scheduled_messages
-          SET ${setClause}
-        WHERE id = $2 AND status = 'pending'
-          AND date_trunc('milliseconds', next_send_at)
-            = date_trunc('milliseconds', $3::timestamptz)
-          AND (lease_until IS NULL OR lease_until <= NOW())${groupGuard}
-       RETURNING id`,
-      params
-    );
-    return rows.length > 0;
+    return claimTask((text, params) => sql.query(text, params), taskId, expectedNextSendAt, leaseUntil, serializeGroup);
+  }
+  // 投递期间的租约续期（run-tick 心跳；语义见 pg-shared.js）。
+  async renewTaskLease(taskId, leaseUntil) {
+    const sql = this._getSql();
+    return renewTaskLease((text, params) => sql.query(text, params), taskId, leaseUntil);
   }
   async listTasks(userId, opts = {}) {
     const sql = this._getSql();
@@ -260,7 +219,7 @@ var NeonAdapter = class {
     const total = parseInt(countRows[0].count, 10);
     const taskParams = [...params, limit, offset];
     const tasks = await sql.query(
-      `SELECT id, user_id, uuid, encrypted_payload, message_type, next_send_at, status, retry_count, created_at, updated_at
+      `SELECT id, user_id, uuid, encrypted_payload, message_type, next_send_at, status, retry_count, last_error, created_at, updated_at
        FROM scheduled_messages
        WHERE ${where}
        ORDER BY next_send_at ASC
@@ -289,57 +248,23 @@ var NeonAdapter = class {
     );
     return rows.length > 0 ? rows[0].status : null;
   }
-  // ── push_subscriptions (user-level Web Push subscription) ──────────────
-  /**
-   * 这个用户当前登记的推送订阅（密文原样返回，解密在上层）。
-   *
-   * @param {string} userId
-   * @returns {Promise<{ subscription: string, updated_at: number }|null>}
-   */
+  // 状态 + 失败摘要（GET /message 对已失败的行透出原因；语义见 pg-shared.js）。
+  async getTaskStatusInfo(uuid, userId) {
+    const sql = this._getSql();
+    return getTaskStatusInfo((text, params) => sql.query(text, params), uuid, userId);
+  }
+  // ── push_subscriptions（实现见 pg-shared.js，pg / neon 共用一份）─────────
   async getPushSubscription(userId) {
     const sql = this._getSql();
-    const rows = await sql.query(
-      "SELECT subscription, updated_at FROM push_subscriptions WHERE user_id = $1 LIMIT 1",
-      [userId]
-    );
-    if (rows.length === 0) return null;
-    return { subscription: rows[0].subscription, updated_at: Number(rows[0].updated_at) };
+    return getPushSubscription((text, params) => sql.query(text, params), userId);
   }
-  /**
-   * 覆盖写这个用户的订阅。一个用户一行，没有 last-write-wins 之类的比较——
-   * 客户端拿到的新订阅永远比旧的有效，旧的那份只会 410。
-   *
-   * @param {string} userId
-   * @param {string} encryptedSubscription
-   * @param {number} updatedAt - epoch 毫秒
-   * @returns {Promise<boolean>}
-   */
   async upsertPushSubscription(userId, encryptedSubscription, updatedAt) {
     const sql = this._getSql();
-    const rows = await sql.query(
-      `INSERT INTO push_subscriptions (user_id, subscription, updated_at)
-       VALUES ($1, $2, $3)
-       ON CONFLICT (user_id) DO UPDATE SET
-         subscription = EXCLUDED.subscription,
-         updated_at = EXCLUDED.updated_at
-       RETURNING user_id`,
-      [userId, encryptedSubscription, updatedAt]
-    );
-    return rows.length > 0;
+    return upsertPushSubscription((text, params) => sql.query(text, params), userId, encryptedSubscription, updatedAt);
   }
-  /**
-   * 删掉这个用户的订阅（设置页「停止接收推送」）。
-   *
-   * @param {string} userId
-   * @returns {Promise<boolean>} true = 确实删掉了一行
-   */
   async deletePushSubscription(userId) {
     const sql = this._getSql();
-    const rows = await sql.query(
-      "DELETE FROM push_subscriptions WHERE user_id = $1 RETURNING user_id",
-      [userId]
-    );
-    return rows.length > 0;
+    return deletePushSubscription((text, params) => sql.query(text, params), userId);
   }
 };
 export {