@rei-standard/amsg-shared 0.4.0-next.0 → 0.4.0-next.2

package/dist/llm-call.d.cts

@@ -0,0 +1,113 @@
+/**
+ * OpenAI-compatible LLM HTTP 调用核心 — 单一事实来源。
+ *
+ * `@rei-standard/amsg-instant`（message-processor 的 callLlmRaw）与
+ * `@rei-standard/amsg-server`（lib/llm.js 的 callLlm）此前各写一份
+ * 「构造请求体 + fetch + 超时 + 解析响应 + trim」，并已出现漂移
+ * （stream 字段、messages 模式探测、超时可配性）。现在公共核心收敛到
+ * 这里，两侧差异通过 options 参数化，各包保留自己的导出名与错误码
+ * 包装：
+ *
+ *   - `stream`       — instant 传 `false`（一次性、非流式契约，字段显式
+ *                      出现在请求体里）；server 不传（字段缺省，行为与
+ *                      之前逐字节一致）。
+ *   - `forwardTools` — server 转发 payload.tools / payload.toolChoice
+ *                      （v2.6.0 起）；instant 传 `false` 维持既有
+ *                      「忽略 tools」行为。
+ *   - `timeoutMs`    — server 的 agentic 循环传剩余墙钟预算；instant 传
+ *                      300000 维持现状。默认 300000。
+ *
+ * messages 模式探测统一为 `Array.isArray(payload.messages) &&
+ * payload.messages.length > 0`（server 语义）：`messages: []` 回退
+ * completePrompt 模式，而不是把空数组原样发给上游。
+ */
+/**
+ * Call an OpenAI-compatible API.
+ *
+ * Returns the full response object alongside the extracted (trimmed)
+ * `content` string. Callers that only need the text can ignore
+ * `response`; callers that want `reasoning_content` / `tool_calls`
+ * read from `response.choices[0].message`.
+ *
+ * @param {Object} payload
+ * @param {{
+ *   requireContent?: boolean,
+ *   timeoutMs?: number,
+ *   fetch?: typeof globalThis.fetch,
+ *   stream?: boolean,
+ *   forwardTools?: boolean,
+ * }} [options]
+ *   requireContent defaults to true (legacy single-shot behavior:
+ *   throw when the response carries no content). Tool rounds legitimately
+ *   return no content (pure tool_calls), so agentic loops pass
+ *   `{ requireContent: false }`.
+ *   timeoutMs defaults to 300000 (the legacy per-call ceiling).
+ *   fetch defaults to `globalThis.fetch` (resolved at call time so test
+ *   stubs on the global still take effect).
+ *   stream / forwardTools are forwarded to {@link buildLlmRequestBody}.
+ * @returns {Promise<{ response: unknown, content: string }>}
+ */
+export function callLlm(payload: any, options?: {
+    requireContent?: boolean;
+    timeoutMs?: number;
+    fetch?: typeof globalThis.fetch;
+    stream?: boolean;
+    forwardTools?: boolean;
+}): Promise<{
+    response: unknown;
+    content: string;
+}>;
+/**
+ * Build OpenAI-compatible request body.
+ *
+ * messages mode: forward the caller's OpenAI-style array verbatim — no
+ * auto role injection, no concatenation back to a single user message.
+ * Lets the upstream app preserve system / multi-turn context
+ * byte-for-byte. A missing / empty `payload.messages` falls back to
+ * wrapping `payload.completePrompt` into a single user message.
+ *
+ * `temperature`: only inject the 0.8 default for the legacy
+ * completePrompt path; messages mode forwards whatever the upstream app
+ * set (or nothing) so behavior matches their main chat path.
+ *
+ * `max_tokens` is optional:
+ * - include it only when payload.maxTokens is provided
+ * - omit it when payload.maxTokens is undefined / null
+ *
+ * `tools` / `tool_choice` are optional as well: forwarded only when
+ * `options.forwardTools` is not `false` and the caller passes a
+ * non-empty payload.tools. An empty array is treated as "no tools"
+ * because some OpenAI-compatible relays reject `tools: []`.
+ *
+ * @param {Object} payload
+ * @param {{ stream?: boolean, forwardTools?: boolean }} [options]
+ *   stream — set to include an explicit `stream` field in the body
+ *   (instant passes `false`: one-shot, non-streaming by contract);
+ *   omit to leave the field out entirely (server behavior).
+ * @returns {Object}
+ */
+export function buildLlmRequestBody(payload: any, options?: {
+    stream?: boolean;
+    forwardTools?: boolean;
+}): any;
+/**
+ * Normalize the AI API URL for OpenAI-compatible chat endpoints.
+ *
+ * Rules (idempotent — running it twice is the same as running it once):
+ *   - Already ends with `/chat/completions`           → leave as-is.
+ *   - Bare host (no path or just `/`)                  → append `/v1/chat/completions`.
+ *   - Path ends with a version segment like `/v1`,
+ *     `/v2`, … (with or without trailing slash)       → append only `/chat/completions`
+ *     (never doubles `/v1` for callers who already
+ *      include it).
+ *   - Anything else (custom path that doesn't match
+ *     the OpenAI shape, e.g. `/v1/messages` for
+ *     Anthropic-style proxies, or `/openai/api/foo`)   → leave as-is. We don't
+ *     guess — the caller knows their own routing.
+ *
+ * The query string is preserved verbatim.
+ *
+ * @param {string} apiUrl
+ * @returns {string}
+ */
+export function normalizeAiApiUrl(apiUrl: string): string;

