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

package/dist/adapters/d1.d.ts

@@ -0,0 +1,416 @@
+/**
+ * Create a D1 adapter from a Cloudflare D1 binding (env.DB).
+ * @param {{ prepare: (sql: string) => any }} db
+ * @returns {import('./interface.js').DbAdapter}
+ */
+export function createD1Adapter(db: {
+    prepare: (sql: string) => any;
+}): import("./interface.js").DbAdapter;
+export class D1Adapter {
+    /** @param {{ prepare: (sql: string) => any }} db - Cloudflare D1 binding */
+    constructor(db: {
+        prepare: (sql: string) => any;
+    });
+    /** @private */
+    private _db;
+    /** @private */
+    private _now;
+    /** @private */
+    private _iso;
+    /**
+     * 组一组带 `IN (...)` 的语句：值多到一条塞不下时，按 D1 的绑定参数上限切成
+     * 几条（见 chunkForBoundParams）。
+     *
+     * 只有拿得到事务的绑定才切。没有 batch() 的绑定（测试 shim、自定义适配器，
+     * 都不是真实 D1）原样发一条不切的语句：切批是为 D1 那条上限服务的，这类绑
+     * 定不受它约束，切了反倒会因为没有事务而多出一个「写一半」的中间态。
+     *
+     * @private
+     * @param {(placeholders: string) => string} buildSql - 拿占位符串（`?, ?, ?`）组 SQL
+     * @param {unknown[]} leadingParams - IN 列表之前的固定参数，按出现顺序
+     * @param {unknown[]} values - IN 列表里的全部值
+     * @returns {any[]} 已经 bind 好的语句
+     */
+    private _prepareInClauseStatements;
+    /**
+     * 带 `IN (...)` 的批量写，切成几条也仍然是一次原子操作。
+     *
+     * 一条语句本来天然原子，拆开之后这份保证得自己补回来，否则就会多出「只删掉
+     * 前 99 个」「只 ack 了前 98 条」这类比原问题更难查的中间态。D1 的 batch()
+     * 是隐式事务——其中一条失败，整批回滚——正好接住这件事。
+     *
+     * 一条就够时照旧单发，跟切批以前走的是同一条路，常见调用（一次三五个 id）
+     * 的行为一个字节都没变。
+     *
+     * @private
+     * @param {(placeholders: string) => string} buildSql
+     * @param {unknown[]} leadingParams
+     * @param {unknown[]} values
+     * @returns {Promise<number>} 各批影响行数之和
+     */
+    private _runInClauseWrite;
+    initSchema(): Promise<{
+        columnsCreated: number;
+        indexesCreated: number;
+        indexesFailed: number;
+        columns: any[];
+        indexes: ({
+            name: string;
+            status: string;
+            description: string;
+            critical: boolean;
+            error?: undefined;
+        } | {
+            name: string;
+            status: string;
+            description: string;
+            critical: boolean;
+            error: any;
+        })[];
+    }>;
+    /**
+     * 活库里现在实际有哪些表 / 列 / 索引。
+     *
+     * 只读不写，纯粹如实回报：拿它跟这一版需要的清单对照的活儿在
+     * lib/schema-version.js（`getSchemaVersion` / `ensureSchema`）。库升级后表结
+     * 构变了而老部署没跑过 initSchema 时，cron 会每分钟静默挂在缺的那一列上，
+     * 界面上一切正常——这个方法就是让宿主查得出来。
+     *
+     * @returns {Promise<{ tables: Record<string, string[]>, indexes: string[] }>}
+     */
+    describeSchema(): Promise<{
+        tables: Record<string, string[]>;
+        indexes: string[];
+    }>;
+    dropSchema(): Promise<void>;
+    createTask(params: any): Promise<any>;
+    /**
+     * 建新任务的同时取消旧的那条（`POST /schedule-message` 的 supersedesUuid）。
+     *
+     * 两条语句走一次 batch（D1 的隐式事务 + 单次网络往返）：不会出现「旧的删了、
+     * 新的没建成」的中间态——INSERT 撞 uuid 唯一索引时整个 batch 回滚，旧行原样
+     * 留着，调用方按既有的 409 冲突路径处理。
+     *
+     * @param {import('./interface.js').InsertTaskParams} params
+     * @param {string} supersedesUuid - 要取消的旧任务 uuid（同一 user_id 下）
+     * @returns {Promise<Object>} createTask 的返回行 + `superseded`（旧行是否
+     *   真的被删掉；false = 旧行本就不存在）
+     */
+    createTaskSuperseding(params: import("./interface.js").InsertTaskParams, supersedesUuid: string): Promise<any>;
+    getTaskByUuid(uuid: any, userId: any): Promise<any>;
+    getTaskByUuidOnly(uuid: any): Promise<any>;
+    /**
+     * 这条 uuid 现在是什么状态——不限用户，也不限状态（getTaskByUuidOnly 只看
+     * pending 行）。`runTask` 用它把「这条已经跑完了」和「压根没这条」分开回报。
+     *
+     * @param {string} uuid
+     * @returns {Promise<{ status: string }|null>}
+     */
+    getTaskStatusByUuidOnly(uuid: string): Promise<{
+        status: string;
+    } | null>;
+    updateTaskById(taskId: any, updates: any): Promise<any>;
+    updateTaskByUuid(uuid: any, userId: any, encryptedPayload: any, extraFields: any): Promise<{
+        uuid: any;
+        updated_at: string;
+    }>;
+    deleteTaskById(taskId: any): Promise<boolean>;
+    deleteTaskByUuid(uuid: any, userId: any): Promise<boolean>;
+    getPendingTasks(limit?: number): Promise<any>;
+    /**
+     * 领取一条到点的任务：在 lease_until 上写下「这条归我管到什么时候」，
+     * 本次投递期间别的 tick 领不走它。
+     *
+     * 租约写在自己的列上，next_send_at 全程不动——那一列是用户设的触发时刻，
+     * 任务列表要读它、循环任务推进下一次也要拿它当基准。
+     *
+     * 两个 tick 抢同一行时只有一个能改到行，另一个拿到 changes = 0，据此跳过。
+     * WHERE 里的两个条件各管一件事：
+     *   - lease_until 为空或已过期：没人正在跑这条。领了任务的 tick 中途没了
+     *     也不会把行焊死，租约到期后自然可以被接手。
+     *   - next_send_at 等于读这行时看到的值：读出来之后用户又改了排期的话，
+     *     这一跳就不该再按旧时刻发。
+     *
+     * 不加一个 'sending' 状态来表达「正在跑」：建表语句里 status 有
+     * CHECK (status IN ('pending','sent','failed'))，加值要重建表。
+     *
+     * expectedNextSendAt 按读到的原样比对，不做时区归一化——老部署里可能还留
+     * 着非归一化写法的行（如 +08:00 结尾），归一化后反而对不上，那条任务会永
+     * 远领不到。
+     *
+     * 带 serializeGroup 时多一道分组门：同一分组里已经有别的行拿着未到期的租
+     * 约，这条就领不走（同一分组同时只跑一条）。判定和写租约在同一条 UPDATE
+     * 里完成，「先查再占」的空档天然不存在——两个 tick 同时来，只有一个改得动
+     * 行。分组门只看租约，不看 `retry_after`：等着重试的任务其实闲着，不该把
+     * 同分组的其他任务一起堵住。
+     *
+     * @param {number} taskId
+     * @param {string} expectedNextSendAt - 读这行时拿到的 next_send_at 原值
+     * @param {string|Date} leaseUntil - 租期末尾
+     * @param {string|null} [serializeGroup] - 串行分组标识；空表示不参与分组串行
+     * @returns {Promise<boolean>} true = 领到了；false = 别人正拿着租约、同分组
+     *   有任务正在跑、排期被改过、或行已不是 pending
+     */
+    claimTask(taskId: number, expectedNextSendAt: string, leaseUntil: string | Date, serializeGroup?: string | null): Promise<boolean>;
+    /**
+     * 投递期间的租约续期（run-tick 的心跳用）。只在行仍是 pending 且确实持有
+     * 租约（lease_until 非空）时生效——收尾把租约放掉之后，迟到的心跳不会把
+     * 租约复活。
+     *
+     * @param {number} taskId
+     * @param {string|Date} leaseUntil - 新的租期末尾
+     * @returns {Promise<boolean>} true = 续上了
+     */
+    renewTaskLease(taskId: number, leaseUntil: string | Date): Promise<boolean>;
+    listTasks(userId: any, opts?: {}): Promise<{
+        tasks: any;
+        total: number;
+    }>;
+    cleanupOldTasks(days?: number): Promise<any>;
+    getTaskStatus(uuid: any, userId: any): Promise<any>;
+    /**
+     * 状态 + 失败摘要（GET /message 用它把「为什么失败」透给已失败的行——那些
+     * 行 getTaskByUuid 读不到，payload 里的 lastError 也就够不着了）。
+     *
+     * @param {string} uuid
+     * @param {string} userId
+     * @returns {Promise<{ status: string, last_error: string|null }|null>}
+     */
+    getTaskStatusInfo(uuid: string, userId: string): Promise<{
+        status: string;
+        last_error: string | null;
+    } | null>;
+    /**
+     * Batch upsert. Last-write-wins per (namespace, key): an entry older
+     * than the stored row (updatedAt strictly lower) is skipped; equal or
+     * newer overwrites. Values arrive pre-encrypted (the handler encrypts).
+     *
+     * `cleanups` 是删除项：在同一 batch 里先于 upsert 执行，`updated_at <= ?`
+     * 条件保证陈旧批次删不动更新写入的行。两种形态——
+     *   - `{ namespace, keyPrefix, updatedAt }` 删 key 前缀下的所有行，用来清掉
+     *     大值旧写入留下的切片行（见 lib/state-chunks.js）；
+     *   - `{ namespace, key, updatedAt }` 删这一个 key，用来删整条状态（前缀会
+     *     连带删掉同前缀的兄弟 key，删单条必须走精确匹配）。
+     *
+     * 删掉一整条状态就是这两种各来一条（切片行走前缀、根行走精确 key），
+     * `entries` 传空数组即可——见 lib/client-state-store.js。
+     *
+     * Uses D1's batch() — one network round trip for the whole set (implicit
+     * transaction). The client calls this endpoint inside its few-seconds
+     * background window, so N sequential round trips could eat the whole
+     * window. Bindings without batch() (e.g. the sqlite test shim, custom
+     * adapters) fall back to a sequential loop.
+     *
+     * @param {string} userId
+     * @param {Array<{ namespace: string, key: string, value: string, updatedAt: number }>} entries
+     * @param {Array<{ namespace: string, key?: string, keyPrefix?: string, updatedAt: number }>} [cleanups]
+     * @returns {Promise<{ upserted: number, skipped: number, outcomes: boolean[] }>}
+     *   `outcomes[i]` 对应 entries[i] 是否真的写入（changes > 0）。
+     */
+    upsertClientState(userId: string, entries: Array<{
+        namespace: string;
+        key: string;
+        value: string;
+        updatedAt: number;
+    }>, cleanups?: Array<{
+        namespace: string;
+        key?: string;
+        keyPrefix?: string;
+        updatedAt: number;
+    }>): Promise<{
+        upserted: number;
+        skipped: number;
+        outcomes: boolean[];
+    }>;
+    /**
+     * All entries of one namespace (values still encrypted).
+     *
+     * @param {string} userId
+     * @param {string} namespace
+     * @returns {Promise<Array<{ namespace: string, key: string, value: string, updated_at: number }>>}
+     */
+    getClientState(userId: string, namespace: string): Promise<Array<{
+        namespace: string;
+        key: string;
+        value: string;
+        updated_at: number;
+    }>>;
+    /**
+     * 例行清理：把指定命名空间下太久没更新的条目删掉（run-tick 每跳顺手调，
+     * 宿主配了 `clientStateTtl` 才会调）。
+     *
+     * 不限用户——「这个命名空间只留最近 N 天」是命名空间级的约定，单用户部署
+     * 下也就是这一个用户的行。指令由 lib/client-state-store.js 的
+     * `planClientStateCleanup` 算好（含大值切片所在的保留命名空间），这里只负
+     * 责照着删。
+     *
+     * @param {Array<{ namespace: string, updatedBefore: number }>} targets
+     *   `updatedBefore` 是 epoch 毫秒，与 `updated_at` 列同一把尺子。
+     * @returns {Promise<number>} 删掉的行数
+     */
+    cleanupClientState(targets?: Array<{
+        namespace: string;
+        updatedBefore: number;
+    }>): Promise<number>;
+    /**
+     * Wipe every entry of this user.
+     *
+     * @param {string} userId
+     * @returns {Promise<number>} rows deleted
+     */
+    clearClientState(userId: string): Promise<number>;
+    /**
+     * 这个用户当前登记的推送订阅（密文原样返回，解密在上层）。
+     *
+     * @param {string} userId
+     * @returns {Promise<{ subscription: string, updated_at: number }|null>}
+     */
+    getPushSubscription(userId: string): Promise<{
+        subscription: string;
+        updated_at: number;
+    } | null>;
+    /**
+     * 覆盖写这个用户的订阅。一个用户一行，没有 last-write-wins 之类的比较——
+     * 客户端拿到的新订阅永远比旧的有效，旧的那份只会 410。
+     *
+     * @param {string} userId
+     * @param {string} encryptedSubscription
+     * @param {number} updatedAt - epoch 毫秒
+     * @returns {Promise<boolean>}
+     */
+    upsertPushSubscription(userId: string, encryptedSubscription: string, updatedAt: number): Promise<boolean>;
+    /**
+     * 删掉这个用户的订阅（设置页「停止接收推送」）。
+     *
+     * @param {string} userId
+     * @returns {Promise<boolean>} true = 确实删掉了一行
+     */
+    deletePushSubscription(userId: string): Promise<boolean>;
+    /**
+     * 批量 upsert 这个用户的凭据（value 已是密文，加密在上层）。已存在的行
+     * 覆盖 encrypted_value 并刷 updated_at，created_at 保留首次写入的时刻。
+     *
+     * @param {string} userId
+     * @param {Array<{ credId: string, encryptedValue: string }>} entries
+     * @returns {Promise<number>} 实际写入/覆盖的行数
+     */
+    upsertLlmCredentials(userId: string, entries: Array<{
+        credId: string;
+        encryptedValue: string;
+    }>): Promise<number>;
+    /**
+     * 按 cred_id 批量读这个用户的凭据行（`encrypted_value` 是密文，解密在上
+     * 层）。排程时的存在性检查和 fire 时的解析共用这一个口。
+     *
+     * @param {string} userId
+     * @param {string[]} credIds
+     * @returns {Promise<Array<{ cred_id: string, encrypted_value: string, updated_at: string }>>}
+     */
+    getLlmCredentials(userId: string, credIds: string[]): Promise<Array<{
+        cred_id: string;
+        encrypted_value: string;
+        updated_at: string;
+    }>>;
+    /**
+     * 这个用户名下所有凭据的对账清单（只有 cred_id 和 updated_at，密文不出
+     * 这个方法）。按 cred_id 排序，输出稳定。
+     *
+     * @param {string} userId
+     * @returns {Promise<Array<{ cred_id: string, updated_at: string }>>}
+     */
+    listLlmCredentials(userId: string): Promise<Array<{
+        cred_id: string;
+        updated_at: string;
+    }>>;
+    /**
+     * 删凭据。`credIds` 传数组删指定那几行；传 null 删这个用户的全部
+     * （「清空云端数据」用）。
+     *
+     * @param {string} userId
+     * @param {string[]|null} credIds
+     * @returns {Promise<number>} 删掉的行数
+     */
+    deleteLlmCredentials(userId: string, credIds?: string[] | null): Promise<number>;
+    /**
+     * 发送前把这一批 push 落进 outbox（一次 batch）。(user_id, message_id)
+     * 唯一：重试同一 occurrence 带着同一批 messageId 再来时更新 payload、不加
+     * 第二行；客户端已经 ack 过的行不动（ack 是终态，重试不该把它拉回未读）。
+     *
+     * @param {string} userId
+     * @param {Array<{ message_id: string, task_uuid?: string|null, session_id?: string|null,
+     *   message_index?: number|null, total_messages?: number|null, payload: string, created_at: number }>} rows
+     *   `payload` 是整条 push JSON 的 encryptForStorage 密文。
+     * @returns {Promise<number>} 实际写入/更新的行数
+     */
+    appendOutboxMessages(userId: string, rows: Array<{
+        message_id: string;
+        task_uuid?: string | null;
+        session_id?: string | null;
+        message_index?: number | null;
+        total_messages?: number | null;
+        payload: string;
+        created_at: number;
+    }>): Promise<number>;
+    /**
+     * 把这一批标记为「Web Push 已发出」。发送失败的段不标——delivered_at 为
+     * null 的行正是客户端最需要拉的那部分。
+     *
+     * @param {string} userId
+     * @param {string[]} messageIds
+     * @param {number} deliveredAt - epoch 毫秒
+     * @returns {Promise<number>}
+     */
+    markOutboxDelivered(userId: string, messageIds: string[], deliveredAt: number): Promise<number>;
+    /**
+     * 把这一批还没发出去的行删掉（任务投递到一半被取消 / 顶替时用）。
+     *
+     * 只删 delivered_at 仍为 NULL 的行：已经推给设备的那几条撤不回来，行留着让
+     * 客户端照常 ack。已 ack 的行更不动。
+     *
+     * @param {string} userId
+     * @param {string[]} messageIds
+     * @returns {Promise<number>} 删掉的行数
+     */
+    discardOutboxMessages(userId: string, messageIds: string[]): Promise<number>;
+    /**
+     * 未 ack 的行（id 升序，游标翻页）。payload 仍是密文，解密在 handler。
+     *
+     * @param {string} userId
+     * @param {number} sinceId - 上一页游标（0 = 从头）
+     * @param {number} limit
+     * @returns {Promise<Array<{ id: number, message_id: string, task_uuid: string|null,
+     *   session_id: string|null, message_index: number|null, total_messages: number|null,
+     *   payload: string, created_at: number, delivered_at: number|null }>>}
+     */
+    listUnackedOutbox(userId: string, sinceId?: number, limit?: number): Promise<Array<{
+        id: number;
+        message_id: string;
+        task_uuid: string | null;
+        session_id: string | null;
+        message_index: number | null;
+        total_messages: number | null;
+        payload: string;
+        created_at: number;
+        delivered_at: number | null;
+    }>>;
+    /**
+     * 客户端确认收到这一批（幂等：已 ack 的行再 ack 不动）。
+     *
+     * @param {string} userId
+     * @param {string[]} messageIds
+     * @param {number} ackedAt - epoch 毫秒
+     * @returns {Promise<number>} 本次真正被 ack 的行数
+     */
+    ackOutboxMessages(userId: string, messageIds: string[], ackedAt: number): Promise<number>;
+    /**
+     * outbox 的例行清理（run-tick 每跳顺手调）：已 ack 的行留短一些，未 ack 的
+     * 也不无限留（Web Push TTL 上限四周，比它更老的推送谁也收不到了）。
+     *
+     * @param {{ ackedBeforeMs?: number, allBeforeMs?: number }} opts - epoch 毫秒阈值
+     * @returns {Promise<number>} 删掉的行数
+     */
+    cleanupOutbox({ ackedBeforeMs, allBeforeMs }?: {
+        ackedBeforeMs?: number;
+        allBeforeMs?: number;
+    }): Promise<number>;
+}

package/dist/adapters/factory.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Adapter Factory
+ *
+ * Creates a database adapter instance based on the supplied configuration.
+ *
+ * @typedef {'neon'|'pg'} DriverName
+ *
+ * @typedef {Object} AdapterConfig
+ * @property {DriverName} driver  - Which database driver to use.
+ * @property {string}     connectionString - Database connection URL.
+ */
+/**
+ * Create a database adapter.
+ *
+ * @param {AdapterConfig} config
+ * @returns {Promise<import('./interface.js').DbAdapter>}
+ */
+export function createAdapter(config: AdapterConfig): Promise<import("./interface.js").DbAdapter>;
+/**
+ * Adapter Factory
+ *
+ * Creates a database adapter instance based on the supplied configuration.
+ */
+export type DriverName = "neon" | "pg";
+/**
+ * Adapter Factory
+ *
+ * Creates a database adapter instance based on the supplied configuration.
+ */
+export type AdapterConfig = {
+    /**
+     * - Which database driver to use.
+     */
+    driver: DriverName;
+    /**
+     * - Database connection URL.
+     */
+    connectionString: string;
+};