@rei-standard/amsg-server 2.6.0-next.2 → 2.6.0-next.21

package/dist/lib/request.d.ts

@@ -0,0 +1,182 @@
+/**
+ * 把请求正文读成字符串，`Content-Encoding: gzip` 的在这一步还原。
+ *
+ * 客户端把大 body（一次 fire_pack、一整批 client_state）压了再传能省下几倍
+ * 传输量，代价只有服务端这一次解压。所有带 body 的端点走同一个入口，谁都不用
+ * 各自判一遍这个头。
+ *
+ * 说是 gzip、字节却不是 gzip 开头时按明文处理：有些边缘网关会替你把请求体解
+ * 开却留着原来的 `Content-Encoding` 头，再解一次只会解出乱码。魔数判断两种情
+ * 况都接得住。
+ *
+ * 只认 gzip。deflate / br 回 415 而不是猜着解——猜错解出来的是一段乱码，会变
+ * 成一句让人找不着北的「请求体不是有效的 JSON」。
+ *
+ * @param {{ headers?: { get?: (name: string) => string|null }, text: () => Promise<string>, arrayBuffer: () => Promise<ArrayBuffer> }} request
+ *   Fetch API 的 Request（或形状相同的对象）。
+ * @param {{ maxBytes?: number }} [options] - `maxBytes`：解压后的字节上限，
+ *   默认 {@link DEFAULT_MAX_REQUEST_BODY_BYTES}。
+ * @returns {Promise<{ ok: true, body: string } | { ok: false, error: { status: number, body: Object } }>}
+ *   `error` 就是可以直接回给调用方的那个信封（与 handler 的返回同构）。
+ */
+export function readRequestBody(request: {
+    headers?: {
+        get?: (name: string) => string | null;
+    };
+    text: () => Promise<string>;
+    arrayBuffer: () => Promise<ArrayBuffer>;
+}, options?: {
+    maxBytes?: number;
+}): Promise<{
+    ok: true;
+    body: string;
+} | {
+    ok: false;
+    error: {
+        status: number;
+        body: any;
+    };
+}>;
+/**
+ * @typedef {{ code: string, message: string }} ValidationError
+ */
+/**
+ * @typedef {{
+ *   invalidJson?: ValidationError,
+ *   invalidType?: ValidationError
+ * }} ParseBodyOptions
+ */
+/**
+ * @typedef {{
+ *   ok: true,
+ *   data: Record<string, any>
+ * } | {
+ *   ok: false,
+ *   error: ValidationError
+ * }} ParseBodyResult
+ */
+/**
+ * Parse body into a JSON object.
+ *
+ * @param {unknown} body
+ * @param {ParseBodyOptions} [options]
+ * @returns {ParseBodyResult}
+ */
+export function parseBodyAsObject(body: unknown, options?: ParseBodyOptions): ParseBodyResult;
+/**
+ * Parse a standard JSON object body.
+ *
+ * @param {unknown} body
+ * @returns {ParseBodyResult}
+ */
+export function parseJsonBody(body: unknown): ParseBodyResult;
+/**
+ * Check if a value is a plain object (and not null/array).
+ *
+ * @param {unknown} value
+ * @returns {value is Record<string, any>}
+ */
+export function isPlainObject(value: unknown): value is Record<string, any>;
+/**
+ * Check if an object follows the encrypted payload envelope shape.
+ *
+ * @param {unknown} payload
+ * @returns {payload is { iv: string, authTag: string, encryptedData: string }}
+ */
+export function isEncryptedEnvelope(payload: unknown): payload is {
+    iv: string;
+    authTag: string;
+    encryptedData: string;
+};
+/**
+ * Parse and validate an encrypted payload envelope.
+ *
+ * @param {unknown} body
+ * @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.
+ *
+ * @param {Record<string, any>} headers
+ * @param {string} name
+ * @returns {string}
+ */
+export function getHeader(headers: Record<string, any>, name: string): string;
+export namespace REQUEST_ERRORS {
+    namespace INVALID_JSON {
+        let code: string;
+        let message: string;
+    }
+    namespace INVALID_REQUEST_BODY {
+        let code_1: string;
+        export { code_1 as code };
+        let message_1: string;
+        export { message_1 as message };
+    }
+    namespace INVALID_ENCRYPTED_PAYLOAD {
+        let code_2: string;
+        export { code_2 as code };
+        let message_2: string;
+        export { message_2 as message };
+    }
+}
+/**
+ * 解压后请求体的字节上限（默认 32MB）。
+ *
+ * 只管 gzip 那条路：压缩数据能用很小的体积展开成极大的正文（几百 KB 换几个
+ * GB），不设上限等于把内存交给调用方决定。不压缩的请求体不受这个数约束，行为
+ * 与以前一致——那条路的体积本来就摆在传输量上，平台自己的请求大小限制盖得住。
+ */
+export const DEFAULT_MAX_REQUEST_BODY_BYTES: number;
+export type ValidationError = {
+    code: string;
+    message: string;
+};
+export type ParseBodyOptions = {
+    invalidJson?: ValidationError;
+    invalidType?: ValidationError;
+};
+export type ParseBodyResult = {
+    ok: true;
+    data: Record<string, any>;
+} | {
+    ok: false;
+    error: ValidationError;
+};

