@pluve/logger-sdk 0.0.13 → 0.0.15

package/README.md

@@ -12,33 +12,26 @@
 ## 快速开始
 
 ```ts
-import { LoggerSDK } from './core/loggerSDK';
+import { LoggerSDK } from '@pluve/logger-sdk';
 
 const sdk = LoggerSDK.getInstance();
 
 sdk.init({
-  // endpoint: 'https://logger.yfpharmacy.com/log', // 实际使用以 config 中 API 为准
-  appId: 'fe-vue-pc-seed-frontend',
-  env: 'develop',
-  logStage: 'develop',
-  debug: true,
-  // 采集与性能
+  appId: 'app',
+  logStage: 'product',
+  debug: false,
   enableGzip: true,
-  enableBatch: true,
-  batchSize: 10,
+  enableBatch: false,
+  batchSize: 20,
   batchInterval: 15000,
   maxPixelUrlLen: 8192,
-  // 重试
-  enableRetry: true,
-  maxRetries: 3,
-  retryDelay: 1000,
-  retryBackoff: true,
-  // 身份与鉴权
+  enableRetry: false,
   userId: 'u-001',
   storeCode: 's-001',
   token: '<token>',
-  // 采样率（可选）
   sampleRate: 1,
+  enableAutoCapture: true,
+  autoCapture: { js: true, promise: true, resource: true, wechat: true },
 });
 
 // 业务日志
@@ -57,6 +50,7 @@ sdk.setStage('testing');
 ## 配置项（节选）
 
 - enableGzip：是否启用 gzip 压缩（默认 true）
+- gzipBatchMinSize：开启批量压缩的最小 items 数量（默认 2）
 - enableBatch：是否启用批量上报（默认需显式开启）
 - batchSize：批量阈值（默认 10）
 - batchInterval：批量定时器间隔（默认 15000ms）
@@ -64,16 +58,24 @@ sdk.setStage('testing');
 - enableStorage：队列持久化开关（默认 true）
 - enableRetry/maxRetries/retryDelay/retryBackoff：重试相关配置
 - sampleRate/levelSampleRate/sourceSampleRate/pathSampleRate：采样配置
+- enableAutoCapture：自动采集总开关（默认开启）
+- autoCapture：细粒度开关 { js, promise, resource, wechat }
 
-详细定义参考类型文件：[sdkOptions.ts](src/pages/logger-sdk-tester/logger-sdk-v2/types/sdkOptions.ts).
+说明：
+
+- enableGzip 仅在启用批量模式时生效；当 items 数量 ≥ gzipBatchMinSize 时自动压缩，否则走未压缩编码
+- enableStorage 默认在开启批量时启用；即使未开启批量，若 enableStorage 未显式设为 false，也会启用
+- autoCapture 默认全部开启；可按需关闭各子项，或关闭总开关
+
+详细定义参考类型文件：[sdkOptions.ts](./src/types/sdkOptions.ts).
 
 ## 压缩实现
 
 - gzipCompress(data)
   - 浏览器支持 CompressionStream 时，流式 gzip 压缩，再转 Base64 字符串
-  - 不支持时，回退到 fflate.gzipSync(默认压缩级别)，转 Base64
+  - 不支持时，回退到 fflate.gzipSync，使用 btoa/Buffer 生成 Base64
   - 返回值为 Base64 字符串，适用于传输（像素图 URL/JSON 体）
-- 代码参考：[compression.ts](src/pages/logger-sdk-tester/logger-sdk-v2/compress/compression.ts).
+- 代码参考：[compression.ts](./src/compress/compression.ts).
 - 备注：当前默认压缩级别，无级别可调参数暴露；如需级别控制可在 fflate 路径引入配置。
 
 ## 传输适配
@@ -85,7 +87,7 @@ sdk.setStage('testing');
   - 请求体字符串化 safeStringify
   - enableGzip 时使用 gzipCompress 生成 Base64，Content-Type 设为 `application/json; charset=utf-8`
 - PixelImageTransport
-  - 字符串化 items，enableGzip 时压缩为 Base64，URL 参数附带 `gzip=1`
+  - 字符串化 items，enableGzip 时压缩为 Base64；非 gzip 情况下优先使用全局 Base64，其次 btoa，再次 encodeURIComponent；URL 参数附带 `gzip=1`
   - 构造像素上报 URL（含 appId、appStage、items、cacheBuster）
   - URL 超长打印警告
 - BeaconTransport
@@ -93,26 +95,26 @@ sdk.setStage('testing');
 
 代码参考：
 
-- 适配器选择：[transportAdapter.ts](src/pages/logger-sdk-tester/logger-sdk-v2/transport/transportAdapter.ts)
-- WeChat：[wechatTransport.ts](src/pages/logger-sdk-tester/logger-sdk-v2/transport/wechatTransport.ts)
-- Pixel Image：[pixelImageTransport.ts](src/pages/logger-sdk-tester/logger-sdk-v2/transport/pixelImageTransport.ts)
-- Beacon：[beaconTransport.ts](src/pages/logger-sdk-tester/logger-sdk-v2/transport/beaconTransport.ts)
+- 适配器选择：[transportAdapter.ts](./src/transport/transportAdapter.ts)
+- WeChat：[wechatTransport.ts](./src/transport/wechatTransport.ts)
+- Pixel Image：[pixelImageTransport.ts](./src/transport/pixelImageTransport.ts)
+- Beacon：[beaconTransport.ts](./src/transport/beaconTransport.ts)
 
 ## 批量与队列
 
 - 启用批量后，事件入队，当队列大小达到 batchSize 或定时器触发时 flush
 - flush：按 appId|stage 分组与分块（最多 200/块），批量发送成功后出队
-- 队列持久化：localforage 存储，页面刷新/卸载可恢复
+- 队列持久化：优先 IndexedDB（localforage），失败回退 localStorage；仅在浏览器环境启用
 - 页面事件触发 flush：visibilitychange（hidden）、pagehide、beforeunload
 - 代码参考：
-  - [queueManager.ts](src/pages/logger-sdk-tester/logger-sdk-v2/core/queueManager.ts)
-  - [loggerSDK.ts（flush/sendBatch）](src/pages/logger-sdk-tester/logger-sdk-v2/core/loggerSDK.ts#L452-L485)
+  - [queueManager.ts](./src/core/queueManager.ts)
+  - [loggerSDK.ts（flush/sendBatch）](./src/core/loggerSDK.ts#L394-L467)
 
 ## 重试策略
 
 - 单个事件 sendEvent 与批量 sendBatch 均支持 executeWithRetry
 - 可配置最大次数、基础延迟、指数退避
-- 代码参考：[retryManager.ts](src/pages/logger-sdk-tester/logger-sdk-v2/core/retryManager.ts)
+- 代码参考：[retryManager.ts](./src/core/retryManager.ts)
 
 ## 采样与开关
 
@@ -124,13 +126,13 @@ sdk.setStage('testing');
   - 综合 level/source/path/global 采样率
   - 基于 seed 哈希概率决定是否发送
 - 参考：
-  - [loggerSDK.ts（shouldSend）](src/pages/logger-sdk-tester/logger-sdk-v2/core/loggerSDK.ts#L348-L411)
-  - [api.ts](src/pages/logger-sdk-tester/logger-sdk-v2/types/api.ts)
+  - [loggerSDK.ts（shouldSend）](./src/core/loggerSDK.ts#L324-L365)
+  - [api.ts](./src/types/api.ts)
 
 ## 数据格式
 
 - LogEvent：标准化日志格式（logId/seq/appId/stage/level/traceId/frontendId/url/location/message/throwable/userId/storeCode/tags）
-  - 类型参考：[logEvent.ts](src/pages/logger-sdk-tester/logger-sdk-v2/types/logEvent.ts)
+  - 类型参考：[logEvent.ts](./src/types/logEvent.ts)
 - ReportData：上报批次（appId/appStage/items[]）
 
 ## 限制与注意
@@ -139,8 +141,72 @@ sdk.setStage('testing');
 - 像素图：URL 长度受限；压缩可显著降低长度但 Base64 会比二进制略增
 - 压缩：CompressionStream 不提供压缩级别参数；fflate 同步压缩适合小批量数据
 - 安全：不要在日志中包含敏感数据（token、密码、隐私信息等）
+- 依赖：js-base64、localforage 均为 peerDependencies；UMD 外部化由应用或 CDN 提供全局；ESM/CJS 下由应用安装解析
 
 ## 流程图
 
 - 完整 Mermaid 流程图见文件：
-  - [logger-sdk.mermaid](src/pages/logger-sdk-tester/logger-sdk-v2/logger-sdk.mermaid)
+  - [logger-sdk.mermaid](./src/logger-sdk.mermaid)
+  - [logger-sdk.svg](./src/logger-sdk.svg)
+
+## 类型与打包
+
+- 类型入口：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/compress/compression.js

@@ -40,7 +40,7 @@ async function gzipCompress(data) {
   } catch (e) {
     console.log("gzipCompress 压缩失败", e);
   }
-  return data;
+  throw new Error("gzipCompress 不支持压缩");
 }
 function convert2Base64FromArray(data) {
   let binary = "";
@@ -55,7 +55,7 @@ function convert2Base64FromArray(data) {
   }
   throw new Error("convert2Base64FromArray 不支持转换");
 }
-function convert2Base64(data) {
+async function convert2Base64(data) {
   if (typeof btoa !== "undefined") {
     try {
       return btoa(data);
@@ -65,6 +65,12 @@ function convert2Base64(data) {
   if (typeof Buffer !== "undefined") {
     return Buffer.from(data, "base64").toString("base64");
   }
+  try {
+    const mod = await import("js-base64");
+    return mod.Base64.encode(data);
+  } catch (e) {
+    console.log("convert2Base64 动态引入 js-base64 库失败", e);
+  }
   return data;
 }
 function isGzipSupported() {

package/dist/esm/core/loggerSDK.js

@@ -50,9 +50,9 @@ var LoggerSDK = class {
       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/core/queueManager.js

@@ -23,10 +23,7 @@ var QueueManager = class {
         return this.localforage;
       }
       try {
-        const mod = await import(
-          /* @vite-ignore */
-          "localforage"
-        );
+        const mod = await import("localforage");
         this.localforage = mod;
         return this.localforage;
       } catch (e) {

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,7 +20,7 @@ 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);
@@ -28,7 +28,7 @@ var PixelImageTransport = class {
       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);
     } else {
-      compressedBody = convert2Base64(body);
+      compressedBody = await convert2Base64(body);
     }
     const cacheBuster = `_=${Date.now()}`;
     const qs = `appId=${((_i = this.opts) == null ? void 0 : _i.appId) || ""}&appStage=${((_j = this.opts) == null ? void 0 : _j.logStage) || ""}&${param}=${encodeURIComponent(compressedBody)}&gzip=${((_k = this.opts) == null ? void 0 : _k.enableGzip) ? 1 : 0}&${cacheBuster}`;

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/compress/compression.d.ts

@@ -5,7 +5,7 @@
  */
 export declare function gzipCompress(data: string): Promise<string>;
 export declare function convert2Base64FromArray(data: any): any;
-export declare function convert2Base64(data: string): string;
+export declare function convert2Base64(data: string): Promise<string>;
 /**
  * 检查是否支持 gzip 压缩
  */

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.13",
+  "version": "0.0.15",
   "description": "logger sdk",
   "keywords": [
     "logger"
@@ -58,15 +58,14 @@
   },
   "devDependencies": {
     "jsdom": "^27.4.0",
-    "vitest": "^4.0.15",
-    "localforage": "^1.10.0",
-    "@mermaid-js/mermaid-cli": "^10.9.1"
+    "vitest": "^4.0.15"
   },
   "dependencies": {
     "fflate": "^0.8.2",
     "stacktrace-js": "^2.0.2"
   },
   "peerDependencies": {
-    "localforage": "^1.10.0"
+    "localforage": "^1.10.0",
+    "js-base64": "^3.7.8"
   }
 }