@pluve/mp-logger-sdk 0.0.1

package/README.md

@@ -0,0 +1,133 @@
+# @pluve/mp-logger-sdk
+
+微信小程序日志上报 SDK，专为小程序环境优化，剔除了浏览器相关逻辑与冗余依赖。
+
+## 概览
+
+- **环境支持**：仅支持微信小程序（WeChat Mini Program）
+- **采集与采样**：支持开关控制、日志等级白名单、分级/来源/路径采样率
+- **传输适配**：使用微信原生 `wx.request` 进行上报
+- **批量与队列**：支持批量上报（阈值与定时器双重触发）、队列持久化（使用 `wx.setStorageSync`）
+- **重试策略**：可配置最大重试次数与指数退避策略
+- **压缩能力**：支持 Gzip 压缩（使用 `fflate` + `wx.arrayBufferToBase64`），显著减少上报流量
+
+## 快速开始
+
+### 安装
+
+```bash
+pnpm add @pluve/mp-logger-sdk
+# 或
+npm install @pluve/mp-logger-sdk
+```
+
+### 使用示例
+
+```ts
+import { LoggerSDK } from '@pluve/mp-logger-sdk';
+
+const sdk = LoggerSDK.getInstance();
+
+// 1. 初始化 SDK
+sdk.init({
+  appId: 'your-app-id',
+  logStage: 'product', // 环境：develop/trial/release
+  token: 'your-access-token',
+  
+  // 可选配置
+  debug: false,
+  userId: 'u-001',
+  storeCode: 's-001',
+  
+  // 批量上报配置
+  enableBatch: true,
+  batchSize: 20,
+  batchInterval: 15000,
+  
+  // 压缩配置
+  enableGzip: true,
+  gzipBatchMinSize: 2,
+  
+  // 自动采集配置
+  enableAutoCapture: true,
+  autoCapture: {
+    wechat: true // 开启小程序异常自动捕获（JS Error & Promise Rejection）
+  },
+  
+  // 采样率（0.0 - 1.0）
+  sampleRate: 1,
+});
+
+// 2. 业务日志上报
+sdk.track({
+  message: '用户点击了购买按钮',
+  traceId: 'trace-xyz', // 可选：链路追踪 ID
+  logLevel: 'INFO',     // INFO | WARN | ERROR | FATAL
+});
+
+// 3. 动态设置用户信息
+sdk.identify('u-002');
+sdk.setStoreCode('s-002');
+```
+
+## 配置项说明
+
+详细类型定义请参考 [SDKOptions](./src/types/sdkOptions.ts)。
+
+| 配置项 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `appId` | `string` | (必填) | 应用标识 |
+| `token` | `string` | (必填) | 上报鉴权 Token |
+| `logStage` | `string` | (必填) | 日志环境（develop/trial/release） |
+| `enableBatch` | `boolean` | `false` | 是否启用批量上报 |
+| `batchSize` | `number` | `20` | 批量上报阈值（条数） |
+| `batchInterval` | `number` | `15000` | 批量上报时间间隔（ms） |
+| `enableGzip` | `boolean` | `true` | 是否启用 Gzip 压缩（仅批量模式生效） |
+| `enableStorage` | `boolean` | `true` | 是否启用队列持久化（使用 wx.storage） |
+| `enableRetry` | `boolean` | `true` | 是否启用失败重试 |
+| `enableAutoCapture` | `boolean` | `true` | 自动采集总开关 |
+| `sampleRate` | `number` | `1.0` | 全局采样率 (0.0-1.0) |
+
+## 核心特性实现原理
+
+### 1. 压缩实现
+- 使用轻量级 `fflate` 库进行 Gzip 压缩。
+- 压缩后使用小程序原生 API `wx.arrayBufferToBase64` 转换为 Base64 字符串。
+- 相比通用 Base64 库，利用原生能力大幅提升性能并减少包体积。
+- 代码参考：[compression.ts](./src/compress/compression.ts)
+
+### 2. 传输机制
+- **WechatTransport**：封装 `wx.request` 发送 POST 请求。
+- **编码方式**：
+  - 未压缩：Body 为 JSON 字符串。
+  - 启用压缩：将日志条目数组序列化并 Gzip 压缩为 Base64 字符串，作为字段 `items` 上报。
+- 代码参考：[wechatTransport.ts](./src/transport/wechatTransport.ts)
+
+### 3. 持久化队列
+- 使用 `wx.getStorageSync` / `wx.setStorageSync` 实现队列持久化。
+- 当发生异常或小程序退出时，未上报的日志会保存在本地，下次启动时自动恢复并尝试上报，防止数据丢失。
+- 代码参考：[queueManager.ts](./src/core/queueManager.ts)
+
+### 4. 堆栈解析
+- 内置轻量级堆栈解析器，替代庞大的 `stacktrace-js` 库。
+- 支持 V8 格式（开发者工具/Android）和 JSC 格式（iOS）的 Error Stack 解析。
+- 代码参考：[stacktrace.ts](./src/stack/stacktrace.ts)
+
+## 依赖说明
+
+- **fflate**: 用于 Gzip 压缩（已作为 `dependencies` 包含）。
+- **无其他运行时依赖**：移除了 `js-base64`、`localforage` 等浏览器端依赖。
+
+## 流程图
+
+![流程图](./src/logger-sdk.svg)
+
+## 构建
+
+```bash
+# 安装依赖
+pnpm install
+
+# 构建产物 (ESM + CJS)
+pnpm run build
+```

