@rei-standard/amsg-client 2.2.3 → 2.3.0-next.2

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,
+      })
+    );
+  }
+});
+```
 
 ## 安装
 
@@ -144,24 +180,24 @@ await client.sendInstant({
 - 传**正则 source**，不要带 `/.../` 也不要尾 flag。`'/foo/i'` 会被当字面量斜杠 + 字面量 `i`，不是大小写不敏感的 `foo`。大小写不敏感请用 `[Aa]` 字符类替代。
 - 想让分隔符回贴到前一段（默认行为），把分隔符包进 `(...)` 捕获组。库**不会自动包**——传 `'\\n+'` 而不是 `'(\\n+)'` 会得到首尾相连、分隔符丢失的奇怪结果。
 
-### 本地预校验：`avatarUrl` 与 payload 体积（2.2.3+）
+### 本地软清空：`avatarUrl` 与 payload 体积（2.2.4+ / 2.3.0-next.1+）
 
-`scheduleMessage` / `sendInstant` / `updateMessage` 在发请求**之前**会在本地做两项预检，避免一次远端往返才拿到 `413` 或 Web Push 4KB 上限报错：
+`scheduleMessage` / `sendInstant` / `updateMessage` 在发请求**之前**会在本地做两项保护：
 
-| 触发条件 | 抛出 `Error.code` | 触发原因（背景说明，不在 message 里） |
+| 触发条件 | 处理方式 | 触发原因（背景说明，不在 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 }` 方便定位。 |
+| `payload.avatarUrl` 以 `data:` 开头（含 `data:image/...;base64,...`） | `console.warn` + 在 payload 上把 `avatarUrl` 置为 `null`，请求照发（`updateMessage` 从 patch 里删除该字段，保留服务端原头像） | base64 内嵌头像把单个 push payload 撑到几十 KB，远端 Web Push 服务直接返回 4KB 超限 / 网关 `413`。 |
+| `payload.avatarUrl` 长度 > 2048 字符 | 同上 | 同上。建议用 CDN 缩略图 URL。 |
+| `payload.avatarUrl` 不是字符串 | 同上 | 类型错误。 |
+| `JSON.stringify(payload)` UTF-8 字节数 > 3072 | 抛出 `Error.code === 'PAYLOAD_TOO_LARGE_LOCAL'`，错误对象带 `.details = { method, actualBytes, limitBytes }` | 远端网关 / Web Push 4KB 硬上限的本地兜底。 |
+
+头像是装饰字段，单个不合规 URL 不再让整次调度 / 推送挂掉；想拦到错误请监听 `console.warn`，或在调用前自己用 `validateAvatarUrl` 预检（server / instant 包都有导出）。`PAYLOAD_TOO_LARGE_LOCAL` 仍然是真正的"整包过大"信号，照常用 try/catch 捕获：
 
 ```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') {
+  if (err.code === 'PAYLOAD_TOO_LARGE_LOCAL') {
     // err.details = { method: 'sendInstant', actualBytes: 8732, limitBytes: 3072 }
   } else {
     throw err;
@@ -169,7 +205,7 @@ try {
 }
 ```
 
-服务端（`@rei-standard/amsg-instant` 0.6.1+ / `@rei-standard/amsg-server` 2.3.1+）有等价的二道防线，业务可以放心依赖 client 这一道做 UX 提示。
+服务端（`@rei-standard/amsg-instant` 0.7.1+ / 0.8.0-next.1+，`@rei-standard/amsg-server` 2.3.3+ / 2.4.0-next.1+）有同样的软清空二道防线，client 这一道主要省一次远端往返。
 
 ## 导出 API（Exports）
 

package/dist/index.cjs