package/dist/llm-call.d.ts

@@ -0,0 +1,113 @@
+/**
+ * OpenAI-compatible LLM HTTP 调用核心 — 单一事实来源。
+ *
+ * `@rei-standard/amsg-instant`（message-processor 的 callLlmRaw）与
+ * `@rei-standard/amsg-server`（lib/llm.js 的 callLlm）此前各写一份
+ * 「构造请求体 + fetch + 超时 + 解析响应 + trim」，并已出现漂移
+ * （stream 字段、messages 模式探测、超时可配性）。现在公共核心收敛到
+ * 这里，两侧差异通过 options 参数化，各包保留自己的导出名与错误码
+ * 包装：
+ *
+ *   - `stream`       — instant 传 `false`（一次性、非流式契约，字段显式
+ *                      出现在请求体里）；server 不传（字段缺省，行为与
+ *                      之前逐字节一致）。
+ *   - `forwardTools` — server 转发 payload.tools / payload.toolChoice
+ *                      （v2.6.0 起）；instant 传 `false` 维持既有
+ *                      「忽略 tools」行为。
+ *   - `timeoutMs`    — server 的 agentic 循环传剩余墙钟预算；instant 传
+ *                      300000 维持现状。默认 300000。
+ *
+ * messages 模式探测统一为 `Array.isArray(payload.messages) &&
+ * payload.messages.length > 0`（server 语义）：`messages: []` 回退
+ * completePrompt 模式，而不是把空数组原样发给上游。
+ */
+/**
+ * Call an OpenAI-compatible API.
+ *
+ * Returns the full response object alongside the extracted (trimmed)
+ * `content` string. Callers that only need the text can ignore
+ * `response`; callers that want `reasoning_content` / `tool_calls`
+ * read from `response.choices[0].message`.
+ *
+ * @param {Object} payload
+ * @param {{
+ *   requireContent?: boolean,
+ *   timeoutMs?: number,
+ *   fetch?: typeof globalThis.fetch,
+ *   stream?: boolean,
+ *   forwardTools?: boolean,
+ * }} [options]
+ *   requireContent defaults to true (legacy single-shot behavior:
+ *   throw when the response carries no content). Tool rounds legitimately
+ *   return no content (pure tool_calls), so agentic loops pass
+ *   `{ requireContent: false }`.
+ *   timeoutMs defaults to 300000 (the legacy per-call ceiling).
+ *   fetch defaults to `globalThis.fetch` (resolved at call time so test
+ *   stubs on the global still take effect).
+ *   stream / forwardTools are forwarded to {@link buildLlmRequestBody}.
+ * @returns {Promise<{ response: unknown, content: string }>}
+ */
+export function callLlm(payload: any, options?: {
+    requireContent?: boolean;
+    timeoutMs?: number;
+    fetch?: typeof globalThis.fetch;
+    stream?: boolean;
+    forwardTools?: boolean;
+}): Promise<{
+    response: unknown;
+    content: string;
+}>;
+/**
+ * Build OpenAI-compatible request body.
+ *
+ * messages mode: forward the caller's OpenAI-style array verbatim — no
+ * auto role injection, no concatenation back to a single user message.
+ * Lets the upstream app preserve system / multi-turn context
+ * byte-for-byte. A missing / empty `payload.messages` falls back to
+ * wrapping `payload.completePrompt` into a single user message.
+ *
+ * `temperature`: only inject the 0.8 default for the legacy
+ * completePrompt path; messages mode forwards whatever the upstream app
+ * set (or nothing) so behavior matches their main chat path.
+ *
+ * `max_tokens` is optional:
+ * - include it only when payload.maxTokens is provided
+ * - omit it when payload.maxTokens is undefined / null
+ *
+ * `tools` / `tool_choice` are optional as well: forwarded only when
+ * `options.forwardTools` is not `false` and the caller passes a
+ * non-empty payload.tools. An empty array is treated as "no tools"
+ * because some OpenAI-compatible relays reject `tools: []`.
+ *
+ * @param {Object} payload
+ * @param {{ stream?: boolean, forwardTools?: boolean }} [options]
+ *   stream — set to include an explicit `stream` field in the body
+ *   (instant passes `false`: one-shot, non-streaming by contract);
+ *   omit to leave the field out entirely (server behavior).
+ * @returns {Object}
+ */
+export function buildLlmRequestBody(payload: any, options?: {
+    stream?: boolean;
+    forwardTools?: boolean;
+}): any;
+/**
+ * Normalize the AI API URL for OpenAI-compatible chat endpoints.
+ *
+ * Rules (idempotent — running it twice is the same as running it once):
+ *   - Already ends with `/chat/completions`           → leave as-is.
+ *   - Bare host (no path or just `/`)                  → append `/v1/chat/completions`.
+ *   - Path ends with a version segment like `/v1`,
+ *     `/v2`, … (with or without trailing slash)       → append only `/chat/completions`
+ *     (never doubles `/v1` for callers who already
+ *      include it).
+ *   - Anything else (custom path that doesn't match
+ *     the OpenAI shape, e.g. `/v1/messages` for
+ *     Anthropic-style proxies, or `/openai/api/foo`)   → leave as-is. We don't
+ *     guess — the caller knows their own routing.
+ *
+ * The query string is preserved verbatim.
+ *
+ * @param {string} apiUrl
+ * @returns {string}
+ */
+export function normalizeAiApiUrl(apiUrl: string): string;

