@tracelog/lib 0.5.5 → 0.6.1

package/dist/cjs/utils/validations/config-validations.utils.js

@@ -1,10 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isValidConfigApiResponse = exports.validateAndNormalizeConfig = exports.validateAppConfig = void 0;
+exports.validateAndNormalizeConfig = exports.validateAppConfig = void 0;
 const constants_1 = require("../../constants");
-const types_1 = require("../../types");
 const validation_error_types_1 = require("../../types/validation-error.types");
-const logging_1 = require("../logging");
+const logging_utils_1 = require("../logging.utils");
 /**
  * Validates the app configuration object (before normalization)
  * This validates the structure and basic types but allows for normalization afterward
@@ -13,42 +12,18 @@ const logging_1 = require("../logging");
  * @throws {AppConfigValidationError} If other configuration validation fails
  */
 const validateAppConfig = (config) => {
-    // Validate config exists and has id property
     if (!config || typeof config !== 'object') {
-        logging_1.debugLog.clientError('ConfigValidation', 'Configuration must be an object', { config });
         throw new validation_error_types_1.AppConfigValidationError('Configuration must be an object', 'config');
     }
-    // Check if id property exists (allow falsy values to be handled by normalization)
-    if (!('id' in config)) {
-        logging_1.debugLog.clientError('ConfigValidation', 'Project ID is missing from configuration');
-        throw new validation_error_types_1.ProjectIdValidationError(constants_1.VALIDATION_MESSAGES.MISSING_PROJECT_ID, 'config');
-    }
-    // Check basic type - null, undefined, or non-string values should fail here
-    if (config.id === null || config.id === undefined || typeof config.id !== 'string') {
-        logging_1.debugLog.clientError('ConfigValidation', 'Project ID must be a non-empty string', {
-            providedId: config.id,
-            type: typeof config.id,
-        });
-        throw new validation_error_types_1.ProjectIdValidationError(constants_1.VALIDATION_MESSAGES.MISSING_PROJECT_ID, 'config');
-    }
     if (config.sessionTimeout !== undefined) {
         if (typeof config.sessionTimeout !== 'number' ||
             config.sessionTimeout < constants_1.MIN_SESSION_TIMEOUT_MS ||
             config.sessionTimeout > constants_1.MAX_SESSION_TIMEOUT_MS) {
-            logging_1.debugLog.clientError('ConfigValidation', 'Invalid session timeout', {
-                provided: config.sessionTimeout,
-                min: constants_1.MIN_SESSION_TIMEOUT_MS,
-                max: constants_1.MAX_SESSION_TIMEOUT_MS,
-            });
             throw new validation_error_types_1.SessionTimeoutValidationError(constants_1.VALIDATION_MESSAGES.INVALID_SESSION_TIMEOUT, 'config');
         }
     }
     if (config.globalMetadata !== undefined) {
         if (typeof config.globalMetadata !== 'object' || config.globalMetadata === null) {
-            logging_1.debugLog.clientError('ConfigValidation', 'Global metadata must be an object', {
-                provided: config.globalMetadata,
-                type: typeof config.globalMetadata,
-            });
             throw new validation_error_types_1.AppConfigValidationError(constants_1.VALIDATION_MESSAGES.INVALID_GLOBAL_METADATA, 'config');
         }
     }
@@ -60,31 +35,24 @@ const validateAppConfig = (config) => {
     }
     if (config.sensitiveQueryParams !== undefined) {
         if (!Array.isArray(config.sensitiveQueryParams)) {
-            logging_1.debugLog.clientError('ConfigValidation', 'Sensitive query params must be an array', {
-                provided: config.sensitiveQueryParams,
-                type: typeof config.sensitiveQueryParams,
-            });
             throw new validation_error_types_1.AppConfigValidationError(constants_1.VALIDATION_MESSAGES.INVALID_SENSITIVE_QUERY_PARAMS, 'config');
         }
         for (const param of config.sensitiveQueryParams) {
             if (typeof param !== 'string') {
-                logging_1.debugLog.clientError('ConfigValidation', 'All sensitive query params must be strings', {
-                    param,
-                    type: typeof param,
-                });
                 throw new validation_error_types_1.AppConfigValidationError('All sensitive query params must be strings', 'config');
             }
         }
     }
     if (config.errorSampling !== undefined) {
         if (typeof config.errorSampling !== 'number' || config.errorSampling < 0 || config.errorSampling > 1) {
-            logging_1.debugLog.clientError('ConfigValidation', 'Invalid error sampling rate', {
-                provided: config.errorSampling,
-                expected: '0-1',
-            });
             throw new validation_error_types_1.SamplingRateValidationError(constants_1.VALIDATION_MESSAGES.INVALID_ERROR_SAMPLING_RATE, 'config');
         }
     }
+    if (config.samplingRate !== undefined) {
+        if (typeof config.samplingRate !== 'number' || config.samplingRate < 0 || config.samplingRate > 1) {
+            throw new validation_error_types_1.SamplingRateValidationError(constants_1.VALIDATION_MESSAGES.INVALID_SAMPLING_RATE, 'config');
+        }
+    }
 };
 exports.validateAppConfig = validateAppConfig;
 /**
@@ -136,19 +104,25 @@ const validateScrollContainerSelectors = (selectors) => {
     const selectorsArray = Array.isArray(selectors) ? selectors : [selectors];
     for (const selector of selectorsArray) {
         if (typeof selector !== 'string' || selector.trim() === '') {
-            logging_1.debugLog.clientError('ConfigValidation', 'Invalid scroll container selector', {
-                selector,
-                type: typeof selector,
-                isEmpty: selector === '' || (typeof selector === 'string' && selector.trim() === ''),
+            (0, logging_utils_1.log)('error', 'Invalid scroll container selector', {
+                showToClient: true,
+                data: {
+                    selector,
+                    type: typeof selector,
+                    isEmpty: selector === '' || (typeof selector === 'string' && selector.trim() === ''),
+                },
             });
             throw new validation_error_types_1.AppConfigValidationError(constants_1.VALIDATION_MESSAGES.INVALID_SCROLL_CONTAINER_SELECTORS, 'config');
         }
         // Validate CSS selector syntax using regex-based validation (XSS prevention)
         // This validates syntax WITHOUT executing document.querySelector()
         if (!isValidCssSelectorSyntax(selector)) {
-            logging_1.debugLog.clientError('ConfigValidation', 'Invalid or potentially unsafe CSS selector', {
-                selector,
-                reason: 'Failed security validation',
+            (0, logging_utils_1.log)('error', 'Invalid or potentially unsafe CSS selector', {
+                showToClient: true,
+                data: {
+                    selector,
+                    reason: 'Failed security validation',
+                },
             });
             throw new validation_error_types_1.AppConfigValidationError('Invalid or potentially unsafe CSS selector', 'config');
         }
@@ -159,23 +133,42 @@ const validateScrollContainerSelectors = (selectors) => {
  * @param integrations - Integrations configuration to validate
  */
 const validateIntegrations = (integrations) => {
-    if (!integrations)
+    if (!integrations) {
         return;
+    }
+    if (integrations.tracelog) {
+        if (!integrations.tracelog.projectId ||
+            typeof integrations.tracelog.projectId !== 'string' ||
+            integrations.tracelog.projectId.trim() === '') {
+            throw new validation_error_types_1.IntegrationValidationError(constants_1.VALIDATION_MESSAGES.INVALID_TRACELOG_PROJECT_ID, 'config');
+        }
+    }
+    if (integrations.custom) {
+        if (!integrations.custom.apiUrl ||
+            typeof integrations.custom.apiUrl !== 'string' ||
+            integrations.custom.apiUrl.trim() === '') {
+            throw new validation_error_types_1.IntegrationValidationError(constants_1.VALIDATION_MESSAGES.INVALID_CUSTOM_API_URL, 'config');
+        }
+        if (integrations.custom.allowHttp !== undefined && typeof integrations.custom.allowHttp !== 'boolean') {
+            throw new validation_error_types_1.IntegrationValidationError('allowHttp must be a boolean', 'config');
+        }
+        const apiUrl = integrations.custom.apiUrl.trim();
+        if (!apiUrl.startsWith('http://') && !apiUrl.startsWith('https://')) {
+            throw new validation_error_types_1.IntegrationValidationError('Custom API URL must start with "http://" or "https://"', 'config');
+        }
+        const allowHttp = integrations.custom.allowHttp ?? false;
+        if (!allowHttp && apiUrl.startsWith('http://')) {
+            throw new validation_error_types_1.IntegrationValidationError('Custom API URL must use HTTPS in production. Set allowHttp: true in integration config to allow HTTP (not recommended)', 'config');
+        }
+    }
     if (integrations.googleAnalytics) {
         if (!integrations.googleAnalytics.measurementId ||
             typeof integrations.googleAnalytics.measurementId !== 'string' ||
             integrations.googleAnalytics.measurementId.trim() === '') {
-            logging_1.debugLog.clientError('ConfigValidation', 'Invalid Google Analytics measurement ID', {
-                provided: integrations.googleAnalytics.measurementId,
-                type: typeof integrations.googleAnalytics.measurementId,
-            });
             throw new validation_error_types_1.IntegrationValidationError(constants_1.VALIDATION_MESSAGES.INVALID_GOOGLE_ANALYTICS_ID, 'config');
         }
         const measurementId = integrations.googleAnalytics.measurementId.trim();
         if (!measurementId.match(/^(G-|UA-)/)) {
-            logging_1.debugLog.clientError('ConfigValidation', 'Google Analytics measurement ID must start with "G-" or "UA-"', {
-                provided: measurementId,
-            });
             throw new validation_error_types_1.IntegrationValidationError('Google Analytics measurement ID must start with "G-" or "UA-"', 'config');
         }
     }
@@ -189,52 +182,22 @@ const validateIntegrations = (integrations) => {
  * @throws {AppConfigValidationError} If other configuration validation fails
  */
 const validateAndNormalizeConfig = (config) => {
-    // First validate the structure and basic types
     (0, exports.validateAppConfig)(config);
-    // Normalize string values
     const normalizedConfig = {
         ...config,
-        id: config.id.trim(),
+        sessionTimeout: config.sessionTimeout ?? constants_1.DEFAULT_SESSION_TIMEOUT,
         globalMetadata: config.globalMetadata ?? {},
         sensitiveQueryParams: config.sensitiveQueryParams ?? [],
+        errorSampling: config.errorSampling ?? 1,
+        samplingRate: config.samplingRate ?? 1,
     };
-    // Validate normalized values - this catches whitespace-only IDs
-    if (!normalizedConfig.id) {
-        logging_1.debugLog.clientError('ConfigValidation', 'Project ID is empty after trimming whitespace', {
-            originalId: config.id,
-            normalizedId: normalizedConfig.id,
-        });
-        throw new validation_error_types_1.ProjectIdValidationError(constants_1.VALIDATION_MESSAGES.PROJECT_ID_EMPTY_AFTER_TRIM, 'config');
+    // Normalize integrations
+    if (normalizedConfig.integrations?.custom) {
+        normalizedConfig.integrations.custom = {
+            ...normalizedConfig.integrations.custom,
+            allowHttp: normalizedConfig.integrations.custom.allowHttp ?? false,
+        };
     }
     return normalizedConfig;
 };
 exports.validateAndNormalizeConfig = validateAndNormalizeConfig;
-/**
- * Type guard to check if a JSON response is a valid API config
- * @param json - The JSON to validate
- * @returns True if the JSON is a valid API config
- */
-const isValidConfigApiResponse = (json) => {
-    try {
-        if (typeof json !== 'object' || !json) {
-            return false;
-        }
-        const response = json;
-        const result = {
-            mode: response['mode'] === undefined || [types_1.Mode.QA, types_1.Mode.DEBUG].includes(response['mode']),
-            // Zero is valid for samplingRate (means "sample nothing")
-            samplingRate: response['samplingRate'] === undefined ||
-                (typeof response['samplingRate'] === 'number' &&
-                    response['samplingRate'] >= 0 &&
-                    response['samplingRate'] <= 1),
-            tags: response['tags'] === undefined || Array.isArray(response['tags']),
-            excludedUrlPaths: response['excludedUrlPaths'] === undefined || Array.isArray(response['excludedUrlPaths']),
-            ipExcluded: response['ipExcluded'] === undefined || typeof response['ipExcluded'] === 'boolean',
-        };
-        return Object.values(result).every(Boolean);
-    }
-    catch {
-        return false;
-    }
-};
-exports.isValidConfigApiResponse = isValidConfigApiResponse;

package/dist/cjs/utils/validations/event-validations.utils.js

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isEventValid = void 0;
+const logging_utils_1 = require("../logging.utils");
 const metadata_validations_utils_1 = require("./metadata-validations.utils");
-const logging_1 = require("../logging");
 /**
  * Validates a complete event with name and optional metadata
  * @param eventName - The event name to validate
@@ -12,7 +12,10 @@ const logging_1 = require("../logging");
 const isEventValid = (eventName, metadata) => {
     const nameValidation = (0, metadata_validations_utils_1.isValidEventName)(eventName);
     if (!nameValidation.valid) {
-        logging_1.debugLog.clientError('EventValidation', 'Event name validation failed', { eventName, error: nameValidation.error });
+        (0, logging_utils_1.log)('error', 'Event name validation failed', {
+            showToClient: true,
+            data: { eventName, error: nameValidation.error },
+        });
         return nameValidation;
     }
     if (!metadata) {
@@ -20,9 +23,12 @@ const isEventValid = (eventName, metadata) => {
     }
     const metadataValidation = (0, metadata_validations_utils_1.isValidMetadata)(eventName, metadata, 'customEvent');
     if (!metadataValidation.valid) {
-        logging_1.debugLog.clientError('EventValidation', 'Event metadata validation failed', {
-            eventName,
-            error: metadataValidation.error,
+        (0, logging_utils_1.log)('error', 'Event metadata validation failed', {
+            showToClient: true,
+            data: {
+                eventName,
+                error: metadataValidation.error,
+            },
         });
     }
     return metadataValidation;

package/dist/cjs/utils/validations/index.d.ts

@@ -2,4 +2,3 @@ export * from './config-validations.utils';
 export * from './event-validations.utils';
 export * from './metadata-validations.utils';
 export * from './type-guards.utils';
-export * from './url-validations.utils';

package/dist/cjs/utils/validations/index.js

@@ -18,4 +18,3 @@ __exportStar(require("./config-validations.utils"), exports);
 __exportStar(require("./event-validations.utils"), exports);
 __exportStar(require("./metadata-validations.utils"), exports);
 __exportStar(require("./type-guards.utils"), exports);
-__exportStar(require("./url-validations.utils"), exports);

package/dist/cjs/utils/validations/metadata-validations.utils.js

@@ -142,7 +142,6 @@ const isValidMetadata = (eventName, metadata, type) => {
                 sanitizedArray.push(itemValidation.sanitizedMetadata);
             }
         }
-        // Allow empty arrays after sanitization
         return {
             valid: true,
             sanitizedMetadata: sanitizedArray,

package/dist/cjs/utils/validations/type-guards.utils.d.ts

@@ -1,6 +1,6 @@
 /**
- * Checks if an object contains only primitive fields (string, number, boolean, or string arrays)
+ * Checks if an object contains only primitive fields, string arrays, or arrays of flat objects
  * @param object - The object to check
- * @returns True if the object contains only primitive fields
+ * @returns True if the object contains only valid fields
  */
 export declare const isOnlyPrimitiveFields: (object: Record<string, unknown>) => boolean;

package/dist/cjs/utils/validations/type-guards.utils.js

@@ -1,10 +1,41 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isOnlyPrimitiveFields = void 0;
+const constants_1 = require("../../constants");
 /**
- * Checks if an object contains only primitive fields (string, number, boolean, or string arrays)
+ * Validates if an item in an array is a valid nested object
+ * @param item - The item to validate
+ * @returns True if the item is a valid nested object
+ */
+const isValidArrayItem = (item) => {
+    if (typeof item === 'string') {
+        return true;
+    }
+    // Allow objects with primitive fields only (one level deep)
+    if (typeof item === 'object' && item !== null && !Array.isArray(item)) {
+        const entries = Object.entries(item);
+        // Check key count limit
+        if (entries.length > constants_1.MAX_NESTED_OBJECT_KEYS) {
+            return false;
+        }
+        // All values must be primitives (no nested objects or arrays)
+        for (const [, value] of entries) {
+            if (value === null || value === undefined) {
+                continue;
+            }
+            const type = typeof value;
+            if (type !== 'string' && type !== 'number' && type !== 'boolean') {
+                return false;
+            }
+        }
+        return true;
+    }
+    return false;
+};
+/**
+ * Checks if an object contains only primitive fields, string arrays, or arrays of flat objects
  * @param object - The object to check
- * @returns True if the object contains only primitive fields
+ * @returns True if the object contains only valid fields
  */
 const isOnlyPrimitiveFields = (object) => {
     if (typeof object !== 'object' || object === null) {
@@ -19,8 +50,23 @@ const isOnlyPrimitiveFields = (object) => {
             continue;
         }
         if (Array.isArray(value)) {
-            if (!value.every((item) => typeof item === 'string')) {
-                return false;
+            if (value.length === 0) {
+                continue;
+            }
+            // Determine array type from first item
+            const firstItem = value[0];
+            const isStringArray = typeof firstItem === 'string';
+            // All items must be of the same type (all strings OR all objects)
+            if (isStringArray) {
+                if (!value.every((item) => typeof item === 'string')) {
+                    return false;
+                }
+            }
+            else {
+                // Must be all objects
+                if (!value.every((item) => isValidArrayItem(item))) {
+                    return false;
+                }
             }
             continue;
         }

package/dist/esm/api.d.ts

@@ -1,8 +1,18 @@
-import { MetadataType, AppConfig, EmitterCallback, EmitterMap } from './types';
+import { App } from './app';
+import { MetadataType, Config, EmitterCallback, EmitterMap } from './types';
 import './types/window.types';
-export declare const init: (appConfig: AppConfig) => Promise<void>;
+export declare const init: (config: Config) => Promise<void>;
 export declare const event: (name: string, metadata?: Record<string, MetadataType> | Record<string, MetadataType>[]) => void;
 export declare const on: <K extends keyof EmitterMap>(event: K, callback: EmitterCallback<EmitterMap[K]>) => void;
 export declare const off: <K extends keyof EmitterMap>(event: K, callback: EmitterCallback<EmitterMap[K]>) => void;
 export declare const isInitialized: () => boolean;
 export declare const destroy: () => Promise<void>;
+/**
+ * Internal sync function - ONLY for TestBridge in development
+ *
+ * WARNING: This function is internal and should NEVER be called directly.
+ * It's only exported for TestBridge synchronization in dev mode.
+ *
+ * @internal
+ */
+export declare const __setAppInstance: (instance: App | null) => void;

package/dist/esm/api.js

@@ -1,48 +1,58 @@
 import { App } from './app';
-import { debugLog, validateAndNormalizeConfig } from './utils';
+import { log, validateAndNormalizeConfig } from './utils';
 import { TestBridge } from './test-bridge';
+import { INITIALIZATION_TIMEOUT_MS } from './constants';
 import './types/window.types';
+// Buffer for listeners registered before init()
+const pendingListeners = [];
 let app = null;
 let isInitializing = false;
 let isDestroying = false;
-export const init = async (appConfig) => {
+export const init = async (config) => {
     if (typeof window === 'undefined' || typeof document === 'undefined') {
-        throw new Error('This library can only be used in a browser environment');
+        throw new Error('[TraceLog] This library can only be used in a browser environment');
     }
     if (window.__traceLogDisabled) {
         return;
     }
     if (app) {
-        debugLog.debug('API', 'Library already initialized, skipping duplicate initialization');
         return;
     }
     if (isInitializing) {
-        debugLog.warn('API', 'Initialization already in progress');
-        throw new Error('Initialization already in progress');
+        return;
     }
     isInitializing = true;
     try {
-        debugLog.info('API', 'Initializing TraceLog', { projectId: appConfig.id });
-        const validatedConfig = validateAndNormalizeConfig(appConfig);
+        const validatedConfig = validateAndNormalizeConfig(config);
         const instance = new App();
         try {
-            await instance.init(validatedConfig);
+            // Attach buffered listeners BEFORE init() so they capture initial events
+            pendingListeners.forEach(({ event, callback }) => {
+                instance.on(event, callback);
+            });
+            pendingListeners.length = 0;
+            // Wrap initialization with timeout using Promise.race
+            const initPromise = instance.init(validatedConfig);
+            const timeoutPromise = new Promise((_, reject) => {
+                setTimeout(() => {
+                    reject(new Error(`[TraceLog] Initialization timeout after ${INITIALIZATION_TIMEOUT_MS}ms`));
+                }, INITIALIZATION_TIMEOUT_MS);
+            });
+            await Promise.race([initPromise, timeoutPromise]);
             app = instance;
-            debugLog.info('API', 'TraceLog initialized successfully', { projectId: validatedConfig.id });
         }
         catch (error) {
             try {
                 await instance.destroy(true);
             }
             catch (cleanupError) {
-                debugLog.warn('API', 'Failed to cleanup partially initialized app', { cleanupError });
+                log('error', 'Failed to cleanup partially initialized app', { error: cleanupError });
             }
             throw error;
         }
     }
     catch (error) {
         app = null;
-        debugLog.error('API', 'Initialization failed', { error });
         throw error;
     }
     finally {
@@ -51,25 +61,29 @@ export const init = async (appConfig) => {
 };
 export const event = (name, metadata) => {
     if (!app) {
-        throw new Error('TraceLog not initialized. Please call init() first.');
-    }
-    try {
-        app.sendCustomEvent(name, metadata);
+        throw new Error('[TraceLog] TraceLog not initialized. Please call init() first.');
     }
-    catch (error) {
-        debugLog.error('API', 'Failed to send custom event', { eventName: name, error });
-        throw error;
+    if (isDestroying) {
+        throw new Error('[TraceLog] Cannot send events while TraceLog is being destroyed');
     }
+    app.sendCustomEvent(name, metadata);
 };
 export const on = (event, callback) => {
-    if (!app) {
-        throw new Error('TraceLog not initialized. Please call init() first.');
+    if (!app || isInitializing) {
+        // Buffer listeners registered before or during init()
+        pendingListeners.push({ event, callback });
+        return;
     }
     app.on(event, callback);
 };
 export const off = (event, callback) => {
     if (!app) {
-        throw new Error('TraceLog not initialized. Please call init() first.');
+        // Remove from pending listeners if not yet initialized
+        const index = pendingListeners.findIndex((l) => l.event === event && l.callback === callback);
+        if (index !== -1) {
+            pendingListeners.splice(index, 1);
+        }
+        return;
     }
     app.off(event, callback);
 };
@@ -78,25 +92,30 @@ export const isInitialized = () => {
 };
 export const destroy = async () => {
     if (!app) {
-        throw new Error('App not initialized');
+        throw new Error('[TraceLog] App not initialized');
     }
     if (isDestroying) {
-        throw new Error('Destroy operation already in progress');
+        throw new Error('[TraceLog] Destroy operation already in progress');
     }
     isDestroying = true;
     try {
-        debugLog.info('API', 'Destroying TraceLog instance');
         await app.destroy();
         app = null;
         isInitializing = false;
-        debugLog.info('API', 'TraceLog destroyed successfully');
+        pendingListeners.length = 0;
+        // Clear TestBridge reference in dev mode to prevent stale references
+        if (process.env.NODE_ENV === 'dev' && typeof window !== 'undefined' && window.__traceLogBridge) {
+            // Don't call destroy on bridge (would cause recursion), just clear reference
+            window.__traceLogBridge = undefined;
+        }
     }
     catch (error) {
-        // Force cleanup even if destroy fails
         app = null;
         isInitializing = false;
-        debugLog.error('API', 'Error during destroy, forced cleanup', { error });
-        throw error;
+        pendingListeners.length = 0;
+        // Log error but don't re-throw - destroy should always complete successfully
+        // Applications should be able to tear down TraceLog even if internal cleanup fails
+        log('warn', 'Error during destroy, forced cleanup completed', { error });
     }
     finally {
         isDestroying = false;
@@ -113,3 +132,28 @@ if (process.env.NODE_ENV === 'dev' && typeof window !== 'undefined') {
         injectTestingBridge();
     }
 }
+/**
+ * Internal sync function - ONLY for TestBridge in development
+ *
+ * WARNING: This function is internal and should NEVER be called directly.
+ * It's only exported for TestBridge synchronization in dev mode.
+ *
+ * @internal
+ */
+export const __setAppInstance = (instance) => {
+    if (instance !== null) {
+        const hasRequiredMethods = typeof instance === 'object' &&
+            'init' in instance &&
+            'destroy' in instance &&
+            'on' in instance &&
+            'off' in instance;
+        if (!hasRequiredMethods) {
+            throw new Error('[TraceLog] Invalid app instance type');
+        }
+    }
+    // Prevent overwriting an already initialized app (except when clearing)
+    if (app !== null && instance !== null && app !== instance) {
+        throw new Error('[TraceLog] Cannot overwrite existing app instance. Call destroy() first.');
+    }
+    app = instance;
+};

package/dist/esm/app.d.ts

@@ -4,7 +4,7 @@ import { SessionHandler } from './handlers/session.handler';
 import { PageViewHandler } from './handlers/page-view.handler';
 import { ClickHandler } from './handlers/click.handler';
 import { ScrollHandler } from './handlers/scroll.handler';
-import { AppConfig, EmitterCallback, EmitterMap } from './types';
+import { Config, EmitterCallback, EmitterMap } from './types';
 import { GoogleAnalyticsIntegration } from './integrations/google-analytics.integration';
 import { StorageManager } from './managers/storage.manager';
 import { PerformanceHandler } from './handlers/performance.handler';
@@ -29,7 +29,7 @@ export declare class App extends StateManager {
         googleAnalytics?: GoogleAnalyticsIntegration;
     };
     get initialized(): boolean;
-    init(appConfig: AppConfig): Promise<void>;
+    init(config: Config): Promise<void>;
     sendCustomEvent(name: string, metadata?: Record<string, unknown> | Record<string, unknown>[]): void;
     on<K extends keyof EmitterMap>(event: K, callback: EmitterCallback<EmitterMap[K]>): void;
     off<K extends keyof EmitterMap>(event: K, callback: EmitterCallback<EmitterMap[K]>): void;