@be-link/cls-logger 1.0.1-beta.2 → 1.0.1-beta.20

package/README.md

@@ -1,6 +1,6 @@
 # @be-link/cls-logger
 
-腾讯云 CLS（`tencentcloud-cls-sdk-js-web`）日志上报封装，参考仓库内 `@be-link/utils` 的构建方式（Rollup 打包 + tsc 仅产出 d.ts）。
+腾讯云 CLS（`tencentcloud-cls-sdk-js-web` / `tencentcloud-cls-sdk-js-mini`）日志上报封装，支持 Web、H5 和小程序环境，提供统一的调用方式。
 
 ## 安装
 
@@ -8,58 +8,170 @@
 pnpm add @be-link/cls-logger
 ```
 
+> **注意**：
+>
+> 1. SDK 内部会自动根据运行环境加载对应的腾讯云 SDK（Web 或小程序），无需手动安装额外依赖。
+> 2. 如果业务对包体积有极致要求，建议使用**分环境引入方式**（见下文）。
+
 ## 使用
 
+### 1. 统一引入方式（推荐快速接入）
+
+无需关心运行环境（Web 或 小程序），SDK 内部会自动识别并适配。此方式包含全量逻辑，支持动态加载 SDK。
+
+```ts
+import clsLogger from '@be-link/cls-logger';
+
+// 初始化（建议在应用入口处调用）
+clsLogger.init({
+  projectId: 'my-project',
+  appId: 'my-app-id',
+  // 默认配置可不传
+  // tencentCloud: {
+  //   endpoint: 'https://ap-shanghai.cls.tencentcs.com',
+  //   topicID: '17475bcd-6315-4b20-859c-e7b087fb3683',
+  // },
+  source: 'my-source',
+});
+```
+
+### 2. 分环境引入方式（推荐生产环境使用）
+
+为了获得更小的包体积（Tree Shaking）和更清晰的逻辑，建议根据项目类型引入不同的入口。此方式将物理隔离 Web 和小程序的特有逻辑（如 Web 的 `fetch` 拦截 vs 小程序的 `wx.request` 拦截）。
+
+#### Web / H5 项目：
+
 ```ts
-import clsLogger, { ClsLogger } from '@be-link/cls-logger';
+// 仅包含 Web 相关逻辑，不再包含小程序代码
+import { clsLogger } from '@be-link/cls-logger/web';
 
 clsLogger.init({
-  topic_id: 'xxx',
-  projectName: 'my-project',
-  generateBaseFields: () => ({ env: 'prod', uid: 'u_1' }),
+  projectId: 'my-web-project',
+  // tencentCloud: { ... }, // 可选
+  source: 'web-source',
 });
+```
 
-// 直接上报（展开字段）
-clsLogger.put({ event: 'login', ok: true });
+#### 小程序项目：
 
-// 直接上报（JSON 放进单个 key，默认 “日志内容”）
-clsLogger.putJson({ event: 'click', x: 1, y: 2 });
+```ts
+// 仅包含小程序相关逻辑，不再包含 Web 代码
+import { clsLogger } from '@be-link/cls-logger/mini';
 
