@rei-standard/amsg-client 2.2.1 → 2.2.3

package/README.md

@@ -116,6 +116,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

@@ -22,6 +22,14 @@ __export(src_exports, {
   ReiClient: () => ReiClient
 });
 module.exports = __toCommonJS(src_exports);
+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 +105,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 +151,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 +193,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 +281,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

@@ -52,6 +52,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 +170,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 +219,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 +267,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 +367,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

@@ -52,6 +52,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 +170,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 +219,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 +267,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 +367,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,12 @@
 // src/index.js
+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 +82,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 +128,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 +170,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 +258,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rei-standard/amsg-client",
-  "version": "2.2.1",
+  "version": "2.2.3",
   "description": "ReiStandard Active Messaging browser client SDK",
   "repository": {
     "type": "git",