@pluve/logger-sdk 0.0.14 → 0.0.16

package/README.md

@@ -50,6 +50,7 @@ sdk.setStage('testing');
 ## 配置项（节选）
 
 - enableGzip：是否启用 gzip 压缩（默认 true）
+- gzipBatchMinSize：开启批量压缩的最小 items 数量（默认 2）
 - enableBatch：是否启用批量上报（默认需显式开启）
 - batchSize：批量阈值（默认 10）
 - batchInterval：批量定时器间隔（默认 15000ms）
@@ -60,6 +61,12 @@ sdk.setStage('testing');
 - enableAutoCapture：自动采集总开关（默认开启）
 - autoCapture：细粒度开关 { js, promise, resource, wechat }
 
+说明：
+
+- enableGzip 仅在启用批量模式时生效；当 items 数量 ≥ gzipBatchMinSize 时自动压缩，否则走未压缩编码
+- enableStorage 默认在开启批量时启用；即使未开启批量，若 enableStorage 未显式设为 false，也会启用
+- autoCapture 默认全部开启；可按需关闭各子项，或关闭总开关
+
 详细定义参考类型文件：[sdkOptions.ts](./src/types/sdkOptions.ts).
 
 ## 压缩实现
@@ -147,3 +154,59 @@ sdk.setStage('testing');
 - 类型入口：package.json exports.types 与 typesVersions 指向 dist/types
 - TypeScript 解析：推荐在应用设置 moduleResolution: "bundler" 或 "nodenext"/"node16"
 - 声明构建：`yarn build-types`（tsconfig.types.json 禁用默认 @types 扫描，避免冲突）
+
+## 依赖说明
+
+- peerDependencies（由应用安装或 CDN 提供）
+  - js-base64（^3.7.5）
+  - localforage（^1.10.0）
+- 安装示例（应用侧）
+  - `yarn add js-base64 localforage`
+- CDN 全局（UMD 产物）
+  - 先引入 js-base64 提供全局 Base64，再引入 logger-sdk UMD
+  - localforage 可选（IndexedDB 持久化），未提供时回退到 localStorage
+- 构建外部化（UMD）
+  - .fatherrc.ts 已将 js-base64 与 localforage 外部化映射到全局变量
+- 运行时回退策略
+  - PixelImageTransport：优先使用全局 Base64，其次 btoa，再次 encodeURIComponent
+  - 压缩：CompressionStream 优先；回退 fflate.gzipSync + btoa/Buffer
+  - 队列：优先 localforage（IndexedDB）；失败回退 localStorage（仅浏览器启用）
+
+## 编码细节（传输 × 压缩）
+
+- WechatTransport（POST）
+  - 未压缩
+    - Body：JSON（safeStringify(payload)）
+    - Header：Content-Type: application/json；token: <opts.token>
+    - items：字符串化后的数组（message/throwable 等为字符串）
+    - Endpoint：[config.getReportApi](.src/config/index.ts)
+  - 启用压缩
+    - items：safeStringify(items) 后使用 [gzipCompress](.src/compress/compression.ts) 生成 Base64
+    - Body：JSON（...payload, items: Base64）
+    - Header：Content-Type: application/json; charset=utf-8；token: <opts.token>
+
+- BeaconTransport（sendBeacon）
+  - 未压缩
+    - Body：JSON（safeStringify(payload)）
+    - Content-Type：application/json（通过 Blob 指定）
+    - 发送方式：navigator.sendBeacon(endpoint, blob)
+  - 启用压缩（满足批量条件或显式开启）
+    - items：safeStringify(items) 后 gzipCompress → Base64
+    - Body：JSON（...payload, items: Base64）
+    - Content-Type：application/json（Blob）
+
+- PixelImageTransport（Image GET）
+  - 未压缩
+    - items：safeStringify(items)
+    - 编码：优先使用 Base64.encode(items)，其次 encodeURIComponent(items)
+    - Query 参数：items=encodeURIComponent(编码结果)；gzip=0；携带 appId、appStage、cacheBuster
+  - 启用压缩
+    - items：safeStringify(items) 后 gzipCompress → Base64
+    - Query 参数：items=encodeURIComponent(Base64)；gzip=1；携带 appId、appStage、cacheBuster
+  - URL 长度检查：默认最大 8192，超长打印警告
+
+说明：
+
+- Base64 来源优先级：全局 Base64（CDN 或应用注入） > 原生 btoa > encodeURIComponent 回退
+- 压缩实现优先级：CompressionStream（浏览器） > fflate.gzipSync（通用），均返回 Base64 字符串便于传输
+- 所有传输模式的 items 都基于统一结构（level/traceId/frontendId/location/message/throwable）

package/dist/esm/core/loggerSDK.js