-// 入队（写入 localStorage，默认 15 条自动 flush）
-clsLogger.enqueue({ event: 'page_view', page: '/home' });
+clsLogger.init({
+  projectId: 'my-mini-project',
+  appId: 'wx123456789', // 小程序建议传入 appId
+  // tencentCloud: { ... }, // 可选
+  source: 'mini-source',
+});
 ```
 
-## 请求监控（requestMonitor）
+## 常用 API
 
-初始化后默认会开启 HTTP 请求监控（Web/H5：`fetch`/`XMLHttpRequest`；小程序：`wx.request`/`cloud.callFunction`），并把请求信息通过 `track('http', payload)` 上报。
+### 开发日志
 
-- **关闭**：`clsLogger.init({ requestMonitor: false })`
-- **忽略上报请求避免递归**：默认会忽略 CLS 上报域名（会把 `endpoint` 自动加入 `ignoreUrls`），并在内部增加了“上报发送”保护，避免上报请求在跨域失败时出现递归上报/死循环。
-- **自定义忽略**：`clsLogger.init({ requestMonitor: { ignoreUrls: ['example.com', /\\/internal\\//] } })`
+```ts
+// info / warn / error
+clsLogger.info('应用启动', { startUpTime: 120 });
+
+// Error 日志（支持直接传入 Error 对象，自动解析堆栈）
+try {
+  doSomething();
+} catch (err) {
+  clsLogger.error(err, { module: 'payment' });
+}
+```
 
-## 性能监控（performanceMonitor）
+### 自定义埋点 (Track)
 
-初始化后默认会开启性能监控，并通过 `track('perf', payload)` 上报，包含：
+```ts
+clsLogger.track('click_event', {
+  button: 'submit',
+  page: '/home',
+});
+```
 
-- **Web Vitals**：FCP/LCP/CLS/FID
-- **Navigation Timing**：TTFB 等
-- **Resource Timing**：资源加载耗时（`PerformanceObserver({ type: 'resource', buffered: true })`，首屏会比较多）
+### 统计埋点 (Stat)
 
-常见降噪配置：
+用于简单的计数/分布统计。
 
 ```ts
-import clsLogger from '@be-link/cls-logger';
+clsLogger.stat({
+  pageName: '首页',
+  scene: '入口',
+  subScene: '活动弹窗',
+  data: 1,
+});
+```
+
+## 功能特性
 
+### 1. 自动环境适配
+
+- **Web / H5**: 自动采集浏览器环境信息（UserAgent、屏幕尺寸、网络状态等）。
+- **小程序**: 自动采集小程序环境信息（系统信息、微信版本、网络类型等）。
+
+### 2. 请求监控 (Request Monitor)
+
+默认开启。
+
+- **Web**: 拦截 `fetch` / `XMLHttpRequest`。
+- **小程序**: 拦截 `wx.request` / `wx.cloud.callFunction`。
+
+### 3. 性能监控 (Performance Monitor)
+
+默认开启。
+
+- **Web**: 采集 FCP, LCP, CLS, FID 等 Core Web Vitals 及资源加载耗时。
+- **小程序**: 支持采集页面首屏渲染耗时 (`firstRender`)、路由切换耗时 (`route`) 及启动耗时 (`appLaunch`)。
+
+### 4. 行为埋点 (Behavior Monitor)
+
+默认开启，支持 PV (Page View) 和 UV (User View) 自动上报。
+
+- **UV ID**: 自动生成并持久化。小程序环境下优先尝试使用 `openid`。
+- **点击追踪**: 自动监听点击事件。
+  - **Web**: 识别带 `data-track-id` 的元素。
+    ```html
+    <!-- HTML -->
+    <button data-track-id="submit_btn">提交</button>
+    ```
+  - **小程序**: 识别带 `data-track-id` 的组件（需在 `dataset` 中）。
+    ```html
+    <!-- WXML -->
+    <button data-track-id="submit_btn" bindtap="handleClick">提交</button>
+    ```
+
+## 高级用法
+
+### 内存队列与批量发送
+
+SDK 默认开启内存队列，每 500ms 或达到 20 条日志时自动批量上报，以减少网络请求次数。可通过 `batch` 参数配置：
+
+```ts
 clsLogger.init({
-  topic_id: 'xxx',
-  projectName: 'my-project',
-  performanceMonitor: {
-    // 降低采样（0~1）
-    sampleRate: 0.1,
-    // 忽略本地开发资源 & sourcemap（按你的资源特征调整）
-    ignoreUrls: ['localhost:8080', /\\.map$/],
+  batch: {
+    maxSize: 20,
+    intervalMs: 500,
+    startupDelayMs: 1000, // 启动阶段合并窗口
   },
-  // 可选：启动阶段合并窗口，减少首屏 perf/resource 被 intervalMs 拆成多次上报
-  // batch: { startupDelayMs: 2000 },
+});
+```
+
+### 失败重试与本地缓存
+
+上报失败的日志会自动进入重试流程（指数退避算法）。若多次重试仍失败，日志会落盘到本地缓存（`localStorage` 或小程序 `Storage`），在下次应用启动时尝试重新上报。
+
+### 手动注入 SDK
+
+在某些特殊构建环境（如某些不允许动态 require 的小程序框架）下，可以手动注入：
+
+```ts
+import { clsLogger } from '@be-link/cls-logger/mini';
+import * as MiniSdk from 'tencentcloud-cls-sdk-js-mini';
+
+clsLogger.init({
+  tencentCloud: { topicID: 'xxx', endpoint: 'xxx' },
+  sdk: MiniSdk, // 手动传入 SDK 实例
 });
 ```

package/dist/ClsLogger.d.ts

@@ -1,98 +1,17 @@
-import { AsyncClient } from 'tencentcloud-cls-sdk-js-web';
-import type { ClsLoggerInitOptions, FlatFields, PutOptions, QueueItem, ReportLog } from './types';
-export declare class ClsLogger {
-    private client;
-    private topicId;
-    private endpoint;
-    private retryTimes;
-    private source;
-    private projectId;
-    private projectName;
-    private appId;
-    private appVersion;
-    private envType;
-    private userGenerateBaseFields;
-    private autoGenerateBaseFields;
-    private storageKey;
-    private batchSize;
-    private memoryQueue;
-    private batchMaxSize;
-    private batchIntervalMs;
-    private batchTimer;
-    private batchTimerDueAt;
-    private initTs;
-    private startupDelayMs;
-    private failedCacheKey;
-    private failedCacheMax;
-    private requestMonitorStarted;
-    private errorMonitorStarted;
-    private performanceMonitorStarted;
-    private behaviorMonitorStarted;
-    private behaviorMonitorCleanup;
-    userId: unknown;
-    userName: unknown;
-    init(options: ClsLoggerInitOptions): void;
-    private getBaseFields;
-    private startRequestMonitor;
-    private startErrorMonitor;
-    private startPerformanceMonitor;
-    private startBehaviorMonitor;
-    /**
-     * 停止行为埋点监听（PV/UV/点击）
-     * - 如需重启：可再次调用 init（或自行调用 init 后的默认启动逻辑）
-     */
-    stopBehaviorMonitor(): void;
-    getInstance(): AsyncClient;
-    private detectEnvType;
-    /**
-     * 直接上报：埋点入参必须是一维（扁平）Object
-     * - 非原始值（对象/数组等）会被自动 stringify 成 string
-     * - 最终会把 fields 展开成 CLS 的 content（key/value 都会转成 string）
-     */
-    put(fields: FlatFields, options?: PutOptions): void;
-    /**
-     * 直接上报：把 data 序列化后放入指定 key（默认 “日志内容”）
-     */
-    putJson(data: unknown, clsLoggerKey?: string, options?: PutOptions): void;
-    /**
-     * 入队：写入 localStorage 队列；达到 batchSize 自动 flush
-     * - 埋点入参必须是一维（扁平）Object，非原始值会被 stringify
-     */
-    enqueue(fields: FlatFields, options?: PutOptions): void;
-    /**
-     * 从 localStorage 读取队列并批量上报
-     */
-    flush(): void;
-    /**
-     * 批量上报（每条 item.data 展开为 log content）
-     */
-    putBatch(queue: QueueItem[]): void;
-    /**
-     * 参考《一、概述》：统一上报入口（内存队列 + 批量发送）
-     */
-    report(log: ReportLog): void;
-    private getDesiredBatchFlushDueAt;
-    info(message: string, data?: FlatFields): void;
-    warn(message: string, data?: FlatFields): void;
-    error(message: string, data?: FlatFields): void;
-    track(trackType: string, data?: FlatFields): void;
-    /**
-     * 立即发送内存队列
-     */
-    flushBatch(): Promise<void>;
-    private buildReportFields;
-    private sendReportLogs;
-    private retrySendReportLogs;
-    private cacheFailedReportLogs;
-    flushFailed(): void;
-    /**
-     * 统计/计数类日志：按字段展开上报（若 data 为空默认 1）
-     */
-    stat(param: {
-        pageName: string;
-        scene: string;
-        subScene: string;
-        data?: number | string;
-    }): void;
+import { ClsLoggerCore } from './ClsLoggerCore';
+import type { ClsSdkModule } from './clsSdkTypes';
+import type { FlatFields, RequestMonitorOptions, ErrorMonitorOptions, PerformanceMonitorOptions, BehaviorMonitorOptions, DeviceInfoOptions } from './types';
+/**
+ * 兼容版 ClsLogger（默认入口）
+ * - 保留了自动识别环境 + 动态 import 的逻辑
+ * - 如果业务想瘦身，建议改用 @be-link/cls-logger/web 或 /mini
+ */
+export declare class ClsLogger extends ClsLoggerCore {
+    protected loadSdk(): Promise<ClsSdkModule>;
+    protected installRequestMonitor(report: (type: string, data: FlatFields) => void, options: RequestMonitorOptions): void;
+    protected installErrorMonitor(report: (type: string, data: FlatFields) => void, options: boolean | ErrorMonitorOptions): void;
+    protected installPerformanceMonitor(report: (type: string, data: FlatFields) => void, options: boolean | PerformanceMonitorOptions): void;
+    protected installBehaviorMonitor(report: (type: string, data: FlatFields) => void, options: boolean | BehaviorMonitorOptions): () => void;
+    protected createDeviceInfoBaseFields(options: boolean | DeviceInfoOptions | undefined): (() => FlatFields) | null;
 }
 //# sourceMappingURL=ClsLogger.d.ts.map

package/dist/ClsLogger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ClsLogger.d.ts","sourceRoot":"","sources":["../src/ClsLogger.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ClsLogger.d.ts","sourceRoot":"","sources":["../src/ClsLogger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAOlD,OAAO,KAAK,EACV,UAAU,EACV,qBAAqB,EACrB,mBAAmB,EACnB,yBAAyB,EACzB,sBAAsB,EACtB,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAEjB;;;;GAIG;AACH,qBAAa,SAAU,SAAQ,aAAa;cAC1B,OAAO,IAAI,OAAO,CAAC,YAAY,CAAC;IAgGhD,SAAS,CAAC,qBAAqB,CAC7B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,KAAK,IAAI,EAChD,OAAO,EAAE,qBAAqB,GAC7B,IAAI;IAIP,SAAS,CAAC,mBAAmB,CAC3B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,KAAK,IAAI,EAChD,OAAO,EAAE,OAAO,GAAG,mBAAmB,GACrC,IAAI;IAIP,SAAS,CAAC,yBAAyB,CACjC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,KAAK,IAAI,EAChD,OAAO,EAAE,OAAO,GAAG,yBAAyB,GAC3C,IAAI;IAIP,SAAS,CAAC,sBAAsB,CAC9B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,KAAK,IAAI,EAChD,OAAO,EAAE,OAAO,GAAG,sBAAsB,GACxC,MAAM,IAAI;IAIb,SAAS,CAAC,0BAA0B,CAAC,OAAO,EAAE,OAAO,GAAG,iBAAiB,GAAG,SAAS,GAAG,CAAC,MAAM,UAAU,CAAC,GAAG,IAAI;CAGlH"}

package/dist/ClsLoggerCore.d.ts

@@ -0,0 +1,177 @@
+import type { ClsLoggerInitOptions, ErrorMonitorOptions, EnvType, FlatFields, PerformanceMonitorOptions, PutOptions, QueueItem, ReportLog, ReportOptions, RequestMonitorOptions, BehaviorMonitorOptions, DeviceInfoOptions } from './types';
+import type { ClsSdkModule } from './clsSdkTypes';
+/**
+ * CLS Logger 核心基类
+ * - 负责所有上报、队列、监控逻辑
+ * - 不包含具体的 SDK 加载实现（由子类负责）
+ * - 这样可以把 web/mini 的 SDK 依赖彻底解耦到子入口
+ */
+export declare abstract class ClsLoggerCore {
+    protected sdk: ClsSdkModule | null;
+    protected sdkPromise: Promise<ClsSdkModule> | null;
+    protected sdkOverride: unknown | null;
+    protected sdkLoaderOverride: (() => unknown | Promise<unknown>) | null;
+    protected client: {
+        PutLogs: (request: unknown) => Promise<unknown> | unknown;
+    } | null;
+    protected clientPromise: Promise<{
+        PutLogs: (request: unknown) => Promise<unknown> | unknown;
+    }> | null;
+    protected topicId: string | null;
+    protected endpoint: string;
+    protected retryTimes: number;
+    protected source: string;
+    protected enabled: boolean;
+    protected projectId: string;
+    protected projectName: string;
+    protected appId: string;
+    protected appVersion: string;
+    protected envType: EnvType;
+    protected userGenerateBaseFields: (() => FlatFields) | null;
+    protected autoGenerateBaseFields: (() => FlatFields) | null;
+    protected storageKey: string;
+    protected batchSize: number;
+    protected memoryQueue: ReportLog[];
+    protected batchMaxSize: number;
+    protected batchIntervalMs: number;
+    protected batchTimer: ReturnType<typeof setTimeout> | null;
+    protected batchTimerDueAt: number | null;
+    protected initTs: number;
+    protected startupDelayMs: number;
+    protected useIdleCallback: boolean;
+    protected idleTimeout: number;
+    protected visibilityCleanup: (() => void) | null;
+    protected failedCacheKey: string;
+    protected failedCacheMax: number;
+    protected requestMonitorStarted: boolean;
+    protected errorMonitorStarted: boolean;
+    protected performanceMonitorStarted: boolean;
+    protected behaviorMonitorStarted: boolean;
+    protected behaviorMonitorCleanup: (() => void) | null;
+    userId: unknown;
+    userName: unknown;
+    /**
+     * 子类必须实现此方法来加载 SDK
+     */
+    protected abstract loadSdk(): Promise<ClsSdkModule>;
+    /**
+     * 子类必须实现：安装请求监听
+     */
+    protected abstract installRequestMonitor(report: (type: string, data: FlatFields) => void, options: RequestMonitorOptions): void;
+    /**
+     * 子类必须实现：安装错误监控
+     */
+    protected abstract installErrorMonitor(report: (type: string, data: FlatFields) => void, options: boolean | ErrorMonitorOptions): void;
+    /**
+     * 子类必须实现：安装性能监控
+     */
+    protected abstract installPerformanceMonitor(report: (type: string, data: FlatFields) => void, options: boolean | PerformanceMonitorOptions): void;
+    /**
+     * 子类必须实现：安装行为埋点
+     */
+    protected abstract installBehaviorMonitor(report: (type: string, data: FlatFields) => void, options: boolean | BehaviorMonitorOptions): () => void;
+    /**
+     * 子类必须实现：创建设备信息获取器
+     */
+    protected abstract createDeviceInfoBaseFields(options: boolean | DeviceInfoOptions | undefined): (() => FlatFields) | null;
+    /**
+     * 子类可按需重写（默认检测 wx）
+     */
+    protected detectEnvType(): EnvType;
+    init(options: ClsLoggerInitOptions): void;
+    private getBaseFields;
+    /**
+     * 设置页面可见性监听
+     * - visibilitychange: 页面隐藏时使用 sendBeacon 发送队列
+     * - pagehide: 作为移动端 fallback
+     */
+    private setupVisibilityListener;
+    /**
+     * 同步发送内存队列（使用 sendBeacon）
+     * - 用于页面关闭时确保数据发送
+     * - sendBeacon 不可用时降级为缓存到 localStorage
+     */
+    private flushBatchSync;
+    /**
+     * 构建 sendBeacon 的 payload
+     */
+    private buildSendBeaconPayload;
+    private startRequestMonitor;
+    private startErrorMonitor;
+    private startPerformanceMonitor;
+    private startBehaviorMonitor;
+    /**
+     * 停止行为埋点监听（PV/UV/点击）
+     * - 如需重启：可再次调用 init（或自行调用 init 后的默认启动逻辑）
+     */
+    stopBehaviorMonitor(): void;
+    /**
+     * 获取 CLS client（按环境懒加载 SDK）
+     */
+    getInstance(): Promise<{
+        PutLogs: (request: unknown) => Promise<unknown> | unknown;
+    }>;
+    /**
+     * 直接上报：埋点入参必须是一维（扁平）Object
+     * - 非原始值（对象/数组等）会被自动 stringify 成 string
+     * - 最终会把 fields 展开成 CLS 的 content（key/value 都会转成 string）
+     */
+    put(fields: FlatFields, options?: PutOptions): void;
+    private putAsync;
+    /**
+     * 直接上报：把 data 序列化后放入指定 key（默认 “日志内容”）
+     */
+    putJson(data: unknown, clsLoggerKey?: string, options?: PutOptions): void;
+    /**
+     * 入队：写入 localStorage 队列；达到 batchSize 自动 flush
+     * - 埋点入参必须是一维（扁平）Object，非原始值会被 stringify
+     */
+    enqueue(fields: FlatFields, options?: PutOptions): void;
+    /**
+     * 从 localStorage 读取队列并批量上报
+     */
+    flush(): void;
+    /**
+     * 批量上报（每条 item.data 展开为 log content）
+     */
+    putBatch(queue: QueueItem[]): void;
+    private putBatchAsync;
+    /**
+     * 参考《一、概述》：统一上报入口（内存队列 + 批量发送）
+     */
+    report(log: ReportLog): void;
+    /**
+     * 调度批量发送
+     * - 支持 requestIdleCallback（浏览器空闲时执行）
+     * - 降级为 setTimeout
+     */
+    private scheduleFlush;
+    /**
+     * 取消已调度的批量发送
+     */
+    private cancelScheduledFlush;
+    private getDesiredBatchFlushDueAt;
+    info(message: string | Error, data?: FlatFields, options?: ReportOptions): void;
+    warn(message: string | Error, data?: FlatFields, options?: ReportOptions): void;
+    error(message: string | Error, data?: FlatFields, options?: ReportOptions): void;
+    track(trackType: string, data?: FlatFields): void;
+    /**
+     * 立即发送内存队列
+     */
+    flushBatch(): Promise<void>;
+    private buildReportFields;
+    private sendReportLogs;
+    private retrySendReportLogs;
+    private cacheFailedReportLogs;
+    flushFailed(): void;
+    /**
+     * 统计/计数类日志：按字段展开上报（若 data 为空默认 1）
+     */
+    stat(param: {
+        pageName: string;
+        scene: string;
+        subScene: string;
+        data?: number | string;
+    }): void;
+}
+//# sourceMappingURL=ClsLoggerCore.d.ts.map

package/dist/ClsLoggerCore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClsLoggerCore.d.ts","sourceRoot":"","sources":["../src/ClsLoggerCore.ts"],"names":[],"mappings":"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"}

package/dist/behaviorMonitor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"behaviorMonitor.d.ts","sourceRoot":"","sources":["../src/behaviorMonitor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAG3E,KAAK,QAAQ,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;AA8FzD,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,QAAQ,EAChB,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,sBAA2B,GACnC,MAAM,IAAI,CA4WZ"}
+{"version":3,"file":"behaviorMonitor.d.ts","sourceRoot":"","sources":["../src/behaviorMonitor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAK3E,KAAK,QAAQ,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;AAEzD,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,QAAQ,EAChB,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,sBAA2B,GACnC,MAAM,IAAI,CAKZ"}

package/dist/clsSdkTypes.d.ts

@@ -0,0 +1,18 @@
+export type ClsSdkModule = {
+    AsyncClient: new (options: {
+        endpoint: string;
+        retry_times?: number;
+    }) => {
+        PutLogs: (request: unknown) => Promise<unknown> | unknown;
+    };
+    Log: new (time: number) => {
+        addContent: (k: string, v: string) => void;
+    };
+    LogGroup: new (source: string) => {
+        setSource: (source: string) => void;
+        addLog: (log: unknown) => void;
+        getLogs: () => unknown[];
+    };
+    PutLogsRequest: new (topicId: string, logGroup: unknown) => unknown;
+};
+//# sourceMappingURL=clsSdkTypes.d.ts.map

package/dist/clsSdkTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clsSdkTypes.d.ts","sourceRoot":"","sources":["../src/clsSdkTypes.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG;IACzB,WAAW,EAAE,KAAK,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK;QACxE,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;KAC3D,CAAC;IACF,GAAG,EAAE,KAAK,IAAI,EAAE,MAAM,KAAK;QAAE,UAAU,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;IAC1E,QAAQ,EAAE,KAAK,MAAM,EAAE,MAAM,KAAK;QAChC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;QACpC,MAAM,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;QAC/B,OAAO,EAAE,MAAM,OAAO,EAAE,CAAC;KAC1B,CAAC;IACF,cAAc,EAAE,KAAK,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,KAAK,OAAO,CAAC;CACrE,CAAC"}

package/dist/deviceInfo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deviceInfo.d.ts","sourceRoot":"","sources":["../src/deviceInfo.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAwMtE,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,OAAO,GAAG,iBAAiB,GAAG,SAAS,GAC5C,CAAC,MAAM,UAAU,CAAC,GAAG,IAAI,CAyC3B"}
+{"version":3,"file":"deviceInfo.d.ts","sourceRoot":"","sources":["../src/deviceInfo.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAKtE,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,OAAO,GAAG,iBAAiB,GAAG,SAAS,GAC5C,CAAC,MAAM,UAAU,CAAC,GAAG,IAAI,CAK3B"}

package/dist/errorMonitor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errorMonitor.d.ts","sourceRoot":"","sources":["../src/errorMonitor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAG/D,KAAK,QAAQ,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;AA8MzD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,GAAE,OAAO,GAAG,mBAAmB,GAAG,SAAc,GAAG,IAAI,CAmBhH"}
+{"version":3,"file":"errorMonitor.d.ts","sourceRoot":"","sources":["../src/errorMonitor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAK/D,KAAK,QAAQ,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;AAEzD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,GAAE,OAAO,GAAG,mBAAmB,GAAG,SAAc,GAAG,IAAI,CAKhH"}