@qhr123/sa2kit 0.3.0 → 0.4.0

package/dist/analytics/index.d.mts

@@ -524,6 +524,45 @@ declare function createDesktopConfig(appId: string, options?: {
     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
@@ -688,15 +727,209 @@ declare function useAutoTracking(analytics: Analytics | null, options?: {
     trackErrors?: boolean;
 }): void;
 
+/**
+ * Web 平台适配器
+ * Browser/Next.js Platform Adapters
+ */
+
+/**
+ * Web 存储适配器（使用 localStorage）
+ */
+declare class WebStorageAdapter implements AnalyticsStorageAdapter {
+    private EVENTS_KEY;
+    private DEVICE_INFO_KEY;
+    private SESSION_ID_KEY;
+    saveEvents(events: AnalyticsEvent[]): Promise<void>;
+    getEvents(): Promise<AnalyticsEvent[]>;
+    clearEvents(): Promise<void>;
+    saveDeviceInfo(info: DeviceInfo): Promise<void>;
+    getDeviceInfo(): Promise<DeviceInfo | null>;
+    saveSessionId(sessionId: string): Promise<void>;
+    getSessionId(): Promise<string | null>;
+}
+/**
+ * Web 网络适配器
+ */
+declare class WebNetworkAdapter implements AnalyticsNetworkAdapter {
+    upload(url: string, events: AnalyticsEvent[]): Promise<UploadResponse>;
+    isOnline(): Promise<boolean>;
+}
+/**
+ * Web 设备信息适配器
+ */
+declare class WebDeviceAdapter implements AnalyticsDeviceAdapter {
+    getDeviceInfo(): Promise<DeviceInfo>;
+    generateDeviceId(): Promise<string>;
+    private getOSName;
+    private getOSVersion;
+    private getBrowserName;
+    private getBrowserVersion;
+}
+/**
+ * 统一的 Web 适配器对象
+ */
+declare const webAdapter: {
+    storage: WebStorageAdapter;
+    network: WebNetworkAdapter;
+    device: WebDeviceAdapter;
+};
+
+/**
+ * Mobile 平台适配器
+ * React Native Platform Adapters
+ */
+
+/**
+ * Mobile 存储适配器
+ * 需要在 mobile 项目中实现具体的 AsyncStorage 逻辑
+ */
+declare class MobileStorageAdapter implements AnalyticsStorageAdapter {
+    private storage;
+    private EVENTS_KEY;
+    private DEVICE_INFO_KEY;
+    private SESSION_ID_KEY;
+    constructor(storage: {
+        getItem: (key: string) => Promise<string | null>;
+        setItem: (key: string, value: string) => Promise<void>;
+        removeItem: (key: string) => Promise<void>;
+    });
+    saveEvents(events: AnalyticsEvent[]): Promise<void>;
+    getEvents(): Promise<AnalyticsEvent[]>;
+    clearEvents(): Promise<void>;
+    saveDeviceInfo(info: DeviceInfo): Promise<void>;
+    getDeviceInfo(): Promise<DeviceInfo | null>;
+    saveSessionId(sessionId: string): Promise<void>;
+    getSessionId(): Promise<string | null>;
+}
+/**
+ * Mobile 网络适配器
+ */
+declare class MobileNetworkAdapter implements AnalyticsNetworkAdapter {
+    private netInfo?;
+    constructor(netInfo?: {
+        fetch: () => Promise<{
+            isConnected: boolean | null;
+        }>;
+    } | undefined);
+    upload(url: string, events: AnalyticsEvent[]): Promise<UploadResponse>;
+    isOnline(): Promise<boolean>;
+}
+/**
+ * Mobile 设备信息适配器
+ */
+declare class MobileDeviceAdapter implements AnalyticsDeviceAdapter {
+    private deviceInfoModule?;
+    constructor(deviceInfoModule?: {
+        getSystemName: () => Promise<string>;
+        getSystemVersion: () => Promise<string>;
+        getModel: () => Promise<string>;
+        getBrand: () => Promise<string>;
+        getUniqueId: () => Promise<string>;
+    } | undefined);
+    getDeviceInfo(): Promise<DeviceInfo>;
+    generateDeviceId(): Promise<string>;
+    private getDefaultDeviceInfo;
+}
+
+/**
+ * 小程序平台适配器
+ * WeChat MiniProgram Platform Adapters
+ */
+
+/**
+ * 小程序存储适配器
+ */
+declare class MiniappStorageAdapter implements AnalyticsStorageAdapter {
+    private storage?;
+    private EVENTS_KEY;
+    private DEVICE_INFO_KEY;
+    private SESSION_ID_KEY;
+    constructor(storage?: {
+        getStorageSync: (key: string) => any;
+        setStorageSync: (key: string, data: any) => void;
+        removeStorageSync: (key: string) => void;
+    } | undefined);
+    saveEvents(events: AnalyticsEvent[]): Promise<void>;
+    getEvents(): Promise<AnalyticsEvent[]>;
+    clearEvents(): Promise<void>;
+    saveDeviceInfo(info: DeviceInfo): Promise<void>;
+    getDeviceInfo(): Promise<DeviceInfo | null>;
+    saveSessionId(sessionId: string): Promise<void>;
+    getSessionId(): Promise<string | null>;
+}
+/**
+ * 小程序网络适配器
+ */
+declare class MiniappNetworkAdapter implements AnalyticsNetworkAdapter {
+    private request?;
+    private netInfo?;
+    constructor(request?: {
+        request: (options: any) => Promise<any>;
+    } | undefined, netInfo?: {
+        getNetworkType: () => Promise<{
+            networkType: string;
+        }>;
+    } | undefined);
+    upload(url: string, events: AnalyticsEvent[]): Promise<UploadResponse>;
+    isOnline(): Promise<boolean>;
+}
+/**
+ * 小程序设备信息适配器
+ */
+declare class MiniappDeviceAdapter implements AnalyticsDeviceAdapter {
+    private systemInfo?;
+    constructor(systemInfo?: {
+        getSystemInfoSync: () => any;
+    } | undefined);
+    getDeviceInfo(): Promise<DeviceInfo>;
+    generateDeviceId(): Promise<string>;
+    private getDefaultDeviceInfo;
+}
+
+/**
+ * Desktop 平台适配器
+ * Electron Platform Adapters
+ */
+
+/**
+ * Desktop 存储适配器（使用 localStorage）
+ */
+declare class DesktopStorageAdapter implements AnalyticsStorageAdapter {
+    private EVENTS_KEY;
+    private DEVICE_INFO_KEY;
+    private SESSION_ID_KEY;
+    saveEvents(events: AnalyticsEvent[]): Promise<void>;
+    getEvents(): Promise<AnalyticsEvent[]>;
+    clearEvents(): Promise<void>;
+    saveDeviceInfo(info: DeviceInfo): Promise<void>;
+    getDeviceInfo(): Promise<DeviceInfo | null>;
+    saveSessionId(sessionId: string): Promise<void>;
+    getSessionId(): Promise<string | null>;
+}
+/**
+ * Desktop 网络适配器
+ */
+declare class DesktopNetworkAdapter implements AnalyticsNetworkAdapter {
+    upload(url: string, events: AnalyticsEvent[]): Promise<UploadResponse>;
+    isOnline(): Promise<boolean>;
+}
+/**
+ * Desktop 设备信息适配器
+ */
+declare class DesktopDeviceAdapter implements AnalyticsDeviceAdapter {
+    getDeviceInfo(): Promise<DeviceInfo>;
+    generateDeviceId(): Promise<string>;
+    private getOSName;
+    private getOSVersion;
+}
+
 /**
  * Analytics 埋点分析模块
  *
  * 提供完整的事件追踪、用户行为分析、数据上报等功能
- *
- * 注意：此模块不包含平台特定的适配器（web/mobile/desktop/miniapp）
- * 如需使用平台适配器，请在项目中自行实现
+ * 包含多平台适配器（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, createDesktopConfig, createMiniappConfig, createMobileConfig, createWebConfig, debounce, deepClone, formatEvent, formatTimestamp, generateUniqueId, getBatchSize, getCurrentPageTitle, getCurrentPageUrl, getEventSize, getGlobalAnalytics, getPageDuration, getReferrer, isDevelopment, isMobile, mergeEventProperties, safeParse, safeStringify, sanitizeEvent, setGlobalAnalytics, throttle, useAnalytics, useAutoTracking, useErrorTracking, usePageDuration, usePageView, usePerformanceTracking, useTrackClick, useTrackEvent, validateEvent, validateEvents };
+export { ANALYTICS_VERSION, Analytics, type AnalyticsConfig, type AnalyticsDeviceAdapter, type AnalyticsEvent, type AnalyticsNetworkAdapter, type AnalyticsStorageAdapter, type ApiCallEvent, type BaseEvent, CatchError, type ClickEvent, DesktopDeviceAdapter, DesktopNetworkAdapter, DesktopStorageAdapter, type DeviceInfo, type ErrorEvent, EventPriority, EventQueue, EventType, MiniappDeviceAdapter, MiniappNetworkAdapter, MiniappStorageAdapter, MobileDeviceAdapter, MobileNetworkAdapter, MobileStorageAdapter, type PageViewEvent, type PerformanceEvent, Track, TrackClick, TrackPerformance, type UploadResponse, Uploader, WebDeviceAdapter, WebNetworkAdapter, WebStorageAdapter, 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, webAdapter };

package/dist/analytics/index.d.ts

@@ -524,6 +524,45 @@ declare function createDesktopConfig(appId: string, options?: {
     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
@@ -688,15 +727,209 @@ declare function useAutoTracking(analytics: Analytics | null, options?: {
     trackErrors?: boolean;
 }): void;
 
+/**
+ * Web 平台适配器
+ * Browser/Next.js Platform Adapters
+ */
+
+/**
+ * Web 存储适配器（使用 localStorage）
+ */
+declare class WebStorageAdapter implements AnalyticsStorageAdapter {
+    private EVENTS_KEY;
+    private DEVICE_INFO_KEY;
+    private SESSION_ID_KEY;
+    saveEvents(events: AnalyticsEvent[]): Promise<void>;
+    getEvents(): Promise<AnalyticsEvent[]>;
+    clearEvents(): Promise<void>;
+    saveDeviceInfo(info: DeviceInfo): Promise<void>;
+    getDeviceInfo(): Promise<DeviceInfo | null>;
+    saveSessionId(sessionId: string): Promise<void>;
+    getSessionId(): Promise<string | null>;
+}
+/**
+ * Web 网络适配器
+ */
+declare class WebNetworkAdapter implements AnalyticsNetworkAdapter {
+    upload(url: string, events: AnalyticsEvent[]): Promise<UploadResponse>;
+    isOnline(): Promise<boolean>;
+}
+/**
+ * Web 设备信息适配器
+ */
+declare class WebDeviceAdapter implements AnalyticsDeviceAdapter {
+    getDeviceInfo(): Promise<DeviceInfo>;
+    generateDeviceId(): Promise<string>;
+    private getOSName;
+    private getOSVersion;
+    private getBrowserName;
+    private getBrowserVersion;
+}
+/**
+ * 统一的 Web 适配器对象
+ */
+declare const webAdapter: {
+    storage: WebStorageAdapter;
+    network: WebNetworkAdapter;
+    device: WebDeviceAdapter;
+};
+
+/**
+ * Mobile 平台适配器
+ * React Native Platform Adapters
+ */
+
+/**
+ * Mobile 存储适配器
+ * 需要在 mobile 项目中实现具体的 AsyncStorage 逻辑
+ */
+declare class MobileStorageAdapter implements AnalyticsStorageAdapter {
+    private storage;
+    private EVENTS_KEY;
+    private DEVICE_INFO_KEY;
+    private SESSION_ID_KEY;
+    constructor(storage: {
+        getItem: (key: string) => Promise<string | null>;
+        setItem: (key: string, value: string) => Promise<void>;
+        removeItem: (key: string) => Promise<void>;
+    });
+    saveEvents(events: AnalyticsEvent[]): Promise<void>;
+    getEvents(): Promise<AnalyticsEvent[]>;
+    clearEvents(): Promise<void>;
+    saveDeviceInfo(info: DeviceInfo): Promise<void>;
+    getDeviceInfo(): Promise<DeviceInfo | null>;
+    saveSessionId(sessionId: string): Promise<void>;
+    getSessionId(): Promise<string | null>;
+}
+/**
+ * Mobile 网络适配器
+ */
+declare class MobileNetworkAdapter implements AnalyticsNetworkAdapter {
+    private netInfo?;
+    constructor(netInfo?: {
+        fetch: () => Promise<{
+            isConnected: boolean | null;
+        }>;
+    } | undefined);
+    upload(url: string, events: AnalyticsEvent[]): Promise<UploadResponse>;
+    isOnline(): Promise<boolean>;
+}
+/**
+ * Mobile 设备信息适配器
+ */
+declare class MobileDeviceAdapter implements AnalyticsDeviceAdapter {
+    private deviceInfoModule?;
+    constructor(deviceInfoModule?: {
+        getSystemName: () => Promise<string>;
+        getSystemVersion: () => Promise<string>;
+        getModel: () => Promise<string>;
+        getBrand: () => Promise<string>;
+        getUniqueId: () => Promise<string>;
+    } | undefined);
+    getDeviceInfo(): Promise<DeviceInfo>;
+    generateDeviceId(): Promise<string>;
+    private getDefaultDeviceInfo;
+}
+
+/**
+ * 小程序平台适配器
+ * WeChat MiniProgram Platform Adapters
+ */
+
+/**
+ * 小程序存储适配器
+ */
+declare class MiniappStorageAdapter implements AnalyticsStorageAdapter {
+    private storage?;
+    private EVENTS_KEY;
+    private DEVICE_INFO_KEY;
+    private SESSION_ID_KEY;
+    constructor(storage?: {
+        getStorageSync: (key: string) => any;
+        setStorageSync: (key: string, data: any) => void;
+        removeStorageSync: (key: string) => void;
+    } | undefined);
+    saveEvents(events: AnalyticsEvent[]): Promise<void>;
+    getEvents(): Promise<AnalyticsEvent[]>;
+    clearEvents(): Promise<void>;
+    saveDeviceInfo(info: DeviceInfo): Promise<void>;
+    getDeviceInfo(): Promise<DeviceInfo | null>;
+    saveSessionId(sessionId: string): Promise<void>;
+    getSessionId(): Promise<string | null>;
+}
+/**
+ * 小程序网络适配器
+ */
+declare class MiniappNetworkAdapter implements AnalyticsNetworkAdapter {
+    private request?;
+    private netInfo?;
+    constructor(request?: {
+        request: (options: any) => Promise<any>;
+    } | undefined, netInfo?: {
+        getNetworkType: () => Promise<{
+            networkType: string;
+        }>;
+    } | undefined);
+    upload(url: string, events: AnalyticsEvent[]): Promise<UploadResponse>;
+    isOnline(): Promise<boolean>;
+}
+/**
+ * 小程序设备信息适配器
+ */
+declare class MiniappDeviceAdapter implements AnalyticsDeviceAdapter {
+    private systemInfo?;
+    constructor(systemInfo?: {
+        getSystemInfoSync: () => any;
+    } | undefined);
+    getDeviceInfo(): Promise<DeviceInfo>;
+    generateDeviceId(): Promise<string>;
+    private getDefaultDeviceInfo;
+}
+
+/**
+ * Desktop 平台适配器
+ * Electron Platform Adapters
+ */
+
+/**
+ * Desktop 存储适配器（使用 localStorage）
+ */
+declare class DesktopStorageAdapter implements AnalyticsStorageAdapter {
+    private EVENTS_KEY;
+    private DEVICE_INFO_KEY;
+    private SESSION_ID_KEY;
+    saveEvents(events: AnalyticsEvent[]): Promise<void>;
+    getEvents(): Promise<AnalyticsEvent[]>;
+    clearEvents(): Promise<void>;
+    saveDeviceInfo(info: DeviceInfo): Promise<void>;
+    getDeviceInfo(): Promise<DeviceInfo | null>;
+    saveSessionId(sessionId: string): Promise<void>;
+    getSessionId(): Promise<string | null>;
+}
+/**
+ * Desktop 网络适配器
+ */
+declare class DesktopNetworkAdapter implements AnalyticsNetworkAdapter {
+    upload(url: string, events: AnalyticsEvent[]): Promise<UploadResponse>;
+    isOnline(): Promise<boolean>;
+}
+/**
+ * Desktop 设备信息适配器
+ */
+declare class DesktopDeviceAdapter implements AnalyticsDeviceAdapter {
+    getDeviceInfo(): Promise<DeviceInfo>;
+    generateDeviceId(): Promise<string>;
+    private getOSName;
+    private getOSVersion;
+}
+
 /**
  * Analytics 埋点分析模块
  *
  * 提供完整的事件追踪、用户行为分析、数据上报等功能
- *
- * 注意：此模块不包含平台特定的适配器（web/mobile/desktop/miniapp）
- * 如需使用平台适配器，请在项目中自行实现
+ * 包含多平台适配器（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, createDesktopConfig, createMiniappConfig, createMobileConfig, createWebConfig, debounce, deepClone, formatEvent, formatTimestamp, generateUniqueId, getBatchSize, getCurrentPageTitle, getCurrentPageUrl, getEventSize, getGlobalAnalytics, getPageDuration, getReferrer, isDevelopment, isMobile, mergeEventProperties, safeParse, safeStringify, sanitizeEvent, setGlobalAnalytics, throttle, useAnalytics, useAutoTracking, useErrorTracking, usePageDuration, usePageView, usePerformanceTracking, useTrackClick, useTrackEvent, validateEvent, validateEvents };
+export { ANALYTICS_VERSION, Analytics, type AnalyticsConfig, type AnalyticsDeviceAdapter, type AnalyticsEvent, type AnalyticsNetworkAdapter, type AnalyticsStorageAdapter, type ApiCallEvent, type BaseEvent, CatchError, type ClickEvent, DesktopDeviceAdapter, DesktopNetworkAdapter, DesktopStorageAdapter, type DeviceInfo, type ErrorEvent, EventPriority, EventQueue, EventType, MiniappDeviceAdapter, MiniappNetworkAdapter, MiniappStorageAdapter, MobileDeviceAdapter, MobileNetworkAdapter, MobileStorageAdapter, type PageViewEvent, type PerformanceEvent, Track, TrackClick, TrackPerformance, type UploadResponse, Uploader, WebDeviceAdapter, WebNetworkAdapter, WebStorageAdapter, 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, webAdapter };