cwj_monitoring 0.0.23 → 0.0.25

package/dist/index.d.ts

@@ -1,25 +1,302 @@
-type Plugin = 'error' | 'click' | 'performance' | 'router';
+/**
+ * 事件发送类型标识符
+ * 用于向追踪系统发送事件时使用
+ */
+declare enum EMIT_TYPE {
+    ERROR = "error",
+    BEHAVIOR_CLICK = "click",
+    ROUTE_CHANGE = "route_change",
+    PERFORMANCE_FP = "performance_fp",
+    PERFORMANCE_FCP = "performance_fcp",
+    PERFORMANCE_LCP = "performance_lcp",
+    PERFORMANCE_INP = "performance_inp",
+    PERFORMANCE_LONGTASK = "performance_longtask",
+    PERFORMANCE_RESOURCE = "performance_resource",
+    PERFORMANCE_LOAF = "performance_loaf",
+    XHR = "xhr",
+    FETCH = "fetch",
+    CUSTOM = "custom"
+}
+
+/**
+ * 插件执行上下文
+ * 提供插件所需的最小功能集，实现插件与核心实例的解耦
+ */
+interface PluginContext {
+    /** 发送事件 */
+    emit: (type: EMIT_TYPE | string, data: any) => void;
+    /** 监控上报地址（用于网络插件过滤） */
+    url: string;
+}
+/**
+ * 基础插件接口
+ * 所有监控插件必须实现此接口
+ */
+interface IPlugin {
+    /**
+     * 唯一的插件标识符
+     */
+    readonly name: string;
+    /**
+     * 插件安装函数
+     * 当插件注册到追踪器时调用
+     *
+     * @param context - 插件执行上下文
+     */
+    install(context: PluginContext): void;
+    /**
+     * 插件卸载函数（可选）
+     * 用于清理监听器等
+     */
+    uninstall?(): void;
+}
+
+/**
+ * SDK 收集的完整设备信息
+ */
+interface Device {
+  /** 浏览器信息 */
+  browser: {
+    name?: string;
+    version?: string;
+  };
+  /** 操作系统 */
+  os: {
+    name?: string;
+    version?: string;
+    versionName?: string;
+  };
+  /** 设备种类 */
+  platform: {
+    type?: string;
+  };
+  /** 浏览器缩放比例 */
+  ratio: number;
+  /** 浏览器宽高 */
+  wh: {
+    /** 浏览器宽 */
+    width: number;
+    /** 浏览器高 */
+    height: number;
+  };
+}
+
+/**
+ * 发送到监控后端的数据格式
+ */
+interface MonitoringPayload {
+  /** 设备信息 */
+  device: Device;
+  /** 唯一访客标识（指纹） */
+  uuid: string;
+  /** 事件类型 */
+  type: string;
+  /** 事件特定数据 */
+  data: any;
+  /** ISO 8601 格式的时间戳 */
+  date: string;
+  /** 用户自定义元数据 */
+  userData?: Record<string, any>;
+}
+
+/**
+ * 数据发送和批处理配置
+ */
+interface TransportConfig {
+  /**
+   * 批量发送前的最大事件数
+   * @default 5
+   */
+  maxBatchSize?: number;
+  /**
+   * 批量发送前的最大等待时间（毫秒）
+   * @default 30000（30秒）
+   */
+  maxWaitTime?: number;
+}
 
-//初始化时传入的参数
+
+/**
+ * SDK 初始化配置选项
+ */
 interface Options {
+  /**
+   * 发送监控数据的后端 URL
+   * @required 必填
+   */
   url: string;
-  max?: number;
-  time?: number;
-  plugin?: Plugin[];
-  data?: any;
+
+  /**
+   * 要启用的插件列表
+   * @optional 可选
+   */
+  plugin?: IPlugin[];
+
+  /**
+   * 附加到所有事件的自定义用户元数据
+   * 用于存储应用版本、环境、用户属性等
+   * @optional 可选
+   * @example { version: '1.2.3', env: 'production', userId: '12345' }
+   */
+  data?: Record<string, any>;
+
+  /**
+   * 传输/批处理配置
+   * @optional 可选
+   */
+  transport?: TransportConfig;
+
+  /**
+   * 挂载在 window 上的全局变量名称
+   * @default '$track'
+   */
+  globalKey?: string;
+
+  /**
+   * 存储 UUID 的 localStorage key
+   * @default 'track_uuid'
+   */
+  uuidKey?: string;
 }
 
