@qhr123/sa2kit 0.2.0 → 0.3.1

package/dist/analytics/index.d.mts

@@ -0,0 +1,741 @@
+/**
+ * 埋点系统类型定义
+ * Analytics System Type Definitions
+ */
+/**
+ * 事件类型枚举
+ */
+declare enum EventType {
+    PAGE_VIEW = "page_view",
+    PAGE_LEAVE = "page_leave",
+    CLICK = "click",
+    SCROLL = "scroll",
+    INPUT = "input",
+    SUBMIT = "submit",
+    LOGIN = "login",
+    LOGOUT = "logout",
+    REGISTER = "register",
+    SEARCH = "search",
+    SHARE = "share",
+    PERFORMANCE = "performance",
+    ERROR = "error",
+    API_CALL = "api_call",
+    CUSTOM = "custom"
+}
+/**
+ * 事件优先级
+ */
+declare enum EventPriority {
+    LOW = 0,// 低优先级，可延迟上报
+    NORMAL = 1,// 普通优先级，批量上报
+    HIGH = 2,// 高优先级，实时上报
+    CRITICAL = 3
+}
+/**
+ * 基础事件数据接口
+ */
+interface BaseEvent {
+    event_id: string;
+    event_type: EventType;
+    event_name: string;
+    timestamp: number;
+    priority: EventPriority;
+    user_id?: string;
+    session_id: string;
+    device_id: string;
+    page_url?: string;
+    page_title?: string;
+    referrer?: string;
+    properties?: Record<string, any>;
+    platform: string;
+    app_version: string;
+    sdk_version: string;
+}
+/**
+ * 页面浏览事件
+ */
+interface PageViewEvent extends BaseEvent {
+    event_type: EventType.PAGE_VIEW;
+    page_url: string;
+    page_title: string;
+    duration?: number;
+}
+/**
+ * 点击事件
+ */
+interface ClickEvent extends BaseEvent {
+    event_type: EventType.CLICK;
+    element_id?: string;
+    element_class?: string;
+    element_text?: string;
+    element_type?: string;
+    position?: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * 错误事件
+ */
+interface ErrorEvent extends BaseEvent {
+    event_type: EventType.ERROR;
+    error_message: string;
+    error_stack?: string;
+    error_type?: string;
+    error_level?: 'warning' | 'error' | 'fatal';
+}
+/**
+ * 性能事件
+ */
+interface PerformanceEvent extends BaseEvent {
+    event_type: EventType.PERFORMANCE;
+    metric_name: string;
+    metric_value: number;
+    metric_unit?: string;
+}
+/**
+ * API调用事件
+ */
+interface ApiCallEvent extends BaseEvent {
+    event_type: EventType.API_CALL;
+    api_url: string;
+    api_method: string;
+    api_status?: number;
+    duration?: number;
+    success: boolean;
+}
+/**
+ * 所有事件类型联合
+ */
+type AnalyticsEvent = BaseEvent | PageViewEvent | ClickEvent | ErrorEvent | PerformanceEvent | ApiCallEvent;
+/**
+ * 事件上报配置
+ */
+interface AnalyticsConfig {
+    appId: string;
+    appVersion: string;
+    endpoint: string;
+    platform?: string;
+    debug?: boolean;
+    batchSize?: number;
+    batchInterval?: number;
+    maxQueueSize?: number;
+    retryTimes?: number;
+    retryInterval?: number;
+    enableAutoPageView?: boolean;
+    enableAutoClick?: boolean;
+    enableAutoError?: boolean;
+    enableAutoPerformance?: boolean;
+    ignoreUrls?: string[];
+    ignoreErrors?: string[];
+    beforeSend?: (event: AnalyticsEvent) => AnalyticsEvent | null;
+    userId?: string;
+    customProperties?: Record<string, any>;
+}
+/**
+ * 设备信息接口
+ */
+interface DeviceInfo {
+    device_id: string;
+    device_model?: string;
+    device_brand?: string;
+    os_name: string;
+    os_version: string;
+    screen_width: number;
+    screen_height: number;
+    language: string;
+    timezone: string;
+    network_type?: string;
+    carrier?: string;
+}
+/**
+ * 上报响应接口
+ */
+interface UploadResponse {
+    success: boolean;
+    message?: string;
+    code?: number;
+}
+/**
+ * 存储适配器接口
+ */
+interface AnalyticsStorageAdapter {
+    /**
+     * 保存事件到本地存储
+     */
+    saveEvents(events: AnalyticsEvent[]): Promise<void>;
+    /**
+     * 获取本地存储的事件
+     */
+    getEvents(): Promise<AnalyticsEvent[]>;
+    /**
+     * 清除本地存储的事件
+     */
+    clearEvents(): Promise<void>;
+    /**
+     * 保存设备信息
+     */
+    saveDeviceInfo(info: DeviceInfo): Promise<void>;
+    /**
+     * 获取设备信息
+     */
+    getDeviceInfo(): Promise<DeviceInfo | null>;
+    /**
+     * 保存会话ID
+     */
+    saveSessionId(sessionId: string): Promise<void>;
+    /**
+     * 获取会话ID
+     */
+    getSessionId(): Promise<string | null>;
+}
+/**
+ * 网络适配器接口
+ */
+interface AnalyticsNetworkAdapter {
+    /**
+     * 上传事件数据
+     */
+    upload(url: string, events: AnalyticsEvent[]): Promise<UploadResponse>;
+    /**
+     * 检查网络连接状态
+     */
+    isOnline(): Promise<boolean>;
+}
+/**
+ * 设备信息适配器接口
+ */
+interface AnalyticsDeviceAdapter {
+    /**
+     * 获取设备信息
+     */
+    getDeviceInfo(): Promise<DeviceInfo>;
+    /**
+     * 生成设备唯一ID
+     */
+    generateDeviceId(): Promise<string>;
+}
+
+/**
+ * 埋点系统核心类
+ * Analytics Core SDK
+ */
+
+declare class Analytics {
+    private config;
+    private eventQueue;
+    private uploader;
+    private storageAdapter;
+    private networkAdapter;
+    private deviceAdapter;
+    private sessionId;
+    private deviceId;
+    private deviceInfo;
+    private initialized;
+    private batchTimer;
+    constructor(config: Omit<AnalyticsConfig, 'endpoint'> & {
+        adapter?: {
+            storage: AnalyticsStorageAdapter;
+            network: AnalyticsNetworkAdapter;
+            device: AnalyticsDeviceAdapter;
+        };
+        platform?: string;
+        serverUrl?: string;
+        endpoint?: string;
+    }, storageAdapter?: AnalyticsStorageAdapter, networkAdapter?: AnalyticsNetworkAdapter, deviceAdapter?: AnalyticsDeviceAdapter);
+    /**
+     * 初始化
+     */
+    init(): Promise<void>;
+    /**
+     * 追踪事件（简化版本，支持两种调用方式）
+     */
+    track(eventNameOrType: string | EventType, propertiesOrName?: Record<string, any> | string, maybeProperties?: Record<string, any>, priority?: EventPriority): void;
+    /**
+     * 追踪页面浏览
+     */
+    trackPageView(pageUrl: string, pageTitle: string, properties?: Record<string, any>): void;
+    /**
+     * 追踪点击事件
+     */
+    trackClick(elementInfo: {
+        elementId?: string;
+        elementClass?: string;
+        elementText?: string;
+        elementType?: string;
+        position?: {
+            x: number;
+            y: number;
+        };
+    }, properties?: Record<string, any>): void;
+    /**
+     * 追踪错误
+     */
+    trackError(errorMessage: string, errorStack?: string, errorType?: string, properties?: Record<string, any>): void;
+    /**
+     * 追踪性能指标
+     */
+    trackPerformance(metricName: string, metricValue: number, metricUnit?: string, properties?: Record<string, any>): void;
+    /**
+     * 追踪 API 调用
+     */
+    trackApiCall(apiUrl: string, apiMethod: string, apiStatus: number, duration: number, success: boolean, properties?: Record<string, any>): void;
+    /**
+     * 设置用户ID
+     */
+    setUserId(userId: string): void;
+    /**
+     * 设置用户信息（包括用户ID和其他属性）
+     */
+    setUser(userInfo: {
+        userId: string;
+        [key: string]: any;
+    }): void;
+    /**
+     * 设置自定义属性
+     */
+    setCustomProperties(properties: Record<string, any>): void;
+    /**
+     * 立即上传所有事件
+     */
+    flush(): Promise<void>;
+    /**
+     * 立即上传高优先级事件
+     */
+    private flushHighPriority;
+    /**
+     * 销毁实例
+     */
+    destroy(): Promise<void>;
+    /**
+     * 创建事件对象
+     */
+    private createEvent;
+    /**
+     * 初始化设备信息
+     */
+    private initDeviceInfo;
+    /**
+     * 初始化会话
+     */
+    private initSession;
+    /**
+     * 启动批量上传定时器
+     */
+    private startBatchTimer;
+    /**
+     * 上传成功回调
+     */
+    private onUploadSuccess;
+    /**
+     * 上传失败回调
+     */
+    private onUploadError;
+    /**
+     * 生成事件ID
+     */
+    private generateEventId;
+    /**
+     * 生成会话ID
+     */
+    private generateSessionId;
+    /**
+     * 获取平台标识
+     */
+    private getPlatform;
+    /**
+     * 日志输出
+     */
+    private log;
+    /**
+     * 获取队列状态
+     */
+    getQueueStatus(): {
+        size: number;
+        isFull: boolean;
+        isEmpty: boolean;
+    };
+    /**
+     * 获取初始化状态
+     */
+    isInitialized(): boolean;
+}
+
+/**
+ * 事件队列管理器
+ * Event Queue Manager
+ */
+
+declare class EventQueue {
+    private queue;
+    private maxSize;
+    constructor(maxSize?: number);
+    /**
+     * 添加事件到队列
+     */
+    enqueue(event: AnalyticsEvent): void;
+    /**
+     * 批量添加事件
+     */
+    enqueueBatch(events: AnalyticsEvent[]): void;
+    /**
+     * 获取指定数量的事件
+     */
+    dequeue(count: number): AnalyticsEvent[];
+    /**
+     * 获取所有事件
+     */
+    dequeueAll(): AnalyticsEvent[];
+    /**
+     * 获取高优先级事件
+     */
+    getHighPriorityEvents(): AnalyticsEvent[];
+    /**
+     * 查看队列长度
+     */
+    size(): number;
+    /**
+     * 队列是否为空
+     */
+    isEmpty(): boolean;
+    /**
+     * 队列是否已满
+     */
+    isFull(): boolean;
+    /**
+     * 清空队列
+     */
+    clear(): void;
+    /**
+     * 移除最低优先级的事件
+     */
+    private removeLowestPriorityEvent;
+    /**
+     * 获取队列快照（不移除事件）
+     */
+    snapshot(): AnalyticsEvent[];
+}
+
+/**
+ * 事件上传器
+ * Event Uploader
+ */
+
+interface UploaderConfig {
+    endpoint: string;
+    batchSize: number;
+    retryTimes: number;
+    retryInterval: number;
+    networkAdapter: AnalyticsNetworkAdapter;
+    storageAdapter: AnalyticsStorageAdapter;
+    onSuccess?: (events: AnalyticsEvent[]) => void;
+    onError?: (error: Error, events: AnalyticsEvent[]) => void;
+}
+declare class Uploader {
+    private config;
+    private uploading;
+    private retryQueue;
+    constructor(config: UploaderConfig);
+    /**
+     * 上传事件
+     */
+    upload(events: AnalyticsEvent[]): Promise<boolean>;
+    /**
+     * 批量上传
+     */
+    uploadBatch(events: AnalyticsEvent[]): Promise<boolean>;
+    /**
+     * 重试失败的上传
+     */
+    retryFailedUploads(): Promise<void>;
+    /**
+     * 上传本地缓存的事件
+     */
+    uploadCachedEvents(): Promise<void>;
+    /**
+     * 保存事件到本地存储
+     */
+    private saveToLocal;
+    /**
+     * 添加到重试队列
+     */
+    private addToRetryQueue;
+    /**
+     * 分割成批次
+     */
+    private splitIntoBatches;
+    /**
+     * 延迟函数
+     */
+    private delay;
+    /**
+     * 是否正在上传
+     */
+    isUploading(): boolean;
+    /**
+     * 获取重试队列大小
+     */
+    getRetryQueueSize(): number;
+    /**
+     * 清空重试队列
+     */
+    clearRetryQueue(): void;
+}
+
+/**
+ * Analytics 预设配置
+ * Analytics Preset Configurations
+ *
+ * 提供常见场景的配置模板（不包含平台适配器）
+ * 使用时需要提供具体的 adapter 实现
+ */
+
+/**
+ * Web 应用基础配置模板
+ */
+declare function createWebConfig(appId: string, options?: {
+    endpoint?: string;
+    debug?: boolean;
+    enableAutoPageView?: boolean;
+    appVersion?: string;
+}): Partial<AnalyticsConfig>;
+/**
+ * 移动应用基础配置模板
+ */
+declare function createMobileConfig(appId: string, options?: {
+    endpoint?: string;
+    debug?: boolean;
+    appVersion?: string;
+}): Partial<AnalyticsConfig>;
+/**
+ * 小程序基础配置模板
+ */
+declare function createMiniappConfig(appId: string, options?: {
+    endpoint?: string;
+    debug?: boolean;
+    appVersion?: string;
+}): Partial<AnalyticsConfig>;
+/**
+ * 桌面应用基础配置模板
+ */
+declare function createDesktopConfig(appId: string, options?: {
+    endpoint?: string;
+    debug?: boolean;
+    appVersion?: string;
+}): Partial<AnalyticsConfig>;
+
+/**
+ * Analytics 单例管理器
+ * Analytics Singleton Manager
+ *
+ * 提供统一的单例创建和管理功能，支持多个独立实例
+ */
+
+/**
+ * 创建或获取 Analytics 实例
+ * @param instanceKey 实例唯一标识
+ * @param config Analytics 配置
+ * @returns Analytics 实例
+ */
+declare function createAnalytics(instanceKey: string, config: AnalyticsConfig): Analytics;
+/**
+ * 获取已存在的 Analytics 实例
+ * @param instanceKey 实例唯一标识
+ * @returns Analytics 实例或 null
+ */
+declare function getAnalyticsInstance(instanceKey: string): Analytics | null;
+/**
+ * 重置指定实例
+ * @param instanceKey 实例唯一标识
+ */
+declare function resetAnalytics(instanceKey: string): void;
+/**
+ * 重置所有实例
+ */
+declare function resetAllAnalytics(): void;
+/**
+ * 检查实例是否已初始化
+ * @param instanceKey 实例唯一标识
+ */
+declare function isAnalyticsInitialized(instanceKey: string): boolean;
+/**
+ * 获取所有已创建的实例键名
+ */
+declare function getAllInstanceKeys(): string[];
+
+/**
+ * 埋点工具函数
+ * Analytics Helper Functions
+ */
+
+/**
+ * 节流函数
+ */
+declare function throttle<T extends (...args: any[]) => any>(func: T, wait: number): (...args: Parameters<T>) => void;
+/**
+ * 防抖函数
+ */
+declare function debounce<T extends (...args: any[]) => any>(func: T, wait: number): (...args: Parameters<T>) => void;
+/**
+ * 格式化事件数据
+ */
+declare function formatEvent(event: AnalyticsEvent): string;
+/**
+ * 验证事件数据
+ */
+declare function validateEvent(event: AnalyticsEvent): boolean;
+/**
+ * 批量验证事件
+ */
+declare function validateEvents(events: AnalyticsEvent[]): {
+    valid: AnalyticsEvent[];
+    invalid: AnalyticsEvent[];
+};
+/**
+ * 计算事件大小（字节）
+ */
+declare function getEventSize(event: AnalyticsEvent): number;
+/**
+ * 计算批量事件大小
+ */
+declare function getBatchSize(events: AnalyticsEvent[]): number;
+/**
+ * 过滤敏感信息
+ */
+declare function sanitizeEvent(event: AnalyticsEvent, sensitiveKeys?: string[]): AnalyticsEvent;
+/**
+ * 合并事件属性
+ */
+declare function mergeEventProperties(baseProperties: Record<string, any>, ...additionalProperties: Record<string, any>[]): Record<string, any>;
+/**
+ * 生成唯一ID
+ */
+declare function generateUniqueId(prefix?: string): string;
+/**
+ * 判断是否为移动设备
+ */
+declare function isMobile(): boolean;
+/**
+ * 判断是否为开发环境
+ */
+declare function isDevelopment(): boolean;
+/**
+ * 格式化时间戳
+ */
+declare function formatTimestamp(timestamp: number, format?: 'date' | 'datetime' | 'time'): string;
+/**
+ * 深拷贝对象
+ */
+declare function deepClone<T>(obj: T): T;
+/**
+ * 安全的 JSON.stringify
+ */
+declare function safeStringify(obj: any, fallback?: string): string;
+/**
+ * 安全的 JSON.parse
+ */
+declare function safeParse<T>(json: string, fallback: T): T;
+/**
+ * 获取页面停留时长
+ */
+declare function getPageDuration(startTime: number): number;
+/**
+ * 获取当前页面 URL
+ */
+declare function getCurrentPageUrl(): string;
+/**
+ * 获取当前页面标题
+ */
+declare function getCurrentPageTitle(): string;
+/**
+ * 获取来源页面
+ */
+declare function getReferrer(): string;
+
+/**
+ * 埋点装饰器
+ * Analytics Decorators
+ */
+
+/**
+ * 追踪方法执行
+ * @param eventName 事件名称
+ * @param priority 事件优先级
+ */
+declare function Track(eventName?: string, priority?: EventPriority): (_target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * 追踪点击事件
+ */
+declare function TrackClick(eventName?: string): (_target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * 追踪性能
+ */
+declare function TrackPerformance(metricName?: string): (_target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * 自动捕获错误
+ */
+declare function CatchError(_eventName?: string): (_target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * 设置全局 Analytics 实例
+ */
+declare function setGlobalAnalytics(analytics: Analytics): void;
+/**
+ * 获取全局 Analytics 实例
+ */
+declare function getGlobalAnalytics(): Analytics | null;
+
+/**
+ * 使用埋点实例
+ */
+declare function useAnalytics(analytics: Analytics | null): Analytics | null;
+/**
+ * 追踪页面浏览
+ */
+declare function usePageView(analytics: Analytics | null, pageUrl?: string, pageTitle?: string): void;
+/**
+ * 追踪事件（返回追踪函数）
+ */
+declare function useTrackEvent(analytics: Analytics | null): (eventType: EventType, eventName: string, properties?: Record<string, any>, priority?: EventPriority) => void;
+/**
+ * 追踪点击事件
+ */
+declare function useTrackClick(analytics: Analytics | null): (elementInfo: {
+    elementId?: string;
+    elementClass?: string;
+    elementText?: string;
+    elementType?: string;
+}) => void;
+/**
+ * 追踪页面停留时长
+ */
+declare function usePageDuration(analytics: Analytics | null): void;
+/**
+ * 追踪性能指标
+ */
+declare function usePerformanceTracking(analytics: Analytics | null): void;
+/**
+ * 追踪错误
+ */
+declare function useErrorTracking(analytics: Analytics | null): void;
+/**
+ * 自动追踪用户行为（综合 Hook）
+ */
+declare function useAutoTracking(analytics: Analytics | null, options?: {
+    trackPageView?: boolean;
+    trackPageDuration?: boolean;
+    trackPerformance?: boolean;
+    trackErrors?: boolean;
+}): void;
+
+/**
+ * Analytics 埋点分析模块
+ *
+ * 提供完整的事件追踪、用户行为分析、数据上报等功能
+ *
+ * 注意：此模块不包含平台特定的适配器（web/mobile/desktop/miniapp）
+ * 如需使用平台适配器，请在项目中自行实现
+ */
+
+declare const ANALYTICS_VERSION = "1.0.0";
+
+export { ANALYTICS_VERSION, Analytics, type AnalyticsConfig, type AnalyticsDeviceAdapter, type AnalyticsEvent, type AnalyticsNetworkAdapter, type AnalyticsStorageAdapter, type ApiCallEvent, type BaseEvent, CatchError, type ClickEvent, type DeviceInfo, type ErrorEvent, EventPriority, EventQueue, EventType, type PageViewEvent, type PerformanceEvent, Track, TrackClick, TrackPerformance, type UploadResponse, Uploader, createAnalytics, createDesktopConfig, createMiniappConfig, createMobileConfig, createWebConfig, debounce, deepClone, formatEvent, formatTimestamp, generateUniqueId, getAllInstanceKeys, getAnalyticsInstance, getBatchSize, getCurrentPageTitle, getCurrentPageUrl, getEventSize, getGlobalAnalytics, getPageDuration, getReferrer, isAnalyticsInitialized, isDevelopment, isMobile, mergeEventProperties, resetAllAnalytics, resetAnalytics, safeParse, safeStringify, sanitizeEvent, setGlobalAnalytics, throttle, useAnalytics, useAutoTracking, useErrorTracking, usePageDuration, usePageView, usePerformanceTracking, useTrackClick, useTrackEvent, validateEvent, validateEvents };