@@ -19,9 +19,21 @@ 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) {
@@ -105,16 +117,16 @@ 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.
+   * If `avatarUrl` is unusable (`data:` URI, > 2 KB, or non-string), the
+   * client soft-strips it on the payload and emits a `console.warn` — the
+   * schedule still ships, just without an avatar. The only throw left is
+   * `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) {
-    this._validateAvatarUrl(payload && payload.avatarUrl);
+    this._sanitizeAvatarUrl(payload);
     const json = JSON.stringify(payload);
     this._assertPayloadSize(json, "scheduleMessage");
     const encrypted = await this._encrypt(json);
@@ -151,10 +163,10 @@ 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.
+   * If `avatarUrl` is unusable (`data:` URI, > 2 KB, or non-string), the
+   * client soft-strips it on the payload and emits a `console.warn` — the
+   * push still ships, just without an icon. The only throw left is
+   * `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'.
@@ -162,7 +174,7 @@ var ReiClient = class {
    * @returns {Promise<Object>} `{ success, data?: { messagesSent, sentAt }, error? }`
    */
   async sendInstant(payload, endpointPath = "/instant", opts = {}) {
-    this._validateAvatarUrl(payload && payload.avatarUrl);
+    this._sanitizeAvatarUrl(payload);
     const json = JSON.stringify(payload);
     this._assertPayloadSize(json, "sendInstant");
     const headers = { "Content-Type": "application/json" };
@@ -193,17 +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.
+   * If `updates.avatarUrl` is unusable (`data:` URI, > 2 KB, or non-string),
+   * the client soft-strips it from the patch and emits a `console.warn` —
+   * the rest of the update still applies, and the stored avatar is left
+   * untouched. The only throw left is `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) {
-    this._validateAvatarUrl(updates && updates.avatarUrl);
+    if (this._sanitizeAvatarUrl(updates)) {
+      delete updates.avatarUrl;
+    }
     const json = JSON.stringify(updates);
     this._assertPayloadSize(json, "updateMessage");
     const encrypted = await this._encrypt(json);
@@ -283,33 +298,36 @@ var ReiClient = class {
   }
   // ─── 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).
+   * Sanitize `avatarUrl` on an outgoing payload. If the value is unusable
+   * (`data:` URI / oversized / non-string), set the field to `null` on the
+   * payload, log a `console.warn`, and let the rest of the request go
+   * through. Avatar is cosmetic — failing the entire schedule / instant
+   * call over a bad image URL is too punishing. Mirrors the server-side
+   * soft-strip in `@rei-standard/amsg-server` 2.3.3+ and `@rei-standard/amsg-instant`
+   * 0.7.1+. See standards §6.2.
    *
    * @private
-   * @param {unknown} value
+   * @param {object|null|undefined} target - Payload-like object holding `avatarUrl`.
+   * @returns {boolean} `true` if the field was stripped, `false` otherwise.
    */
-  _validateAvatarUrl(value) {
-    if (value === void 0 || value === null) return;
+  _sanitizeAvatarUrl(target) {
+    if (!target || typeof target !== "object") return false;
+    const value = target.avatarUrl;
+    if (value === void 0 || value === null) return false;
+    let reason = null;
     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"
-      );
+      reason = "avatarUrl \u5FC5\u987B\u662F\u5B57\u7B26\u4E32";
+    } else if (/^data:/i.test(value)) {
+      reason = "\u5934\u50CF\u4E0D\u652F\u6301\u4F20\u5165 data: URI\uFF0C\u8BF7\u6539\u4E3A\u516C\u7F51\u53EF\u8BBF\u95EE\u7684 https:// \u56FE\u7247 URL";
+    } else if (value.length > AVATAR_URL_MAX_LENGTH) {
+      reason = `\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`;
     }
-    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 }
-      );
+    if (reason) {
+      console.warn("[rei-standard-amsg-client] avatarUrl \u4E0D\u5408\u6CD5\uFF0C\u5DF2\u7F6E\u7A7A\uFF1A", reason);
+      target.avatarUrl = null;
+      return true;
     }
+    return false;
   }
   /**
    * Reject outgoing payloads larger than 3 KB pre-encryption. Spares the

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).
@@ -170,16 +181,16 @@ 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.
+   * If `avatarUrl` is unusable (`data:` URI, > 2 KB, or non-string), the
+   * client soft-strips it on the payload and emits a `console.warn` — the
+   * schedule still ships, just without an avatar. The only throw left is
+   * `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) {
-    this._validateAvatarUrl(payload && payload.avatarUrl);
+    this._sanitizeAvatarUrl(payload);
     const json = JSON.stringify(payload);
     this._assertPayloadSize(json, 'scheduleMessage');
     const encrypted = await this._encrypt(json);
@@ -219,10 +230,10 @@ 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.
+   * If `avatarUrl` is unusable (`data:` URI, > 2 KB, or non-string), the
+   * client soft-strips it on the payload and emits a `console.warn` — the
+   * push still ships, just without an icon. The only throw left is
+   * `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'.
@@ -230,7 +241,7 @@ class ReiClient {
    * @returns {Promise<Object>} `{ success, data?: { messagesSent, sentAt }, error? }`
    */
   async sendInstant(payload, endpointPath = '/instant', opts = {}) {
-    this._validateAvatarUrl(payload && payload.avatarUrl);
+    this._sanitizeAvatarUrl(payload);
     const json = JSON.stringify(payload);
     this._assertPayloadSize(json, 'sendInstant');
 
@@ -267,17 +278,23 @@ 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.
+   * If `updates.avatarUrl` is unusable (`data:` URI, > 2 KB, or non-string),
+   * the client soft-strips it from the patch and emits a `console.warn` —
+   * the rest of the update still applies, and the stored avatar is left
+   * untouched. The only throw left is `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) {
-    this._validateAvatarUrl(updates && updates.avatarUrl);
+    // Match server-side semantics: a stripped patch shouldn't overwrite the
+    // stored avatar with `null`. When sanitize fires, remove the field
+    // entirely so the existing image is preserved.
+    if (this._sanitizeAvatarUrl(updates)) {
+      delete updates.avatarUrl;
+    }
     const json = JSON.stringify(updates);
     this._assertPayloadSize(json, 'updateMessage');
     const encrypted = await this._encrypt(json);
@@ -370,33 +387,36 @@ class ReiClient {
   // ─── 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).
+   * Sanitize `avatarUrl` on an outgoing payload. If the value is unusable
+   * (`data:` URI / oversized / non-string), set the field to `null` on the
+   * payload, log a `console.warn`, and let the rest of the request go
+   * through. Avatar is cosmetic — failing the entire schedule / instant
+   * call over a bad image URL is too punishing. Mirrors the server-side
+   * soft-strip in `@rei-standard/amsg-server` 2.3.3+ and `@rei-standard/amsg-instant`
+   * 0.7.1+. See standards §6.2.
    *
    * @private
-   * @param {unknown} value
+   * @param {object|null|undefined} target - Payload-like object holding `avatarUrl`.
+   * @returns {boolean} `true` if the field was stripped, `false` otherwise.
    */
-  _validateAvatarUrl(value) {
-    if (value === undefined || value === null) return;
+  _sanitizeAvatarUrl(target) {
+    if (!target || typeof target !== 'object') return false;
+    const value = target.avatarUrl;
+    if (value === undefined || value === null) return false;
+    let reason = null;
     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'
-      );
+      reason = 'avatarUrl 必须是字符串';
+    } else if (/^data:/i.test(value)) {
+      reason = '头像不支持传入 data: URI，请改为公网可访问的 https:// 图片 URL';
+    } else if (value.length > AVATAR_URL_MAX_LENGTH) {
+      reason = `头像 URL 长度 ${value.length} 字符超过 ${AVATAR_URL_MAX_LENGTH} 上限，请改为更短的图片 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 }
-      );
+    if (reason) {
+      console.warn('[rei-standard-amsg-client] avatarUrl 不合法，已置空：', reason);
+      target.avatarUrl = null;
+      return true;
     }
+    return false;
   }
 
   /**

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).
@@ -170,16 +181,16 @@ 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.
+   * If `avatarUrl` is unusable (`data:` URI, > 2 KB, or non-string), the
+   * client soft-strips it on the payload and emits a `console.warn` — the
+   * schedule still ships, just without an avatar. The only throw left is
+   * `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) {
-    this._validateAvatarUrl(payload && payload.avatarUrl);
+    this._sanitizeAvatarUrl(payload);
     const json = JSON.stringify(payload);
     this._assertPayloadSize(json, 'scheduleMessage');
     const encrypted = await this._encrypt(json);
@@ -219,10 +230,10 @@ 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.
+   * If `avatarUrl` is unusable (`data:` URI, > 2 KB, or non-string), the
+   * client soft-strips it on the payload and emits a `console.warn` — the
+   * push still ships, just without an icon. The only throw left is
+   * `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'.
@@ -230,7 +241,7 @@ class ReiClient {
    * @returns {Promise<Object>} `{ success, data?: { messagesSent, sentAt }, error? }`
    */
   async sendInstant(payload, endpointPath = '/instant', opts = {}) {
-    this._validateAvatarUrl(payload && payload.avatarUrl);
+    this._sanitizeAvatarUrl(payload);
     const json = JSON.stringify(payload);
     this._assertPayloadSize(json, 'sendInstant');
 
@@ -267,17 +278,23 @@ 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.
+   * If `updates.avatarUrl` is unusable (`data:` URI, > 2 KB, or non-string),
+   * the client soft-strips it from the patch and emits a `console.warn` —
+   * the rest of the update still applies, and the stored avatar is left
+   * untouched. The only throw left is `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) {
-    this._validateAvatarUrl(updates && updates.avatarUrl);
+    // Match server-side semantics: a stripped patch shouldn't overwrite the
+    // stored avatar with `null`. When sanitize fires, remove the field
+    // entirely so the existing image is preserved.
+    if (this._sanitizeAvatarUrl(updates)) {
+      delete updates.avatarUrl;
+    }
     const json = JSON.stringify(updates);
     this._assertPayloadSize(json, 'updateMessage');
     const encrypted = await this._encrypt(json);
@@ -370,33 +387,36 @@ class ReiClient {
   // ─── 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).
+   * Sanitize `avatarUrl` on an outgoing payload. If the value is unusable
+   * (`data:` URI / oversized / non-string), set the field to `null` on the
+   * payload, log a `console.warn`, and let the rest of the request go
+   * through. Avatar is cosmetic — failing the entire schedule / instant
+   * call over a bad image URL is too punishing. Mirrors the server-side
+   * soft-strip in `@rei-standard/amsg-server` 2.3.3+ and `@rei-standard/amsg-instant`
+   * 0.7.1+. See standards §6.2.
    *
    * @private
-   * @param {unknown} value
+   * @param {object|null|undefined} target - Payload-like object holding `avatarUrl`.
+   * @returns {boolean} `true` if the field was stripped, `false` otherwise.
    */
-  _validateAvatarUrl(value) {
-    if (value === undefined || value === null) return;
+  _sanitizeAvatarUrl(target) {
+    if (!target || typeof target !== 'object') return false;
+    const value = target.avatarUrl;
+    if (value === undefined || value === null) return false;
+    let reason = null;
     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'
-      );
+      reason = 'avatarUrl 必须是字符串';
+    } else if (/^data:/i.test(value)) {
+      reason = '头像不支持传入 data: URI，请改为公网可访问的 https:// 图片 URL';
+    } else if (value.length > AVATAR_URL_MAX_LENGTH) {
+      reason = `头像 URL 长度 ${value.length} 字符超过 ${AVATAR_URL_MAX_LENGTH} 上限，请改为更短的图片 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 }
-      );
+    if (reason) {
+      console.warn('[rei-standard-amsg-client] avatarUrl 不合法，已置空：', reason);
+      target.avatarUrl = null;
+      return true;
     }
+    return false;
   }
 
   /**

package/dist/index.mjs

@@ -1,4 +1,17 @@
 // 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) {
@@ -82,16 +95,16 @@ 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.
+   * If `avatarUrl` is unusable (`data:` URI, > 2 KB, or non-string), the
+   * client soft-strips it on the payload and emits a `console.warn` — the
+   * schedule still ships, just without an avatar. The only throw left is
+   * `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) {
-    this._validateAvatarUrl(payload && payload.avatarUrl);
+    this._sanitizeAvatarUrl(payload);
     const json = JSON.stringify(payload);
     this._assertPayloadSize(json, "scheduleMessage");
     const encrypted = await this._encrypt(json);
@@ -128,10 +141,10 @@ 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.
+   * If `avatarUrl` is unusable (`data:` URI, > 2 KB, or non-string), the
+   * client soft-strips it on the payload and emits a `console.warn` — the
+   * push still ships, just without an icon. The only throw left is
+   * `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'.
@@ -139,7 +152,7 @@ var ReiClient = class {
    * @returns {Promise<Object>} `{ success, data?: { messagesSent, sentAt }, error? }`
    */
   async sendInstant(payload, endpointPath = "/instant", opts = {}) {
-    this._validateAvatarUrl(payload && payload.avatarUrl);
+    this._sanitizeAvatarUrl(payload);
     const json = JSON.stringify(payload);
     this._assertPayloadSize(json, "sendInstant");
     const headers = { "Content-Type": "application/json" };
@@ -170,17 +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.
+   * If `updates.avatarUrl` is unusable (`data:` URI, > 2 KB, or non-string),
+   * the client soft-strips it from the patch and emits a `console.warn` —
+   * the rest of the update still applies, and the stored avatar is left
+   * untouched. The only throw left is `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) {
-    this._validateAvatarUrl(updates && updates.avatarUrl);
+    if (this._sanitizeAvatarUrl(updates)) {
+      delete updates.avatarUrl;
+    }
     const json = JSON.stringify(updates);
     this._assertPayloadSize(json, "updateMessage");
     const encrypted = await this._encrypt(json);
@@ -260,33 +276,36 @@ var ReiClient = class {
   }
   // ─── 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).
+   * Sanitize `avatarUrl` on an outgoing payload. If the value is unusable
+   * (`data:` URI / oversized / non-string), set the field to `null` on the
+   * payload, log a `console.warn`, and let the rest of the request go
+   * through. Avatar is cosmetic — failing the entire schedule / instant
+   * call over a bad image URL is too punishing. Mirrors the server-side
+   * soft-strip in `@rei-standard/amsg-server` 2.3.3+ and `@rei-standard/amsg-instant`
+   * 0.7.1+. See standards §6.2.
    *
    * @private
-   * @param {unknown} value
+   * @param {object|null|undefined} target - Payload-like object holding `avatarUrl`.
+   * @returns {boolean} `true` if the field was stripped, `false` otherwise.
    */
-  _validateAvatarUrl(value) {
-    if (value === void 0 || value === null) return;
+  _sanitizeAvatarUrl(target) {
+    if (!target || typeof target !== "object") return false;
+    const value = target.avatarUrl;
+    if (value === void 0 || value === null) return false;
+    let reason = null;
     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"
-      );
+      reason = "avatarUrl \u5FC5\u987B\u662F\u5B57\u7B26\u4E32";
+    } else if (/^data:/i.test(value)) {
+      reason = "\u5934\u50CF\u4E0D\u652F\u6301\u4F20\u5165 data: URI\uFF0C\u8BF7\u6539\u4E3A\u516C\u7F51\u53EF\u8BBF\u95EE\u7684 https:// \u56FE\u7247 URL";
+    } else if (value.length > AVATAR_URL_MAX_LENGTH) {
+      reason = `\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`;
     }
-    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 }
-      );
+    if (reason) {
+      console.warn("[rei-standard-amsg-client] avatarUrl \u4E0D\u5408\u6CD5\uFF0C\u5DF2\u7F6E\u7A7A\uFF1A", reason);
+      target.avatarUrl = null;
+      return true;
     }
+    return false;
   }
   /**
    * Reject outgoing payloads larger than 3 KB pre-encryption. Spares the
@@ -382,5 +401,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.3",
-  "description": "ReiStandard Active Messaging browser client SDK",
+  "version": "2.3.0-next.2",
+  "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.4"
+  },
   "devDependencies": {
     "tsup": "^8.0.0",
     "typescript": "^5.0.0"