package/dist/lib/result-emitter.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @typedef {Object} ResultEmitter
+ * @property {(payload: Object) => Promise<{ messageId: string, pushed: boolean }>} emitResult
+ *   把一条结果落进收件箱并推送出去。`payload` 是宿主自己的形状，只有两个约束：
+ *   必须是普通对象，且带一个非空的 `resultKind`（这类结果的名字，客户端按它
+ *   分流）。返回 `messageId`（补收和去重的键）与 `pushed`（这次推送有没有真
+ *   的发出去；`false` 只表示没能当场送达，行还在收件箱里等补收）。
+ */
+/**
+ * 造一份作用于某条任务的结果出口。
+ *
+ * 身份字段（`taskId` / `taskUuid` / `recurrenceType` / `occurrenceMs` /
+ * `messageKind`）由库覆盖写：它们描述的是这条任务行的事实，不是内容。
+ * `messageId` / `sessionId` / `timestamp` 宿主没给才补——`messageId` 的缺省
+ * 值掺了任务 id 与本次名义触发时刻，同一次触发重试时组出同一个 id，收件箱靠
+ * `(user_id, message_id)` 唯一约束天然去重，不会补出第二条。
+ *
+ * @param {Object} args
+ * @param {import('../adapters/interface.js').DbAdapter} args.db
+ * @param {Object} args.task - 数据库任务行
+ * @param {string} args.userKey - per-user 存储密钥
+ * @param {Object} args.decryptedPayload - 解密后的任务 payload（取 messageType / recurrenceType / 老任务里的订阅）
+ * @param {string} args.messageIdBase - messageId 的前缀（与推送链路同一份）
+ * @param {string} args.sessionId
+ * @param {number|null} args.occurrenceMs
+ * @param {{ sendNotification: Function }|null} args.webpush
+ * @param {() => number} [args.now] - 取当前时刻（测试可注入假时钟）
+ * @returns {ResultEmitter}
+ */
+export function createResultEmitter({ db, task, userKey, decryptedPayload, messageIdBase, sessionId, occurrenceMs, webpush, now, }: {
+    db: import("../adapters/interface.js").DbAdapter;
+    task: any;
+    userKey: string;
+    decryptedPayload: any;
+    messageIdBase: string;
+    sessionId: string;
+    occurrenceMs: number | null;
+    webpush: {
+        sendNotification: Function;
+    } | null;
+    now?: () => number;
+}): ResultEmitter;
+export type ResultEmitter = {
+    /**
+     *   把一条结果落进收件箱并推送出去。`payload` 是宿主自己的形状，只有两个约束：
+     *   必须是普通对象，且带一个非空的 `resultKind`（这类结果的名字，客户端按它
+     *   分流）。返回 `messageId`（补收和去重的键）与 `pushed`（这次推送有没有真
+     *   的发出去；`false` 只表示没能当场送达，行还在收件箱里等补收）。
+     */
+    emitResult: (payload: any) => Promise<{
+        messageId: string;
+        pushed: boolean;
+    }>;
+};

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

