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

package/README.md

@@ -180,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;
@@ -205,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

@@ -117,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);
@@ -163,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'.
@@ -174,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" };
@@ -205,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);
@@ -295,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

@@ -181,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);
@@ -230,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'.
@@ -241,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');
 
@@ -278,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);
@@ -381,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

@@ -181,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);
@@ -230,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'.
@@ -241,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');
 
@@ -278,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);
@@ -381,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

@@ -95,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);
@@ -141,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'.
@@ -152,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" };
@@ -183,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);
@@ -273,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rei-standard/amsg-client",
-  "version": "2.3.0-next.0",
+  "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",
@@ -33,7 +33,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@rei-standard/amsg-shared": "0.1.0-next.0"
+    "@rei-standard/amsg-shared": "0.1.0-next.4"
   },
   "devDependencies": {
     "tsup": "^8.0.0",