-declare enum TYPES {
-    ERROR = "error",
-    CLICK = "click",
-    PERFORMANCE = "performance",
-    ROUTER = "router"
+/**
+ * Reporter 类负责数据的批量上报、重试和调度
+ */
+declare class Reporter {
+    private url;
+    private transportConfig;
+    private events;
+    private isSending;
+    private timer;
+    constructor(url: string, config?: TransportConfig);
+    /**
+     * 将事件加入队列
+     */
+    send(payload: MonitoringPayload): void;
+    /**
+     * 立即刷新所有待发送事件
+     */
+    flush(): Promise<void>;
+    private clearTimer;
+    /**
+     * 触发发送逻辑
+     */
+    private triggerSend;
+    /**
+     * 使用 navigator.sendBeacon 或 XMLHttpRequest 安全发送事件
+     */
+    private safeSend;
+    /**
+     * 通过 XMLHttpRequest 发送
+     */
+    private sendViaXHR;
 }
 
-declare const init: (options: Options) => void;
+/**
+ * EventTrack 类处理事件收集和转换
+ * 职责：
+ * 1. 管理设备信息 (DeviceInfo)
+ * 2. 格式化原始数据为 MonitoringPayload
+ * 3. 将格式化后的数据交给 Reporter 发送
+ */
+declare class EventTrack {
+    private deviceInfo;
+    private reporter;
+    private data?;
+    constructor(options: Options, reporter: Reporter);
+    /**
+     * 格式化事件数据用于传输
+     */
+    private formatter;
+    /**
+     * 公共方法：发送事件
+     * 将事件格式化后交给 reporter 处理
+     */
+    emit(type: EMIT_TYPE | string, data?: any): void;
+    /**
+     * 获取上报器实例 (供 Core 使用)
+     */
+    getReporter(): Reporter;
+}
+
+declare class Core extends EventTrack {
+    private pluginMap;
+    private options;
+    constructor(options: Options);
+    use(plugin: IPlugin): Core;
+    /**
+     * 自定义事件上报
+     * @param data 上报的数据
+     * @param type 事件类型，默认为 'custom'
+     */
+    log(data: any, type?: string): void;
+    run(): void;
+    stop(): void;
+    private mount;
+    private unmount;
+}
+/**
+ * 创建监控实例的工厂函数
+ * @param options 配置项
+ */
+declare function createMonitor(options: Options): Core;
+
+interface ErrorOptions {
+    /** 过滤函数，返回 false 则不记录该错误 */
+    filter?: (error: any) => boolean;
+}
+/**
+ * 错误监控插件
+ * 监控并捕获 JavaScript 错误、资源加载错误、Promise 拒绝以及 console.error 调用
+ */
+declare const ErrorPlugin: (options?: ErrorOptions) => IPlugin;
+
+interface PVOptions {
+    /** 过滤函数，返回 false 则不记录该路由变化 */
+    filter?: (to: string, from: string) => boolean;
+}
+declare const PVPlugin: (options?: PVOptions) => IPlugin;
 
-declare const _default: {
-    init: (options: Options) => void;
-};
+interface BehaviorOptions {
+    /** 过滤函数，返回 false 则不记录该点击事件 */
+    filter?: (element: HTMLElement) => boolean;
+    /** 节流延迟时间（ms），默认 500ms */
+    throttleDelay?: number;
+}
+declare const BehaviorPlugin: (options?: BehaviorOptions) => IPlugin;
+
+interface PerformanceOptions {
+    /** 过滤函数，返回 false 则不记录该性能指标 */
+    filter?: (type: EMIT_TYPE, value: any) => boolean;
+    /** 长任务阈值 (ms)，超过此值则上报，默认 100 */
+    longTaskThreshold?: number;
+    /** 资源加载阈值 (ms)，超过此值则上报，默认 1000 */
+    resourceThreshold?: number;
+    /** INP 阈值 (ms)，超过此值则上报，默认 200 */
+    inpThreshold?: number;
+    /** LoAF 阈值 (ms)，超过此值则上报，默认 100 */
+    loafThreshold?: number;
+}
+declare const PerformancePlugin: (options?: PerformanceOptions) => IPlugin;
+
+interface XHROptions {
+    /** 过滤函数，返回 false 则不记录该请求 */
+    filter?: (method: string, url: string) => boolean;
+}
+/**
+ * XHR 监控插件
+ * 监控 XMLHttpRequest 请求，记录失败的请求（状态码非 2xx）
+ */
+declare const XHRPlugin: (options?: XHROptions) => IPlugin;
+
+interface FetchOptions {
+    /** 过滤函数，返回 false 则不记录该请求 */
+    filter?: (method: string, url: string) => boolean;
+}
+/**
+ * Fetch 监控插件
+ * 监控 fetch 请求，记录失败的请求（状态码非 2xx 或网络错误）
+ */
+declare const FetchPlugin: (options?: FetchOptions) => IPlugin;
 
-export { TYPES, _default as default, init };
+export { BehaviorPlugin, Core, EMIT_TYPE, ErrorPlugin, FetchPlugin, PVPlugin, PerformancePlugin, XHRPlugin, createMonitor };