@rei-standard/amsg-server 2.6.0-next.1 → 2.6.0-next.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ReiStandard contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -104,10 +104,77 @@ AI 配置消息的提示词可以用两种形态之一，**互斥二选一**：
 - 限制：每项 ≤ 200 字符，数组 ≤ 10 项；非法或无法 `new RegExp(...)` 通过 → `400 INVALID_PARAMETERS`（schedule）/ `400 INVALID_UPDATE_DATA`（update）。
 - `update-message` 显式传 `splitPattern: null` 可重置回默认；不传则保留原值。
 
+## 一条 Web Push 能塞多少
+
+推送服务（FCM / APNs / Mozilla autopush）限的是**加密后** body 的 4096 字节，超了当场 413 拒收，用户什么也收不到。明文额度要把 aes128gcm 的固定开销减掉——header 86（salt 16 + record size 4 + keyid 长度 1 + 应用服务器公钥 65）+ 填充分隔符 1 + GCM auth tag 16 = 103 字节——所以**一条 push 的 payload 上限是 3993 字节**，按 UTF-8 字节算，不是字符数。
+
+`sendWebPush` 会在发出去之前挡下超限的 payload，抛出 `err.code === 'PUSH_PAYLOAD_TOO_LARGE'` 的错误，消息里带实际字节数和上限。
+
+组 payload 之前想自己做预算，用导出的常量和工具函数，别写死魔法数字：
+
+```js
+import { MAX_PUSH_PAYLOAD_BYTES, measurePushPayload } from '@rei-standard/amsg-server';
+
+const { bytes, remainingBytes, withinLimit } = measurePushPayload(JSON.stringify(push));
+// remainingBytes = 还能再塞多少字节（已超限时为负）
+```
+
+装不下的内容（长文、附件详情）建议走旁路：正文存进 `client_state`，push 里只带一个引用键，客户端上线后用 `GET /client-state` 取回。单用户 Worker 的 fire-time hook 用 `ctx.writeState()` 写，见 [`examples/cloudflare-single-user/README.md`](https://github.com/Tosd0/ReiStandard/blob/main/packages/rei-standard-amsg/server/examples/cloudflare-single-user/README.md)。
+
+## Fire 时刻 hooks
+
+配上 `hooks: { onBeforeFire, onLLMOutput, executeToolCalls }` 之后，AI 类任务的 prompt 不再是排程那一刻冻结的文本，而是 cron 触发时现场组装，工具也在服务端就地跑完，全程不需要客户端在线。完整用法见 [`examples/cloudflare-single-user/README.md`](https://github.com/Tosd0/ReiStandard/blob/main/packages/rei-standard-amsg/server/examples/cloudflare-single-user/README.md) 的「Fire 时刻 hooks」。
+
+三个 hook 拿到的 ctx 上都有这几个口子：
+
+| ctx 上的口子 | 干什么 |
+|---|---|
+| `readState(ns)` / `writeState(ns, entries)` | 读写 `client_state`，和客户端 `GET/PUT /client-state` 是同一份数据 |
+| `scheduleTask(options)` | 给同一个用户再建一条定时任务 |
+| `scratch` | 本次 fire 的便签对象，三个 hook 共享同一个引用，fire 结束即丢弃 |
+
+### `ctx.scheduleTask(options)`
+
+角色在这次 fire 里给自己排一条后续任务：「这条发完，一个半小时后我再接着说一句」。建出来的是一条正常的任务行，到点由 cron 触发，用户全程离线也不影响。
+
+```js
+const result = await ctx.scheduleTask({
+  firstSendTime: new Date(Date.now() + 90 * 60_000).toISOString(), // 必填，ISO 字符串
+  messageType: 'auto',            // 可选，默认继承当前任务
+  recurrenceType: 'none',         // 可选，默认 none
+  metadata: { beat: 'followup' }, // 可选，整体替换当前任务的 metadata（不深合并）
+  uuid: `fire-${ctx.task.id}-${ctx.task.nextSendAt}`, // 可选，默认随机
+});
+// → { created: true, id, uuid, nextSendAt }
+//   或 { created: false, reason: 'duplicate', uuid }
+```
+
+凭据和投递配置（`pushSubscription` / `apiUrl` / `apiKey` / `primaryModel` / `maxTokens` / `temperature` / `splitPattern`）以及 `contactName` / `avatarUrl` / `messageSubtype` / `userMessage` 从当前任务继承，宿主只说「什么时候、说什么方向」——hook 全程看不到凭据。`completePrompt` / `messages` 不继承（都置 `null`）：hook 每次现场重组 prompt，把排程时冻结的旧 prompt 带过去，新任务万一走回冻结 prompt 老链路就会静默发出一条谁也没打算发的文案。
+
+护栏：
+
+| 护栏 | 阈值 / 规则 | 不满足时 | 为什么 |
+|---|---|---|---|
+| `firstSendTime` | 必填、能解析成合法时间、至少比现在晚 **60 秒** | `RangeError` | cron 一分钟一跳，排在 60 秒内等于让下一跳立刻捡走，容易变成自己触发自己的紧密循环 |
+| `messageType` | 只收 `auto` / `prompted` / `fixed` | `TypeError` | `instant` 的语义是「建行的那一刻就投递」，那条路径归 `POST /schedule-message` 管；从 fire 里造这么一行，投递时机反而说不清 |
+| `messageType: 'fixed'` | 必须有 `userMessage`（自己传或继承到） | `TypeError` | 固定文本任务没有正文，就是一条永远发空的任务 |
+| 单次 fire 的建任务条数 | 默认 **2 条**，factory 配置 `maxScheduledTasksPerFire` 可调（`0` = 不许自排） | `RangeError` | 模型自排后续本质上是条能无限延伸的链，没有上限就没人按停止键 |
+| `uuid` 撞车 | 不当错误处理 | 返回 `{ created: false, reason: 'duplicate', uuid }` | fire 失败会整条重跑，宿主传一个由「任务 id + 触发时刻」推出来的确定性 uuid 就天然幂等 |
+| 数据库适配器没有 `createTask` | — | 抛 `AGENTIC_SCHEDULE_UNSUPPORTED` | 静默成功会让宿主以为后续那条排上了，其实谁也不会触发它 |
+
+`recurrenceType` 沿用排程接口那套 `none` / `daily` / `weekly`，别的值抛 `TypeError`。参数不合法的调用不占建任务额度；uuid 撞车占（那条任务其实已经建出来了）。
+
+`GET /capabilities` 的 features 里有 `agentic-schedule-task`，前端可以据此判断部署的 worker 认不认这条链路。
+
 ## 导出（新增）
 
-- `validateLlmMessagesArray(messages)` — 同步预校验 messages 数组，返回 `string | null`（错误信息 / 通过）。和 `@rei-standard/amsg-instant` 的校验规则字节级一致。
+- `validateLlmMessagesArray(messages)` — 同步预校验 messages 数组，返回 `string | null`（错误信息 / 通过）。形状规则统一在 `@rei-standard/amsg-shared` 的 `validateLlmMessagesShape`，和 `@rei-standard/amsg-instant` 共用同一实现（含 agentic 会话：assistant 带 `tool_calls` 时 content 可空、`role:'tool'` 要求 `tool_call_id`）。
 - `validateSplitPattern(value)` — 同步预校验 splitPattern（string / string[] / null），返回 `string | null`。
+- `MAX_PUSH_PAYLOAD_BYTES` — 一条 push 的明文上限，3993 字节。
+- `WEB_PUSH_MAX_BODY_BYTES` / `WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES` — 推送服务的密文 body 上限（4096）与 aes128gcm 固定开销（103），上面那个数就是两者相减。
+- `measurePushPayload(payload)` — 量一段 payload 的字节数与剩余额度，返回 `{ bytes, maxBytes, remainingBytes, withinLimit }`。
+
+以上四个在包根和 `@rei-standard/amsg-server/cloudflare` 两个入口都有。
 
 ## 一体化初始化流程
 
@@ -123,6 +190,22 @@ AI 配置消息的提示词可以用两种形态之一，**互斥二选一**：
 - `send-notifications`
   - `Authorization: Bearer <cronToken>` 或 `?token=<cronToken>`
 
+## 触发任务时的占位
+
+`send-notifications`（以及单用户 Worker 的 `scheduled()`）每条任务开跑前会先占位：在这一行的 `lease_until` 上写下「归我管到现在 + 租期为止」，本次投递期间别的 tick 领不走它；占位改到 0 行说明别人先领走了，本次直接跳过。cron 一分钟一跳而带工具的 AI 任务常常跑过一分钟，没有这层占位同一条任务会被相邻几跳重复触发。
+
+租约写在自己的列上，`next_send_at` 全程不动——任务列表读到的一直是用户设的那个时刻，循环任务也按它推进到下一次。投递收尾时租约就放掉，失败重试的退避（2 分钟起）不会被租期压住。
+
+领了任务的那一跳中途没了（Worker 被回收之类）就没人来放租约，这条任务要等租约到期才会被后面的 tick 接手。把租期设得比最慢的一次投递长一点即可。
+
+租期默认 10 分钟；配了 `totalTimeoutMs` 的话按它 + 2 分钟往上抬。想自己定就在 `runScheduledTick` 的 ctx（或单用户 Worker 的 config）里传 `claimLeaseMs`——注意 `createReiServer` 内置的 `/send-notifications` 处理器不透传这两个值，要调租期就自己调 `runScheduledTick`。`onBeforeFire` 里按次放宽的预算占位时看不到，那种情况也要显式设 `claimLeaseMs`。
+
+占位管的是定时触发这条路径。`messageType: 'instant'` 走的是「建行 → 当场投递」，不经过占位。
+
+内置适配器都实现了占位。自定义适配器可以不实现 `claimTask`，跑得动，只是回到不占位的行为。
+
+`lease_until` 是这次新加的列。走 `POST /init-tenant`（或任何一次 `initSchema`）会自动给已有的表补上；手工建表的看 `examples/cloudflare-single-user/schema.sql`。
+
 ## 导出 API（Exports）
 
 - `createReiServer`
@@ -134,6 +217,10 @@ AI 配置消息的提示词可以用两种形态之一，**互斥二选一**：
 - `encryptForStorage`
 - `decryptFromStorage`
 - `validateScheduleMessagePayload`
+- `measurePushPayload`
+- `MAX_PUSH_PAYLOAD_BYTES`
+- `WEB_PUSH_MAX_BODY_BYTES`
+- `WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES`
 - `isValidISO8601`
 - `isValidUrl`
 - `isValidUUID`

package/dist/adapters/d1.d.ts

@@ -0,0 +1,146 @@
+/**
+ * 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;
+    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;
+        })[];
+    }>;
+    dropSchema(): Promise<void>;
+    createTask(params: any): Promise<any>;
+    getTaskByUuid(uuid: any, userId: any): Promise<any>;
+    getTaskByUuidOnly(uuid: any): Promise<any>;
+    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 结尾），归一化后反而对不上，那条任务会永
+     * 远领不到。
+     *
+     * @param {number} taskId
+     * @param {string} expectedNextSendAt - 读这行时拿到的 next_send_at 原值
+     * @param {string|Date} leaseUntil - 租期末尾
+     * @returns {Promise<boolean>} true = 领到了；false = 别人正拿着租约、排期被改过、或行已不是 pending
+     */
+    claimTask(taskId: number, expectedNextSendAt: string, 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>;
+    /**
+     * 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;
+    }>>;
+    /**
+     * Wipe every entry of this user.
+     *
+     * @param {string} userId
+     * @returns {Promise<number>} rows deleted
+     */
+    clearClientState(userId: string): 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;
+};

package/dist/adapters/interface.d.ts

@@ -0,0 +1,137 @@
+export type TaskRow = {
+    id: number;
+    user_id: string;
+    uuid: string;
+    encrypted_payload: string;
+    message_type: string;
+    next_send_at: string;
+    status: string;
+    retry_count: number;
+    created_at: string;
+    updated_at: string;
+};
+export type InsertTaskParams = {
+    user_id: string;
+    uuid: string;
+    encrypted_payload: string;
+    next_send_at: string;
+    message_type: string;
+};
+export type InitSchemaResult = {
+    columnsCreated: number;
+    indexesCreated: number;
+    indexesFailed: number;
+    columns: any[];
+    indexes: any[];
+};
+export type DbAdapter = {
+    /**
+     *   Create the scheduled_messages table and all indexes.
+     */
+    initSchema: () => Promise<InitSchemaResult>;
+    /**
+     *   Drop the scheduled_messages table (CASCADE).
+     */
+    dropSchema: () => Promise<void>;
+    /**
+     *   Insert a new task row and return the created record.
+     */
+    createTask: (params: InsertTaskParams) => Promise<TaskRow>;
+    /**
+     *   Fetch a single pending task by uuid + user_id.
+     */
+    getTaskByUuid: (uuid: string, userId: string) => Promise<TaskRow | null>;
+    /**
+     *   Fetch a single pending task by uuid only (used by instant processing).
+     */
+    getTaskByUuidOnly: (uuid: string) => Promise<TaskRow | null>;
+    /**
+     *   Partially update a task row by its numeric id.
+     *   实现了 `claimTask` 的适配器还要认 `lease_until`（含写 null）：投递收尾
+     *   时 runScheduledTick 用它把租约放掉。
+     */
+    updateTaskById: (taskId: number, updates: any) => Promise<TaskRow | null>;
+    /**
+     *   Update a pending task's encrypted_payload (and optional index fields) by uuid + user_id.
+     */
+    updateTaskByUuid: (uuid: string, userId: string, encryptedPayload: string, extraFields?: any) => Promise<TaskRow | null>;
+    /**
+     *   Delete a task by numeric id. Returns true if a row was affected.
+     */
+    deleteTaskById: (taskId: number) => Promise<boolean>;
+    /**
+     *   Delete a task by uuid + user_id. Returns true if a row was affected.
+     */
+    deleteTaskByUuid: (uuid: string, userId: string) => Promise<boolean>;
+    /**
+     *   Fetch pending tasks whose next_send_at <= NOW(), ordered ASC.
+     *   跳过租约还没到期的行（`lease_until` 为空或已过期才算待发）。
+     */
+    getPendingTasks: (limit?: number) => Promise<TaskRow[]>;
+    /**
+     * 领取一条到点的任务，返回是否领到。cron 每分钟一跳而一次投递可能跑几分
+     * 钟，runScheduledTick 靠它保证同一行同时只被一个 tick 跑。
+     * 三个条件同时成立才领得走：行仍是 pending；`lease_until` 为空或已过期
+     * （没别人正在跑）；`next_send_at` 还等于 `expectedNextSendAt`（读这行时
+     * 拿到的值，用户中途改了排期就不发了）。领到就把 `lease_until` 写成
+     * `leaseUntil`，`next_send_at` 不动。
+     * 自定义适配器可以不实现（runScheduledTick 会退回不占位的行为，代价是慢
+     * 任务可能被下一跳重复触发）。
+     */
+    claimTask?: (taskId: number, expectedNextSendAt: string | Date, leaseUntil: string | Date) => Promise<boolean>;
+    /**
+     *   List tasks for a user with optional filters and pagination.
+     */
+    listTasks: (userId: string, opts: {
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }) => Promise<{
+        tasks: TaskRow[];
+        total: number;
+    }>;
+    /**
+     *   Delete completed / failed tasks older than `days` (default 7).
+     */
+    cleanupOldTasks: (days?: number) => Promise<number>;
+    /**
+     *   Return the status string of a task (used to distinguish 404 from 409).
+     */
+    getTaskStatus: (uuid: string, userId: string) => Promise<string | null>;
+    /**
+     * (optional; single-user/D1 only) Batch upsert of client state, last-write-wins on updatedAt.
+     * `cleanups` 先于 upsert 在同一事务里删旧行，两种形态：带 `keyPrefix` 的按 key 前缀删（清理大值
+     * 旧写入留下的切片行，见 lib/state-chunks.js），带 `key` 的删这一个 key（删整条状态；前缀会连带
+     * 删掉同前缀的兄弟 key）。两种都只删 `updated_at <= updatedAt` 的行。自定义 adapter 忽略前缀形态
+     * 只损失存储卫生；忽略精确 key 形态则删不掉状态，`ctx.writeState()` 的删除会失效。
+     * `outcomes` 逐条报告 entries[i] 是否真的写入（缺席时调用方按物理行计数兜底）。
+     */
+    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[];
+    }>;
+    /**
+     * (optional; single-user/D1 only) All entries of one namespace; values still encrypted.
+     */
+    getClientState?: (userId: string, namespace: string) => Promise<Array<{
+        namespace: string;
+        key: string;
+        value: string;
+        updated_at: number;
+    }>>;
+    /**
+     * (optional; single-user/D1 only) Delete every entry of this user; returns rows deleted.
+     */
+    clearClientState?: (userId: string) => Promise<number>;
+};

package/dist/adapters/neon.d.ts

@@ -0,0 +1,75 @@
+export class NeonAdapter {
+    /** @param {string} connectionString */
+    constructor(connectionString: string);
+    /** @private */
+    private _connectionString;
+    /** @private */
+    private _sql;
+    /** @private */
+    private _getSql;
+    initSchema(): Promise<{
+        columnsCreated: number;
+        indexesCreated: number;
+        indexesFailed: number;
+        columns: {
+            table: string;
+            name: any;
+            type: any;
+            nullable: boolean;
+        }[];
+        indexes: ({
+            name: string;
+            status: string;
+            description: string;
+            critical: boolean;
+            error?: undefined;
+        } | {
+            name: string;
+            status: string;
+            description: string;
+            critical: boolean;
+            error: any;
+        })[];
+    }>;
+    dropSchema(): Promise<void>;
+    createTask(params: any): Promise<Record<string, any>>;
+    getTaskByUuid(uuid: any, userId: any): Promise<Record<string, any>>;
+    getTaskByUuidOnly(uuid: any): Promise<Record<string, any>>;
+    updateTaskById(taskId: any, updates: any): Promise<Record<string, any>>;
+    updateTaskByUuid(uuid: any, userId: any, encryptedPayload: any, extraFields: any): Promise<Record<string, any>>;
+    deleteTaskById(taskId: any): Promise<boolean>;
+    deleteTaskByUuid(uuid: any, userId: any): Promise<boolean>;
+    getPendingTasks(limit?: number): Promise<Record<string, any>[]>;
+    /**
+     * 领取一条到点的任务：在 lease_until 上写下「这条归我管到什么时候」，
+     * 本次投递期间别的 tick 领不走它。
+     *
+     * 租约写在自己的列上，next_send_at 全程不动——那一列是用户设的触发时刻，
+     * 任务列表要读它、循环任务推进下一次也要拿它当基准。
+     *
+     * 两个 tick 抢同一行时只有一个改得动，另一个拿不到 RETURNING 行，据此跳
+     * 过。WHERE 里的两个条件各管一件事：
+     *   - lease_until 为空或已过期：没人正在跑这条。领了任务的 tick 中途没了
+     *     也不会把行焊死，租约到期后自然可以被接手。
+     *   - next_send_at 等于读这行时看到的值：读出来之后用户又改了排期的话，
+     *     这一跳就不该再按旧时刻发。
+     *
+     * 不加一个 'sending' 状态来表达「正在跑」：status 上有 CHECK 约束，加值
+     * 要改表。
+     *
+     * 比 next_send_at 时两边都截到毫秒：列是 timestamptz（微秒精度），驱动读
+     * 出来是 JS Date（毫秒精度），原值送回去可能因为亚毫秒差对不上。
+     *
+     * @param {number} taskId
+     * @param {string|Date} expectedNextSendAt - 读这行时拿到的 next_send_at 原值
+     * @param {string|Date} leaseUntil - 租期末尾
+     * @returns {Promise<boolean>} true = 领到了；false = 别人正拿着租约、排期被改过、或行已不是 pending
+     */
+    claimTask(taskId: number, expectedNextSendAt: string | Date, leaseUntil: string | Date): Promise<boolean>;
+    listTasks(userId: any, opts?: {}): Promise<{
+        tasks: Record<string, any>[];
+        total: number;
+    }>;
+    cleanupOldTasks(days?: number): Promise<number>;
+    getTaskStatus(uuid: any, userId: any): Promise<any>;
+}

package/dist/adapters/pg.d.ts

@@ -0,0 +1,77 @@
+export class PgAdapter {
+    /** @param {string} connectionString */
+    constructor(connectionString: string);
+    /** @private */
+    private _connectionString;
+    /** @private */
+    private _pool;
+    /** @private */
+    private _getPool;
+    /** @private */
+    private _query;
+    initSchema(): Promise<{
+        columnsCreated: number;
+        indexesCreated: number;
+        indexesFailed: number;
+        columns: {
+            table: string;
+            name: any;
+            type: any;
+            nullable: boolean;
+        }[];
+        indexes: ({
+            name: string;
+            status: string;
+            description: string;
+            critical: boolean;
+            error?: undefined;
+        } | {
+            name: string;
+            status: string;
+            description: string;
+            critical: boolean;
+            error: any;
+        })[];
+    }>;
+    dropSchema(): Promise<void>;
+    createTask(params: any): Promise<any[]>;
+    getTaskByUuid(uuid: any, userId: any): Promise<any[]>;
+    getTaskByUuidOnly(uuid: any): Promise<any[]>;
+    updateTaskById(taskId: any, updates: any): Promise<any[]>;
+    updateTaskByUuid(uuid: any, userId: any, encryptedPayload: any, extraFields: any): Promise<any[]>;
+    deleteTaskById(taskId: any): Promise<boolean>;
+    deleteTaskByUuid(uuid: any, userId: any): Promise<boolean>;
+    getPendingTasks(limit?: number): Promise<any[][]>;
+    /**
+     * 领取一条到点的任务：在 lease_until 上写下「这条归我管到什么时候」，
+     * 本次投递期间别的 tick 领不走它。
+     *
+     * 租约写在自己的列上，next_send_at 全程不动——那一列是用户设的触发时刻，
+     * 任务列表要读它、循环任务推进下一次也要拿它当基准。
+     *
+     * 两个 tick 抢同一行时只有一个改得动，另一个拿不到 RETURNING 行，据此跳
+     * 过。WHERE 里的两个条件各管一件事：
+     *   - lease_until 为空或已过期：没人正在跑这条。领了任务的 tick 中途没了
+     *     也不会把行焊死，租约到期后自然可以被接手。
+     *   - next_send_at 等于读这行时看到的值：读出来之后用户又改了排期的话，
+     *     这一跳就不该再按旧时刻发。
+     *
+     * 不加一个 'sending' 状态来表达「正在跑」：status 上有 CHECK 约束，加值
+     * 要改表。
+     *
+     * 比 next_send_at 时两边都截到毫秒：列是 timestamptz（微秒精度），驱动读
+     * 出来是 JS Date（毫秒精度），原值送回去可能因为亚毫秒差对不上。
+     *
+     * @param {number} taskId
+     * @param {string|Date} expectedNextSendAt - 读这行时拿到的 next_send_at 原值
+     * @param {string|Date} leaseUntil - 租期末尾
+     * @returns {Promise<boolean>} true = 领到了；false = 已被别人领走或行已不是 pending
+     */
+    claimTask(taskId: number, expectedNextSendAt: string | Date, leaseUntil: string | Date): Promise<boolean>;
+    listTasks(userId: any, opts?: {}): Promise<{
+        tasks: any[][];
+        total: number;
+    }>;
+    cleanupOldTasks(days?: number): Promise<number>;
+    getTaskStatus(uuid: any, userId: any): Promise<any>;
+}

package/dist/adapters/schema.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared SQL schema constants
+ */
+export const TABLE_SQL: "\n  CREATE TABLE IF NOT EXISTS scheduled_messages (\n    id SERIAL PRIMARY KEY,\n    user_id VARCHAR(255) NOT NULL,\n    uuid VARCHAR(36),\n    encrypted_payload TEXT NOT NULL,\n    message_type VARCHAR(50) NOT NULL CHECK (message_type IN ('fixed', 'prompted', 'auto', 'instant')),\n    next_send_at TIMESTAMP WITH TIME ZONE NOT NULL,\n    lease_until TIMESTAMP WITH TIME ZONE,\n    status VARCHAR(50) NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'sent', 'failed')),\n    retry_count INTEGER DEFAULT 0,\n    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),\n    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()\n  )\n";
+/**
+ * 建表语句用的是 CREATE TABLE IF NOT EXISTS，已经存在的表不会被改动，所以
+ * 后加的列要单独补。initSchema 每次都会跑一遍，Postgres 的 IF NOT EXISTS
+ * 让重复执行也没事。
+ */
+export const MIGRATIONS: {
+    name: string;
+    sql: string;
+    description: string;
+}[];
+export const INDEXES: ({
+    name: string;
+    sql: string;
+    description: string;
+    critical?: undefined;
+} | {
+    name: string;
+    sql: string;
+    description: string;
+    critical: boolean;
+})[];
+export const VERIFY_TABLE_SQL: "\n  SELECT table_name\n  FROM information_schema.tables\n  WHERE table_schema = 'public'\n    AND table_name = 'scheduled_messages'\n";
+export const COLUMNS_SQL: "\n  SELECT column_name, data_type, is_nullable\n  FROM information_schema.columns\n  WHERE table_schema = 'public'\n    AND table_name = 'scheduled_messages'\n  ORDER BY ordinal_position\n";
+export const UPDATABLE_COLUMNS: Set<string>;