@@ -0,0 +1,115 @@
+/**
+ * 把宿主给的分组 key 变成落库用的分组标识。
+ *
+ * 不直接存 key 本身：它多半是角色 id / 联系人名这类宿主数据，而任务内容一律
+ * 加密落库，多开一列明文出口不合适。这里用该用户的存储密钥做 HMAC——同一个
+ * 用户的同一个 key 每次都得到同一个值（分组判定要的就是相等性），换个用户
+ * 得到的值必然不同（分组天然按用户隔开，SQL 那边不用再比 user_id），拿到数
+ * 据库也反推不回原 key。
+ *
+ * @param {string} userKey - 该用户的存储密钥（deriveUserEncryptionKey 的结果）
+ * @param {string} rawKey - serializeBy 返回的分组 key
+ * @returns {Promise<string>} 43 字符的 base64url 串（列宽 64 够放）
+ */
+export function deriveSerializeGroup(userKey: string, rawKey: string): Promise<string>;
+export function runScheduledTick(ctx: any): Promise<{
+    totalTasks: any;
+    successCount: number;
+    failedCount: number;
+    processedAt: string;
+    executionTime: number;
+    details: {
+        claimSkippedTasks: number;
+        serializeSkippedTasks: number;
+        deletedOnceOffTasks: number;
+        updatedRecurringTasks: number;
+        staleTasks: any[];
+        cancelledTasks: any[];
+        reasoningSkippedTasks: any[];
+        failedTasks: any[];
+    };
+}>;
+/**
+ * 只跑一条任务的官方入口，给「fetch 里只来得及 enqueue、真正的 fire 交给
+ * CF Queue 消费者（15 分钟预算）跑」这类宿主用——不用再依赖 cron 恰好捞到。
+ *
+ * 与 cron tick 走完全同一条投递链：占位（含心跳续租）、过期守卫、分组串行
+ * （单任务场景下退化为占位时的跨 tick 分组门）、失败重试/终态、hook 全套。
+ * 行没到点（next_send_at 在未来）或正处在退避窗口（retry_after 未到点）时不
+ * 跑——这个入口只是换了个触发器，不是绕过排期的后门。
+ *
+ * 四种不跑的情形分开回报，调用方不用猜：
+ *   - `not_found`：没有这条 uuid。一次性任务发完即删，所以「发完了」的那条也
+ *     落在这里；行还在但已经是终态的走下面那条。
+ *   - `already_settled`：行还在，但已经是 sent / failed（`status` 带上是哪
+ *     个）。适配器没实现 `getTaskStatusByUuidOnly` 时这种情况并进 `not_found`。
+ *   - `not_due`：还没到 `next_send_at`（`nextSendAt` 带上是什么时候）。
+ *   - `retry_pending`：上次投递失败，还在退避窗口里（`retryAfter` 带上什么时
+ *     候到点）。
+ *
+ * @param {Object} ctx - 与 runScheduledTick 同一份 ctx
+ * @param {string} uuid - 任务 uuid（pending 行）
+ * @returns {Promise<{ ran: false, reason: 'not_found'|'already_settled'|'not_due'|'retry_pending', status?: string, 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" | "already_settled" | "not_due" | "retry_pending";
+    status?: string;
+    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";
+    /**
+     *   `expired` = 一次性任务，这一次永远不会补发了，行已标 failed；
+     *   `fast_forwarded` = 循环任务，攒下的这几次都跳过，排期已快进到未来第一个
+     *   名义时刻，行仍是 pending，下一次照常触发。
+     */
+    action: "expired" | "fast_forwarded";
+    /**
+     * - 解密 payload 里的 metadata 子字段
+     */
+    metadata: any | null;
+    /**
+     * - 'none' / 'daily' / 'weekly'
+     */
+    recurrenceType: string;
+    /**
+     * - 被跳过的第一个名义时刻（epoch 毫秒）
+     */
+    occurrenceMs: number | null;
+    /**
+     * - 一共跳过几次（一次性任务恒为 1）
+     */
+    skippedCount: number;
+    /**
+     * - 被跳过的名义时刻列表（epoch 毫秒）；
+     * 超过 32 次时只给首末两个，并把 skippedTruncated 置 true
+     */
+    skippedOccurrences: number[];
+    skippedTruncated: boolean;
+    /**
+     * - 循环任务快进到的下一次触发时刻；一次性任务为 null
+     */
+    nextSendAt: string | null;
+    readState: (namespace: string) => Promise<any[]>;
+    writeState: (namespace: string, entries: any[]) => Promise<any>;
+    /**
+     *   往客户端补一条自定义结果（落收件箱 + 推送，见 lib/result-emitter.js）。
+     */
+    emitResult: (payload: any) => Promise<{
+        messageId: string;
+        pushed: boolean;
+    }>;
+};
+import { sanitizeErrorSummary } from './errors.js';

