@rei-standard/amsg-server 2.6.0-next.9 → 3.0.0

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

@@ -0,0 +1,121 @@
+/**
+ * 把宿主给的分组 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[];
+        deferredTasks: any[];
+        cancelledTasks: any[];
+        reasoningSkippedTasks: any[];
+        redeliveredTasks: 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`：上次投递失败还在退避窗口里，或者上次 onBeforeFire 把
+ *     它推迟了（`{ defer }`）还没到点（`retryAfter` 带上什么时候到点）。
+ *
+ * 这一次跑的时候 onBeforeFire 返回 `{ defer }` 的话，结果是 `ran: true`，任务
+ * 列在 summary.details.deferredTasks 里；到点之前再调都回 `retry_pending`。
+ *
+ * @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 { DEFAULT_MAX_DELIVERY_RETRIES } from "./retry-policy.js";
+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-cloud-data.2";
+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,65 @@
+/** 某个用户 namespace 的切片行所在的保留 namespace。 */
+export function chunkNamespaceFor(namespace: any): string;
+/** 这个 namespace 是不是库内部的切片保留 namespace。 */
+export function isChunkNamespace(namespace: any): boolean;
+/** 第 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;
+/**
+ * 切片行所在保留 namespace 的固定前缀（`\u001famsg-chunks\u001f`）。
+ *
+ * 露出来是给「按前缀折算统计」那类调用方用的（见 handlers/client-state-namespaces.js）：
+ * 保留 namespace 对宿主是不存在的东西，统计要把它折回原 namespace。适配器不
+ * import 这一份——分块是 lib 层的事，前缀由调用方传下去。
+ */
+export const CHUNK_NAMESPACE_PREFIX: "\u001Famsg-chunks\u001F";

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;
+};

package/dist/lib/validation.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Validate ISO 8601 date string.
+ * @param {string} dateString
+ * @returns {boolean}
+ */
+export function isValidISO8601(dateString: string): boolean;
+/**
+ * Validate UUID format.
+ * @param {string} uuid
+ * @returns {boolean}
+ */
+export function isValidUUID(uuid: string): boolean;
+/**
+ * Validate UUID v4 format.
+ * @param {string} uuid
+ * @returns {boolean}
+ */
+export function isValidUUIDv4(uuid: string): boolean;
+/**
+ * Validate the optional `splitPattern` field (amsg-server scheduled tasks
+ * only; amsg-instant 0.8.0 dropped its request-level `splitPattern`).
+ * Accepts `string`, `string[]`, or absent/null. Returns an error message
+ * string, or null when valid.
+ *
+ * Limits (per-item length ≤ 200, array ≤ 10 items, must compile via
+ * `new RegExp(item)`) are an **input-size guard**, NOT a ReDoS defense —
+ * a 6-character pattern like `(a+)+$` is enough to trigger catastrophic
+ * backtracking. The real backstop is Worker / runtime CPU limits + the
+ * fact that splitPattern is stored under the user's own encrypted task
+ * and matched against output from the user's own LLM API key, so the
+ * blast radius is self-inflicted only (no cross-tenant attack surface).
+ *
+ * @param {unknown} value
+ * @returns {string | null}
+ */
+export function validateSplitPattern(value: unknown): string | null;
+/**
+ * Validate an OpenAI-style messages array. 形状规则统一在
+ * `@rei-standard/amsg-shared` 的 `validateLlmMessagesShape`（amsg-instant
+ * 的 `validateMessagesArray` 走同一实现，两包接受的形状不会漂移）——
+ * 因此 agentic 会话回放（assistant 带 `tool_calls` 时 content 可空、
+ * `role:'tool'` 消息要求 `tool_call_id`）在这里同样合法。本函数只把
+ * 结构化错误码映射成本包既有的英文错误文案，返回形状不变。
+ *
+ * @param {unknown} messages
+ * @returns {string | null}   Error message, or null if valid.
+ */
+export function validateLlmMessagesArray(messages: unknown): string | null;
+/**
+ * 落库前量一次任务正文。合法返回 null，超限返回可以直接放进 400 响应体的
+ * error 对象——`POST /schedule-message` 与 `PUT /update-message` 共用同一个错
+ * 误码和同一套 details，下游判断读 `details.bytes` / `details.maxBytes`，不用
+ * 去解析那句人话。
+ *
+ * 按 UTF-8 字节算而不是字符数：D1 限的是字节，加密前也是先转 UTF-8，一段全中
+ * 文的正文字符数只有字节数的三分之一，用 `.length` 量等于把上限放大三倍。
+ *
+ * @param {string} serializedPayload - 将要交给 encryptForStorage 的那个字符串。
+ * @returns {{ code: string, message: string, details: { bytes: number, maxBytes: number } } | null}
+ */
+export function validateTaskPayloadSize(serializedPayload: string): {
+    code: string;
+    message: string;
+    details: {
+        bytes: number;
+        maxBytes: number;
+    };
+} | null;
+/**
+ * 任务正文的 UTF-8 字节数（与 {@link validateTaskPayloadSize} 同一把尺子）。
+ *
+ * `PUT /update-message` 拿它跟改动前的正文比大小：上限是后加的，比它更早建出来
+ * 的大任务不该因此连排期都改不了，只要这次改动没把它变得更大就放行。
+ *
+ * @param {string} serializedPayload
+ * @returns {number}
+ */
+export function taskPayloadByteLength(serializedPayload: string): number;
+/**
+ * Validate the schedule-message request payload.
+ *
+ * @param {Object} payload
+ * @returns {{ valid: boolean, errorCode?: string, errorMessage?: string, details?: Object }}
+ */
+export function validateScheduleMessagePayload(payload: any): {
+    valid: boolean;
+    errorCode?: string;
+    errorMessage?: string;
+    details?: any;
+};
+/**
+ * 一条任务正文（`JSON.stringify` 的结果）的明文上限，UTF-8 字节数。
+ * 客户端想在提交前自己预算就读这个数（从 `@rei-standard/amsg-server` 导出）。
+ */
+export const MAX_TASK_PAYLOAD_BYTES: number;
+import { isValidTimeZoneId } from './recurrence.js';
+export { isValidTimeZoneId, isValidUrl, validateAvatarUrl };

