@error-monitor/sdk

/** * 监控SDK核心类型定义 * 统一各平台的数据类型，确保数据结构一致性 */ /** * 基础配置接口 */ interface BaseConfig { /** 项目ID */ projectId: string; /** 服务器地址 */ serverUrl: string; /** API密钥 */ apiKey?: string; /** 用户ID */ userId?: string; /** 自定义标签 */ tags?: Record<string, string>; /** 是否在开发环境启用 */ enableInDev?: boolean; /** 采样率 (0-1) */ sampleRate?: number; /** 项目版本 */ projectVersion?: string; /** 构建ID */ buildId?: string; /** 构建时间 */ buildTime?: string; /** 环境 */ environment?: "development" | "testing" | "staging" | "production"; /** 是否启用源代码映射 */ enableSourceMapping?: boolean; } /** * 错误监控配置 */ interface ErrorConfig { /** 是否启用错误监控 */ enabled?: boolean; /** 最大错误数量 */ maxErrors?: number; /** 错误过滤规则 */ filters?: RegExp[]; /** 采样率 */ sampleRate?: number; } /** * 性能监控配置 */ interface PerformanceConfig { /** 是否启用性能监控 */ enabled?: boolean; /** 最大性能数据数量 */ maxPerformance?: number; /** 是否监控资源加载 */ enableResourceTiming?: boolean; /** 是否监控用户交互 */ enableUserTiming?: boolean; } /** * 行为监控配置 */ interface BehaviorConfig { /** 是否启用行为监控 */ enabled?: boolean; /** 最大行为数据数量 */ maxBehaviors?: number; /** 是否自动追踪点击 */ autoTrackClick?: boolean; /** 是否自动追踪页面浏览 */ autoTrackPageView?: boolean; } /** * 数据上报配置 */ interface ReportConfig { /** 上报间隔(毫秒) */ interval?: number; /** 最大队列大小 */ maxQueueSize?: number; /** 批量上报大小 */ batchSize?: number; /** 请求超时时间 */ timeout?: number; /** 最大重试次数 */ maxRetries?: number; /** 重试延迟 */ retryDelay?: number; /** 是否启用离线缓存 */ enableOfflineCache?: boolean; } /** * 完整的监控配置 */ interface MonitorConfig extends BaseConfig { /** 错误监控配置 */ error?: ErrorConfig; /** 性能监控配置 */ performance?: PerformanceConfig; /** 行为监控配置 */ behavior?: BehaviorConfig; /** 数据上报配置 */ report?: ReportConfig; } /** * 错误类型枚举 */ declare enum ErrorType { /** JavaScript运行时错误 */ JS_ERROR = "js_error", /** Promise未捕获错误 */ PROMISE_ERROR = "promise_error", /** 资源加载错误 */ RESOURCE_ERROR = "resource_error", /** 网络请求错误 */ HTTP_ERROR = "http_error", /** 自定义错误 */ CUSTOM_ERROR = "custom_error", /** 框架错误 */ FRAMEWORK_ERROR = "framework_error" } /** * 性能指标类型 */ declare enum PerformanceType { /** 页面加载性能 */ PAGE_LOAD = "page_load", /** 网络请求性能 */ HTTP_REQUEST = "http_request", /** 资源加载性能 */ RESOURCE_LOAD = "resource_load", /** 用户交互性能 */ USER_INTERACTION = "user_interaction", /** 自定义性能指标 */ CUSTOM_METRIC = "custom_metric" } /** * 用户行为类型 */ declare enum BehaviorType { /** 页面访问 */ PAGE_VIEW = "page_view", /** 点击事件 */ CLICK = "click", /** 滚动事件 */ SCROLL = "scroll", /** 表单提交 */ FORM_SUBMIT = "form_submit", /** 路由变化 */ ROUTE_CHANGE = "route_change", /** 自定义事件 */ CUSTOM = "custom" } /** * 基础监控数据接口 */ interface BaseMonitorData { /** 数据ID */ id: string; /** 时间戳 */ timestamp: number; /** 项目ID */ projectId: string; /** 项目版本 */ projectVersion?: string; /** 用户ID */ userId?: string; /** 会话ID */ sessionId: string; /** 页面URL */ url: string; /** 用户代理 */ userAgent: string; /** 平台信息 */ platform: string; /** 自定义标签 */ tags?: Record<string, string>; } /** * 错误监控数据 */ interface ErrorData extends BaseMonitorData { /** 错误类型 */ type: ErrorType; /** 错误消息 */ message: string; /** 错误堆栈 */ stack?: string; /** 文件名 */ filename?: string; /** 行号 */ lineno?: number; /** 列号 */ colno?: number; /** 错误对象 */ error?: any; /** 组件堆栈(React等框架) */ componentStack?: string; /** 错误级别 */ level?: "error" | "warning" | "info"; /** 项目版本 */ projectVersion?: string; /** 构建ID */ buildId?: string; /** 源代码映射状态 */ sourceMappingStatus?: "mapped" | "unmapped" | "pending"; /** 原始源文件路径 */ sourceFilePath?: string; /** 原始源代码行号 */ sourceLineNumber?: number; /** 原始源代码列号 */ sourceColumnNumber?: number; /** 源代码上下文 */ sourceContext?: { /** 前面的代码行 */ preLines: string[]; /** 错误行 */ errorLine: string; /** 后面的代码行 */ postLines: string[]; }; } /** * 性能监控数据 */ interface PerformanceData extends BaseMonitorData { /** 性能类型 */ type: PerformanceType; /** 性能指标 */ metrics: Record<string, number>; /** 资源信息 */ resource?: { name: string; size: number; duration: number; type: string; }; /** 导航时间 */ navigation?: { fetchStart: number; domainLookupStart: number; domainLookupEnd: number; connectStart: number; connectEnd: number; requestStart: number; responseStart: number; responseEnd: number; domContentLoadedEventStart: number; domContentLoadedEventEnd: number; loadEventStart: number; loadEventEnd: number; }; } /** * 用户行为数据 */ interface BehaviorData extends BaseMonitorData { /** 行为类型 */ type: BehaviorType; /** 事件名称 */ event: string; /** 目标元素 */ target?: string; /** 元素路径 */ xpath?: string; /** 额外数据 */ data?: Record<string, any>; /** 持续时间 */ duration?: number; } /** * 上报数据联合类型 */ type MonitorData = ErrorData | PerformanceData | BehaviorData; /** * 事件发射器接口 */ interface EventEmitter { on(event: string, listener: Function): void; off(event: string, listener?: Function): void; emit(event: string, ...args: any[]): boolean; once(event: string, listener: Function): void; } /** * 队列状态 */ interface QueueStatus { /** 队列大小 */ size: number; /** 最大队列大小 */ maxSize: number; /** 是否已满 */ isFull: boolean; /** 错误数量 */ errorCount: number; /** 性能数据数量 */ performanceCount: number; /** 行为数据数量 */ behaviorCount: number; } /** * SDK状态 */ interface SDKStatus { /** 是否已初始化 */ initialized: boolean; /** 是否启用 */ enabled: boolean; /** 队列状态 */ queue: QueueStatus; /** 上次上报时间 */ lastReportTime: number; /** 错误监控状态 */ errorMonitor: boolean; /** 性能监控状态 */ performanceMonitor: boolean; /** 行为监控状态 */ behaviorMonitor: boolean; } /** * 平台适配器接口 * 定义各平台需要实现的核心接口，实现平台无关的监控功能 */ /** * 平台环境信息 */ interface PlatformInfo { /** 平台类型 */ platform: "web" | "taro-mini" | "wechat-mini" | "react-native"; /** 平台版本 */ version: string; /** 用户代理信息 */ userAgent: string; /** 设备信息 */ deviceInfo: Record<string, any>; } /** * 错误捕获接口 */ interface ErrorCaptureAdapter { /** * 初始化错误监听 * @param onError 错误回调函数 */ initErrorListeners(onError: (error: ErrorData) => void): void; /** * 销毁错误监听 */ destroyErrorListeners(): void; /** * 手动捕获错误 * @param error 错误对象或消息 * @param extra 额外信息 */ captureError(error: Error | string, extra?: Record<string, any>): ErrorData; /** * 捕获HTTP错误 * @param request 请求信息 */ captureHttpError(request: HttpRequestInfo): ErrorData; } /** * 性能监控接口 */ interface PerformanceAdapter { /** * 初始化性能监控 * @param onPerformance 性能数据回调 */ initPerformanceMonitor(onPerformance: (data: PerformanceData) => void): void; /** * 销毁性能监控 */ destroyPerformanceMonitor(): void; /** * 手动记录性能指标 * @param name 指标名称 * @param metrics 指标数据 */ recordPerformance(name: string, metrics: Record<string, number>): PerformanceData; /** * 获取页面性能指标 */ getPagePerformance(): Record<string, number>; } /** * 行为监控接口 */ interface BehaviorAdapter { /** * 初始化行为监控 * @param onBehavior 行为数据回调 */ initBehaviorMonitor(onBehavior: (data: BehaviorData) => void): void; /** * 销毁行为监控 */ destroyBehaviorMonitor(): void; /** * 手动记录行为 * @param event 事件名称 * @param data 事件数据 */ recordBehavior(event: string, data?: Record<string, any>): BehaviorData; } /** * 网络适配接口 */ interface NetworkAdapter { /** * 拦截网络请求 * @param onRequest 请求回调 * @param onResponse 响应回调 * @param onError 错误回调 */ interceptNetwork(onRequest: (request: any) => void, onResponse: (response: any) => void, onError: (error: any) => void): void; /** * 发送监控数据 * @param url 接口地址 * @param data 数据 * @param options 选项 */ sendData(url: string, data: any, options?: { timeout?: number; retries?: number; headers?: Record<string, string>; }): Promise<any>; } /** * 存储适配接口 */ interface StorageAdapter { /** * 设置本地存储 * @param key 键 * @param value 值 */ setItem(key: string, value: string): void; /** * 获取本地存储 * @param key 键 */ getItem(key: string): string | null; /** * 删除本地存储 * @param key 键 */ removeItem(key: string): void; /** * 清空本地存储 */ clear(): void; } /** * HTTP请求信息 */ interface HttpRequestInfo { url: string; method: string; status: number; statusText: string; duration: number; requestSize?: number; responseSize?: number; error?: string; } /** * 完整的平台适配器接口 */ interface PlatformAdapter { /** 平台信息 */ readonly platformInfo: PlatformInfo; /** 错误捕获适配器 */ readonly errorCapture: ErrorCaptureAdapter; /** 性能监控适配器 */ readonly performance: PerformanceAdapter; /** 行为监控适配器 */ readonly behavior: BehaviorAdapter; /** 网络适配器 */ readonly network: NetworkAdapter; /** 存储适配器 */ readonly storage: StorageAdapter; /** * 初始化平台适配器 * @param config 配置选项 */ init(config: Record<string, any>): void; /** * 销毁平台适配器 */ destroy(): void; } /** * 核心基础管理器 * 提供监控SDK的基础功能：配置管理、事件系统、队列管理等 */ /** * 监控SDK核心管理器 */ declare class BaseManager implements EventEmitter { protected config: MonitorConfig; protected platformAdapter: PlatformAdapter; protected sessionId: string; protected dataQueue: MonitorData[]; protected isInitialized: boolean; protected isEnabled: boolean; protected listeners: Map<string, Function[]>; protected reportTimer?: any; constructor(config: MonitorConfig, platformAdapter: PlatformAdapter); /** * 合并默认配置和用户配置 * @param userConfig 用户配置 * @returns 合并后的配置 */ private mergeConfig; /** * 深度合并对象 * @param target 目标对象 * @param source 源对象 * @returns 合并后的对象 */ private deepMerge; /** * 初始化监控SDK */ init(): Promise<void>; /** * 检查是否应该启用监控 * @returns 是否启用 */ private shouldEnable; /** * 检查是否为开发环境 * @returns 是否为开发环境 */ private isDevelopment; /** * 初始化错误监控 */ private initErrorMonitor; /** * 初始化性能监控 */ private initPerformanceMonitor; /** * 初始化行为监控 */ private initBehaviorMonitor; /** * 添加数据到队列 * @param data 监控数据 */ protected addToQueue(data: MonitorData): void; /** * 启动定时上报 */ private startReportTimer; /** * 立即上报所有数据 * @returns Promise */ flush(): Promise<void>; /** * 发送数据到服务器 * @param data 要发送的数据 */ private sendData; /** * 手动捕获错误 * @param error 错误对象或消息 * @param extra 额外信息 */ captureError(error: Error | string, extra?: Record<string, any>): void; /** * 手动记录性能指标 * @param name 指标名称 * @param metrics 指标数据 */ recordPerformance(name: string, metrics: Record<string, number>): void; /** * 手动记录用户行为 * @param event 事件名称 * @param data 事件数据 */ recordBehavior(event: string, data?: Record<string, any>): void; /** * 获取SDK状态 * @returns SDK状态 */ getStatus(): SDKStatus; /** * 销毁SDK */ destroy(): void; on(event: string, listener: Function): void; off(event: string, listener?: Function): void; emit(event: string, ...args: any[]): boolean; once(event: string, listener: Function): void; } /** * 版本信息工具 * 提供版本信息管理和源代码映射相关功能 */ /** * 版本信息接口 */ interface VersionInfo { /** 项目版本 */ projectVersion: string; /** 构建ID */ buildId?: string; /** 构建时间 */ buildTime?: string; /** 环境 */ environment?: string; /** 是否包含 sourcemap */ hasSourcemap?: boolean; /** 额外信息 */ extra?: Record<string, string>; } /** * Web监控SDK类 */ declare class WebMonitorSDK extends BaseManager { private static instance; constructor(config: MonitorConfig); /** * 初始化Web监控SDK（单例模式） * @param config 配置选项 * @returns SDK实例 */ static init(config: MonitorConfig): WebMonitorSDK; /** * 获取当前SDK实例 * @returns SDK实例或null */ static getInstance(): WebMonitorSDK | null; /** * 销毁SDK */ static destroy(): void; } declare const MonitorSDK: { /** * 初始化监控SDK * @param config 配置选项 * @returns SDK实例 */ init: (config: MonitorConfig) => WebMonitorSDK; /** * 设置版本信息 * @param versionInfo 版本信息对象 */ setVersionInfo: (versionInfo: VersionInfo) => void; /** * 获取当前实例 * @returns SDK实例或null */ getInstance: () => WebMonitorSDK | null; /** * 手动捕获错误 * @param error 错误对象或消息 * @param extra 额外信息 */ captureError: (error: Error | string, extra?: Record<string, any>) => void; /** * 记录性能指标 * @param name 指标名称 * @param metrics 指标数据 */ recordPerformance: (name: string, metrics: Record<string, number>) => void; /** * 记录用户行为 * @param event 事件名称 * @param data 事件数据 */ recordBehavior: (event: string, data?: Record<string, any>) => void; /** * 立即上报数据 */ flush: () => Promise<void>; /** * 获取SDK状态 */ getStatus: () => SDKStatus | null; /** * 销毁SDK */ destroy: () => void; /** * 监听事件 * @param event 事件名称 * @param listener 监听器函数 */ on: (event: string, listener: Function) => void; /** * 移除事件监听 * @param event 事件名称 * @param listener 监听器函数 */ off: (event: string, listener?: Function) => void; }; export { BehaviorType, ErrorType, PerformanceType, WebMonitorSDK, MonitorSDK as default }; export type { BaseConfig, BaseMonitorData, BehaviorConfig, BehaviorData, ErrorConfig, ErrorData, EventEmitter, MonitorConfig, MonitorData, PerformanceConfig, PerformanceData, QueueStatus, ReportConfig, SDKStatus, VersionInfo };