package/dist/lib/schema-version.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 活库的表结构够不够这一版代码用。只读，不改任何东西。
+ *
+ * @param {import('../adapters/interface.js').DbAdapter} db - 数据库适配器
+ *   （要实现 `describeSchema()`；内置的 D1 适配器实现了）
+ * @returns {Promise<SchemaVersionResult>}
+ */
+export function getSchemaVersion(db: import("../adapters/interface.js").DbAdapter): Promise<SchemaVersionResult>;
+/**
+ * 缺什么补什么：自查一遍，不够用就跑一次 `initSchema()`（建表 + 补列 + 建索
+ * 引，重复跑没事），再自查一遍把结果回报出去。
+ *
+ * 本来就够用时不跑——`initSchema()` 是好几个来回，能省则省。
+ *
+ * @param {import('../adapters/interface.js').DbAdapter} db - 数据库适配器
+ * @returns {Promise<EnsureSchemaResult>} 补齐之后的自查结果；`migrated` 说明这
+ *   次有没有真的动手。补完仍然 `ok: false`（例如 ALTER 被库拒了）时 `missing`
+ *   里还留着没补上的那几项
+ */
+export function ensureSchema(db: import("../adapters/interface.js").DbAdapter): Promise<EnsureSchemaResult>;
+/**
+ * 表结构自己的版本号，只在表 / 列 / 关键索引变化时抬，与包版本各走各的。
+ * 数值取自引入当前这套表结构的那条发布线。
+ */
+export const SCHEMA_VERSION: "2.6.0";
+export type SchemaVersionResult = {
+    /**
+     * - 活库当前满足的版本：够用就是 `SCHEMA_VERSION`，
+     * 缺东西就是 `null`（只知道不够用，不知道它停在哪一版）
+     */
+    current: string | null;
+    /**
+     * - 这一版代码需要的表结构版本
+     */
+    required: string;
+    /**
+     * - 需要的表 / 列 / 关键索引是不是都在
+     */
+    ok: boolean;
+    /**
+     * - 缺什么，形如 `'table:message_outbox'` /
+     * `'column:scheduled_messages.last_error'` / `'index:uidx_uuid'`。整张表缺席
+     * 时只报这一张表，不再逐列展开。`ok` 为 true 时是空数组
+     */
+    missing: string[];
+};
+export type EnsureSchemaResult = SchemaVersionResult & {
+    migrated: boolean;
+    schema: any | null;
+};

package/dist/lib/state-accessors.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @typedef {Object} StateAccessors
+ * @property {(namespace: string) => Promise<Array<{ namespace: string, key: string, value: string, updatedAt: number }>>} readState
+ *   一个 namespace 下的全部条目（值已解密、分块的已拼回原文）。适配器不支持
+ *   client_state 时返回空数组——读不到状态，hook 走自己的兜底就行。
+ * @property {(namespace: string, entries: Array<{ key: string, value: string|null, updatedAt?: number }>) => Promise<{ upserted: number, skipped: number, deleted: number }>} writeState
+ *   批量写。`value` 是字符串 → 整条覆盖（不是追加，宿主自己序列化）；
+ *   `value` 为 `null` → 删掉这个 key（连它的分块切片行一起）。`updatedAt`
+ *   默认取当前时刻，语义与客户端同步一致：比库里已有值旧的写入（或删除）
+ *   不生效，客户端后写的数据不会被这次调用盖回去。
+ *   适配器不支持 client_state 时抛错（静默成功会让 push 带上一个指向不存在
+ *   数据的引用键）。
+ */
+/**
+ * 造一份作用于某个用户的状态读写口。
+ *
+ * 典型用法是「大内容旁路」：一条 Web Push 的正文只有 4KB 出头（见
+ * lib/webpush-webcrypto.js 的 MAX_PUSH_PAYLOAD_BYTES），塞不下的内容先写进
+ * client_state，push 里只带一个引用键，客户端上线后按键取回。
+ *
+ * 谁清、什么时候清：库不做 TTL 也不自动回收，写进去的东西一直在，直到有人
+ * 覆盖或删除它。旁路内容建议放在固定的少量 key 上（例如每个角色一个），下次
+ * 写同一个 key 直接覆盖，存量天然有上限；一次性的大内容在确认客户端取走后，
+ * 用 `{ key, value: null }` 删掉。`DELETE /client-state` 仍然是清空这个用户
+ * 全部状态的兜底。
+ *
+ * @param {Object} args
+ * @param {import('../adapters/interface.js').DbAdapter} args.db
+ * @param {string} args.userId
+ * @param {string} args.userKey - per-user 存储密钥
+ * @param {number} [args.maxStateValueBytes] - 单条 value 的字节上限（默认 5MB）
+ * @param {() => number} [args.now] - 取当前时刻（测试可注入假时钟）
+ * @returns {StateAccessors}
+ */
+export function createStateAccessors({ db, userId, userKey, maxStateValueBytes, now }: {
+    db: import("../adapters/interface.js").DbAdapter;
+    userId: string;
+    userKey: string;
+    maxStateValueBytes?: number;
+    now?: () => number;
+}): StateAccessors;
+export type StateAccessors = {
+    /**
+     *   一个 namespace 下的全部条目（值已解密、分块的已拼回原文）。适配器不支持
+     *   client_state 时返回空数组——读不到状态，hook 走自己的兜底就行。
+     */
+    readState: (namespace: string) => Promise<Array<{
+        namespace: string;
+        key: string;
+        value: string;
+        updatedAt: number;
+    }>>;
+    /**
+     *   批量写。`value` 是字符串 → 整条覆盖（不是追加，宿主自己序列化）；
+     *   `value` 为 `null` → 删掉这个 key（连它的分块切片行一起）。`updatedAt`
+     *   默认取当前时刻，语义与客户端同步一致：比库里已有值旧的写入（或删除）
+     *   不生效，客户端后写的数据不会被这次调用盖回去。
+     *   适配器不支持 client_state 时抛错（静默成功会让 push 带上一个指向不存在
+     *   数据的引用键）。
+     */
+    writeState: (namespace: string, entries: Array<{
+        key: string;
+        value: string | null;
+        updatedAt?: number;
+    }>) => Promise<{
+        upserted: number;
+        skipped: number;
+        deleted: number;
+    }>;
+};