package/dist/llm-messages.d.cts

@@ -0,0 +1,66 @@
+/**
+ * @typedef {Object} LlmMessagesShapeError
+ * @property {LlmMessagesErrorCode} code
+ * @property {number} [index]         - 出错的 messages 下标（数组级错误时缺省）。
+ * @property {number} [toolCallIndex] - 出错的 tool_calls 下标（仅 TOOL_CALL_MALFORMED）。
+ */
+/**
+ * Validate an OpenAI-style messages array. Pure（无副作用）。
+ *
+ * 接受的形状（与 OpenAI chat.completions 协议对齐）：
+ *   - system / user / assistant: content 为非空字符串或长度 ≥ 1 的数组
+ *     （数组元素 schema 故意不校验 — 原样透传给上游 LLM）。
+ *   - assistant 带非空 `tool_calls`: content 可为 null / 空串 / 缺省；
+ *     每个 tool_call 需满足 `{ id: string, function }` 的轻量形状
+ *     （不严 — 上游 LLM API 会再校一遍）。
+ *   - tool: content 允许空串（工具返回空结果合法，如 search 无命中），
+ *     但必须是字符串或数组；`tool_call_id` 必填（OpenAI 协议硬约束）。
+ *
+ * @param {unknown} messages
+ * @returns {LlmMessagesShapeError | null}   Structured error, or null if valid.
+ */
+export function validateLlmMessagesShape(messages: unknown): LlmMessagesShapeError | null;
+/**
+ * {@link validateLlmMessagesShape} 可能返回的稳定错误码。枚举固定 —
+ * 新增校验分支时必须新增 code，各消费包据此穷举映射错误文案。
+ *
+ * @typedef {'MESSAGES_NOT_ARRAY'
+ *   | 'MESSAGE_NOT_OBJECT'
+ *   | 'INVALID_ROLE'
+ *   | 'TOOL_CALL_MALFORMED'
+ *   | 'TOOL_CONTENT_INVALID'
+ *   | 'TOOL_CALL_ID_MISSING'
+ *   | 'CONTENT_EMPTY_STRING'
+ *   | 'CONTENT_EMPTY_ARRAY'
+ *   | 'CONTENT_INVALID_TYPE'} LlmMessagesErrorCode
+ */
+/**
+ * Runtime constant mirroring the {@link LlmMessagesErrorCode} type.
+ */
+export const LLM_MESSAGES_ERROR: Readonly<{
+    MESSAGES_NOT_ARRAY: "MESSAGES_NOT_ARRAY";
+    MESSAGE_NOT_OBJECT: "MESSAGE_NOT_OBJECT";
+    INVALID_ROLE: "INVALID_ROLE";
+    TOOL_CALL_MALFORMED: "TOOL_CALL_MALFORMED";
+    TOOL_CONTENT_INVALID: "TOOL_CONTENT_INVALID";
+    TOOL_CALL_ID_MISSING: "TOOL_CALL_ID_MISSING";
+    CONTENT_EMPTY_STRING: "CONTENT_EMPTY_STRING";
+    CONTENT_EMPTY_ARRAY: "CONTENT_EMPTY_ARRAY";
+    CONTENT_INVALID_TYPE: "CONTENT_INVALID_TYPE";
+}>;
+export type LlmMessagesShapeError = {
+    code: LlmMessagesErrorCode;
+    /**
+     * - 出错的 messages 下标（数组级错误时缺省）。
+     */
+    index?: number;
+    /**
+     * - 出错的 tool_calls 下标（仅 TOOL_CALL_MALFORMED）。
+     */
+    toolCallIndex?: number;
+};
+/**
+ * {@link validateLlmMessagesShape} 可能返回的稳定错误码。枚举固定 —
+ * 新增校验分支时必须新增 code，各消费包据此穷举映射错误文案。
+ */
+export type LlmMessagesErrorCode = "MESSAGES_NOT_ARRAY" | "MESSAGE_NOT_OBJECT" | "INVALID_ROLE" | "TOOL_CALL_MALFORMED" | "TOOL_CONTENT_INVALID" | "TOOL_CALL_ID_MISSING" | "CONTENT_EMPTY_STRING" | "CONTENT_EMPTY_ARRAY" | "CONTENT_INVALID_TYPE";