package/dist/lib/version.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 构建期注入的包版本。tsup 用 define 把 __AMSG_SERVER_VERSION__ 替换成
+ * package.json 的 version（见 tsup.config.js），发布产物里是真实版本号；
+ * 直接跑 src（node --test / 本地调试）没有这个替换，typeof 守卫落到
+ * '0.0.0-dev'。
+ */
+export const SERVER_VERSION: any;

package/dist/lib/webcrypto-utils.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/webpush-webcrypto.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 组 payload 前做预算用：先量骨架有多大，剩下多少字节才是能塞附加数据的额度。
+ *
+ * @example
+ * // hook 里组 push：把库要补的信封字段先扣掉
+ * const { remainingBytes } = measurePushPayload(
+ *   JSON.stringify({ ...basePush, message: '' }),
+ *   { reserveEnvelope: true }
+ * );
+ * const excerpt = remainingBytes > 0 ? text.slice(0, remainingBytes) : '';
+ *
+ * @param {string} payload - 待发送的 payload 字符串（通常是 JSON.stringify 的结果）。
+ * @param {{ reserveEnvelope?: boolean }} [options]
+ *   `reserveEnvelope: true` → 额度里扣掉 {@link PUSH_ENVELOPE_RESERVED_BYTES}，
+ *   也就是「库补完字段之后还装得下」的口径。fire-time hook 组 payload 时用这个。
+ *   默认 false = 量这个字符串本身对上限的占用。
+ * @returns {{ bytes: number, maxBytes: number, remainingBytes: number, withinLimit: boolean, envelopeReservedBytes: number }}
+ *   `bytes` 是 payload 的 UTF-8 字节数；`maxBytes` 是本次口径下的上限；
+ *   `remainingBytes` 是还能加多少字节（已超限时为负）；`withinLimit` 为 false
+ *   时（不留信封的口径下）sendWebPush 会抛 `PUSH_PAYLOAD_TOO_LARGE`。
+ */
+export function measurePushPayload(payload: string, options?: {
+    reserveEnvelope?: boolean;
+}): {
+    bytes: number;
+    maxBytes: number;
+    remainingBytes: number;
+    withinLimit: boolean;
+    envelopeReservedBytes: number;
+};
+/**
+ * Send a single Web Push notification. 委托 shared 的 `sendWebPush`（参数、
+ * 返回值与之完全一致），只在加密前多做一步 payload 大小护栏——超限的
+ * payload 发出去只会被推送服务 413 掉，用户什么也收不到。加密之前就拦下
+ * 来，让调用方拿到一个说得清的错误（宿主可以退回一条短消息 + 引用键）。
+ *
+ * @param {Object} args - 同 shared `sendWebPush`：{ subscription, payload, vapid, ttl, fetch }。
+ * @returns {Promise<{ statusCode: number, body: string, headers: Headers }>}
+ * @throws  {Error}  err.code = 'PUSH_PAYLOAD_TOO_LARGE' when the payload
+ *                   exceeds MAX_PUSH_PAYLOAD_BYTES (nothing is sent);
+ *                   err.code = 'PUSH_SEND_FAILED' on push-service error.
+ */
+export function sendWebPush(args: any): Promise<{
+    statusCode: number;
+    body: string;
+    headers: Headers;
+}>;
+/**
+ * web-push-compatible sender backed by the shared Web Crypto implementation.
+ * message-processor calls `ctx.webpush.sendNotification(subscription, payloadString)`,
+ * so we only need that one method. VAPID keys are baked in at construction.
+ *
+ * @param {{ email: string, publicKey: string, privateKey: string }} [vapid]
+ * @param {{ ttl?: number }} [options] - Push TTL in seconds; defaults to 4 weeks
+ *   (matches the web-push backend) so scheduled pushes outlive an offline device.
+ * @returns {{ sendNotification: (subscription: Object, payload: string) => Promise<any> }}
+ */
+export function createWebCryptoWebPush(vapid?: {
+    email: string;
+    publicKey: string;
+    privateKey: string;
+}, { ttl }?: {
+    ttl?: number;
+}): {
+    sendNotification: (subscription: any, payload: string) => Promise<any>;
+};
+/** 推送服务对加密后 body 的上限（字节）。 */
+export const WEB_PUSH_MAX_BODY_BYTES: 4096;
+/** aes128gcm 固定开销：header 86 + 填充分隔符 1 + GCM tag 16。 */
+export const WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES: number;
+/** 一条 push 的明文（JSON 字符串）上限，UTF-8 字节数。 */
+export const MAX_PUSH_PAYLOAD_BYTES: number;
+/**
+ * 库在 hook 交还 payload 之后还要补的那批字段占的字节数上界。
+ * 组 payload 时按 `MAX_PUSH_PAYLOAD_BYTES - PUSH_ENVELOPE_RESERVED_BYTES`
+ * 预算，或者直接用 `measurePushPayload(s, { reserveEnvelope: true })`。
+ */
+export const PUSH_ENVELOPE_RESERVED_BYTES: 384;