package/dist/cjs/capture/wechatError.js

@@ -0,0 +1,85 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/capture/wechatError.ts
+var wechatError_exports = {};
+__export(wechatError_exports, {
+  registerWechatErrorCapture: () => registerWechatErrorCapture,
+  registerWechatUnhandledCapture: () => registerWechatUnhandledCapture
+});
+module.exports = __toCommonJS(wechatError_exports);
+var import_stacktrace = require("../stack/stacktrace");
+var import_tools = require("../utils/tools");
+function registerWechatErrorCapture(debug, callback) {
+  try {
+    const wxAny = globalThis.wx;
+    if (wxAny && typeof wxAny.onError === "function") {
+      const handler = async (error) => {
+        (0, import_tools.logDebug)(debug, "registerWechatErrorCapture onError", error);
+        const msg = String((error == null ? void 0 : error.message) ?? error);
+        const err = error instanceof Error ? error : new Error(msg);
+        const stack = await (0, import_stacktrace.parseStack)(err);
+        callback({
+          type: "js",
+          message: err.message,
+          stack,
+          throwable: err.stack || ""
+        });
+      };
+      wxAny.onError(handler);
+      return () => {
+        try {
+          wxAny.offError && wxAny.offError(handler);
+        } catch {
+        }
+      };
+    }
+  } catch (e) {
+    (0, import_tools.logDebug)(debug, "registerWechatErrorCapture attach failed", e);
+  }
+  return void 0;
+}
+function registerWechatUnhandledCapture(debug, callback) {
+  try {
+    const wxAny = globalThis.wx;
+    if (wxAny && typeof wxAny.onUnhandledRejection === "function") {
+      const handler = async (res) => {
+        const reason = res == null ? void 0 : res.reason;
+        (0, import_tools.logDebug)(debug, "registerWechatUnhandledCapture onUnhandledRejection", reason);
+        const err = reason instanceof Error ? reason : new Error(String(reason));
+        const stack = await (0, import_stacktrace.parseStack)(err);
+        callback({
+          type: "promise",
+          message: err.message,
+          stack,
+          throwable: err.stack || ""
+        });
+      };
+      wxAny.onUnhandledRejection(handler);
+      return () => {
+        try {
+          wxAny.offUnhandledRejection && wxAny.offUnhandledRejection(handler);
+        } catch {
+        }
+      };
+    }
+  } catch (e) {
+    (0, import_tools.logDebug)(debug, "registerWechatUnhandledCapture attach failed", e);
+  }
+  return void 0;
+}

package/dist/cjs/compress/compression.js