package/dist/llm-messages.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @typedef {Object} LlmMessagesShapeError
+ * @property {LlmMessagesErrorCode} code
+ * @property {number} [index]         - 出错的 messages 下标（数组级错误时缺省）。
+ * @property {number} [toolCallIndex] - 出错的 tool_calls 下标（仅 TOOL_CALL_MALFORMED）。
+ */
+/**
+ * Validate an OpenAI-style messages array. Pure（无副作用）。
+ *
+ * 接受的形状（与 OpenAI chat.completions 协议对齐）：
+ *   - system / user / assistant: content 为非空字符串或长度 ≥ 1 的数组
+ *     （数组元素 schema 故意不校验 — 原样透传给上游 LLM）。
+ *   - assistant 带非空 `tool_calls`: content 可为 null / 空串 / 缺省；
+ *     每个 tool_call 需满足 `{ id: string, function }` 的轻量形状
+ *     （不严 — 上游 LLM API 会再校一遍）。
+ *   - tool: content 允许空串（工具返回空结果合法，如 search 无命中），
+ *     但必须是字符串或数组；`tool_call_id` 必填（OpenAI 协议硬约束）。
+ *
+ * @param {unknown} messages
+ * @returns {LlmMessagesShapeError | null}   Structured error, or null if valid.
+ */
+export function validateLlmMessagesShape(messages: unknown): LlmMessagesShapeError | null;
+/**
+ * {@link validateLlmMessagesShape} 可能返回的稳定错误码。枚举固定 —
+ * 新增校验分支时必须新增 code，各消费包据此穷举映射错误文案。
+ *
+ * @typedef {'MESSAGES_NOT_ARRAY'
+ *   | 'MESSAGE_NOT_OBJECT'
+ *   | 'INVALID_ROLE'
+ *   | 'TOOL_CALL_MALFORMED'
+ *   | 'TOOL_CONTENT_INVALID'
+ *   | 'TOOL_CALL_ID_MISSING'
+ *   | 'CONTENT_EMPTY_STRING'
+ *   | 'CONTENT_EMPTY_ARRAY'
+ *   | 'CONTENT_INVALID_TYPE'} LlmMessagesErrorCode
+ */
+/**
+ * Runtime constant mirroring the {@link LlmMessagesErrorCode} type.
+ */
+export const LLM_MESSAGES_ERROR: Readonly<{
+    MESSAGES_NOT_ARRAY: "MESSAGES_NOT_ARRAY";
+    MESSAGE_NOT_OBJECT: "MESSAGE_NOT_OBJECT";
+    INVALID_ROLE: "INVALID_ROLE";
+    TOOL_CALL_MALFORMED: "TOOL_CALL_MALFORMED";
+    TOOL_CONTENT_INVALID: "TOOL_CONTENT_INVALID";
+    TOOL_CALL_ID_MISSING: "TOOL_CALL_ID_MISSING";
+    CONTENT_EMPTY_STRING: "CONTENT_EMPTY_STRING";
+    CONTENT_EMPTY_ARRAY: "CONTENT_EMPTY_ARRAY";
+    CONTENT_INVALID_TYPE: "CONTENT_INVALID_TYPE";
+}>;
+export type LlmMessagesShapeError = {
+    code: LlmMessagesErrorCode;
+    /**
+     * - 出错的 messages 下标（数组级错误时缺省）。
+     */
+    index?: number;
+    /**
+     * - 出错的 tool_calls 下标（仅 TOOL_CALL_MALFORMED）。
+     */
+    toolCallIndex?: number;
+};
+/**
+ * {@link validateLlmMessagesShape} 可能返回的稳定错误码。枚举固定 —
+ * 新增校验分支时必须新增 code，各消费包据此穷举映射错误文案。
+ */
+export type LlmMessagesErrorCode = "MESSAGES_NOT_ARRAY" | "MESSAGE_NOT_OBJECT" | "INVALID_ROLE" | "TOOL_CALL_MALFORMED" | "TOOL_CONTENT_INVALID" | "TOOL_CALL_ID_MISSING" | "CONTENT_EMPTY_STRING" | "CONTENT_EMPTY_ARRAY" | "CONTENT_INVALID_TYPE";