package/dist/lib/state-chunks.d.ts

@@ -0,0 +1,55 @@
+/** 某个用户 namespace 的切片行所在的保留 namespace。 */
+export function chunkNamespaceFor(namespace: any): string;
+/** 第 index 片的存储 key。 */
+export function chunkKeyFor(key: any, index: any): string;
+/** 清理某 key 全部切片行用的 key 前缀。 */
+export function chunkKeyPrefixFor(key: any): string;
+/** 分块根行的 value（纯文本 marker，不加密——不含用户数据）。 */
+export function buildChunkedRootValue(chunkCount: any): string;
+/**
+ * 严格解析根行 marker。不是 marker（普通密文 / 任意文本 / 计数非正整数）
+ * → null，调用方按普通单行处理。
+ *
+ * @param {unknown} value
+ * @returns {number | null}
+ */
+export function parseChunkedRootCount(value: unknown): number | null;
+/**
+ * 把超限 value 切成 ≤ STATE_CHUNK_SLICE_BYTES 的切片。切点在码点边界
+ * （chunkReasoningByUtf8Bytes 保证多字节字符 / emoji 代理对不被劈开，
+ * join('') === 原文）。
+ *
+ * @param {string} value
+ * @returns {string[]}
+ */
+export function splitStateValue(value: string): string[];
+/**
+ * 把一个 namespace 的存储行解析成逻辑条目（GET /client-state 与 readState
+ * 共用）。普通行解密直读；分块根行按 marker 拼回。切片行查询是惰性的：
+ * 整个 namespace 没有分块根行时一次都不发。
+ *
+ * @param {Array<{ namespace: string, key: string, value: string, updated_at: number }>} rows
+ *   用户 namespace 的存储行（getClientState 返回值）。
+ * @param {() => Promise<Array<{ key: string, value: string, updated_at: number }>>} fetchChunkRows
+ *   取该 namespace 对应保留 namespace 的全部切片行（最多调用一次）。
+ * @param {(value: string) => Promise<string>} decryptValue
+ * @returns {Promise<Array<{ namespace: string, key: string, value: string, updatedAt: number }>>}
+ */
+export function resolveClientStateEntries(rows: Array<{
+    namespace: string;
+    key: string;
+    value: string;
+    updated_at: number;
+}>, fetchChunkRows: () => Promise<Array<{
+    key: string;
+    value: string;
+    updated_at: number;
+}>>, decryptValue: (value: string) => Promise<string>): Promise<Array<{
+    namespace: string;
+    key: string;
+    value: string;
+    updatedAt: number;
+}>>;
+export const STATE_CHUNK_SLICE_BYTES: number;
+export const DEFAULT_MAX_STATE_VALUE_BYTES: number;
+export const INTERNAL_STATE_CHAR_RE: RegExp;

