@rei-standard/amsg-client 2.2.1 → 2.3.0-next.0

package/README.md

@@ -2,6 +2,42 @@
 
 `@rei-standard/amsg-client` 是 ReiStandard 主动消息标准的浏览器端 SDK 包，负责加密请求、解密响应和 Push 订阅。
 
+## v2.3.0 — Shared push types
+
+The client now re-exports `@rei-standard/amsg-shared` 的类型、运行时常量（`MESSAGE_KIND` / `MESSAGE_TYPE` / `PUSH_SOURCE`）、推送 builder（`buildContentPush` 等）和类型守卫（`isContentPush` 等）。调用方可以直接 `import { MessageKind, buildContentPush, isContentPush } from '@rei-standard/amsg-client'`，无需单独再装一个 `@rei-standard/amsg-shared` 依赖。client 本身在运行时不消费这些导出 —— 它们是给同时调 `ReiClient` 又在 Service Worker / 客户端处理推送的 app 用的便利出口。
+
+```js
+// app.js — 用 ReiClient 发即时消息
+import { ReiClient } from '@rei-standard/amsg-client';
+
+const client = new ReiClient({
+  baseUrl: 'https://instant.example.com',
+  instantEncryption: false,
+});
+await client.sendInstant({
+  contactName: 'Rei',
+  completePrompt: '你是 Rei，用一句话提醒用户带伞',
+  apiUrl: 'https://api.openai.com/v1/chat/completions',
+  apiKey: '...',
+  primaryModel: 'gpt-4o-mini',
+  pushSubscription: subscription.toJSON(),
+});
+
+// service-worker.js — 用 isContentPush 在收到推送时收窄类型
+import { isContentPush } from '@rei-standard/amsg-client';
+
+self.addEventListener('push', (event) => {
+  const payload = event.data?.json();
+  if (isContentPush(payload)) {
+    // payload 已被收窄为 ContentPush —— 安全读取 payload.message
+    event.waitUntil(
+      self.registration.showNotification(payload.contactName ?? 'Rei', {
+        body: payload.message,
+      })
+    );
+  }
+});
+```
 
 ## 安装
 