package/dist/protocol.d.cts

@@ -0,0 +1,57 @@
+/**
+ * Wire-protocol constants — the strings both ends of a transport must
+ * agree on, byte-for-byte.
+ *
+ * 这是全生态唯一一份线协议常量：multipart transport 的 kind / encoding /
+ * version 与默认限额（instant 发送端与 sw 重组端共用），以及 SW ↔ 页面
+ * postMessage 信封的 type / event 常量（sw 广播端与页面订阅端共用）。
+ * 页面侧代码请从本包 import 这些常量，而不要从 `@rei-standard/amsg-sw`
+ * import —— sw 包的模块顶层带有 SW 运行时状态，在窗口环境里执行并不合适。
+ * 实现在独立模块 — shared 内部按主题拆文件，index 只负责聚合导出。
+ */
+/** Transport-level `messageKind` carried by every multipart chunk. */
+export const MULTIPART_MESSAGE_KIND: "_multipart";
+/** Chunk body encoding: JSON → UTF-8 bytes → base64url. */
+export const MULTIPART_ENCODING: "json-utf8-base64url";
+/**
+ * Multipart wire-format version. Producers stamp `multipart.version`
+ * with this; the SW drops any chunk whose version doesn't match.
+ */
+export const MULTIPART_VERSION: 1;
+export const DEFAULT_MULTIPART_TTL_MS: 60000;
+export const DEFAULT_MULTIPART_MAX_CHUNKS: 128;
+export const DEFAULT_MULTIPART_MAX_TOTAL_BYTES: 256000;
+/**
+ * Wire-level message type for SW → client postMessage envelopes.
+ * Clients filter on `e.data.type === 'REI_AMSG_PUSH'` before reading
+ * `e.data.event` (which is one of {@link REI_SW_EVENT}'s values).
+ */
+export const REI_AMSG_POSTMESSAGE_TYPE: "REI_AMSG_PUSH";
+/**
+ * Per-kind event names dispatched to controlled clients. Each push the
+ * SW receives is mirrored to every window via
+ * `postMessage({ type: 'REI_AMSG_PUSH', event: <one of these>, payload })`.
+ *
+ * The mapping is keyed by `payload.messageKind`. Legacy payloads (and
+ * blob envelopes) without a `messageKind` field dispatch as
+ * {@link REI_SW_EVENT.UNKNOWN_RECEIVED} so apps can still handle 2.0.x
+ * producers during migration.
+ */
+export const REI_SW_EVENT: Readonly<{
+    CONTENT_RECEIVED: "rei-amsg-content-received";
+    REASONING_RECEIVED: "rei-amsg-reasoning-received";
+    TOOL_REQUEST_RECEIVED: "rei-amsg-tool-request-received";
+    ERROR_RECEIVED: "rei-amsg-error-received";
+    MULTIPART_EXPIRED: "rei-amsg-multipart-expired";
+    UNKNOWN_RECEIVED: "rei-amsg-unknown-received";
+}>;
+/**
+ * 页面 → SW 方向的 message type（离线队列与业务投递管线）。
+ */
+export const REI_SW_MESSAGE_TYPE: Readonly<{
+    ENQUEUE_REQUEST: "REI_ENQUEUE_REQUEST";
+    DELIVER: "REI_AMSG_DELIVER";
+    FLUSH_QUEUE: "REI_FLUSH_QUEUE";
+    QUEUE_RESULT: "REI_QUEUE_RESULT";
+}>;
+export const REI_AMSG_DELIVER_MESSAGE_TYPE: "REI_AMSG_DELIVER";

