@rei-standard/amsg-client 2.6.0 → 2.8.0

package/README.md

@@ -178,6 +178,13 @@ interface DeliverOptions {
                                                             // / X-Client-Token / Authorization
   authorization?: string;                                  // 透传成 Authorization header（与 sendInstant 对齐）
   endpointPath?: string;                                   // 默认 '/instant'，可改 '/continue' 续跑
+  compressRequest?: boolean | { thresholdBytes?: number }; // 可选请求体 gzip。不传/falsy = 关（行为不变）
+                                                            // true / {} = 开，阈值默认 16384 字节(16KB)
+                                                            // { thresholdBytes: N } = 开 + 自定义阈值
+                                                            // 仅当 body 超阈值且运行时有 CompressionStream 才压；
+                                                            // 否则发明文（优雅降级，绝不抛）。压时发 gzip 字节 +
+                                                            // 头 X-Amsg-Request-Encoding: gzip（非标准 Content-
+                                                            // Encoding），由接收端 gunzip。SSE / JSON 两路通用。
 }
 
 interface ObservedDeliveryReceipt {
@@ -199,6 +206,8 @@ interface RawReadMeta {
 
 > `onRawRead` 是诊断钩子：SSE 解析层默认丢弃 `:` 注释行（含每秒一发的 keepalive），出问题时无从判断「静默期里到底有没有字节到达」。挂上它就能在 raw `reader.read()` 这一层看到每次读到的原始字节与 keepalive 帧。不传则零开销、行为不变。
 
+> `compressRequest` 用于大 body 上传：开启后，要发的 JSON 在上网线前 gzip（中文 + 重复结构压缩比很高），网线上字节小了就能在慢/不稳链路的发送超时之前传完，且上下文一字不动。仅当 body 超阈值且运行时支持 `CompressionStream` 才压，否则照常发明文；压缩出错也兜回明文，永不影响发送。压缩的是请求体，与响应 / `onChunk` / `onRawRead` 无关。接收端需按 `X-Amsg-Request-Encoding: gzip` 头自行解压。
+
 ### `delivery.mode` 必须显式选
 
 | mode | 何时用 | outcome 取值 |

package/dist/index.cjs

@@ -36,7 +36,6 @@ module.exports = __toCommonJS(src_exports);
 var import_amsg_shared = require("@rei-standard/amsg-shared");
 var import_amsg_shared2 = require("@rei-standard/amsg-shared");
 var TEXT_ENCODER = new TextEncoder();
-var AVATAR_URL_MAX_LENGTH = 2048;
 function makeLocalError(code, message, details) {
   const err = new Error(`[rei-standard-amsg-client] ${message}`);
   err.code = code;
@@ -54,6 +53,25 @@ function classifyContentType(contentType) {
   if (/^application\/[\w.+-]+\+json$/.test(main)) return "json";
   return "unknown";
 }
+var COMPRESS_REQUEST_DEFAULT_THRESHOLD = 16384;
+var COMPRESS_REQUEST_HEADER = "X-Amsg-Request-Encoding";
+async function maybeCompressRequestBody(body, compressRequest) {
+  if (!compressRequest) return { body, header: null };
+  const threshold = typeof compressRequest === "object" && typeof compressRequest.thresholdBytes === "number" ? compressRequest.thresholdBytes : COMPRESS_REQUEST_DEFAULT_THRESHOLD;
+  try {
+    if (typeof CompressionStream === "undefined") return { body, header: null };
+    const bytes = new TextEncoder().encode(body);
+    if (bytes.length <= threshold) return { body, header: null };
+    const gz = new Uint8Array(
+      await new Response(
+        new Blob([bytes]).stream().pipeThrough(new CompressionStream("gzip"))
+      ).arrayBuffer()
+    );
+    return { body: gz, header: COMPRESS_REQUEST_HEADER };
+  } catch {
+    return { body, header: null };
+  }
+}
 var ReiClient = class {
   /**
    * @param {ReiClientConfig} config
@@ -316,7 +334,8 @@ var ReiClient = class {
       headers,
       authorization,
       endpointPath,
-      onRawRead
+      onRawRead,
+      compressRequest
     } = opts;
     if (!delivery || typeof delivery !== "object") {
       throw new TypeError("[rei-standard-amsg-client] deliver() requires opts.delivery (discriminated union)");
@@ -378,7 +397,8 @@ var ReiClient = class {
         const result = await this._runInstantTransport(built, {
           signal: internalAbort.signal,
           onChunk: wrappedOnChunk,
-          onRawRead
+          onRawRead,
+          compressRequest
         });
         if (finalized) return;
         transportEnded = true;
@@ -576,16 +596,7 @@ var ReiClient = class {
    */
   _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") {
-      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`;
-    }
+    const reason = (0, import_amsg_shared.validateAvatarUrl)(target.avatarUrl);
     if (reason) {
       console.warn("[rei-standard-amsg-client] avatarUrl \u4E0D\u5408\u6CD5\uFF0C\u5DF2\u7F6E\u7A7A\uFF1A", reason);
       target.avatarUrl = null;
@@ -657,21 +668,25 @@ var ReiClient = class {
    *
    * @private
    * @param {{ url: string, headers: Record<string, string>, body: string }} built
-   * @param {{ signal: AbortSignal, onChunk?: (p: unknown) => Promise<void> | void, onRawRead?: (meta: RawReadMeta) => void }} opts
+   * @param {{ signal: AbortSignal, onChunk?: (p: unknown) => Promise<void> | void, onRawRead?: (meta: RawReadMeta) => void, compressRequest?: boolean | { thresholdBytes?: number } }} opts
    *   `onRawRead` is forwarded to the SSE consumer for raw read-loop telemetry (see `DeliverOptions.onRawRead`).
+   *   `compressRequest` opts the request body into gzip before `fetch` (see `DeliverOptions.compressRequest`).
    * @returns {Promise<{ kind: 'sse' } | { kind: 'json', body: unknown }>}
    */
   async _runInstantTransport(built, opts) {
-    const { signal, onChunk, onRawRead } = opts;
+    const { signal, onChunk, onRawRead, compressRequest } = opts;
     const { url, headers, body } = built;
-    const res = await fetch(url, { method: "POST", headers, body, signal });
+    const { body: wireBody, header: compressionHeader } = await maybeCompressRequestBody(body, compressRequest);
+    const wireHeaders = compressionHeader ? { ...headers, [compressionHeader]: "gzip" } : headers;
+    const res = await fetch(url, { method: "POST", headers: wireHeaders, body: wireBody, signal });
     if (!res.ok) {
       const text2 = await res.text().catch(() => "");
       const err = new Error(`Instant request failed: ${res.status} ${text2}`);
       err.status = res.status;
       throw err;
     }
-    const contentType = res.headers.get("content-type") || "";
+    const rawContentType = res.headers.get("content-type");
+    const contentType = rawContentType || "";
     const kind = classifyContentType(contentType);
     if (kind === "sse") {
       if (!res.body) throw new Error("Response body is null");
@@ -681,7 +696,7 @@ var ReiClient = class {
         responseMeta: {
           status: res.status,
           contentEncoding: res.headers.get("content-encoding"),
-          contentType: res.headers.get("content-type")
+          contentType: rawContentType
         }
       });
       return { kind: "sse" };

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { base64UrlToBytes } from '@rei-standard/amsg-shared';
+import { base64UrlToBytes, validateAvatarUrl } from '@rei-standard/amsg-shared';
 export { MESSAGE_KIND, MESSAGE_TYPE, PUSH_SOURCE, buildContentPush, buildErrorPush, buildReasoningPush, buildToolRequestPush, isContentPush, isErrorPush, isReasoningPush, isToolRequestPush } from '@rei-standard/amsg-shared';
 
 /**
@@ -201,6 +201,17 @@ const TEXT_ENCODER = new TextEncoder();
  *   silently drops. Use it to tell "connection alive but no business data" apart from "no bytes flowing
  *   at all" when diagnosing stalled streams. Purely observational: throws are swallowed and never affect
  *   transport. Not invoked for the JSON transport.
+ * @property {boolean | { thresholdBytes?: number }} [compressRequest] - Opt-in gzip of the request
+ *   BODY before it is sent (applies to both the SSE and JSON transports — it compresses the request,
+ *   not the response). Omit / falsy = OFF and behavior is fully unchanged (backward compatible).
+ *   `true` or `{}` enables it at the default 16384-byte (16 KB) threshold; `{ thresholdBytes: N }`
+ *   sets a custom threshold. When enabled, the body is gzip-compressed only if its UTF-8 byte length
+ *   exceeds the threshold AND the runtime provides `CompressionStream`; otherwise it is sent as
+ *   plaintext (graceful degradation, never throws). On compression the request gains the custom
+ *   header `X-Amsg-Request-Encoding: gzip` (NOT standard `Content-Encoding`, which CDNs / proxies
+ *   would auto-decompress and double-decode) and the body is the raw gzip bytes — the receiving
+ *   worker is responsible for gunzipping. Use it when delivering large bodies over slow / flaky
+ *   uplinks where a big upload can outrun the connection's send timeout.
  */
 
 /**
@@ -220,14 +231,6 @@ const TEXT_ENCODER = new TextEncoder();
  * @property {number}  [status]                 - `res.status`. First call 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;
-
 function makeLocalError(code, message, details) {
   const err = new Error(`[rei-standard-amsg-client] ${message}`);
   err.code = code;
@@ -266,6 +269,68 @@ function classifyContentType(contentType) {
   return 'unknown';
 }
 
+/**
+ * Default size floor for request-body gzip: bodies at or below this are not
+ * worth compressing (the gzip header/overhead can outweigh the gain on tiny
+ * payloads). 16 KB matches the contract documented on `DeliverOptions.compressRequest`.
+ */
+const COMPRESS_REQUEST_DEFAULT_THRESHOLD = 16384;
+
+/**
+ * Custom request header used to mark a gzip-compressed body. Deliberately NOT
+ * the standard `Content-Encoding` — CDNs / reverse proxies (Cloudflare, etc.)
+ * auto-decompress `Content-Encoding: gzip` on the way in, which would double-
+ * decompress and corrupt the body. The receiving worker keys off this custom
+ * header to know it must gunzip the body itself.
+ */
+const COMPRESS_REQUEST_HEADER = 'X-Amsg-Request-Encoding';
+
+/**
+ * Optionally gzip a request body string before it hits `fetch`.
+ *
+ * Pure optimization with graceful degradation: returns the original plaintext
+ * body (and no extra header) whenever compression is disabled, the body is at
+ * or below the threshold, the runtime lacks `CompressionStream`, or anything
+ * throws. The wire bytes shrink (Chinese / repetitive JSON compresses ~5-8x)
+ * so large uploads finish before flaky links time out — without dropping any
+ * context. Decompression is the receiving worker's job (keyed off
+ * `X-Amsg-Request-Encoding: gzip`).
+ *
+ * @param {string} body - The already-serialized request body (plaintext JSON).
+ * @param {boolean | { thresholdBytes?: number } | undefined} compressRequest
+ *   `undefined`/falsy ⇒ disabled (no-op, backward compatible). `true` / `{}` ⇒
+ *   enabled at the 16 KB default. `{ thresholdBytes: N }` ⇒ enabled at N bytes.
+ * @returns {Promise<{ body: string | Uint8Array, header: string | null }>}
+ *   `header` is the gzip marker header name to set when compression happened,
+ *   or `null` to send plaintext with no extra header.
+ */
+async function maybeCompressRequestBody(body, compressRequest) {
+  // Disabled / no opt-in ⇒ behavior unchanged.
+  if (!compressRequest) return { body, header: null };
+
+  const threshold =
+    typeof compressRequest === 'object' && typeof compressRequest.thresholdBytes === 'number'
+      ? compressRequest.thresholdBytes
+      : COMPRESS_REQUEST_DEFAULT_THRESHOLD;
+
+  try {
+    if (typeof CompressionStream === 'undefined') return { body, header: null };
+
+    const bytes = new TextEncoder().encode(body);
+    if (bytes.length <= threshold) return { body, header: null };
+
+    const gz = new Uint8Array(
+      await new Response(
+        new Blob([bytes]).stream().pipeThrough(new CompressionStream('gzip'))
+      ).arrayBuffer()
+    );
+    return { body: gz, header: COMPRESS_REQUEST_HEADER };
+  } catch {
+    // Compression is an optimization, never a failure mode: fall back to plaintext.
+    return { body, header: null };
+  }
+}
+
 class ReiClient {
   /**
    * @param {ReiClientConfig} config
@@ -560,6 +625,7 @@ class ReiClient {
     const {
       delivery, timeoutMs, onChunk, postTransportGraceMs,
       signal, headers, authorization, endpointPath, onRawRead,
+      compressRequest,
     } = opts;
 
     if (!delivery || typeof delivery !== 'object') {
@@ -653,6 +719,7 @@ class ReiClient {
           signal: internalAbort.signal,
           onChunk: wrappedOnChunk,
           onRawRead,
+          compressRequest,
         });
         if (finalized) return;
         transportEnded = true;
@@ -916,16 +983,7 @@ class ReiClient {
    */
   _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') {
-      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`;
-    }
+    const reason = validateAvatarUrl(target.avatarUrl);
     if (reason) {
       console.warn('[rei-standard-amsg-client] avatarUrl 不合法，已置空：', reason);
       target.avatarUrl = null;
@@ -1005,15 +1063,23 @@ class ReiClient {
    *
    * @private
    * @param {{ url: string, headers: Record<string, string>, body: string }} built
-   * @param {{ signal: AbortSignal, onChunk?: (p: unknown) => Promise<void> | void, onRawRead?: (meta: RawReadMeta) => void }} opts
+   * @param {{ signal: AbortSignal, onChunk?: (p: unknown) => Promise<void> | void, onRawRead?: (meta: RawReadMeta) => void, compressRequest?: boolean | { thresholdBytes?: number } }} opts
    *   `onRawRead` is forwarded to the SSE consumer for raw read-loop telemetry (see `DeliverOptions.onRawRead`).
+   *   `compressRequest` opts the request body into gzip before `fetch` (see `DeliverOptions.compressRequest`).
    * @returns {Promise<{ kind: 'sse' } | { kind: 'json', body: unknown }>}
    */
   async _runInstantTransport(built, opts) {
-    const { signal, onChunk, onRawRead } = opts;
+    const { signal, onChunk, onRawRead, compressRequest } = opts;
     const { url, headers, body } = built;
 
-    const res = await fetch(url, { method: 'POST', headers, body, signal });
+    // Optionally gzip the request body (opt-in, graceful fallback to plaintext).
+    const { body: wireBody, header: compressionHeader } =
+      await maybeCompressRequestBody(body, compressRequest);
+    const wireHeaders = compressionHeader
+      ? { ...headers, [compressionHeader]: 'gzip' }
+      : headers;
+
+    const res = await fetch(url, { method: 'POST', headers: wireHeaders, body: wireBody, signal });
 
     if (!res.ok) {
       const text = await res.text().catch(() => '');
@@ -1022,7 +1088,8 @@ class ReiClient {
       throw err;
     }
 
-    const contentType = res.headers.get('content-type') || '';
+    const rawContentType = res.headers.get('content-type');
+    const contentType = rawContentType || '';
     const kind = classifyContentType(contentType);
     if (kind === 'sse') {
       if (!res.body) throw new Error('Response body is null');
@@ -1032,7 +1099,7 @@ class ReiClient {
         responseMeta: {
           status: res.status,
           contentEncoding: res.headers.get('content-encoding'),
-          contentType: res.headers.get('content-type'),
+          contentType: rawContentType,
         },
       });
       return { kind: 'sse' };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { base64UrlToBytes } from '@rei-standard/amsg-shared';
+import { base64UrlToBytes, validateAvatarUrl } from '@rei-standard/amsg-shared';
 export { MESSAGE_KIND, MESSAGE_TYPE, PUSH_SOURCE, buildContentPush, buildErrorPush, buildReasoningPush, buildToolRequestPush, isContentPush, isErrorPush, isReasoningPush, isToolRequestPush } from '@rei-standard/amsg-shared';
 
 /**
@@ -201,6 +201,17 @@ const TEXT_ENCODER = new TextEncoder();
  *   silently drops. Use it to tell "connection alive but no business data" apart from "no bytes flowing
  *   at all" when diagnosing stalled streams. Purely observational: throws are swallowed and never affect
  *   transport. Not invoked for the JSON transport.
+ * @property {boolean | { thresholdBytes?: number }} [compressRequest] - Opt-in gzip of the request
+ *   BODY before it is sent (applies to both the SSE and JSON transports — it compresses the request,
+ *   not the response). Omit / falsy = OFF and behavior is fully unchanged (backward compatible).
+ *   `true` or `{}` enables it at the default 16384-byte (16 KB) threshold; `{ thresholdBytes: N }`
+ *   sets a custom threshold. When enabled, the body is gzip-compressed only if its UTF-8 byte length
+ *   exceeds the threshold AND the runtime provides `CompressionStream`; otherwise it is sent as
+ *   plaintext (graceful degradation, never throws). On compression the request gains the custom
+ *   header `X-Amsg-Request-Encoding: gzip` (NOT standard `Content-Encoding`, which CDNs / proxies
+ *   would auto-decompress and double-decode) and the body is the raw gzip bytes — the receiving
+ *   worker is responsible for gunzipping. Use it when delivering large bodies over slow / flaky
+ *   uplinks where a big upload can outrun the connection's send timeout.
  */
 
 /**
@@ -220,14 +231,6 @@ const TEXT_ENCODER = new TextEncoder();
  * @property {number}  [status]                 - `res.status`. First call 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;
-
 function makeLocalError(code, message, details) {
   const err = new Error(`[rei-standard-amsg-client] ${message}`);
   err.code = code;
@@ -266,6 +269,68 @@ function classifyContentType(contentType) {
   return 'unknown';
 }
 
+/**
+ * Default size floor for request-body gzip: bodies at or below this are not
+ * worth compressing (the gzip header/overhead can outweigh the gain on tiny
+ * payloads). 16 KB matches the contract documented on `DeliverOptions.compressRequest`.
+ */
+const COMPRESS_REQUEST_DEFAULT_THRESHOLD = 16384;
+
+/**
+ * Custom request header used to mark a gzip-compressed body. Deliberately NOT
+ * the standard `Content-Encoding` — CDNs / reverse proxies (Cloudflare, etc.)
+ * auto-decompress `Content-Encoding: gzip` on the way in, which would double-
+ * decompress and corrupt the body. The receiving worker keys off this custom
+ * header to know it must gunzip the body itself.
+ */
+const COMPRESS_REQUEST_HEADER = 'X-Amsg-Request-Encoding';
+
+/**
+ * Optionally gzip a request body string before it hits `fetch`.
+ *
+ * Pure optimization with graceful degradation: returns the original plaintext
+ * body (and no extra header) whenever compression is disabled, the body is at
+ * or below the threshold, the runtime lacks `CompressionStream`, or anything
+ * throws. The wire bytes shrink (Chinese / repetitive JSON compresses ~5-8x)
+ * so large uploads finish before flaky links time out — without dropping any
+ * context. Decompression is the receiving worker's job (keyed off
+ * `X-Amsg-Request-Encoding: gzip`).
+ *
+ * @param {string} body - The already-serialized request body (plaintext JSON).
+ * @param {boolean | { thresholdBytes?: number } | undefined} compressRequest
+ *   `undefined`/falsy ⇒ disabled (no-op, backward compatible). `true` / `{}` ⇒
+ *   enabled at the 16 KB default. `{ thresholdBytes: N }` ⇒ enabled at N bytes.
+ * @returns {Promise<{ body: string | Uint8Array, header: string | null }>}
+ *   `header` is the gzip marker header name to set when compression happened,
+ *   or `null` to send plaintext with no extra header.
+ */
+async function maybeCompressRequestBody(body, compressRequest) {
+  // Disabled / no opt-in ⇒ behavior unchanged.
+  if (!compressRequest) return { body, header: null };
+
+  const threshold =
+    typeof compressRequest === 'object' && typeof compressRequest.thresholdBytes === 'number'
+      ? compressRequest.thresholdBytes
+      : COMPRESS_REQUEST_DEFAULT_THRESHOLD;
+
+  try {
+    if (typeof CompressionStream === 'undefined') return { body, header: null };
+
+    const bytes = new TextEncoder().encode(body);
+    if (bytes.length <= threshold) return { body, header: null };
+
+    const gz = new Uint8Array(
+      await new Response(
+        new Blob([bytes]).stream().pipeThrough(new CompressionStream('gzip'))
+      ).arrayBuffer()
+    );
+    return { body: gz, header: COMPRESS_REQUEST_HEADER };
+  } catch {
+    // Compression is an optimization, never a failure mode: fall back to plaintext.
+    return { body, header: null };
+  }
+}
+
 class ReiClient {
   /**
    * @param {ReiClientConfig} config
@@ -560,6 +625,7 @@ class ReiClient {
     const {
       delivery, timeoutMs, onChunk, postTransportGraceMs,
       signal, headers, authorization, endpointPath, onRawRead,
+      compressRequest,
     } = opts;
 
     if (!delivery || typeof delivery !== 'object') {
@@ -653,6 +719,7 @@ class ReiClient {
           signal: internalAbort.signal,
           onChunk: wrappedOnChunk,
           onRawRead,
+          compressRequest,
         });
         if (finalized) return;
         transportEnded = true;
@@ -916,16 +983,7 @@ class ReiClient {
    */
   _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') {
-      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`;
-    }
+    const reason = validateAvatarUrl(target.avatarUrl);
     if (reason) {
       console.warn('[rei-standard-amsg-client] avatarUrl 不合法，已置空：', reason);
       target.avatarUrl = null;
@@ -1005,15 +1063,23 @@ class ReiClient {
    *
    * @private
    * @param {{ url: string, headers: Record<string, string>, body: string }} built
-   * @param {{ signal: AbortSignal, onChunk?: (p: unknown) => Promise<void> | void, onRawRead?: (meta: RawReadMeta) => void }} opts
+   * @param {{ signal: AbortSignal, onChunk?: (p: unknown) => Promise<void> | void, onRawRead?: (meta: RawReadMeta) => void, compressRequest?: boolean | { thresholdBytes?: number } }} opts
    *   `onRawRead` is forwarded to the SSE consumer for raw read-loop telemetry (see `DeliverOptions.onRawRead`).
+   *   `compressRequest` opts the request body into gzip before `fetch` (see `DeliverOptions.compressRequest`).
    * @returns {Promise<{ kind: 'sse' } | { kind: 'json', body: unknown }>}
    */
   async _runInstantTransport(built, opts) {
-    const { signal, onChunk, onRawRead } = opts;
+    const { signal, onChunk, onRawRead, compressRequest } = opts;
     const { url, headers, body } = built;
 
-    const res = await fetch(url, { method: 'POST', headers, body, signal });
+    // Optionally gzip the request body (opt-in, graceful fallback to plaintext).
+    const { body: wireBody, header: compressionHeader } =
+      await maybeCompressRequestBody(body, compressRequest);
+    const wireHeaders = compressionHeader
+      ? { ...headers, [compressionHeader]: 'gzip' }
+      : headers;
+
+    const res = await fetch(url, { method: 'POST', headers: wireHeaders, body: wireBody, signal });
 
     if (!res.ok) {
       const text = await res.text().catch(() => '');
@@ -1022,7 +1088,8 @@ class ReiClient {
       throw err;
     }
 
-    const contentType = res.headers.get('content-type') || '';
+    const rawContentType = res.headers.get('content-type');
+    const contentType = rawContentType || '';
     const kind = classifyContentType(contentType);
     if (kind === 'sse') {
       if (!res.body) throw new Error('Response body is null');
@@ -1032,7 +1099,7 @@ class ReiClient {
         responseMeta: {
           status: res.status,
           contentEncoding: res.headers.get('content-encoding'),
-          contentType: res.headers.get('content-type'),
+          contentType: rawContentType,
         },
       });
       return { kind: 'sse' };

package/dist/index.mjs

@@ -1,5 +1,5 @@
 // src/index.js
-import { base64UrlToBytes } from "@rei-standard/amsg-shared";
+import { base64UrlToBytes, validateAvatarUrl } from "@rei-standard/amsg-shared";
 import {
   MESSAGE_KIND,
   MESSAGE_TYPE,
@@ -14,7 +14,6 @@ import {
   isErrorPush
 } from "@rei-standard/amsg-shared";
 var TEXT_ENCODER = new TextEncoder();
-var AVATAR_URL_MAX_LENGTH = 2048;
 function makeLocalError(code, message, details) {
   const err = new Error(`[rei-standard-amsg-client] ${message}`);
   err.code = code;
@@ -32,6 +31,25 @@ function classifyContentType(contentType) {
   if (/^application\/[\w.+-]+\+json$/.test(main)) return "json";
   return "unknown";
 }
+var COMPRESS_REQUEST_DEFAULT_THRESHOLD = 16384;
+var COMPRESS_REQUEST_HEADER = "X-Amsg-Request-Encoding";
+async function maybeCompressRequestBody(body, compressRequest) {
+  if (!compressRequest) return { body, header: null };
+  const threshold = typeof compressRequest === "object" && typeof compressRequest.thresholdBytes === "number" ? compressRequest.thresholdBytes : COMPRESS_REQUEST_DEFAULT_THRESHOLD;
+  try {
+    if (typeof CompressionStream === "undefined") return { body, header: null };
+    const bytes = new TextEncoder().encode(body);
+    if (bytes.length <= threshold) return { body, header: null };
+    const gz = new Uint8Array(
+      await new Response(
+        new Blob([bytes]).stream().pipeThrough(new CompressionStream("gzip"))
+      ).arrayBuffer()
+    );
+    return { body: gz, header: COMPRESS_REQUEST_HEADER };
+  } catch {
+    return { body, header: null };
+  }
+}
 var ReiClient = class {
   /**
    * @param {ReiClientConfig} config
@@ -294,7 +312,8 @@ var ReiClient = class {
       headers,
       authorization,
       endpointPath,
-      onRawRead
+      onRawRead,
+      compressRequest
     } = opts;
     if (!delivery || typeof delivery !== "object") {
       throw new TypeError("[rei-standard-amsg-client] deliver() requires opts.delivery (discriminated union)");
@@ -356,7 +375,8 @@ var ReiClient = class {
         const result = await this._runInstantTransport(built, {
           signal: internalAbort.signal,
           onChunk: wrappedOnChunk,
-          onRawRead
+          onRawRead,
+          compressRequest
         });
         if (finalized) return;
         transportEnded = true;
@@ -554,16 +574,7 @@ var ReiClient = class {
    */
   _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") {
-      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`;
-    }
+    const reason = validateAvatarUrl(target.avatarUrl);
     if (reason) {
       console.warn("[rei-standard-amsg-client] avatarUrl \u4E0D\u5408\u6CD5\uFF0C\u5DF2\u7F6E\u7A7A\uFF1A", reason);
       target.avatarUrl = null;
@@ -635,21 +646,25 @@ var ReiClient = class {
    *
    * @private
    * @param {{ url: string, headers: Record<string, string>, body: string }} built
-   * @param {{ signal: AbortSignal, onChunk?: (p: unknown) => Promise<void> | void, onRawRead?: (meta: RawReadMeta) => void }} opts
+   * @param {{ signal: AbortSignal, onChunk?: (p: unknown) => Promise<void> | void, onRawRead?: (meta: RawReadMeta) => void, compressRequest?: boolean | { thresholdBytes?: number } }} opts
    *   `onRawRead` is forwarded to the SSE consumer for raw read-loop telemetry (see `DeliverOptions.onRawRead`).
+   *   `compressRequest` opts the request body into gzip before `fetch` (see `DeliverOptions.compressRequest`).
    * @returns {Promise<{ kind: 'sse' } | { kind: 'json', body: unknown }>}
    */
   async _runInstantTransport(built, opts) {
-    const { signal, onChunk, onRawRead } = opts;
+    const { signal, onChunk, onRawRead, compressRequest } = opts;
     const { url, headers, body } = built;
-    const res = await fetch(url, { method: "POST", headers, body, signal });
+    const { body: wireBody, header: compressionHeader } = await maybeCompressRequestBody(body, compressRequest);
+    const wireHeaders = compressionHeader ? { ...headers, [compressionHeader]: "gzip" } : headers;
+    const res = await fetch(url, { method: "POST", headers: wireHeaders, body: wireBody, signal });
     if (!res.ok) {
       const text2 = await res.text().catch(() => "");
       const err = new Error(`Instant request failed: ${res.status} ${text2}`);
       err.status = res.status;
       throw err;
     }
-    const contentType = res.headers.get("content-type") || "";
+    const rawContentType = res.headers.get("content-type");
+    const contentType = rawContentType || "";
     const kind = classifyContentType(contentType);
     if (kind === "sse") {
       if (!res.body) throw new Error("Response body is null");
@@ -659,7 +674,7 @@ var ReiClient = class {
         responseMeta: {
           status: res.status,
           contentEncoding: res.headers.get("content-encoding"),
-          contentType: res.headers.get("content-type")
+          contentType: rawContentType
         }
       });
       return { kind: "sse" };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rei-standard/amsg-client",
-  "version": "2.6.0",
+  "version": "2.8.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",
@@ -33,7 +33,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@rei-standard/amsg-shared": "0.2.0"
+    "@rei-standard/amsg-shared": "^0.3.0"
   },
   "devDependencies": {
     "tsup": "^8.0.0",