@@ -116,6 +152,61 @@ await client.sendInstant({
 
 注意 `completePrompt` 和 `messages` **必须恰好二选一**——两者同时给会被 Worker / Server 端返回 `400 INVALID_PAYLOAD_FORMAT` / `INVALID_PARAMETERS`。`scheduleMessage` 也接受同样的 `messages` 字段（amsg-server 2.2.0+ 起持久化层一并支持），用法相同。
 
+### `splitPattern` 自定义分句正则（对接 amsg-instant 0.6.0+ / amsg-server 2.3.0+）
+
+LLM 返回的整段文本默认按 `/([。！？!?]+)/` 切成多条推送。要换成别的正则（按换行、按段落、自定义符号……）就在 payload 里加 `splitPattern`：
+
+```js
+// 单正则：按换行切
+await client.sendInstant({
+  contactName: 'Rei',
+  completePrompt: '...',
+  splitPattern: '([\\n]+)',
+  // 其余字段同上
+});
+
+// 数组级联：先按段落，每段再按句号
+await client.sendInstant({
+  contactName: 'Rei',
+  completePrompt: '...',
+  splitPattern: ['(\\n\\n+)', '([。！？!?]+)'],
+});
+```
+
+`splitPattern` 类型是 `string | string[]`。`scheduleMessage` 也支持，`updateMessage` 可显式传 `splitPattern: null` 重置回默认。client SDK 完全透传不校验，所有错误在 Worker / Server 端返回（每项 ≤ 200 字符、数组 ≤ 10 项、必须能 `new RegExp()` 通过）。
+
+**两个常见 footgun**：
+
+- 传**正则 source**，不要带 `/.../` 也不要尾 flag。`'/foo/i'` 会被当字面量斜杠 + 字面量 `i`，不是大小写不敏感的 `foo`。大小写不敏感请用 `[Aa]` 字符类替代。
+- 想让分隔符回贴到前一段（默认行为），把分隔符包进 `(...)` 捕获组。库**不会自动包**——传 `'\\n+'` 而不是 `'(\\n+)'` 会得到首尾相连、分隔符丢失的奇怪结果。
+
+### 本地预校验：`avatarUrl` 与 payload 体积（2.2.3+）
+
+`scheduleMessage` / `sendInstant` / `updateMessage` 在发请求**之前**会在本地做两项预检，避免一次远端往返才拿到 `413` 或 Web Push 4KB 上限报错：
+
+| 触发条件 | 抛出 `Error.code` | 触发原因（背景说明，不在 message 里） |
+| --- | --- | --- |
+| `payload.avatarUrl` 以 `data:` 开头（含 `data:image/...;base64,...`） | `INVALID_AVATAR_URL_LOCAL` | base64 内嵌头像把单个 push payload 撑到几十 KB，远端 Web Push 服务直接返回 4KB 超限 / 网关 `413`。 |
+| `payload.avatarUrl` 长度 > 2048 字符 | `INVALID_AVATAR_URL_LOCAL` | 同上。建议用 CDN 缩略图 URL。 |
+| `payload.avatarUrl` 不是字符串 | `INVALID_AVATAR_URL_LOCAL` | 类型错误。 |
+| `JSON.stringify(payload)` UTF-8 字节数 > 3072 | `PAYLOAD_TOO_LARGE_LOCAL` | 远端网关 / Web Push 4KB 硬上限的本地兜底。错误对象带 `.details = { method, actualBytes, limitBytes }` 方便定位。 |
+
+```js
+try {
+  await client.sendInstant(payload);
+} catch (err) {
+  if (err.code === 'INVALID_AVATAR_URL_LOCAL') {
+    // err.message 形如「头像不支持传入 data: URI，请改为公网可访问的 https:// 图片 URL」
+  } else if (err.code === 'PAYLOAD_TOO_LARGE_LOCAL') {
+    // err.details = { method: 'sendInstant', actualBytes: 8732, limitBytes: 3072 }
+  } else {
+    throw err;
+  }
+}
+```
+
+服务端（`@rei-standard/amsg-instant` 0.6.1+ / `@rei-standard/amsg-server` 2.3.1+）有等价的二道防线，业务可以放心依赖 client 这一道做 UX 提示。
+
 ## 导出 API（Exports）
 
 - `ReiClient`

package/dist/index.cjs

@@ -19,9 +19,29 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.js
 var src_exports = {};
 __export(src_exports, {
-  ReiClient: () => ReiClient
+  MESSAGE_KIND: () => import_amsg_shared.MESSAGE_KIND,
+  MESSAGE_TYPE: () => import_amsg_shared.MESSAGE_TYPE,
+  PUSH_SOURCE: () => import_amsg_shared.PUSH_SOURCE,
+  ReiClient: () => ReiClient,
+  buildContentPush: () => import_amsg_shared.buildContentPush,
+  buildErrorPush: () => import_amsg_shared.buildErrorPush,
+  buildReasoningPush: () => import_amsg_shared.buildReasoningPush,
+  buildToolRequestPush: () => import_amsg_shared.buildToolRequestPush,
+  isContentPush: () => import_amsg_shared.isContentPush,
+  isErrorPush: () => import_amsg_shared.isErrorPush,
+  isReasoningPush: () => import_amsg_shared.isReasoningPush,
+  isToolRequestPush: () => import_amsg_shared.isToolRequestPush
 });
 module.exports = __toCommonJS(src_exports);
+var import_amsg_shared = require("@rei-standard/amsg-shared");
+var AVATAR_URL_MAX_LENGTH = 2048;
+var PAYLOAD_LOCAL_MAX_BYTES = 3072;
+function makeLocalError(code, message, details) {
+  const err = new Error(`[rei-standard-amsg-client] ${message}`);
+  err.code = code;
+  if (details) err.details = details;
+  return err;
+}
 var ReiClient = class {
   /**
    * @param {ReiClientConfig} config
@@ -97,11 +117,19 @@ var ReiClient = class {
    *
    * The payload is automatically encrypted before transmission.
    *
+   * Throws (without a network round-trip):
+   *   - `INVALID_AVATAR_URL_LOCAL` — `avatarUrl` is a `data:` URI, > 2 KB,
+   *     or otherwise unacceptable.
+   *   - `PAYLOAD_TOO_LARGE_LOCAL` — JSON-serialized payload exceeds 3 KB.
+   *
    * @param {Object} payload - Schedule message payload.
    * @returns {Promise<Object>} API response body.
    */
   async scheduleMessage(payload) {
-    const encrypted = await this._encrypt(JSON.stringify(payload));
+    this._validateAvatarUrl(payload && payload.avatarUrl);
+    const json = JSON.stringify(payload);
+    this._assertPayloadSize(json, "scheduleMessage");
+    const encrypted = await this._encrypt(json);
     const res = await fetch(`${this._baseUrl}/schedule-message`, {
       method: "POST",
       headers: {
@@ -135,21 +163,29 @@ var ReiClient = class {
    *
    * Routes to `customBaseUrls.instant` if configured, otherwise `baseUrl`.
    *
+   * Throws (without a network round-trip):
+   *   - `INVALID_AVATAR_URL_LOCAL` — `avatarUrl` is a `data:` URI, > 2 KB,
+   *     or otherwise unacceptable.
+   *   - `PAYLOAD_TOO_LARGE_LOCAL` — JSON-serialized payload exceeds 3 KB.
+   *
    * @param {Object} payload - Instant message payload.
    * @param {string} [endpointPath] - Path under the resolved base URL. Default '/instant'.
    * @param {{ authorization?: string }} [opts] - Optional auth header to forward.
    * @returns {Promise<Object>} `{ success, data?: { messagesSent, sentAt }, error? }`
    */
   async sendInstant(payload, endpointPath = "/instant", opts = {}) {
+    this._validateAvatarUrl(payload && payload.avatarUrl);
+    const json = JSON.stringify(payload);
+    this._assertPayloadSize(json, "sendInstant");
     const headers = { "Content-Type": "application/json" };
     let body;
     if (this._instantEncryption === false) {
-      body = JSON.stringify(payload);
+      body = json;
       if (this._instantClientToken) {
         headers["X-Client-Token"] = this._instantClientToken;
       }
     } else {
-      const encrypted = await this._encrypt(JSON.stringify(payload));
+      const encrypted = await this._encrypt(json);
       headers["X-User-Id"] = this._userId;
       headers["X-Payload-Encrypted"] = "true";
       headers["X-Encryption-Version"] = "1";
@@ -169,12 +205,20 @@ var ReiClient = class {
   /**
    * Update an existing scheduled message.
    *
+   * Throws (without a network round-trip):
+   *   - `INVALID_AVATAR_URL_LOCAL` — `updates.avatarUrl` is a `data:` URI,
+   *     > 2 KB, or otherwise unacceptable.
+   *   - `PAYLOAD_TOO_LARGE_LOCAL` — JSON-serialized updates exceed 3 KB.
+   *
    * @param {string} uuid    - Task UUID.
    * @param {Object} updates - Fields to update.
    * @returns {Promise<Object>}
    */
   async updateMessage(uuid, updates) {
-    const encrypted = await this._encrypt(JSON.stringify(updates));
+    this._validateAvatarUrl(updates && updates.avatarUrl);
+    const json = JSON.stringify(updates);
+    this._assertPayloadSize(json, "updateMessage");
+    const encrypted = await this._encrypt(json);
     const res = await fetch(`${this._baseUrl}/update-message?id=${encodeURIComponent(uuid)}`, {
       method: "PUT",
       headers: {
@@ -249,6 +293,55 @@ var ReiClient = class {
     });
     return subscription;
   }
+  // ─── Local preflight (no network) ────────────────────────────────
+  /**
+   * Reject `avatarUrl` values that would 100% fail downstream — `data:`
+   * URIs (base64 inline image) and anything longer than 2 KB. Mirrors the
+   * server-side check in `@rei-standard/amsg-instant` / `@rei-standard/amsg-server`;
+   * intentionally a fast preflight that does not parse the URL (server
+   * still does that, and `URL` is the bigger of the two costs in browsers).
+   *
+   * @private
+   * @param {unknown} value
+   */
+  _validateAvatarUrl(value) {
+    if (value === void 0 || value === null) return;
+    if (typeof value !== "string") {
+      throw makeLocalError("INVALID_AVATAR_URL_LOCAL", "avatarUrl \u5FC5\u987B\u662F\u5B57\u7B26\u4E32");
+    }
+    if (/^data:/i.test(value)) {
+      throw makeLocalError(
+        "INVALID_AVATAR_URL_LOCAL",
+        "\u5934\u50CF\u4E0D\u652F\u6301\u4F20\u5165 data: URI\uFF0C\u8BF7\u6539\u4E3A\u516C\u7F51\u53EF\u8BBF\u95EE\u7684 https:// \u56FE\u7247 URL"
+      );
+    }
+    if (value.length > AVATAR_URL_MAX_LENGTH) {
+      throw makeLocalError(
+        "INVALID_AVATAR_URL_LOCAL",
+        `\u5934\u50CF URL \u957F\u5EA6 ${value.length} \u5B57\u7B26\u8D85\u8FC7 ${AVATAR_URL_MAX_LENGTH} \u4E0A\u9650\uFF0C\u8BF7\u6539\u4E3A\u66F4\u77ED\u7684\u56FE\u7247 URL`,
+        { actualLength: value.length, limit: AVATAR_URL_MAX_LENGTH }
+      );
+    }
+  }
+  /**
+   * Reject outgoing payloads larger than 3 KB pre-encryption. Spares the
+   * remote a guaranteed 413 / Web Push 4 KB-limit failure and gives the
+   * caller a precise local error pointing at the size cap.
+   *
+   * @private
+   * @param {string} bodyJson  - `JSON.stringify(payload)`.
+   * @param {string} methodName
+   */
+  _assertPayloadSize(bodyJson, methodName) {
+    const bytes = new TextEncoder().encode(bodyJson).length;
+    if (bytes > PAYLOAD_LOCAL_MAX_BYTES) {
+      throw makeLocalError(
+        "PAYLOAD_TOO_LARGE_LOCAL",
+        `${methodName} payload \u4F53\u79EF ${bytes} \u5B57\u8282\u8D85\u8FC7\u672C\u5730\u4E0A\u9650 ${PAYLOAD_LOCAL_MAX_BYTES} \u5B57\u8282`,
+        { method: methodName, actualBytes: bytes, limitBytes: PAYLOAD_LOCAL_MAX_BYTES }
+      );
+    }
+  }
   // ─── Crypto helpers (Web Crypto API) ────────────────────────────
   /**
    * Encrypt plaintext with AES-256-GCM.

package/dist/index.d.cts

@@ -1,3 +1,5 @@
+export { MESSAGE_KIND, MESSAGE_TYPE, PUSH_SOURCE, buildContentPush, buildErrorPush, buildReasoningPush, buildToolRequestPush, isContentPush, isErrorPush, isReasoningPush, isToolRequestPush } from '@rei-standard/amsg-shared';
+
 /**
  * ReiStandard Client SDK
  *
@@ -22,6 +24,15 @@
  *   await client.scheduleMessage({ ... });
  */
 
+/** @typedef {import('@rei-standard/amsg-shared').MessageKind} MessageKind */
+/** @typedef {import('@rei-standard/amsg-shared').MessageType} MessageType */
+/** @typedef {import('@rei-standard/amsg-shared').PushSource} PushSource */
+/** @typedef {import('@rei-standard/amsg-shared').AmsgPush} AmsgPush */
+/** @typedef {import('@rei-standard/amsg-shared').ContentPush} ContentPush */
+/** @typedef {import('@rei-standard/amsg-shared').ReasoningPush} ReasoningPush */
+/** @typedef {import('@rei-standard/amsg-shared').ToolRequestPush} ToolRequestPush */
+/** @typedef {import('@rei-standard/amsg-shared').ErrorPush} ErrorPush */
+
 /**
  * @typedef {Object} ReiClientConfig
  * @property {string} baseUrl                            - Default base URL of the API (e.g. https://host/api/v1).
@@ -52,6 +63,30 @@
  *                                                         read it. Use for casual URL-direct abuse only.
  */
 
+/**
+ * Max length of `avatarUrl` accepted by local preflight (2 KB). Mirrors
+ * `@rei-standard/amsg-instant` / `@rei-standard/amsg-server` server-side
+ * limits — kept in lockstep on purpose so client-side rejects match what
+ * the server would reject.
+ */
+const AVATAR_URL_MAX_LENGTH = 2048;
+
+/**
+ * Max byte length of a single outgoing payload (3 KB, measured pre-encryption
+ * on the plaintext JSON body). Anything over this is almost certainly a base64
+ * avatar smuggled into `avatarUrl` and will trigger downstream `413 Payload
+ * Too Large` or hit the Web Push 4 KB hard limit at delivery. We bail locally
+ * to save a remote round-trip and give a precise error.
+ */
+const PAYLOAD_LOCAL_MAX_BYTES = 3072;
+
+function makeLocalError(code, message, details) {
+  const err = new Error(`[rei-standard-amsg-client] ${message}`);
+  err.code = code;
+  if (details) err.details = details;
+  return err;
+}
+
 class ReiClient {
   /**
    * @param {ReiClientConfig} config
@@ -146,11 +181,19 @@ class ReiClient {
    *
    * The payload is automatically encrypted before transmission.
    *
+   * Throws (without a network round-trip):
+   *   - `INVALID_AVATAR_URL_LOCAL` — `avatarUrl` is a `data:` URI, > 2 KB,
+   *     or otherwise unacceptable.
+   *   - `PAYLOAD_TOO_LARGE_LOCAL` — JSON-serialized payload exceeds 3 KB.
+   *
    * @param {Object} payload - Schedule message payload.
    * @returns {Promise<Object>} API response body.
    */
   async scheduleMessage(payload) {
-    const encrypted = await this._encrypt(JSON.stringify(payload));
+    this._validateAvatarUrl(payload && payload.avatarUrl);
+    const json = JSON.stringify(payload);
+    this._assertPayloadSize(json, 'scheduleMessage');
+    const encrypted = await this._encrypt(json);
 
     const res = await fetch(`${this._baseUrl}/schedule-message`, {
       method: 'POST',
@@ -187,22 +230,31 @@ class ReiClient {
    *
    * Routes to `customBaseUrls.instant` if configured, otherwise `baseUrl`.
    *
+   * Throws (without a network round-trip):
+   *   - `INVALID_AVATAR_URL_LOCAL` — `avatarUrl` is a `data:` URI, > 2 KB,
+   *     or otherwise unacceptable.
+   *   - `PAYLOAD_TOO_LARGE_LOCAL` — JSON-serialized payload exceeds 3 KB.
+   *
    * @param {Object} payload - Instant message payload.
    * @param {string} [endpointPath] - Path under the resolved base URL. Default '/instant'.
    * @param {{ authorization?: string }} [opts] - Optional auth header to forward.
    * @returns {Promise<Object>} `{ success, data?: { messagesSent, sentAt }, error? }`
    */
   async sendInstant(payload, endpointPath = '/instant', opts = {}) {
+    this._validateAvatarUrl(payload && payload.avatarUrl);
+    const json = JSON.stringify(payload);
+    this._assertPayloadSize(json, 'sendInstant');
+
     const headers = { 'Content-Type': 'application/json' };
     let body;
 
     if (this._instantEncryption === false) {
-      body = JSON.stringify(payload);
+      body = json;
       if (this._instantClientToken) {
         headers['X-Client-Token'] = this._instantClientToken;
       }
     } else {
-      const encrypted = await this._encrypt(JSON.stringify(payload));
+      const encrypted = await this._encrypt(json);
       headers['X-User-Id'] = this._userId;
       headers['X-Payload-Encrypted'] = 'true';
       headers['X-Encryption-Version'] = '1';
@@ -226,12 +278,20 @@ class ReiClient {
   /**
    * Update an existing scheduled message.
    *
+   * Throws (without a network round-trip):
+   *   - `INVALID_AVATAR_URL_LOCAL` — `updates.avatarUrl` is a `data:` URI,
+   *     > 2 KB, or otherwise unacceptable.
+   *   - `PAYLOAD_TOO_LARGE_LOCAL` — JSON-serialized updates exceed 3 KB.
+   *
    * @param {string} uuid    - Task UUID.
    * @param {Object} updates - Fields to update.
    * @returns {Promise<Object>}
    */
   async updateMessage(uuid, updates) {
-    const encrypted = await this._encrypt(JSON.stringify(updates));
+    this._validateAvatarUrl(updates && updates.avatarUrl);
+    const json = JSON.stringify(updates);
+    this._assertPayloadSize(json, 'updateMessage');
+    const encrypted = await this._encrypt(json);
 
     const res = await fetch(`${this._baseUrl}/update-message?id=${encodeURIComponent(uuid)}`, {
       method: 'PUT',
@@ -318,6 +378,58 @@ class ReiClient {
     return subscription;
   }
 
+  // ─── Local preflight (no network) ────────────────────────────────
+
+  /**
+   * Reject `avatarUrl` values that would 100% fail downstream — `data:`
+   * URIs (base64 inline image) and anything longer than 2 KB. Mirrors the
+   * server-side check in `@rei-standard/amsg-instant` / `@rei-standard/amsg-server`;
+   * intentionally a fast preflight that does not parse the URL (server
+   * still does that, and `URL` is the bigger of the two costs in browsers).
+   *
+   * @private
+   * @param {unknown} value
+   */
+  _validateAvatarUrl(value) {
+    if (value === undefined || value === null) return;
+    if (typeof value !== 'string') {
+      throw makeLocalError('INVALID_AVATAR_URL_LOCAL', 'avatarUrl 必须是字符串');
+    }
+    if (/^data:/i.test(value)) {
+      throw makeLocalError(
+        'INVALID_AVATAR_URL_LOCAL',
+        '头像不支持传入 data: URI，请改为公网可访问的 https:// 图片 URL'
+      );
+    }
+    if (value.length > AVATAR_URL_MAX_LENGTH) {
+      throw makeLocalError(
+        'INVALID_AVATAR_URL_LOCAL',
+        `头像 URL 长度 ${value.length} 字符超过 ${AVATAR_URL_MAX_LENGTH} 上限，请改为更短的图片 URL`,
+        { actualLength: value.length, limit: AVATAR_URL_MAX_LENGTH }
+      );
+    }
+  }
+
+  /**
+   * Reject outgoing payloads larger than 3 KB pre-encryption. Spares the
+   * remote a guaranteed 413 / Web Push 4 KB-limit failure and gives the
+   * caller a precise local error pointing at the size cap.
+   *
+   * @private
+   * @param {string} bodyJson  - `JSON.stringify(payload)`.
+   * @param {string} methodName
+   */
+  _assertPayloadSize(bodyJson, methodName) {
+    const bytes = new TextEncoder().encode(bodyJson).length;
+    if (bytes > PAYLOAD_LOCAL_MAX_BYTES) {
+      throw makeLocalError(
+        'PAYLOAD_TOO_LARGE_LOCAL',
+        `${methodName} payload 体积 ${bytes} 字节超过本地上限 ${PAYLOAD_LOCAL_MAX_BYTES} 字节`,
+        { method: methodName, actualBytes: bytes, limitBytes: PAYLOAD_LOCAL_MAX_BYTES }
+      );
+    }
+  }
+
   // ─── Crypto helpers (Web Crypto API) ────────────────────────────
 
   /**

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+export { MESSAGE_KIND, MESSAGE_TYPE, PUSH_SOURCE, buildContentPush, buildErrorPush, buildReasoningPush, buildToolRequestPush, isContentPush, isErrorPush, isReasoningPush, isToolRequestPush } from '@rei-standard/amsg-shared';
+
 /**
  * ReiStandard Client SDK
  *
@@ -22,6 +24,15 @@
  *   await client.scheduleMessage({ ... });
  */
 
+/** @typedef {import('@rei-standard/amsg-shared').MessageKind} MessageKind */
+/** @typedef {import('@rei-standard/amsg-shared').MessageType} MessageType */
+/** @typedef {import('@rei-standard/amsg-shared').PushSource} PushSource */
+/** @typedef {import('@rei-standard/amsg-shared').AmsgPush} AmsgPush */
+/** @typedef {import('@rei-standard/amsg-shared').ContentPush} ContentPush */
+/** @typedef {import('@rei-standard/amsg-shared').ReasoningPush} ReasoningPush */
+/** @typedef {import('@rei-standard/amsg-shared').ToolRequestPush} ToolRequestPush */
+/** @typedef {import('@rei-standard/amsg-shared').ErrorPush} ErrorPush */
+
 /**
  * @typedef {Object} ReiClientConfig
  * @property {string} baseUrl                            - Default base URL of the API (e.g. https://host/api/v1).
@@ -52,6 +63,30 @@
  *                                                         read it. Use for casual URL-direct abuse only.
  */
 
+/**
+ * Max length of `avatarUrl` accepted by local preflight (2 KB). Mirrors
+ * `@rei-standard/amsg-instant` / `@rei-standard/amsg-server` server-side
+ * limits — kept in lockstep on purpose so client-side rejects match what
+ * the server would reject.
+ */
+const AVATAR_URL_MAX_LENGTH = 2048;
+
+/**
+ * Max byte length of a single outgoing payload (3 KB, measured pre-encryption
+ * on the plaintext JSON body). Anything over this is almost certainly a base64
+ * avatar smuggled into `avatarUrl` and will trigger downstream `413 Payload
+ * Too Large` or hit the Web Push 4 KB hard limit at delivery. We bail locally
+ * to save a remote round-trip and give a precise error.
+ */
+const PAYLOAD_LOCAL_MAX_BYTES = 3072;
+
+function makeLocalError(code, message, details) {
+  const err = new Error(`[rei-standard-amsg-client] ${message}`);
+  err.code = code;
+  if (details) err.details = details;
+  return err;
+}
+
 class ReiClient {
   /**
    * @param {ReiClientConfig} config
@@ -146,11 +181,19 @@ class ReiClient {
    *
    * The payload is automatically encrypted before transmission.
    *
+   * Throws (without a network round-trip):
+   *   - `INVALID_AVATAR_URL_LOCAL` — `avatarUrl` is a `data:` URI, > 2 KB,
+   *     or otherwise unacceptable.
+   *   - `PAYLOAD_TOO_LARGE_LOCAL` — JSON-serialized payload exceeds 3 KB.
+   *
    * @param {Object} payload - Schedule message payload.
    * @returns {Promise<Object>} API response body.
    */
   async scheduleMessage(payload) {
-    const encrypted = await this._encrypt(JSON.stringify(payload));
+    this._validateAvatarUrl(payload && payload.avatarUrl);
+    const json = JSON.stringify(payload);
+    this._assertPayloadSize(json, 'scheduleMessage');
+    const encrypted = await this._encrypt(json);
 
     const res = await fetch(`${this._baseUrl}/schedule-message`, {
       method: 'POST',
@@ -187,22 +230,31 @@ class ReiClient {
    *
    * Routes to `customBaseUrls.instant` if configured, otherwise `baseUrl`.
    *
+   * Throws (without a network round-trip):
+   *   - `INVALID_AVATAR_URL_LOCAL` — `avatarUrl` is a `data:` URI, > 2 KB,
+   *     or otherwise unacceptable.
+   *   - `PAYLOAD_TOO_LARGE_LOCAL` — JSON-serialized payload exceeds 3 KB.
+   *
    * @param {Object} payload - Instant message payload.
    * @param {string} [endpointPath] - Path under the resolved base URL. Default '/instant'.
    * @param {{ authorization?: string }} [opts] - Optional auth header to forward.
    * @returns {Promise<Object>} `{ success, data?: { messagesSent, sentAt }, error? }`
    */
   async sendInstant(payload, endpointPath = '/instant', opts = {}) {
+    this._validateAvatarUrl(payload && payload.avatarUrl);
+    const json = JSON.stringify(payload);
+    this._assertPayloadSize(json, 'sendInstant');
+
     const headers = { 'Content-Type': 'application/json' };
     let body;
 
     if (this._instantEncryption === false) {
-      body = JSON.stringify(payload);
+      body = json;
       if (this._instantClientToken) {
         headers['X-Client-Token'] = this._instantClientToken;
       }
     } else {
-      const encrypted = await this._encrypt(JSON.stringify(payload));
+      const encrypted = await this._encrypt(json);
       headers['X-User-Id'] = this._userId;
       headers['X-Payload-Encrypted'] = 'true';
       headers['X-Encryption-Version'] = '1';
@@ -226,12 +278,20 @@ class ReiClient {
   /**
    * Update an existing scheduled message.
    *
+   * Throws (without a network round-trip):
+   *   - `INVALID_AVATAR_URL_LOCAL` — `updates.avatarUrl` is a `data:` URI,
+   *     > 2 KB, or otherwise unacceptable.
+   *   - `PAYLOAD_TOO_LARGE_LOCAL` — JSON-serialized updates exceed 3 KB.
+   *
    * @param {string} uuid    - Task UUID.
    * @param {Object} updates - Fields to update.
    * @returns {Promise<Object>}
    */
   async updateMessage(uuid, updates) {
-    const encrypted = await this._encrypt(JSON.stringify(updates));
+    this._validateAvatarUrl(updates && updates.avatarUrl);
+    const json = JSON.stringify(updates);
+    this._assertPayloadSize(json, 'updateMessage');
+    const encrypted = await this._encrypt(json);
 
     const res = await fetch(`${this._baseUrl}/update-message?id=${encodeURIComponent(uuid)}`, {
       method: 'PUT',
@@ -318,6 +378,58 @@ class ReiClient {
     return subscription;
   }
 
+  // ─── Local preflight (no network) ────────────────────────────────
+
+  /**
+   * Reject `avatarUrl` values that would 100% fail downstream — `data:`
+   * URIs (base64 inline image) and anything longer than 2 KB. Mirrors the
+   * server-side check in `@rei-standard/amsg-instant` / `@rei-standard/amsg-server`;
+   * intentionally a fast preflight that does not parse the URL (server
+   * still does that, and `URL` is the bigger of the two costs in browsers).
+   *
+   * @private
+   * @param {unknown} value
+   */
+  _validateAvatarUrl(value) {
+    if (value === undefined || value === null) return;
+    if (typeof value !== 'string') {
+      throw makeLocalError('INVALID_AVATAR_URL_LOCAL', 'avatarUrl 必须是字符串');
+    }
+    if (/^data:/i.test(value)) {
+      throw makeLocalError(
+        'INVALID_AVATAR_URL_LOCAL',
+        '头像不支持传入 data: URI，请改为公网可访问的 https:// 图片 URL'
+      );
+    }
+    if (value.length > AVATAR_URL_MAX_LENGTH) {
+      throw makeLocalError(
+        'INVALID_AVATAR_URL_LOCAL',
+        `头像 URL 长度 ${value.length} 字符超过 ${AVATAR_URL_MAX_LENGTH} 上限，请改为更短的图片 URL`,
+        { actualLength: value.length, limit: AVATAR_URL_MAX_LENGTH }
+      );
+    }
+  }
+
+  /**
+   * Reject outgoing payloads larger than 3 KB pre-encryption. Spares the
+   * remote a guaranteed 413 / Web Push 4 KB-limit failure and gives the
+   * caller a precise local error pointing at the size cap.
+   *
+   * @private
+   * @param {string} bodyJson  - `JSON.stringify(payload)`.
+   * @param {string} methodName
+   */
+  _assertPayloadSize(bodyJson, methodName) {
+    const bytes = new TextEncoder().encode(bodyJson).length;
+    if (bytes > PAYLOAD_LOCAL_MAX_BYTES) {
+      throw makeLocalError(
+        'PAYLOAD_TOO_LARGE_LOCAL',
+        `${methodName} payload 体积 ${bytes} 字节超过本地上限 ${PAYLOAD_LOCAL_MAX_BYTES} 字节`,
+        { method: methodName, actualBytes: bytes, limitBytes: PAYLOAD_LOCAL_MAX_BYTES }
+      );
+    }
+  }
+
   // ─── Crypto helpers (Web Crypto API) ────────────────────────────
 
   /**

package/dist/index.mjs

@@ -1,4 +1,25 @@
 // src/index.js
+import {
+  MESSAGE_KIND,
+  MESSAGE_TYPE,
+  PUSH_SOURCE,
+  buildContentPush,
+  buildReasoningPush,
+  buildToolRequestPush,
+  buildErrorPush,
+  isContentPush,
+  isReasoningPush,
+  isToolRequestPush,
+  isErrorPush
+} from "@rei-standard/amsg-shared";
+var AVATAR_URL_MAX_LENGTH = 2048;
+var PAYLOAD_LOCAL_MAX_BYTES = 3072;
+function makeLocalError(code, message, details) {
+  const err = new Error(`[rei-standard-amsg-client] ${message}`);
+  err.code = code;
+  if (details) err.details = details;
+  return err;
+}
 var ReiClient = class {
   /**
    * @param {ReiClientConfig} config
@@ -74,11 +95,19 @@ var ReiClient = class {
    *
    * The payload is automatically encrypted before transmission.
    *
+   * Throws (without a network round-trip):
+   *   - `INVALID_AVATAR_URL_LOCAL` — `avatarUrl` is a `data:` URI, > 2 KB,
+   *     or otherwise unacceptable.
+   *   - `PAYLOAD_TOO_LARGE_LOCAL` — JSON-serialized payload exceeds 3 KB.
+   *
    * @param {Object} payload - Schedule message payload.
    * @returns {Promise<Object>} API response body.
    */
   async scheduleMessage(payload) {
-    const encrypted = await this._encrypt(JSON.stringify(payload));
+    this._validateAvatarUrl(payload && payload.avatarUrl);
+    const json = JSON.stringify(payload);
+    this._assertPayloadSize(json, "scheduleMessage");
+    const encrypted = await this._encrypt(json);
     const res = await fetch(`${this._baseUrl}/schedule-message`, {
       method: "POST",
       headers: {
@@ -112,21 +141,29 @@ var ReiClient = class {
    *
    * Routes to `customBaseUrls.instant` if configured, otherwise `baseUrl`.
    *
+   * Throws (without a network round-trip):
+   *   - `INVALID_AVATAR_URL_LOCAL` — `avatarUrl` is a `data:` URI, > 2 KB,
+   *     or otherwise unacceptable.
+   *   - `PAYLOAD_TOO_LARGE_LOCAL` — JSON-serialized payload exceeds 3 KB.
+   *
    * @param {Object} payload - Instant message payload.
    * @param {string} [endpointPath] - Path under the resolved base URL. Default '/instant'.
    * @param {{ authorization?: string }} [opts] - Optional auth header to forward.
    * @returns {Promise<Object>} `{ success, data?: { messagesSent, sentAt }, error? }`
    */
   async sendInstant(payload, endpointPath = "/instant", opts = {}) {
+    this._validateAvatarUrl(payload && payload.avatarUrl);
+    const json = JSON.stringify(payload);
+    this._assertPayloadSize(json, "sendInstant");
     const headers = { "Content-Type": "application/json" };
     let body;
     if (this._instantEncryption === false) {
-      body = JSON.stringify(payload);
+      body = json;
       if (this._instantClientToken) {
         headers["X-Client-Token"] = this._instantClientToken;
       }
     } else {
-      const encrypted = await this._encrypt(JSON.stringify(payload));
+      const encrypted = await this._encrypt(json);
       headers["X-User-Id"] = this._userId;
       headers["X-Payload-Encrypted"] = "true";
       headers["X-Encryption-Version"] = "1";
@@ -146,12 +183,20 @@ var ReiClient = class {
   /**
    * Update an existing scheduled message.
    *
+   * Throws (without a network round-trip):
+   *   - `INVALID_AVATAR_URL_LOCAL` — `updates.avatarUrl` is a `data:` URI,
+   *     > 2 KB, or otherwise unacceptable.
+   *   - `PAYLOAD_TOO_LARGE_LOCAL` — JSON-serialized updates exceed 3 KB.
+   *
    * @param {string} uuid    - Task UUID.
    * @param {Object} updates - Fields to update.
    * @returns {Promise<Object>}
    */
   async updateMessage(uuid, updates) {
-    const encrypted = await this._encrypt(JSON.stringify(updates));
+    this._validateAvatarUrl(updates && updates.avatarUrl);
+    const json = JSON.stringify(updates);
+    this._assertPayloadSize(json, "updateMessage");
+    const encrypted = await this._encrypt(json);
     const res = await fetch(`${this._baseUrl}/update-message?id=${encodeURIComponent(uuid)}`, {
       method: "PUT",
       headers: {
@@ -226,6 +271,55 @@ var ReiClient = class {
     });
     return subscription;
   }
+  // ─── Local preflight (no network) ────────────────────────────────
+  /**
+   * Reject `avatarUrl` values that would 100% fail downstream — `data:`
+   * URIs (base64 inline image) and anything longer than 2 KB. Mirrors the
+   * server-side check in `@rei-standard/amsg-instant` / `@rei-standard/amsg-server`;
+   * intentionally a fast preflight that does not parse the URL (server
+   * still does that, and `URL` is the bigger of the two costs in browsers).
+   *
+   * @private
+   * @param {unknown} value
+   */
+  _validateAvatarUrl(value) {
+    if (value === void 0 || value === null) return;
+    if (typeof value !== "string") {
+      throw makeLocalError("INVALID_AVATAR_URL_LOCAL", "avatarUrl \u5FC5\u987B\u662F\u5B57\u7B26\u4E32");
+    }
+    if (/^data:/i.test(value)) {
+      throw makeLocalError(
+        "INVALID_AVATAR_URL_LOCAL",
+        "\u5934\u50CF\u4E0D\u652F\u6301\u4F20\u5165 data: URI\uFF0C\u8BF7\u6539\u4E3A\u516C\u7F51\u53EF\u8BBF\u95EE\u7684 https:// \u56FE\u7247 URL"
+      );
+    }
+    if (value.length > AVATAR_URL_MAX_LENGTH) {
+      throw makeLocalError(
+        "INVALID_AVATAR_URL_LOCAL",
+        `\u5934\u50CF URL \u957F\u5EA6 ${value.length} \u5B57\u7B26\u8D85\u8FC7 ${AVATAR_URL_MAX_LENGTH} \u4E0A\u9650\uFF0C\u8BF7\u6539\u4E3A\u66F4\u77ED\u7684\u56FE\u7247 URL`,
+        { actualLength: value.length, limit: AVATAR_URL_MAX_LENGTH }
+      );
+    }
+  }
+  /**
+   * Reject outgoing payloads larger than 3 KB pre-encryption. Spares the
+   * remote a guaranteed 413 / Web Push 4 KB-limit failure and gives the
+   * caller a precise local error pointing at the size cap.
+   *
+   * @private
+   * @param {string} bodyJson  - `JSON.stringify(payload)`.
+   * @param {string} methodName
+   */
+  _assertPayloadSize(bodyJson, methodName) {
+    const bytes = new TextEncoder().encode(bodyJson).length;
+    if (bytes > PAYLOAD_LOCAL_MAX_BYTES) {
+      throw makeLocalError(
+        "PAYLOAD_TOO_LARGE_LOCAL",
+        `${methodName} payload \u4F53\u79EF ${bytes} \u5B57\u8282\u8D85\u8FC7\u672C\u5730\u4E0A\u9650 ${PAYLOAD_LOCAL_MAX_BYTES} \u5B57\u8282`,
+        { method: methodName, actualBytes: bytes, limitBytes: PAYLOAD_LOCAL_MAX_BYTES }
+      );
+    }
+  }
   // ─── Crypto helpers (Web Crypto API) ────────────────────────────
   /**
    * Encrypt plaintext with AES-256-GCM.
@@ -301,5 +395,16 @@ var ReiClient = class {
   }
 };
 export {
-  ReiClient
+  MESSAGE_KIND,
+  MESSAGE_TYPE,
+  PUSH_SOURCE,
+  ReiClient,
+  buildContentPush,
+  buildErrorPush,
+  buildReasoningPush,
+  buildToolRequestPush,
+  isContentPush,
+  isErrorPush,
+  isReasoningPush,
+  isToolRequestPush
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rei-standard/amsg-client",
-  "version": "2.2.1",
-  "description": "ReiStandard Active Messaging browser client SDK",
+  "version": "2.3.0-next.0",
+  "description": "ReiStandard Active Messaging browser client SDK — also re-exports shared push types, builders, and guards from @rei-standard/amsg-shared",
   "repository": {
     "type": "git",
     "url": "https://github.com/Tosd0/ReiStandard",
@@ -26,11 +26,15 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsup"
+    "build": "tsup",
+    "test": "node --test test/*.test.mjs"
   },
   "engines": {
     "node": ">=20"
   },
+  "dependencies": {
+    "@rei-standard/amsg-shared": "0.1.0-next.0"
+  },
   "devDependencies": {
     "tsup": "^8.0.0",
     "typescript": "^5.0.0"