@@ -0,0 +1,94 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/compress/compression.ts
+var compression_exports = {};
+__export(compression_exports, {
+  convert2Base64: () => convert2Base64,
+  convert2Base64FromArray: () => convert2Base64FromArray,
+  gzipCompress: () => gzipCompress,
+  isGzipSupported: () => isGzipSupported
+});
+module.exports = __toCommonJS(compression_exports);
+var import_fflate = require("fflate");
+function toUtf8Bytes(s) {
+  if (typeof TextEncoder !== "undefined") {
+    return new TextEncoder().encode(s);
+  }
+  const enc = encodeURIComponent(s);
+  const out = [];
+  for (let i = 0; i < enc.length; i += 1) {
+    const c = enc[i];
+    if (c === "%") {
+      out.push(parseInt(enc.slice(i + 1, i + 3), 16));
+      i += 2;
+    } else {
+      out.push(c.charCodeAt(0));
+    }
+  }
+  return new Uint8Array(out);
+}
+async function gzipCompress(data) {
+  try {
+    const input = toUtf8Bytes(data);
+    const compressed = (0, import_fflate.gzipSync)(input);
+    return convert2Base64FromArray(compressed);
+  } catch (e) {
+    console.log("gzipCompress 压缩失败", e);
+  }
+  throw new Error("gzipCompress 不支持压缩");
+}
+function isGzipSupported() {
+  return true;
+}
+function convert2Base64FromArray(data) {
+  try {
+    if (typeof wx !== "undefined" && wx.arrayBufferToBase64) {
+      if (data.byteLength !== data.buffer.byteLength) {
+        const copy = new Uint8Array(data);
+        return wx.arrayBufferToBase64(copy.buffer);
+      }
+      return wx.arrayBufferToBase64(data.buffer);
+    }
+  } catch (e) {
+  }
+  let binary = "";
+  for (let i = 0; i < data.length; i += 1) {
+    binary += String.fromCharCode(data[i]);
+  }
+  if (typeof btoa !== "undefined") {
+    return btoa(binary);
+  }
+  throw new Error("convert2Base64FromArray 不支持转换");
+}
+async function convert2Base64(data) {
+  if (typeof btoa !== "undefined") {
+    try {
+      return btoa(data);
+    } catch {
+    }
+  }
+  try {
+    const bytes = toUtf8Bytes(data);
+    if (typeof wx !== "undefined" && wx.arrayBufferToBase64) {
+      return wx.arrayBufferToBase64(bytes.buffer);
+    }
+  } catch (e) {
+  }
+  return data;
+}

package/dist/cjs/config/index.js

@@ -0,0 +1,48 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/config/index.ts
+var config_exports = {};
+__export(config_exports, {
+  getPixelBatchApi: () => getPixelBatchApi,
+  getRegisterApi: () => getRegisterApi,
+  getReportApi: () => getReportApi,
+  getSDKBaseApi: () => getSDKBaseApi
+});
+module.exports = __toCommonJS(config_exports);
+var getSDKBaseApi = (env) => {
+  switch (env) {
+    case "product":
+      return "https://apm.pharmacyyf.com";
+    case "testing":
+      return "https://apm-te.pharmacyyf.com";
+    case "develop":
+      return "https://chief-dev.yifengx.com";
+    default:
+      return "https://apm.pharmacyyf.com";
+  }
+};
+var getRegisterApi = (env) => {
+  return `${getSDKBaseApi(env)}/yfcloud-apm/log/front/init`;
+};
+var getReportApi = (env) => {
+  return `${getSDKBaseApi(env)}/yfcloud-apm/log/front/batchSave`;
+};
+var getPixelBatchApi = (env) => {
+  return `${getSDKBaseApi(env)}/yfcloud-apm/log/front/pixelBatchSave`;
+};

package/dist/cjs/core/fingerprint.js

@@ -0,0 +1,32 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/core/fingerprint.ts
+var fingerprint_exports = {};
+__export(fingerprint_exports, {
+  generateFingerprint: () => generateFingerprint
+});
+module.exports = __toCommonJS(fingerprint_exports);
+var import_tools = require("../utils/tools");
+function generateFingerprint(error) {
+  var _a;
+  const msg = (0, import_tools.normalizeMessage)(error.message);
+  const frame = (_a = error.stack) == null ? void 0 : _a[0];
+  const frameKey = frame ? `${frame.file}:${frame.line}` : "no_frame";
+  return `${error.type}|${msg}|${frameKey}`;
+}

package/dist/cjs/core/httpClient.js

@@ -0,0 +1,55 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/core/httpClient.ts
+var httpClient_exports = {};
+__export(httpClient_exports, {
+  HttpClient: () => HttpClient
+});
+module.exports = __toCommonJS(httpClient_exports);
+var import_tools = require("../utils/tools");
+var HttpClient = class {
+  /**
+   * 发送 POST 请求,需要兼容浏览器和微信小程序
+   */
+  static async post(url, data, token) {
+    (0, import_tools.logDebug)(true, "post", url, data, token);
+    return new Promise((resolve, reject) => {
+      wx.request({
+        url,
+        method: "POST",
+        data,
+        header: {
+          "Content-Type": "application/json",
+          token
+        },
+        success: (res) => resolve({
+          type: "wechat",
+          response: res
+        }),
+        fail: (err) => (
+          // eslint-disable-next-line prefer-promise-reject-errors
+          reject({
+            type: "wechat",
+            error: err
+          })
+        )
+      });
+    });
+  }
+};