cwj_monitoring/dist/index.d.ts

基于 JS 适用Web端的插件，为前端项目提供【 行为、性能、异常 】监控手段

/**
 * 事件发送类型标识符
 * 用于向追踪系统发送事件时使用
 */
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",
    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;

  /**
   * 要启用的插件列表
   * @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;
}

/**
 * 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;
}

/**
 * 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;

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;
}
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 { BehaviorPlugin, Core, EMIT_TYPE, ErrorPlugin, FetchPlugin, PVPlugin, PerformancePlugin, XHRPlugin, createMonitor };