sobey-monitor-sdk 1.1.1 → 1.1.3

package/dist/index.d.ts

@@ -285,7 +285,7 @@ interface DeviceInfo {
  * ```
  */
 declare const VueMonitorPlugin: {
-    install(app: any, options: MonitorConfig): void;
+    install(app: any, options?: MonitorConfig): void;
 };
 
 /**
@@ -332,7 +332,7 @@ interface ErrorBoundaryState {
  * );
  * ```
  */
-declare function createReactErrorBoundary(React: any, config: MonitorConfig): any;
+declare function createReactErrorBoundary(React: any, config?: MonitorConfig): any;
 /**
  * React Hook: 用于手动上报错误
  *
@@ -361,18 +361,32 @@ declare function createUseMonitorError(React: any): () => any;
  * 监控 SDK 主类
  */
 declare class MonitorSDK {
+    /** SDK 是否已初始化（基础初始化，可能还没有完整配置） */
     private initialized;
-    private initializing;
+    /** SDK 是否已就绪（配置完整，可以上报数据） */
+    private ready;
+    /** 是否正在加载远程配置 */
+    private loading;
+    /** 监控模块是否已安装 */
+    private monitorsInstalled;
     /**
      * 初始化 SDK
-     * 如果配置了 configUrl，将先从远程获取配置（仅获取一次）
-     * 无需 await，SDK 内部会自动处理异步逻辑
+     * 支持空配置初始化，后续通过 updateConfig 传入 configUrl 完成配置
      */
-    init(userConfig: MonitorConfig): void;
+    init(userConfig?: MonitorConfig): void;
     /**
-     * 执行实际的初始化逻辑
+     * 基础初始化（安装监控模块，但不开始上报）
      */
-    private doInit;
+    private initBasic;
+    /**
+     * 激活 SDK（配置完整后调用）
+     */
+    private activate;
+    /**
+     * 动态更新配置
+     * 如果传入 configUrl，会从远程获取配置并激活 SDK
+     */
+    updateConfig(partialConfig: Partial<MonitorConfig>): void;
     /**
      * 从远程获取配置
      */
@@ -382,19 +396,17 @@ declare class MonitorSDK {
      */
     private mergeUserConfig;
     /**
-     * 设置用户信息
+     * 检查 SDK 是否就绪
      */
-    setUser(user: UserInfo): void;
+    isReady(): boolean;
     /**
-     * 动态更新配置
-     * @description 可以在运行时更新 SDK 配置，如 debug、sampling、report 等
-     * 如果传入 configUrl，会从远程获取配置并合并
+     * 设置用户信息
      */
-    updateConfig(partialConfig: Partial<MonitorConfig>): void;
+    setUser(user: UserInfo): void;
     /**
      * 获取当前配置
      */
-    getConfig(): MonitorConfig;
+    getConfig(): MonitorConfig | null;
     /**
      * 手动上报错误
      */
@@ -419,10 +431,6 @@ declare class MonitorSDK {
      * 获取 SDK 版本
      */
     getVersion(): string;
-    /**
-     * 检查是否已初始化
-     */
-    private checkInit;
 }
 declare const monitor: MonitorSDK;
 

package/dist/index.esm.js

@@ -45,27 +45,14 @@ class ConfigManager {
     }
     /**
      * 初始化配置
-     * @param skipValidation 是否跳过必填校验（用于远程配置已获取 appId/dsn 的场景）
      */
     init(userConfig, skipValidation = false) {
         if (!skipValidation) {
-            // 如果没有 configUrl，则 appId 和 dsn 是必填的
-            if (!userConfig.configUrl) {
-                if (!userConfig.appId) {
-                    throw new Error('[Monitor] appId is required when configUrl is not provided');
-                }
-                if (!userConfig.dsn) {
-                    throw new Error('[Monitor] dsn is required when configUrl is not provided');
-                }
-            }
-        }
-        else {
-            // 远程配置模式下，校验合并后的配置
             if (!userConfig.appId) {
-                throw new Error('[Monitor] appId is required (not found in remote config)');
+                throw new Error('[Monitor] appId is required');
             }
             if (!userConfig.dsn) {
-                throw new Error('[Monitor] dsn is required (not found in remote config)');
+                throw new Error('[Monitor] dsn is required');
             }
         }
         this.config = this.mergeConfig(DEFAULT_CONFIG, userConfig);
@@ -289,6 +276,13 @@ class Sender {
     doSend(data) {
         const cfg = config.get();
         const dsn = cfg.dsn;
+        // dsn 未配置，跳过发送
+        if (!dsn) {
+            if (cfg.debug) {
+                console.warn('[Monitor] dsn not configured, skip sending');
+            }
+            return;
+        }
         const payload = JSON.stringify(data);
         // 优先使用 sendBeacon（更可靠、异步、不阻塞页面）
         if (supportsSendBeacon()) {
@@ -387,13 +381,63 @@ const SDK_VERSION$1 = '1.0.0';
  * 上报器类
  */
 class Reporter {
+    constructor() {
+        /** SDK 是否就绪 */
+        this.ready = false;
+        /** 早期数据缓存队列（SDK 未就绪时缓存） */
+        this.earlyBuffer = [];
+        /** 最大缓存数量 */
+        this.maxEarlyBufferSize = 50;
+    }
+    /**
+     * 设置 SDK 就绪状态
+     */
+    setReady(ready) {
+        this.ready = ready;
+        // 就绪后发送缓存的早期数据
+        if (ready && this.earlyBuffer.length > 0) {
+            console.log(`[Monitor] Flushing ${this.earlyBuffer.length} early buffered items`);
+            this.flushEarlyBuffer();
+        }
+    }
+    /**
+     * 发送早期缓存的数据
+     */
+    flushEarlyBuffer() {
+        while (this.earlyBuffer.length > 0) {
+            const item = this.earlyBuffer.shift();
+            if (!item)
+                continue;
+            switch (item.type) {
+                case 'error':
+                    this.reportError(item.data);
+                    break;
+                case 'performance':
+                    this.reportPerformance(item.data);
+                    break;
+                case 'behavior':
+                    this.reportBehavior(item.data);
+                    break;
+            }
+        }
+    }
+    /**
+     * 缓存早期数据
+     */
+    bufferEarly(type, data) {
+        if (this.earlyBuffer.length >= this.maxEarlyBufferSize) {
+            // 缓存已满，丢弃最早的数据
+            this.earlyBuffer.shift();
+        }
+        this.earlyBuffer.push({ type, data });
+    }
     /**
      * 构建基础数据
      */
     buildBaseData() {
         const cfg = config.get();
         return {
-            appId: cfg.appId,
+            appId: cfg.appId || '',
             userId: cfg.user?.userId,
             sessionId: context.getSessionId(),
             pageUrl: getPageUrl(),
@@ -414,6 +458,11 @@ class Reporter {
      * 上报错误
      */
     reportError(data) {
+        // SDK 未就绪时缓存数据
+        if (!this.ready) {
+            this.bufferEarly('error', data);
+            return;
+        }
         if (!this.shouldSample('error'))
             return;
         const cfg = config.get();
@@ -435,6 +484,11 @@ class Reporter {
      * 上报性能
      */
     reportPerformance(data) {
+        // SDK 未就绪时缓存数据
+        if (!this.ready) {
+            this.bufferEarly('performance', data);
+            return;
+        }
         if (!this.shouldSample('performance'))
             return;
         const reportData = {
@@ -447,6 +501,11 @@ class Reporter {
      * 上报行为
      */
     reportBehavior(data) {
+        // SDK 未就绪时缓存数据
+        if (!this.ready) {
+            this.bufferEarly('behavior', data);
+            return;
+        }
         if (!this.shouldSample('behavior'))
             return;
         const reportData = {
@@ -1435,12 +1494,8 @@ function installBehaviorMonitor() {
  * ```
  */
 const VueMonitorPlugin = {
-    install(app, options) {
-        if (!options || !options.appId || !options.dsn) {
-            console.warn('[Monitor] VueMonitorPlugin requires appId and dsn in options');
-            return;
-        }
-        // 初始化 SDK（如果尚未初始化）
+    install(app, options = {}) {
+        // 初始化 SDK（支持空配置，后续通过 updateConfig 激活）
         try {
             monitor.init(options);
         }
@@ -1536,17 +1591,8 @@ const VueMonitorPlugin = {
  * );
  * ```
  */
-function createReactErrorBoundary(React, config) {
-    if (!config || !config.appId || !config.dsn) {
-        console.warn('[Monitor] createReactErrorBoundary requires appId and dsn in config');
-        // 返回一个空的组件
-        return class EmptyBoundary extends React.Component {
-            render() {
-                return this.props.children;
-            }
-        };
-    }
-    // 初始化 SDK（如果尚未初始化）
+function createReactErrorBoundary(React, config = {}) {
+    // 初始化 SDK（支持空配置，后续通过 updateConfig 激活）
     try {
         monitor.init(config);
     }
@@ -1642,64 +1688,131 @@ const SDK_VERSION = '1.0.0';
  */
 class MonitorSDK {
     constructor() {
+        /** SDK 是否已初始化（基础初始化，可能还没有完整配置） */
         this.initialized = false;
-        this.initializing = false;
+        /** SDK 是否已就绪（配置完整，可以上报数据） */
+        this.ready = false;
+        /** 是否正在加载远程配置 */
+        this.loading = false;
+        /** 监控模块是否已安装 */
+        this.monitorsInstalled = false;
     }
     /**
      * 初始化 SDK
-     * 如果配置了 configUrl，将先从远程获取配置（仅获取一次）
-     * 无需 await，SDK 内部会自动处理异步逻辑
+     * 支持空配置初始化，后续通过 updateConfig 传入 configUrl 完成配置
      */
-    init(userConfig) {
-        if (this.initialized || this.initializing) {
-            if (this.initialized) {
-                console.warn('[Monitor] SDK already initialized');
-            }
+    init(userConfig = {}) {
+        if (this.initialized) {
+            console.warn('[Monitor] SDK already initialized');
             return;
         }
-        // 如果配置了 configUrl，异步获取远程配置后再初始化
+        // 如果配置了 configUrl，异步获取远程配置
         if (userConfig.configUrl) {
-            this.initializing = true;
+            this.loading = true;
+            this.initBasic(userConfig);
             this.fetchRemoteConfig(userConfig.configUrl)
                 .then((remoteConfig) => {
-                // 远程配置作为基础，用户本地配置覆盖远程配置
                 const finalConfig = this.mergeUserConfig(remoteConfig, userConfig);
                 if (userConfig.debug) {
                     console.log('[Monitor] Remote config loaded:', remoteConfig);
                 }
-                this.doInit(finalConfig, true);
+                this.activate(finalConfig);
             })
                 .catch((error) => {
-                this.initializing = false;
+                this.loading = false;
                 console.error('[Monitor] Failed to fetch remote config:', error);
             });
         }
+        else if (userConfig.appId && userConfig.dsn) {
+            // 有完整配置，直接激活
+            this.initBasic(userConfig);
+            this.activate(userConfig);
+        }
         else {
-            // 没有 configUrl，直接同步初始化
-            this.doInit(userConfig, false);
+            // 空配置或不完整配置，只做基础初始化，等待后续 updateConfig
+            this.initBasic(userConfig);
+            console.log('[Monitor] SDK initialized in pending mode. Call updateConfig({configUrl}) to activate.');
         }
     }
     /**
-     * 执行实际的初始化逻辑
+     * 基础初始化（安装监控模块，但不开始上报）
      */
-    doInit(finalConfig, isRemoteConfig) {
-        // 初始化配置
-        config.init({
-            ...finalConfig,
-            version: finalConfig.version || SDK_VERSION,
-        }, isRemoteConfig);
+    initBasic(userConfig) {
         // 初始化上下文
-        const maxBreadcrumbs = config.get().behavior?.maxBreadcrumbs || 20;
+        const maxBreadcrumbs = userConfig.behavior?.maxBreadcrumbs || 20;
         context.init(maxBreadcrumbs);
+        // 安装监控模块（早期捕获的数据会被缓存）
+        if (!this.monitorsInstalled) {
+            installErrorHandlers();
+            installPerformanceMonitor();
+            installBehaviorMonitor();
+            this.monitorsInstalled = true;
+        }
         this.initialized = true;
-        this.initializing = false;
+        if (userConfig.debug) {
+            console.log('[Monitor] SDK basic initialized (monitors installed, waiting for config)');
+        }
+    }
+    /**
+     * 激活 SDK（配置完整后调用）
+     */
+    activate(finalConfig) {
+        // 初始化配置管理器
+        config.init({
+            ...finalConfig,
+            version: finalConfig.version || SDK_VERSION,
+        }, true);
+        this.ready = true;
+        this.loading = false;
+        // 通知 reporter 可以开始上报（会自动发送缓存的早期数据）
+        reporter.setReady(true);
         if (config.get().debug) {
-            console.log('[Monitor] SDK initialized', config.get());
+            console.log('[Monitor] SDK activated with config:', config.get());
+        }
+    }
+    /**
+     * 动态更新配置
+     * 如果传入 configUrl，会从远程获取配置并激活 SDK
+     */
+    updateConfig(partialConfig) {
+        // 如果传入了 configUrl，从远程获取配置
+        if (partialConfig.configUrl) {
+            console.log('[Monitor] Fetching remote config from:', partialConfig.configUrl);
+            this.loading = true;
+            this.fetchRemoteConfig(partialConfig.configUrl)
+                .then((remoteConfig) => {
+                const mergedConfig = this.mergeUserConfig(remoteConfig, partialConfig);
+                // 移除 configUrl
+                delete mergedConfig.configUrl;
+                if (this.ready) {
+                    // 已就绪，更新配置
+                    config.update(mergedConfig);
+                    this.loading = false;
+                    if (config.get().debug) {
+                        console.log('[Monitor] Config updated from remote:', mergedConfig);
+                    }
+                }
+                else {
+                    // 未就绪，激活 SDK
+                    this.activate(mergedConfig);
+                }
+            })
+                .catch((error) => {
+                this.loading = false;
+                console.error('[Monitor] Failed to fetch remote config:', error);
+            });
+        }
+        else {
+            // 普通配置更新
+            if (!this.ready) {
+                console.warn('[Monitor] SDK not ready. Please provide configUrl or (appId + dsn) first.');
+                return;
+            }
+            config.update(partialConfig);
+            if (config.get().debug) {
+                console.log('[Monitor] Config updated', partialConfig);
+            }
         }
-        // 安装监控模块
-        installErrorHandlers();
-        installPerformanceMonitor();
-        installBehaviorMonitor();
     }
     /**
      * 从远程获取配置
@@ -1725,7 +1838,7 @@ class MonitorSDK {
             if (Object.prototype.hasOwnProperty.call(local, key)) {
                 const localValue = local[key];
                 const remoteValue = remote[key];
-                // 跳过 configUrl，不需要传递给最终配置
+                // 跳过 configUrl
                 if (key === 'configUrl')
                     continue;
                 if (localValue !== null &&
@@ -1746,55 +1859,33 @@ class MonitorSDK {
         return result;
     }
     /**
-     * 设置用户信息
+     * 检查 SDK 是否就绪
      */
-    setUser(user) {
-        this.checkInit();
-        config.setUser(user);
+    isReady() {
+        return this.ready;
     }
     /**
-     * 动态更新配置
-     * @description 可以在运行时更新 SDK 配置，如 debug、sampling、report 等
-     * 如果传入 configUrl，会从远程获取配置并合并
+     * 设置用户信息
      */
-    updateConfig(partialConfig) {
-        this.checkInit();
-        // 如果传入了 configUrl，从远程获取配置并更新
-        if (partialConfig.configUrl) {
-            this.fetchRemoteConfig(partialConfig.configUrl)
-                .then((remoteConfig) => {
-                // 远程配置作为基础，传入的其他本地配置覆盖远程配置
-                const mergedConfig = this.mergeUserConfig(remoteConfig, partialConfig);
-                // 移除 configUrl，不需要存到配置里
-                delete mergedConfig.configUrl;
-                config.update(mergedConfig);
-                if (config.get().debug) {
-                    console.log('[Monitor] Config updated from remote:', mergedConfig);
-                }
-            })
-                .catch((error) => {
-                console.error('[Monitor] Failed to fetch remote config:', error);
-            });
-        }
-        else {
-            config.update(partialConfig);
-            if (config.get().debug) {
-                console.log('[Monitor] Config updated', partialConfig);
-            }
-        }
+    setUser(user) {
+        if (!this.ready)
+            return;
+        config.setUser(user);
     }
     /**
      * 获取当前配置
      */
     getConfig() {
-        this.checkInit();
+        if (!this.ready)
+            return null;
         return config.get();
     }
     /**
      * 手动上报错误
      */
     captureError(error, extra) {
-        this.checkInit();
+        if (!this.ready)
+            return;
         const errorData = {
             type: 'js_error',
             message: typeof error === 'string' ? error : error.message,
@@ -1807,7 +1898,8 @@ class MonitorSDK {
      * 手动上报性能数据
      */
     capturePerformance(metrics) {
-        this.checkInit();
+        if (!this.ready)
+            return;
         reporter.reportPerformance({
             type: 'performance',
             metrics,
@@ -1817,7 +1909,8 @@ class MonitorSDK {
      * 手动上报行为数据
      */
     captureBehavior(action, data) {
-        this.checkInit();
+        if (!this.ready)
+            return;
         reporter.reportBehavior({
             type: 'behavior',
             action,
@@ -1828,14 +1921,16 @@ class MonitorSDK {
      * 添加面包屑
      */
     addBreadcrumb(crumb) {
-        this.checkInit();
+        if (!this.initialized)
+            return;
         context.addBreadcrumb(crumb);
     }
     /**
      * 立即发送缓冲区数据
      */
     flush() {
-        this.checkInit();
+        if (!this.ready)
+            return;
         reporter.flush();
     }
     /**
@@ -1844,14 +1939,6 @@ class MonitorSDK {
     getVersion() {
         return SDK_VERSION;
     }
-    /**
-     * 检查是否已初始化
-     */
-    checkInit() {
-        if (!this.initialized) {
-            throw new Error('[Monitor] SDK not initialized. Please call init() first.');
-        }
-    }
 }
 // 导出单例
 const monitor = new MonitorSDK();