@@ -43,16 +43,17 @@ var LoggerSDK = class {
   init(options) {
     this.opts = {
       // endpoint: options.endpoint,
-      appId: `${options.appId}-frontend` || "unknown",
+      appId: `${options.appId}`,
+      // 统一与 zadig 部署应用 APPID 保持一致
       env: options.env || "develop",
       /** 日志环境 */
       logStage: options.logStage,
       debug: !!options.debug,
       /** 是否启用 gzip 压缩，默认 true */
       enableGzip: options.enableGzip !== false,
-      // 默认启用
-      gzipOnlyInBatchMode: options.gzipOnlyInBatchMode !== false,
-      // 默认启用
+      // 默认启用，但仅在批量模式开启情况下有效
+      gzipBatchMinSize: options.gzipBatchMinSize || 2,
+      // 默认 2 条数据开启 gzip 压缩
       /** 最大像素图 URL 长度，默认 1900 */
       maxPixelUrlLen: options.maxPixelUrlLen || 8192,
       // 批量上报配置（默认关闭，需显式开启）

package/dist/esm/transport/beaconTransport.js

@@ -18,7 +18,7 @@ var BeaconTransport = class {
     let body = typeof payload === "string" ? payload : safeStringify(payload);
     const endpoint = getReportApi(((_a = this.opts) == null ? void 0 : _a.env) || "develop");
     let contentType = "application/json";
-    if (((_b = this.opts) == null ? void 0 : _b.enableGzip) && (!((_c = this.opts) == null ? void 0 : _c.gzipOnlyInBatchMode) || payload.items.length > 0)) {
+    if (((_b = this.opts) == null ? void 0 : _b.enableGzip) && payload.items.length >= ((_c = this.opts) == null ? void 0 : _c.gzipBatchMinSize)) {
       const compressedItems = await gzipCompress(safeStringify(payload.items));
       body = safeStringify({
         ...payload,

package/dist/esm/transport/pixelImageTransport.js

@@ -20,11 +20,10 @@ var PixelImageTransport = class {
     const param = "items";
     const maxLen = ((_b = this.opts) == null ? void 0 : _b.maxPixelUrlLen) || 8192;
     let compressedBody;
-    if (((_c = this.opts) == null ? void 0 : _c.enableGzip) && (!((_d = this.opts) == null ? void 0 : _d.gzipOnlyInBatchMode) || payload.items.length > 0)) {
+    if (((_c = this.opts) == null ? void 0 : _c.enableGzip) && payload.items.length >= ((_d = this.opts) == null ? void 0 : _d.gzipBatchMinSize)) {
       const t = now();
       logDebug(!!((_e = this.opts) == null ? void 0 : _e.debug), "PixelImage request gzip compress body: ", body);
       compressedBody = await gzipCompress(body);
-      compressedBody = await convert2Base64(compressedBody);
       logDebug(!!((_f = this.opts) == null ? void 0 : _f.debug), "PixelImage request gzip compress cost: ", now() - t);
       logDebug(!!((_g = this.opts) == null ? void 0 : _g.debug), `original body size: ${body.length}, compressed body size: ${compressedBody.length}`);
       logDebug(!!((_h = this.opts) == null ? void 0 : _h.debug), "PixelImage request gzip compress body: ", compressedBody);

package/dist/esm/transport/wechatTransport.js

@@ -19,7 +19,7 @@ var WechatTransport = class {
     const endpoint = getReportApi(((_a = this.opts) == null ? void 0 : _a.env) || "develop");
     const timeout = 1e4;
     let contentType = "application/json";
-    if (((_b = this.opts) == null ? void 0 : _b.enableGzip) && (!((_c = this.opts) == null ? void 0 : _c.gzipOnlyInBatchMode) || payload.items.length > 0)) {
+    if (((_b = this.opts) == null ? void 0 : _b.enableGzip) && payload.items.length >= ((_c = this.opts) == null ? void 0 : _c.gzipBatchMinSize)) {
       const t = now();
       logDebug(!!((_d = this.opts) == null ? void 0 : _d.debug), "WeChat request enable gzip compress: ", t);
       const compressedItems = await gzipCompress(safeStringify(payload.items));

package/dist/types/types/sdkOptions.d.ts

@@ -15,10 +15,10 @@ export interface SDKOptions {
     enableBatch?: boolean;
     /** 批量上报最大数量，默认 10 */
     batchSize?: number;
-    /** 是否启用 gzip 压缩，默认 true */
+    /** 是否启用 gzip 压缩，默认 true (仅在批量模式下有效) */
     enableGzip?: boolean;
-    /** 是否仅在批量模式下启用 gzip 压缩，默认 true */
-    gzipOnlyInBatchMode?: boolean;
+    /** 批量模式下启用 gzip 压缩的最小 items 数量，默认 2 */
+    gzipBatchMinSize?: number;
     /** 最大像素图 URL 长度，默认 1900 */
     maxPixelUrlLen?: number;
     /** 批量上报时间间隔（毫秒），默认 5000 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pluve/logger-sdk",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "description": "logger sdk",
   "keywords": [
     "logger"
@@ -58,8 +58,7 @@
   },
   "devDependencies": {
     "jsdom": "^27.4.0",
-    "vitest": "^4.0.15",
-    "@mermaid-js/mermaid-cli": "^10.9.1"
+    "vitest": "^4.0.15"
   },
   "dependencies": {
     "fflate": "^0.8.2",