@tracelog/lib 0.4.0 → 0.5.0

package/dist/cjs/managers/session.manager.js

@@ -6,7 +6,7 @@ const types_1 = require("../types");
 const logging_1 = require("../utils/logging");
 const state_manager_1 = require("./state.manager");
 class SessionManager extends state_manager_1.StateManager {
-    constructor(storageManager, eventManager) {
+    constructor(storageManager, eventManager, projectId) {
         super();
         this.sessionTimeoutId = null;
         this.broadcastChannel = null;
@@ -16,10 +16,8 @@ class SessionManager extends state_manager_1.StateManager {
         this.isTracking = false;
         this.storageManager = storageManager;
         this.eventManager = eventManager;
+        this.projectId = projectId;
     }
-    /**
-     * Initialize cross-tab synchronization
-     */
     initCrossTabSync() {
         if (typeof BroadcastChannel === 'undefined') {
             logging_1.debugLog.warn('SessionManager', 'BroadcastChannel not supported');
@@ -48,41 +46,38 @@ class SessionManager extends state_manager_1.StateManager {
             }
         };
     }
-    /**
-     * Share session with other tabs
-     */
     shareSession(sessionId) {
-        this.broadcastChannel?.postMessage({
-            action: 'session_start',
-            projectId: this.getProjectId(),
-            sessionId,
-            timestamp: Date.now(),
-        });
+        if (this.broadcastChannel && typeof this.broadcastChannel.postMessage === 'function') {
+            this.broadcastChannel.postMessage({
+                action: 'session_start',
+                projectId: this.getProjectId(),
+                sessionId,
+                timestamp: Date.now(),
+            });
+        }
     }
     broadcastSessionEnd(sessionId, reason) {
         if (!sessionId) {
             return;
         }
-        this.broadcastChannel?.postMessage({
-            action: 'session_end',
-            projectId: this.getProjectId(),
-            sessionId,
-            reason,
-            timestamp: Date.now(),
-        });
+        if (this.broadcastChannel && typeof this.broadcastChannel.postMessage === 'function') {
+            this.broadcastChannel.postMessage({
+                action: 'session_end',
+                projectId: this.getProjectId(),
+                sessionId,
+                reason,
+                timestamp: Date.now(),
+            });
+        }
     }
-    /**
-     * Cleanup cross-tab sync
-     */
     cleanupCrossTabSync() {
         if (this.broadcastChannel) {
-            this.broadcastChannel.close();
+            if (typeof this.broadcastChannel.close === 'function') {
+                this.broadcastChannel.close();
+            }
             this.broadcastChannel = null;
         }
     }
-    /**
-     * Recover session from localStorage if it exists and hasn't expired
-     */
     recoverSession() {
         const storedSession = this.loadStoredSession();
         if (!storedSession) {
@@ -97,9 +92,6 @@ class SessionManager extends state_manager_1.StateManager {
         logging_1.debugLog.info('SessionManager', 'Session recovered from storage', { sessionId: storedSession.id });
         return storedSession.id;
     }
-    /**
-     * Persist session data to localStorage
-     */
     persistSession(sessionId, lastActivity = Date.now()) {
         this.saveStoredSession({
             id: sessionId,
@@ -136,11 +128,8 @@ class SessionManager extends state_manager_1.StateManager {
         return (0, constants_1.SESSION_STORAGE_KEY)(this.getProjectId());
     }
     getProjectId() {
-        return this.get('config')?.id ?? '';
+        return this.projectId;
     }
-    /**
-     * Start session tracking
-     */
     async startTracking() {
         if (this.isTracking) {
             logging_1.debugLog.warn('SessionManager', 'Session tracking already active');
@@ -153,12 +142,11 @@ class SessionManager extends state_manager_1.StateManager {
         try {
             this.set('sessionId', sessionId);
             this.persistSession(sessionId);
-            // Track session start event
-            this.eventManager.track({
-                type: types_1.EventType.SESSION_START,
-                ...(isRecovered && { session_start_recovered: true }),
-            });
-            // Initialize components
+            if (!isRecovered) {
+                this.eventManager.track({
+                    type: types_1.EventType.SESSION_START,
+                });
+            }
             this.initCrossTabSync();
             this.shareSession(sessionId);
             this.setupSessionTimeout();
@@ -176,15 +164,9 @@ class SessionManager extends state_manager_1.StateManager {
             throw error;
         }
     }
-    /**
-     * Generate unique session ID
-     */
     generateSessionId() {
         return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
     }
-    /**
-     * Setup session timeout
-     */
     setupSessionTimeout() {
         this.clearSessionTimeout();
         const sessionTimeout = this.get('config')?.sessionTimeout ?? constants_1.DEFAULT_SESSION_TIMEOUT;
@@ -192,9 +174,6 @@ class SessionManager extends state_manager_1.StateManager {
             this.endSession('inactivity');
         }, sessionTimeout);
     }
-    /**
-     * Reset session timeout and update activity
-     */
     resetSessionTimeout() {
         this.setupSessionTimeout();
         const sessionId = this.get('sessionId');
@@ -202,27 +181,18 @@ class SessionManager extends state_manager_1.StateManager {
             this.persistSession(sessionId);
         }
     }
-    /**
-     * Clear session timeout
-     */
     clearSessionTimeout() {
         if (this.sessionTimeoutId) {
             clearTimeout(this.sessionTimeoutId);
             this.sessionTimeoutId = null;
         }
     }
-    /**
-     * Setup activity listeners to track user engagement
-     */
     setupActivityListeners() {
         this.activityHandler = () => this.resetSessionTimeout();
         document.addEventListener('click', this.activityHandler, { passive: true });
         document.addEventListener('keydown', this.activityHandler, { passive: true });
         document.addEventListener('scroll', this.activityHandler, { passive: true });
     }
-    /**
-     * Clean up activity listeners
-     */
     cleanupActivityListeners() {
         if (this.activityHandler) {
             document.removeEventListener('click', this.activityHandler);
@@ -231,9 +201,6 @@ class SessionManager extends state_manager_1.StateManager {
             this.activityHandler = null;
         }
     }
-    /**
-     * Setup page lifecycle listeners (visibility and unload)
-     */
     setupLifecycleListeners() {
         if (this.visibilityChangeHandler || this.beforeUnloadHandler) {
             return;
@@ -252,9 +219,7 @@ class SessionManager extends state_manager_1.StateManager {
         this.beforeUnloadHandler = () => {
             this.endSession('page_unload');
         };
-        // Handle tab visibility changes
         document.addEventListener('visibilitychange', this.visibilityChangeHandler);
-        // Handle page unload
         window.addEventListener('beforeunload', this.beforeUnloadHandler);
     }
     cleanupLifecycleListeners() {
@@ -267,14 +232,11 @@ class SessionManager extends state_manager_1.StateManager {
             this.beforeUnloadHandler = null;
         }
     }
-    /**
-     * End current session
-     */
-    endSession(reason) {
+    async endSession(reason) {
         const sessionId = this.get('sessionId');
         if (!sessionId) {
             logging_1.debugLog.warn('SessionManager', 'endSession called without active session', { reason });
-            this.resetSessionState();
+            this.resetSessionState(reason);
             return;
         }
         logging_1.debugLog.info('SessionManager', 'Ending session', { sessionId, reason });
@@ -284,42 +246,39 @@ class SessionManager extends state_manager_1.StateManager {
         });
         const finalize = () => {
             this.broadcastSessionEnd(sessionId, reason);
-            this.resetSessionState();
+            this.resetSessionState(reason);
         };
         const flushResult = this.eventManager.flushImmediatelySync();
         if (flushResult) {
             finalize();
             return;
         }
-        this.eventManager
-            .flushImmediately()
-            .then(finalize)
-            .catch((error) => {
+        try {
+            await this.eventManager.flushImmediately();
+            finalize();
+        }
+        catch (error) {
             logging_1.debugLog.warn('SessionManager', 'Async flush failed during session end', {
                 error: error instanceof Error ? error.message : 'Unknown error',
             });
             finalize();
-        });
+        }
     }
-    resetSessionState() {
+    resetSessionState(reason) {
         this.clearSessionTimeout();
         this.cleanupActivityListeners();
         this.cleanupLifecycleListeners();
         this.cleanupCrossTabSync();
-        this.clearStoredSession();
+        if (reason !== 'page_unload') {
+            this.clearStoredSession();
+        }
         this.set('sessionId', null);
         this.set('hasStartSession', false);
         this.isTracking = false;
     }
-    /**
-     * Stop session tracking
-     */
     async stopTracking() {
-        this.endSession('manual_stop');
+        await this.endSession('manual_stop');
     }
-    /**
-     * Clean up all resources
-     */
     destroy() {
         this.clearSessionTimeout();
         this.cleanupActivityListeners();

package/dist/cjs/managers/state.manager.d.ts

@@ -1,38 +1,11 @@
 import { State } from '../types';
-/**
- * Resets the global state to its initial empty state.
- * Used primarily for testing and cleanup scenarios.
- */
+export declare function getGlobalState(): Readonly<State>;
 export declare function resetGlobalState(): void;
-/**
- * Abstract base class providing state management capabilities to TraceLog components.
- *
- * All managers and handlers extend this class to access and modify the shared global state.
- * State operations are synchronous and thread-safe within the single-threaded browser environment.
- */
 export declare abstract class StateManager {
-    /**
-     * Gets a value from the global state
-     */
     protected get<T extends keyof State>(key: T): State[T];
-    /**
-     * Sets a value in the global state
-     */
     protected set<T extends keyof State>(key: T, value: State[T]): void;
-    /**
-     * Gets the entire state object (for debugging purposes)
-     */
     protected getState(): Readonly<State>;
-    /**
-     * Checks if a state key is considered critical for logging
-     */
     private isCriticalStateKey;
-    /**
-     * Determines if a state change should be logged
-     */
     private shouldLog;
-    /**
-     * Formats values for logging (avoiding large object dumps)
-     */
     private formatLogValue;
 }

package/dist/cjs/managers/state.manager.js

@@ -1,45 +1,30 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StateManager = void 0;
+exports.getGlobalState = getGlobalState;
 exports.resetGlobalState = resetGlobalState;
 const logging_1 = require("../utils/logging");
 const constants_1 = require("../constants");
-/**
- * Global state store shared across all TraceLog components
- */
 const globalState = {};
-/**
- * Resets the global state to its initial empty state.
- * Used primarily for testing and cleanup scenarios.
- */
+function getGlobalState() {
+    return globalState;
+}
 function resetGlobalState() {
     Object.keys(globalState).forEach((key) => {
         delete globalState[key];
     });
 }
-/**
- * Abstract base class providing state management capabilities to TraceLog components.
- *
- * All managers and handlers extend this class to access and modify the shared global state.
- * State operations are synchronous and thread-safe within the single-threaded browser environment.
- */
 class StateManager {
-    /**
-     * Gets a value from the global state
-     */
     get(key) {
         return globalState[key];
     }
-    /**
-     * Sets a value in the global state
-     */
     set(key, value) {
         const oldValue = globalState[key];
         if (key === 'config' && value) {
             const configValue = value;
             if (configValue) {
                 const samplingRate = configValue.samplingRate ?? constants_1.DEFAULT_SAMPLING_RATE;
-                const normalizedSamplingRate = samplingRate > 0 ? samplingRate : constants_1.DEFAULT_SAMPLING_RATE;
+                const normalizedSamplingRate = samplingRate < 0 || samplingRate > 1 ? constants_1.DEFAULT_SAMPLING_RATE : samplingRate;
                 const hasNormalizedSampling = normalizedSamplingRate !== samplingRate;
                 if (hasNormalizedSampling) {
                     const normalizedConfig = { ...configValue, samplingRate: normalizedSamplingRate };
@@ -56,7 +41,6 @@ class StateManager {
         else {
             globalState[key] = value;
         }
-        // Log critical state changes for debugging
         if (this.isCriticalStateKey(key) && this.shouldLog(oldValue, globalState[key])) {
             logging_1.debugLog.debug('StateManager', 'State updated', {
                 key,
@@ -65,27 +49,15 @@ class StateManager {
             });
         }
     }
-    /**
-     * Gets the entire state object (for debugging purposes)
-     */
     getState() {
         return { ...globalState };
     }
-    /**
-     * Checks if a state key is considered critical for logging
-     */
     isCriticalStateKey(key) {
         return key === 'sessionId' || key === 'config' || key === 'hasStartSession';
     }
-    /**
-     * Determines if a state change should be logged
-     */
     shouldLog(oldValue, newValue) {
         return oldValue !== newValue;
     }
-    /**
-     * Formats values for logging (avoiding large object dumps)
-     */
     formatLogValue(key, value) {
         if (key === 'config') {
             return value ? '(configured)' : '(not configured)';

package/dist/cjs/managers/storage.manager.d.ts

@@ -6,6 +6,7 @@
 export declare class StorageManager {
     private readonly storage;
     private readonly fallbackStorage;
+    private hasQuotaExceededError;
     constructor();
     /**
      * Retrieves an item from storage
@@ -27,6 +28,11 @@ export declare class StorageManager {
      * Checks if storage is available
      */
     isAvailable(): boolean;
+    /**
+     * Checks if a QuotaExceededError has occurred
+     * This indicates localStorage is full and data may not persist
+     */
+    hasQuotaError(): boolean;
     /**
      * Initialize localStorage with feature detection
      */

package/dist/cjs/managers/storage.manager.js

@@ -10,6 +10,7 @@ const debug_logger_utils_1 = require("../utils/logging/debug-logger.utils");
 class StorageManager {
     constructor() {
         this.fallbackStorage = new Map();
+        this.hasQuotaExceededError = false;
         this.storage = this.initializeStorage();
         if (!this.storage) {
             debug_logger_utils_1.debugLog.warn('StorageManager', 'localStorage not available, using memory fallback');
@@ -41,7 +42,16 @@ class StorageManager {
             }
         }
         catch (error) {
-            debug_logger_utils_1.debugLog.warn('StorageManager', 'Failed to set item, using fallback', { key, error });
+            if (error instanceof DOMException && error.name === 'QuotaExceededError') {
+                this.hasQuotaExceededError = true;
+                debug_logger_utils_1.debugLog.error('StorageManager', 'localStorage quota exceeded - data will not persist after reload', {
+                    key,
+                    valueSize: value.length,
+                });
+            }
+            else {
+                debug_logger_utils_1.debugLog.warn('StorageManager', 'Failed to set item, using fallback', { key, error });
+            }
         }
         // Always update fallback for consistency
         this.fallbackStorage.set(key, value);
@@ -92,6 +102,13 @@ class StorageManager {
     isAvailable() {
         return this.storage !== null;
     }
+    /**
+     * Checks if a QuotaExceededError has occurred
+     * This indicates localStorage is full and data may not persist
+     */
+    hasQuotaError() {
+        return this.hasQuotaExceededError;
+    }
     /**
      * Initialize localStorage with feature detection
      */

package/dist/cjs/public-api.d.ts

@@ -2,7 +2,7 @@ export * from './app.constants';
 export * from './app.types';
 export declare const tracelog: {
     init: (appConfig: import("./app.types").AppConfig) => Promise<void>;
-    event: (name: string, metadata?: Record<string, import("./app.types").MetadataType>) => void;
+    event: (name: string, metadata?: Record<string, import("./app.types").MetadataType> | Record<string, import("./app.types").MetadataType>[]) => void;
     on: <K extends keyof import("./types").EmitterMap>(event: K, callback: import("./types").EmitterCallback<import("./types").EmitterMap[K]>) => void;
     off: <K extends keyof import("./types").EmitterMap>(event: K, callback: import("./types").EmitterCallback<import("./types").EmitterMap[K]>) => void;
     isInitialized: () => boolean;

package/dist/cjs/test-bridge.d.ts

@@ -17,11 +17,12 @@ export declare class TestBridge extends App implements TraceLogTestBridge {
     private _isDestroying;
     constructor(isInitializing: boolean, isDestroying: boolean);
     isInitializing(): boolean;
-    sendCustomEvent(name: string, data?: Record<string, unknown>): void;
+    sendCustomEvent(name: string, data?: Record<string, unknown> | Record<string, unknown>[]): void;
     getSessionData(): Record<string, unknown> | null;
     setSessionTimeout(timeout: number): void;
     getQueueLength(): number;
     forceInitLock(enabled?: boolean): void;
+    simulatePersistedEvents(events: any[]): void;
     get<T extends keyof State>(key: T): State[T];
     getStorageManager(): StorageManager | null;
     getEventManager(): EventManager | null;
@@ -32,7 +33,7 @@ export declare class TestBridge extends App implements TraceLogTestBridge {
     getPerformanceHandler(): PerformanceHandler | null;
     getErrorHandler(): ErrorHandler | null;
     getGoogleAnalytics(): GoogleAnalyticsIntegration | null;
-    destroy(): Promise<void>;
+    destroy(force?: boolean): Promise<void>;
     /**
      * Helper to safely access managers/handlers and convert undefined to null
      */

package/dist/cjs/test-bridge.js

@@ -2,7 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TestBridge = void 0;
 const app_1 = require("./app");
-const utils_1 = require("./utils");
 /**
  * Test bridge for E2E testing
  */
@@ -17,7 +16,10 @@ class TestBridge extends app_1.App {
         return this._isInitializing;
     }
     sendCustomEvent(name, data) {
-        this.ensureInitialized();
+        // Silently ignore events after destroy instead of throwing error
+        if (!this.initialized) {
+            return;
+        }
         super.sendCustomEvent(name, data);
     }
     getSessionData() {
@@ -30,8 +32,7 @@ class TestBridge extends app_1.App {
     setSessionTimeout(timeout) {
         const config = this.get('config');
         if (config) {
-            const { config: normalizedConfig } = (0, utils_1.normalizeConfig)({ ...config, sessionTimeout: timeout });
-            this.set('config', normalizedConfig);
+            this.set('config', { ...config, sessionTimeout: timeout });
         }
     }
     getQueueLength() {
@@ -40,6 +41,29 @@ class TestBridge extends app_1.App {
     forceInitLock(enabled = true) {
         this._isInitializing = enabled;
     }
+    simulatePersistedEvents(events) {
+        const storageManager = this.managers?.storage;
+        if (!storageManager) {
+            throw new Error('Storage manager not available');
+        }
+        const projectId = this.get('config')?.id;
+        const userId = this.get('userId');
+        const sessionId = this.get('sessionId');
+        if (!projectId || !userId) {
+            throw new Error('Project ID or User ID not available. Initialize TraceLog first.');
+        }
+        // Build the persisted data structure matching what SenderManager expects
+        const persistedData = {
+            userId,
+            sessionId: sessionId || `test-session-${Date.now()}`,
+            device: 'desktop',
+            events,
+            timestamp: Date.now(),
+        };
+        // Store in the same format as SenderManager.persistEvents()
+        const storageKey = `tl:${projectId}:queue:${userId}`;
+        storageManager.setItem(storageKey, JSON.stringify(persistedData));
+    }
     get(key) {
         return super.get(key);
     }
@@ -73,12 +97,15 @@ class TestBridge extends app_1.App {
     getGoogleAnalytics() {
         return this.safeAccess(this.integrations?.googleAnalytics);
     }
-    async destroy() {
-        this.ensureInitialized();
+    async destroy(force = false) {
+        // If not initialized and not forcing, silently return (no-op)
+        if (!this.initialized && !force) {
+            return;
+        }
         this.ensureNotDestroying();
         this._isDestroying = true;
         try {
-            await super.destroy();
+            await super.destroy(force);
         }
         finally {
             this._isDestroying = false;

package/dist/cjs/types/api.types.d.ts

@@ -1,9 +1,10 @@
 /**
  * Special project IDs for testing and development
  *
- * Both automatically force mode: 'debug' but differ in HTTP behavior:
+ * All automatically force mode: 'debug' but differ in HTTP behavior:
  * - Skip: NO network calls (pure offline testing)
  * - Localhost: Makes network calls to local server (integration testing)
+ * - Fail: Makes network calls that intentionally fail (persistence testing)
  */
 export declare enum SpecialProjectId {
     /**
@@ -20,17 +21,32 @@ export declare enum SpecialProjectId {
      */
     Skip = "skip",
     /**
-     * Value: 'localhost:' (used as prefix)
+     * Value: 'localhost:8080'
      *
-     * Makes HTTP calls to local development server
-     * Must specify full address: 'localhost:PORT' (e.g., 'localhost:3000')
-     * Converts to http://localhost:PORT/config for requests
+     * Makes HTTP calls to local development server on port 8080
+     * Converts to http://localhost:8080/config for requests
      * Requires origin to be in ALLOWED_ORIGINS list, forces debug mode
      * Perfect for local development with running middleware
      *
      * @example
-     * await TraceLog.init({ id: 'localhost:3000' });
-     * // Makes requests to: http://localhost:3000/config
+     * await TraceLog.init({ id: SpecialProjectId.Localhost });
+     * // or
+     * await TraceLog.init({ id: 'localhost:8080' });
+     * // Makes requests to: http://localhost:8080/config
+     */
+    Localhost = "localhost:8080",
+    /**
+     * Value: 'localhost:9999'
+     *
+     * Makes HTTP calls to non-existent server (port 9999)
+     * All HTTP requests will fail naturally, triggering persistence
+     * Forces debug mode, perfect for testing event persistence & recovery
+     *
+     * @example
+     * await TraceLog.init({ id: SpecialProjectId.Fail });
+     * // or
+     * await TraceLog.init({ id: 'localhost:9999' });
+     * // Makes requests to: http://localhost:9999 (will fail)
      */
-    Localhost = "localhost:"
+    Fail = "localhost:9999"
 }

package/dist/cjs/types/api.types.js

@@ -4,9 +4,10 @@ exports.SpecialProjectId = void 0;
 /**
  * Special project IDs for testing and development
  *
- * Both automatically force mode: 'debug' but differ in HTTP behavior:
+ * All automatically force mode: 'debug' but differ in HTTP behavior:
  * - Skip: NO network calls (pure offline testing)
  * - Localhost: Makes network calls to local server (integration testing)
+ * - Fail: Makes network calls that intentionally fail (persistence testing)
  */
 var SpecialProjectId;
 (function (SpecialProjectId) {
@@ -24,17 +25,32 @@ var SpecialProjectId;
      */
     SpecialProjectId["Skip"] = "skip";
     /**
-     * Value: 'localhost:' (used as prefix)
+     * Value: 'localhost:8080'
      *
-     * Makes HTTP calls to local development server
-     * Must specify full address: 'localhost:PORT' (e.g., 'localhost:3000')
-     * Converts to http://localhost:PORT/config for requests
+     * Makes HTTP calls to local development server on port 8080
+     * Converts to http://localhost:8080/config for requests
      * Requires origin to be in ALLOWED_ORIGINS list, forces debug mode
      * Perfect for local development with running middleware
      *
      * @example
-     * await TraceLog.init({ id: 'localhost:3000' });
-     * // Makes requests to: http://localhost:3000/config
+     * await TraceLog.init({ id: SpecialProjectId.Localhost });
+     * // or
+     * await TraceLog.init({ id: 'localhost:8080' });
+     * // Makes requests to: http://localhost:8080/config
+     */
+    SpecialProjectId["Localhost"] = "localhost:8080";
+    /**
+     * Value: 'localhost:9999'
+     *
+     * Makes HTTP calls to non-existent server (port 9999)
+     * All HTTP requests will fail naturally, triggering persistence
+     * Forces debug mode, perfect for testing event persistence & recovery
+     *
+     * @example
+     * await TraceLog.init({ id: SpecialProjectId.Fail });
+     * // or
+     * await TraceLog.init({ id: 'localhost:9999' });
+     * // Makes requests to: http://localhost:9999 (will fail)
      */
-    SpecialProjectId["Localhost"] = "localhost:";
+    SpecialProjectId["Fail"] = "localhost:9999";
 })(SpecialProjectId || (exports.SpecialProjectId = SpecialProjectId = {}));