package/dist/protocol.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Wire-protocol constants — the strings both ends of a transport must
+ * agree on, byte-for-byte.
+ *
+ * 这是全生态唯一一份线协议常量：multipart transport 的 kind / encoding /
+ * version 与默认限额（instant 发送端与 sw 重组端共用），以及 SW ↔ 页面
+ * postMessage 信封的 type / event 常量（sw 广播端与页面订阅端共用）。
+ * 页面侧代码请从本包 import 这些常量，而不要从 `@rei-standard/amsg-sw`
+ * import —— sw 包的模块顶层带有 SW 运行时状态，在窗口环境里执行并不合适。
+ * 实现在独立模块 — shared 内部按主题拆文件，index 只负责聚合导出。
+ */
+/** Transport-level `messageKind` carried by every multipart chunk. */
+export const MULTIPART_MESSAGE_KIND: "_multipart";
+/** Chunk body encoding: JSON → UTF-8 bytes → base64url. */
+export const MULTIPART_ENCODING: "json-utf8-base64url";
+/**
+ * Multipart wire-format version. Producers stamp `multipart.version`
+ * with this; the SW drops any chunk whose version doesn't match.
+ */
+export const MULTIPART_VERSION: 1;
+export const DEFAULT_MULTIPART_TTL_MS: 60000;
+export const DEFAULT_MULTIPART_MAX_CHUNKS: 128;
+export const DEFAULT_MULTIPART_MAX_TOTAL_BYTES: 256000;
+/**
+ * Wire-level message type for SW → client postMessage envelopes.
+ * Clients filter on `e.data.type === 'REI_AMSG_PUSH'` before reading
+ * `e.data.event` (which is one of {@link REI_SW_EVENT}'s values).
+ */
+export const REI_AMSG_POSTMESSAGE_TYPE: "REI_AMSG_PUSH";
+/**
+ * Per-kind event names dispatched to controlled clients. Each push the
+ * SW receives is mirrored to every window via
+ * `postMessage({ type: 'REI_AMSG_PUSH', event: <one of these>, payload })`.
+ *
+ * The mapping is keyed by `payload.messageKind`. Legacy payloads (and
+ * blob envelopes) without a `messageKind` field dispatch as
+ * {@link REI_SW_EVENT.UNKNOWN_RECEIVED} so apps can still handle 2.0.x
+ * producers during migration.
+ */
+export const REI_SW_EVENT: Readonly<{
+    CONTENT_RECEIVED: "rei-amsg-content-received";
+    REASONING_RECEIVED: "rei-amsg-reasoning-received";
+    TOOL_REQUEST_RECEIVED: "rei-amsg-tool-request-received";
+    ERROR_RECEIVED: "rei-amsg-error-received";
+    MULTIPART_EXPIRED: "rei-amsg-multipart-expired";
+    UNKNOWN_RECEIVED: "rei-amsg-unknown-received";
+}>;
+/**
+ * 页面 → SW 方向的 message type（离线队列与业务投递管线）。
+ */
+export const REI_SW_MESSAGE_TYPE: Readonly<{
+    ENQUEUE_REQUEST: "REI_ENQUEUE_REQUEST";
+    DELIVER: "REI_AMSG_DELIVER";
+    FLUSH_QUEUE: "REI_FLUSH_QUEUE";
+    QUEUE_RESULT: "REI_QUEUE_RESULT";
+}>;
+export const REI_AMSG_DELIVER_MESSAGE_TYPE: "REI_AMSG_DELIVER";