package/dist/lib/task-projection.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 任务行的对外投影：`GET /messages` 列出来的那一份形状。
+ *
+ * 一份实现两处用：HTTP 列表接口，以及 fire-time hook 的
+ * `ctx.scheduleTask()` 撞 uuid 时回给宿主的那条已存在任务。两边给出的字段
+ * 一样，宿主拿到哪一份都能直接进自己的任务面板。
+ *
+ * 白名单式取字段：解密后的 payload 里还躺着 `apiKey` / `apiUrl` /
+ * `pushSubscription` 等凭据，投影只挑下面列出的那几个，凭据一个都不出现。
+ */
+/**
+ * @typedef {Object} TaskProjection
+ * @property {number|null}  id
+ * @property {string|null}  uuid
+ * @property {string}       contactName
+ * @property {string}       messageType
+ * @property {string}       messageSubtype
+ * @property {string|null}  nextSendAt
+ * @property {string}       recurrenceType
+ * @property {string|null}  tzId          - 循环推进用的 IANA 时区 id；没设 → null（按 UTC 推进）
+ * @property {string|null}  status
+ * @property {number}       retryCount
+ * @property {string|null}  createdAt
+ * @property {string|null}  updatedAt
+ * @property {string|null}  charId        - 取自 metadata.charId
+ * @property {string|null}  clientTaskId  - 取自 metadata.amsgClientTaskId
+ * @property {Object|null}  credRefs      - 凭据引用（{ <purpose>: <cred_id> }）；引用不是机密，客户端对账要看。没带 → null
+ * @property {Object|null}  [metadata]    - 只有 includeMetadata 时才有，见下
+ * @property {{ at: string, occurrence: string, reason: string, errorCode?: string, pushStatus?: number }|null} lastError
+ *   `errorCode` 是底层错误的稳定 code（如 `PUSH_PAYLOAD_TOO_LARGE`），拿得到就
+ *   带上；`pushStatus` 只在投递失败于推送这一步时出现，值是推送服务回的 HTTP
+ *   状态码。判断该怎么处置读这两个字段，别去正则匹配 `reason`。
+ */
+/**
+ * @param {Object} row - 数据库任务行
+ * @param {Object} decryptedPayload - 解密后的任务 payload
+ * @param {{ includeMetadata?: boolean }} [options]
+ *   includeMetadata 时多带一个完整的 `metadata`。列表接口不带：一页最多 100
+ *   条，每条都驮着宿主的整份 metadata 会把响应撑得很大，而列表要的只是「有哪
+ *   些任务」。要整份 metadata 的是另一件事——`PUT /update-message` 对 metadata
+ *   是整体替换，宿主想只改其中一个子字段就必须先读回完整的那份，那条路径走
+ *   `GET /message?id=<uuid>`（单条，带完整 metadata）。
+ * @returns {TaskProjection}
+ */
+export function projectTask(row: any, decryptedPayload: any, options?: {
+    includeMetadata?: boolean;
+}): TaskProjection;
+export type TaskProjection = {
+    id: number | null;
+    uuid: string | null;
+    contactName: string;
+    messageType: string;
+    messageSubtype: string;
+    nextSendAt: string | null;
+    recurrenceType: string;
+    /**
+     * - 循环推进用的 IANA 时区 id；没设 → null（按 UTC 推进）
+     */
+    tzId: string | null;
+    status: string | null;
+    retryCount: number;
+    createdAt: string | null;
+    updatedAt: string | null;
+    /**
+     * - 取自 metadata.charId
+     */
+    charId: string | null;
+    /**
+     * - 取自 metadata.amsgClientTaskId
+     */
+    clientTaskId: string | null;
+    /**
+     * - 凭据引用（{ <purpose>: <cred_id> }）；引用不是机密，客户端对账要看。没带 → null
+     */
+    credRefs: any | null;
+    /**
+     * - 只有 includeMetadata 时才有，见下
+     */
+    metadata?: any | null;
+    /**
+     *   `errorCode` 是底层错误的稳定 code（如 `PUSH_PAYLOAD_TOO_LARGE`），拿得到就
+     *   带上；`pushStatus` 只在投递失败于推送这一步时出现，值是推送服务回的 HTTP
+     *   状态码。判断该怎么处置读这两个字段，别去正则匹配 `reason`。
+     */
+    lastError: {
+        at: string;
+        occurrence: string;
+        reason: string;
+        errorCode?: string;
+        pushStatus?: number;
+    } | null;
+};