package/dist/webcrypto-utils.d.cts

@@ -0,0 +1,42 @@
+/**
+ * Coerce ArrayBuffer | Uint8Array | view → Uint8Array (no copy when possible).
+ */
+export function toUint8(buf: any): Uint8Array<ArrayBufferLike>;
+/**
+ * Concatenate Uint8Arrays into a single Uint8Array.
+ * @param {...(Uint8Array | ArrayBuffer | ArrayBufferView)} chunks
+ * @returns {Uint8Array}
+ */
+export function concatBytes(...chunks: (Uint8Array | ArrayBuffer | ArrayBufferView)[]): Uint8Array;
+/** UTF-8 encode a string into a Uint8Array. */
+export function utf8(str: any): Uint8Array<ArrayBuffer>;
+/** UTF-8 decode a Uint8Array / ArrayBuffer into a string. */
+export function utf8Decode(buf: any): string;
+/** Encode bytes as standard base64 (with padding). */
+export function bytesToBase64(buf: any): string;
+/** Encode bytes as base64url (no padding). */
+export function bytesToBase64Url(buf: any): string;
+/**
+ * Decode base64url (with or without padding) → Uint8Array.
+ * @param {string} input
+ * @returns {Uint8Array}
+ */
+export function base64UrlToBytes(input: string): Uint8Array;
+/** Encode a JSON-serializable value as base64url (UTF-8 JSON). */
+export function jsonToBase64Url(value: any): string;
+/** Encode bytes as lowercase hex. */
+export function bytesToHex(buf: any): string;
+/** Decode a hex string into a Uint8Array. */
+export function hexToBytes(hex: any): Uint8Array<ArrayBuffer>;
+/** HMAC-SHA-256 over `data` with `keyBytes`. Returns 32-byte Uint8Array. */
+export function hmacSha256(keyBytes: any, data: any): Promise<Uint8Array<ArrayBuffer>>;
+/**
+ * Constant-time byte comparison. Returns true iff `a` and `b` are equal-length
+ * sequences with the same bytes. Length is intentionally NOT secret — early
+ * length-check is fine and matches Node `timingSafeEqual`'s contract.
+ */
+export function timingSafeEqualBytes(a: any, b: any): boolean;
+/** Cryptographically random bytes. */
+export function randomBytes(n: any): Uint8Array<any>;
+/** `crypto.randomUUID()`. The Node adapter polyfills `globalThis.crypto`. */
+export function randomUUID(): `${string}-${string}-${string}-${string}-${string}`;

package/dist/webcrypto-utils.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Coerce ArrayBuffer | Uint8Array | view → Uint8Array (no copy when possible).
+ */
+export function toUint8(buf: any): Uint8Array<ArrayBufferLike>;
+/**
+ * Concatenate Uint8Arrays into a single Uint8Array.
+ * @param {...(Uint8Array | ArrayBuffer | ArrayBufferView)} chunks
+ * @returns {Uint8Array}
+ */
+export function concatBytes(...chunks: (Uint8Array | ArrayBuffer | ArrayBufferView)[]): Uint8Array;
+/** UTF-8 encode a string into a Uint8Array. */
+export function utf8(str: any): Uint8Array<ArrayBuffer>;
+/** UTF-8 decode a Uint8Array / ArrayBuffer into a string. */
+export function utf8Decode(buf: any): string;
+/** Encode bytes as standard base64 (with padding). */
+export function bytesToBase64(buf: any): string;
+/** Encode bytes as base64url (no padding). */
+export function bytesToBase64Url(buf: any): string;
+/**
+ * Decode base64url (with or without padding) → Uint8Array.
+ * @param {string} input
+ * @returns {Uint8Array}
+ */
+export function base64UrlToBytes(input: string): Uint8Array;
+/** Encode a JSON-serializable value as base64url (UTF-8 JSON). */
+export function jsonToBase64Url(value: any): string;
+/** Encode bytes as lowercase hex. */
+export function bytesToHex(buf: any): string;
+/** Decode a hex string into a Uint8Array. */
+export function hexToBytes(hex: any): Uint8Array<ArrayBuffer>;
+/** HMAC-SHA-256 over `data` with `keyBytes`. Returns 32-byte Uint8Array. */
+export function hmacSha256(keyBytes: any, data: any): Promise<Uint8Array<ArrayBuffer>>;
+/**
+ * Constant-time byte comparison. Returns true iff `a` and `b` are equal-length
+ * sequences with the same bytes. Length is intentionally NOT secret — early
+ * length-check is fine and matches Node `timingSafeEqual`'s contract.
+ */
+export function timingSafeEqualBytes(a: any, b: any): boolean;
+/** Cryptographically random bytes. */
+export function randomBytes(n: any): Uint8Array<any>;
+/** `crypto.randomUUID()`. The Node adapter polyfills `globalThis.crypto`. */
+export function randomUUID(): `${string}-${string}-${string}-${string}-${string}`;

package/dist/webpush.d.cts

@@ -0,0 +1,69 @@
+/**
+ * Send a single Web Push notification.
+ *
+ * @param {Object}   args
+ * @param {Object}   args.subscription  - Standard PushSubscription JSON.
+ * @param {string}   args.subscription.endpoint
+ * @param {Object}   args.subscription.keys
+ * @param {string}   args.subscription.keys.p256dh - base64url, 65 B uncompressed P-256 point.
+ * @param {string}   args.subscription.keys.auth   - base64url, 16 B auth secret.
+ * @param {string}   args.payload       - Already-stringified JSON to deliver.
+ * @param {Object}   args.vapid
+ * @param {string}   args.vapid.email      - VAPID `sub` (mailto: auto-prepended if missing).
+ * @param {string}   args.vapid.publicKey  - base64url, 65 B uncompressed P-256 point.
+ * @param {string}   args.vapid.privateKey - base64url, 32 B scalar.
+ * @param {number}  [args.ttl=60]       - Push service TTL header, seconds.
+ * @param {typeof fetch} [args.fetch]   - Override fetch impl (testing / proxy).
+ * @returns {Promise<{ statusCode: number, body: string, headers: Headers }>}
+ * @throws  {Error}  err.code = 'PUSH_SEND_FAILED' on push-service error.
+ */
+export function sendWebPush({ subscription, payload, vapid, ttl, fetch: fetchImpl }: {
+    subscription: {
+        endpoint: string;
+        keys: {
+            p256dh: string;
+            auth: string;
+        };
+    };
+    payload: string;
+    vapid: {
+        email: string;
+        publicKey: string;
+        privateKey: string;
+    };
+    ttl?: number;
+    fetch?: typeof fetch;
+}): Promise<{
+    statusCode: number;
+    body: string;
+    headers: Headers;
+}>;
+/**
+ * Build a VAPID `Authorization` JWT for a single push.
+ *
+ * @param {Object} args
+ * @param {string} args.audience    - Origin of the push endpoint (e.g. https://fcm.googleapis.com).
+ * @param {string} args.subject     - VAPID `sub` claim, typically `mailto:you@example.com`.
+ * @param {string} args.publicKey   - base64url, 65 B uncompressed P-256 point.
+ * @param {string} args.privateKey  - base64url, 32 B scalar.
+ * @returns {Promise<string>} compact JWS (three base64url segments).
+ */
+export function buildVapidJwt({ audience, subject, publicKey, privateKey }: {
+    audience: string;
+    subject: string;
+    publicKey: string;
+    privateKey: string;
+}): Promise<string>;
+/**
+ * Verify a VAPID JWT signature. Exported for tests / advanced consumers.
+ * Returns the decoded payload if the signature and `exp` are valid.
+ *
+ * @param {string} jwt
+ * @param {string} publicKey  - VAPID public key (base64url, 65 B).
+ * @returns {Promise<{ aud: string, exp: number, sub: string }>}
+ */
+export function verifyVapidJwt(jwt: string, publicKey: string): Promise<{
+    aud: string;
+    exp: number;
+    sub: string;
+}>;