@tracelog/lib 0.0.1

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

@@ -0,0 +1,583 @@
+import { DEFAULT_MOTION_THRESHOLD, DEFAULT_SESSION_TIMEOUT_MS, DEFAULT_THROTTLE_DELAY_MS, DEFAULT_VISIBILITY_TIMEOUT_MS, } from '../constants';
+import { DeviceType, EventType } from '../types';
+import { generateUUID, getDeviceType } from '../utils';
+import { debugLog } from '../utils/logging';
+import { ActivityListenerManager, KeyboardListenerManager, MouseListenerManager, TouchListenerManager, UnloadListenerManager, VisibilityListenerManager, } from '../listeners';
+import { StateManager } from './state.manager';
+import { SessionRecoveryManager } from './session-recovery.manager';
+export class SessionManager extends StateManager {
+    constructor(onActivity, onInactivity, eventManager, storageManager, sessionEndConfig) {
+        super();
+        this.eventManager = null;
+        this.storageManager = null;
+        this.listenerManagers = [];
+        // Recovery manager
+        this.recoveryManager = null;
+        this.isSessionActive = false;
+        this.lastActivityTime = 0;
+        this.inactivityTimer = null;
+        this.sessionStartTime = 0;
+        this.throttleTimeout = null;
+        // Track visibility change timeout for proper cleanup
+        this.visibilityChangeTimeout = null;
+        // Session End Management
+        this.pendingSessionEnd = false;
+        this.sessionEndPromise = null;
+        this.sessionEndLock = Promise.resolve({
+            success: true,
+            reason: 'manual_stop',
+            timestamp: Date.now(),
+            eventsFlushed: 0,
+            method: 'async',
+        });
+        this.cleanupHandlers = [];
+        this.sessionEndReason = null;
+        this.sessionEndPriority = {
+            page_unload: 4,
+            manual_stop: 3,
+            orphaned_cleanup: 2,
+            inactivity: 1,
+            tab_closed: 0,
+        };
+        this.sessionEndStats = {
+            totalSessionEnds: 0,
+            successfulEnds: 0,
+            failedEnds: 0,
+            duplicatePrevented: 0,
+            reasonCounts: {
+                inactivity: 0,
+                page_unload: 0,
+                manual_stop: 0,
+                orphaned_cleanup: 0,
+                tab_closed: 0,
+            },
+        };
+        // Session health monitoring
+        this.sessionHealth = {
+            recoveryAttempts: 0,
+            sessionTimeouts: 0,
+            crossTabConflicts: 0,
+            lastHealthCheck: Date.now(),
+        };
+        this.handleActivity = () => {
+            const now = Date.now();
+            if (now - this.lastActivityTime < this.config.throttleDelay) {
+                return;
+            }
+            this.lastActivityTime = now;
+            if (this.isSessionActive) {
+                // Always call onActivity to update cross-tab session activity
+                this.onActivity();
+                this.resetInactivityTimer();
+            }
+            else {
+                if (this.throttleTimeout) {
+                    clearTimeout(this.throttleTimeout);
+                    this.throttleTimeout = null;
+                }
+                this.throttleTimeout = window.setTimeout(() => {
+                    this.onActivity();
+                    this.throttleTimeout = null;
+                }, 100);
+            }
+        };
+        this.handleInactivity = () => {
+            // Track session timeout for health monitoring
+            this.trackSessionHealth('timeout');
+            this.onInactivity();
+        };
+        this.handleVisibilityChange = () => {
+            if (document.hidden) {
+                if (this.isSessionActive) {
+                    if (this.inactivityTimer) {
+                        clearTimeout(this.inactivityTimer);
+                        this.inactivityTimer = null;
+                    }
+                    this.inactivityTimer = window.setTimeout(this.handleInactivity, this.config.visibilityTimeout);
+                }
+            }
+            else {
+                this.handleActivity();
+            }
+        };
+        this.resetInactivityTimer = () => {
+            if (this.inactivityTimer) {
+                clearTimeout(this.inactivityTimer);
+                this.inactivityTimer = null;
+            }
+            if (this.isSessionActive) {
+                this.inactivityTimer = window.setTimeout(() => {
+                    this.handleInactivity();
+                }, this.config.timeout);
+            }
+        };
+        this.config = {
+            throttleDelay: DEFAULT_THROTTLE_DELAY_MS,
+            visibilityTimeout: DEFAULT_VISIBILITY_TIMEOUT_MS,
+            motionThreshold: DEFAULT_MOTION_THRESHOLD,
+            timeout: this.get('config')?.sessionTimeout ?? DEFAULT_SESSION_TIMEOUT_MS,
+        };
+        this.sessionEndConfig = {
+            enablePageUnloadHandlers: true,
+            syncTimeoutMs: 1000,
+            maxRetries: 2,
+            debugMode: false,
+            ...sessionEndConfig,
+        };
+        this.onActivity = onActivity;
+        this.onInactivity = onInactivity;
+        this.eventManager = eventManager ?? null;
+        this.storageManager = storageManager ?? null;
+        this.deviceCapabilities = this.detectDeviceCapabilities();
+        this.initializeRecoveryManager();
+        this.initializeListenerManagers();
+        this.setupAllListeners();
+        if (this.sessionEndConfig.enablePageUnloadHandlers) {
+            this.setupPageUnloadHandlers();
+        }
+        debugLog.debug('SessionManager', 'SessionManager initialized', {
+            sessionTimeout: this.config.timeout,
+            deviceCapabilities: this.deviceCapabilities,
+            unloadHandlersEnabled: this.sessionEndConfig.enablePageUnloadHandlers,
+        });
+    }
+    /**
+     * Initialize recovery manager
+     */
+    initializeRecoveryManager() {
+        if (!this.storageManager)
+            return;
+        const projectId = this.get('config')?.id;
+        if (!projectId)
+            return;
+        try {
+            // Initialize session recovery manager (always enabled)
+            this.recoveryManager = new SessionRecoveryManager(this.storageManager, projectId, this.eventManager ?? undefined);
+            debugLog.debug('SessionManager', 'Recovery manager initialized', { projectId });
+        }
+        catch (error) {
+            debugLog.error('SessionManager', 'Failed to initialize recovery manager', { error, projectId });
+        }
+    }
+    /**
+     * Store session context for recovery
+     */
+    storeSessionContextForRecovery() {
+        if (!this.recoveryManager)
+            return;
+        const sessionId = this.get('sessionId');
+        if (!sessionId)
+            return;
+        const sessionContext = {
+            sessionId,
+            startTime: this.sessionStartTime,
+            lastActivity: this.lastActivityTime,
+            tabCount: 1, // This will be updated by cross-tab manager
+            recoveryAttempts: 0,
+            metadata: {
+                userAgent: navigator.userAgent,
+                pageUrl: this.get('pageUrl'),
+            },
+        };
+        this.recoveryManager.storeSessionContextForRecovery(sessionContext);
+    }
+    startSession() {
+        const now = Date.now();
+        // Attempt session recovery first
+        let sessionId = '';
+        let wasRecovered = false;
+        if (this.recoveryManager?.hasRecoverableSession()) {
+            const recoveryResult = this.recoveryManager.attemptSessionRecovery();
+            if (recoveryResult.recovered && recoveryResult.recoveredSessionId) {
+                sessionId = recoveryResult.recoveredSessionId;
+                wasRecovered = true;
+                // Track session recovery for health monitoring
+                this.trackSessionHealth('recovery');
+                // Update session timing from recovery context
+                if (recoveryResult.context) {
+                    this.sessionStartTime = recoveryResult.context.startTime;
+                    this.lastActivityTime = now;
+                }
+                else {
+                    this.sessionStartTime = now;
+                    this.lastActivityTime = now;
+                }
+                debugLog.info('SessionManager', 'Session successfully recovered', {
+                    sessionId,
+                    recoveryAttempts: this.sessionHealth.recoveryAttempts,
+                });
+            }
+        }
+        // If no recovery, create new session
+        if (!wasRecovered) {
+            sessionId = generateUUID();
+            this.sessionStartTime = now;
+            this.lastActivityTime = now;
+            debugLog.info('SessionManager', 'New session started', { sessionId });
+        }
+        this.isSessionActive = true;
+        this.resetInactivityTimer();
+        // Store session context for future recovery
+        this.storeSessionContextForRecovery();
+        return { sessionId, recovered: wasRecovered };
+    }
+    endSession() {
+        if (this.sessionStartTime === 0) {
+            return 0;
+        }
+        const durationMs = Date.now() - this.sessionStartTime;
+        this.sessionStartTime = 0;
+        this.isSessionActive = false;
+        if (this.inactivityTimer) {
+            clearTimeout(this.inactivityTimer);
+            this.inactivityTimer = null;
+        }
+        return durationMs;
+    }
+    destroy() {
+        this.clearTimers();
+        this.cleanupAllListeners();
+        this.resetState();
+        this.cleanupHandlers.forEach((cleanup) => cleanup());
+        this.cleanupHandlers = [];
+        this.pendingSessionEnd = false;
+        this.sessionEndPromise = null;
+        this.sessionEndLock = Promise.resolve({
+            success: true,
+            reason: 'manual_stop',
+            timestamp: Date.now(),
+            eventsFlushed: 0,
+            method: 'async',
+        });
+        if (this.recoveryManager) {
+            this.recoveryManager.cleanupOldRecoveryAttempts();
+            this.recoveryManager = null;
+        }
+    }
+    detectDeviceCapabilities() {
+        const hasTouch = 'ontouchstart' in window || navigator.maxTouchPoints > 0;
+        const hasMouse = window.matchMedia('(pointer: fine)').matches;
+        const hasKeyboard = !window.matchMedia('(pointer: coarse)').matches;
+        const isMobile = getDeviceType() === DeviceType.Mobile;
+        return { hasTouch, hasMouse, hasKeyboard, isMobile };
+    }
+    initializeListenerManagers() {
+        this.listenerManagers.push(new ActivityListenerManager(this.handleActivity));
+        if (this.deviceCapabilities.hasTouch) {
+            this.listenerManagers.push(new TouchListenerManager(this.handleActivity, this.config.motionThreshold));
+        }
+        if (this.deviceCapabilities.hasMouse) {
+            this.listenerManagers.push(new MouseListenerManager(this.handleActivity));
+        }
+        if (this.deviceCapabilities.hasKeyboard) {
+            this.listenerManagers.push(new KeyboardListenerManager(this.handleActivity));
+        }
+        this.listenerManagers.push(new VisibilityListenerManager(this.handleActivity, this.handleVisibilityChange, this.deviceCapabilities.isMobile));
+        this.listenerManagers.push(new UnloadListenerManager(this.handleInactivity));
+    }
+    setupAllListeners() {
+        this.listenerManagers.forEach((manager) => manager.setup());
+    }
+    cleanupAllListeners() {
+        this.listenerManagers.forEach((manager) => manager.cleanup());
+    }
+    clearTimers() {
+        if (this.inactivityTimer) {
+            clearTimeout(this.inactivityTimer);
+            this.inactivityTimer = null;
+        }
+        if (this.throttleTimeout) {
+            clearTimeout(this.throttleTimeout);
+            this.throttleTimeout = null;
+        }
+    }
+    resetState() {
+        this.isSessionActive = false;
+        this.lastActivityTime = 0;
+        this.sessionStartTime = 0;
+    }
+    clearInactivityTimer() {
+        if (this.inactivityTimer) {
+            clearTimeout(this.inactivityTimer);
+            this.inactivityTimer = null;
+        }
+    }
+    shouldProceedWithSessionEnd(reason) {
+        return !this.sessionEndReason || this.sessionEndPriority[reason] > this.sessionEndPriority[this.sessionEndReason];
+    }
+    async waitForCompletion() {
+        if (this.sessionEndPromise) {
+            return await this.sessionEndPromise;
+        }
+        return {
+            success: false,
+            reason: 'inactivity',
+            timestamp: Date.now(),
+            eventsFlushed: 0,
+            method: 'async',
+        };
+    }
+    async endSessionManaged(reason) {
+        return (this.sessionEndLock = this.sessionEndLock.then(async () => {
+            this.sessionEndStats.totalSessionEnds++;
+            this.sessionEndStats.reasonCounts[reason]++;
+            if (this.pendingSessionEnd) {
+                this.sessionEndStats.duplicatePrevented++;
+                debugLog.debug('SessionManager', 'Session end already pending, waiting for completion', { reason });
+                return this.waitForCompletion();
+            }
+            if (!this.shouldProceedWithSessionEnd(reason)) {
+                if (this.sessionEndConfig.debugMode) {
+                    debugLog.debug('SessionManager', `Session end skipped due to lower priority. Current: ${this.sessionEndReason}, Requested: ${reason}`);
+                }
+                return {
+                    success: false,
+                    reason,
+                    timestamp: Date.now(),
+                    eventsFlushed: 0,
+                    method: 'async',
+                };
+            }
+            this.sessionEndReason = reason;
+            this.pendingSessionEnd = true;
+            this.sessionEndPromise = this.performSessionEnd(reason, 'async');
+            try {
+                const result = await this.sessionEndPromise;
+                return result;
+            }
+            finally {
+                this.pendingSessionEnd = false;
+                this.sessionEndPromise = null;
+                this.sessionEndReason = null;
+            }
+        }));
+    }
+    endSessionSafely(reason, options) {
+        const shouldUseSync = options?.forceSync ?? (options?.allowSync && ['page_unload', 'tab_closed'].includes(reason));
+        if (shouldUseSync) {
+            return this.endSessionManagedSync(reason);
+        }
+        return this.endSessionManaged(reason);
+    }
+    isPendingSessionEnd() {
+        return this.pendingSessionEnd;
+    }
+    /**
+     * Track session health events for monitoring and diagnostics
+     */
+    trackSessionHealth(event) {
+        const now = Date.now();
+        // Update health counters
+        switch (event) {
+            case 'recovery':
+                this.sessionHealth.recoveryAttempts++;
+                break;
+            case 'timeout':
+                this.sessionHealth.sessionTimeouts++;
+                break;
+            case 'conflict':
+                this.sessionHealth.crossTabConflicts++;
+                break;
+        }
+        this.sessionHealth.lastHealthCheck = now;
+        // Send health degradation event if recovery attempts are high
+        if (this.sessionHealth.recoveryAttempts > 3 && this.eventManager) {
+            this.eventManager.track({
+                type: EventType.CUSTOM,
+                custom_event: {
+                    name: 'session_health_degraded',
+                    metadata: {
+                        ...this.sessionHealth,
+                        event_trigger: event,
+                    },
+                },
+            });
+            if (this.sessionEndConfig.debugMode) {
+                debugLog.warn('SessionManager', `Session health degraded: ${this.sessionHealth.recoveryAttempts} recovery attempts`);
+            }
+        }
+        if (this.sessionEndConfig.debugMode) {
+            debugLog.debug('SessionManager', `Session health event tracked: ${event}`);
+        }
+    }
+    async performSessionEnd(reason, method) {
+        const timestamp = Date.now();
+        let eventsFlushed = 0;
+        try {
+            debugLog.info('SessionManager', 'Starting session end', { method, reason, timestamp });
+            if (this.eventManager) {
+                this.eventManager.track({
+                    type: EventType.SESSION_END,
+                    session_end_reason: reason,
+                });
+                eventsFlushed = this.eventManager.getQueueLength();
+                const flushResult = await this.eventManager.flushImmediately();
+                this.cleanupSession();
+                const result = {
+                    success: flushResult,
+                    reason,
+                    timestamp,
+                    eventsFlushed,
+                    method,
+                };
+                if (flushResult) {
+                    this.sessionEndStats.successfulEnds++;
+                }
+                else {
+                    this.sessionEndStats.failedEnds++;
+                }
+                return result;
+            }
+            this.cleanupSession();
+            const result = {
+                success: true,
+                reason,
+                timestamp,
+                eventsFlushed: 0,
+                method,
+            };
+            this.sessionEndStats.successfulEnds++;
+            return result;
+        }
+        catch (error) {
+            this.sessionEndStats.failedEnds++;
+            debugLog.error('SessionManager', 'Session end failed', { error, reason, method });
+            this.cleanupSession();
+            return {
+                success: false,
+                reason,
+                timestamp,
+                eventsFlushed,
+                method,
+            };
+        }
+    }
+    cleanupSession() {
+        this.endSession();
+        this.clearTimers();
+        this.set('sessionId', null);
+        this.set('hasStartSession', false);
+    }
+    endSessionManagedSync(reason) {
+        this.sessionEndStats.totalSessionEnds++;
+        this.sessionEndStats.reasonCounts[reason]++;
+        if (this.pendingSessionEnd) {
+            this.sessionEndStats.duplicatePrevented++;
+            debugLog.warn('SessionManager', 'Sync session end called while async end pending', { reason });
+        }
+        if (!this.shouldProceedWithSessionEnd(reason)) {
+            if (this.sessionEndConfig.debugMode) {
+                debugLog.debug('SessionManager', `Sync session end skipped due to lower priority. Current: ${this.sessionEndReason}, Requested: ${reason}`);
+            }
+            return {
+                success: false,
+                reason,
+                timestamp: Date.now(),
+                eventsFlushed: 0,
+                method: 'sync',
+            };
+        }
+        this.sessionEndReason = reason;
+        this.pendingSessionEnd = true;
+        try {
+            return this.performSessionEndSync(reason);
+        }
+        finally {
+            this.pendingSessionEnd = false;
+            this.sessionEndPromise = null;
+            this.sessionEndReason = null;
+        }
+    }
+    performSessionEndSync(reason) {
+        const timestamp = Date.now();
+        let eventsFlushed = 0;
+        try {
+            if (this.eventManager) {
+                this.eventManager.track({
+                    type: EventType.SESSION_END,
+                    session_end_reason: reason,
+                });
+                eventsFlushed = this.eventManager.getQueueLength();
+                const success = this.eventManager.flushImmediatelySync();
+                this.cleanupSession();
+                const result = {
+                    success,
+                    reason,
+                    timestamp,
+                    eventsFlushed,
+                    method: 'sync',
+                };
+                if (success) {
+                    this.sessionEndStats.successfulEnds++;
+                }
+                else {
+                    this.sessionEndStats.failedEnds++;
+                }
+                return result;
+            }
+            this.cleanupSession();
+            const result = {
+                success: true,
+                reason,
+                timestamp,
+                eventsFlushed: 0,
+                method: 'sync',
+            };
+            this.sessionEndStats.successfulEnds++;
+            return result;
+        }
+        catch (error) {
+            this.sessionEndStats.failedEnds++;
+            this.cleanupSession();
+            debugLog.error('SessionManager', 'Sync session end failed', { error, reason });
+            return {
+                success: false,
+                reason,
+                timestamp,
+                eventsFlushed,
+                method: 'sync',
+            };
+        }
+    }
+    setupPageUnloadHandlers() {
+        let unloadHandled = false;
+        const handlePageUnload = () => {
+            if (unloadHandled || !this.get('sessionId')) {
+                return;
+            }
+            unloadHandled = true;
+            this.clearInactivityTimer();
+            this.endSessionSafely('page_unload', { forceSync: true });
+        };
+        // Primary handler for modern browsers
+        const beforeUnloadHandler = () => {
+            handlePageUnload();
+        };
+        // Fallback for older browsers and mobile Safari
+        const pageHideHandler = (event) => {
+            if (!event.persisted) {
+                handlePageUnload();
+            }
+        };
+        // Delayed handler for visibility changes (gives time for page transitions)
+        const visibilityChangeHandler = () => {
+            if (document.visibilityState === 'hidden' && this.get('sessionId') && !unloadHandled) {
+                this.visibilityChangeTimeout = window.setTimeout(() => {
+                    if (document.visibilityState === 'hidden' && this.get('sessionId') && !unloadHandled) {
+                        handlePageUnload();
+                    }
+                    this.visibilityChangeTimeout = null;
+                }, 1000);
+            }
+        };
+        window.addEventListener('beforeunload', beforeUnloadHandler);
+        window.addEventListener('pagehide', pageHideHandler);
+        document.addEventListener('visibilitychange', visibilityChangeHandler);
+        this.cleanupHandlers.push(() => window.removeEventListener('beforeunload', beforeUnloadHandler), () => window.removeEventListener('pagehide', pageHideHandler), () => document.removeEventListener('visibilitychange', visibilityChangeHandler), () => {
+            if (this.visibilityChangeTimeout) {
+                clearTimeout(this.visibilityChangeTimeout);
+                this.visibilityChangeTimeout = null;
+            }
+        });
+    }
+}

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

@@ -0,0 +1,5 @@
+import { State } from '../types';
+export declare abstract class StateManager {
+    protected get<T extends keyof State>(key: T): State[T];
+    protected set<T extends keyof State>(key: T, value: State[T]): void;
+}

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

@@ -0,0 +1,19 @@
+import { debugLog } from '../utils/logging';
+const globalState = {};
+export class StateManager {
+    get(key) {
+        return globalState[key];
+    }
+    set(key, value) {
+        const oldValue = globalState[key];
+        globalState[key] = value;
+        // Log critical state changes
+        if (key === 'sessionId' || key === 'config' || key === 'hasStartSession') {
+            debugLog.debug('StateManager', 'Critical state updated', {
+                key,
+                oldValue: key === 'config' ? !!oldValue : oldValue,
+                newValue: key === 'config' ? !!value : value,
+            });
+        }
+    }
+}

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

@@ -0,0 +1,10 @@
+export declare class StorageManager {
+    private readonly storage;
+    private readonly fallbackStorage;
+    private storageAvailable;
+    constructor();
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    private init;
+}

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

@@ -0,0 +1,77 @@
+import { debugLog } from '../utils/logging';
+export class StorageManager {
+    constructor() {
+        this.storage = null;
+        this.fallbackStorage = new Map();
+        this.storageAvailable = false;
+        this.storage = this.init();
+        this.storageAvailable = this.storage !== null;
+        if (!this.storageAvailable) {
+            debugLog.warn('StorageManager', 'localStorage not available, using memory fallback');
+        }
+    }
+    getItem(key) {
+        if (!this.storageAvailable) {
+            return this.fallbackStorage.get(key) ?? null;
+        }
+        try {
+            if (this.storage) {
+                return this.storage.getItem(key);
+            }
+            return this.fallbackStorage.get(key) ?? null;
+        }
+        catch (error) {
+            debugLog.warn('StorageManager', 'Storage getItem failed, using memory fallback', { key, error });
+            this.storageAvailable = false;
+            return this.fallbackStorage.get(key) ?? null;
+        }
+    }
+    setItem(key, value) {
+        if (!this.storageAvailable) {
+            this.fallbackStorage.set(key, value);
+            return;
+        }
+        try {
+            if (this.storage) {
+                this.storage.setItem(key, value);
+                return;
+            }
+            this.fallbackStorage.set(key, value);
+        }
+        catch (error) {
+            debugLog.warn('StorageManager', 'Storage setItem failed, using memory fallback', { key, error });
+            this.storageAvailable = false;
+            this.fallbackStorage.set(key, value);
+        }
+    }
+    removeItem(key) {
+        if (!this.storageAvailable) {
+            this.fallbackStorage.delete(key);
+            return;
+        }
+        try {
+            if (this.storage) {
+                this.storage.removeItem(key);
+                return;
+            }
+            this.fallbackStorage.delete(key);
+        }
+        catch (error) {
+            debugLog.warn('StorageManager', 'Storage removeItem failed, using memory fallback', { key, error });
+            this.storageAvailable = false;
+            this.fallbackStorage.delete(key);
+        }
+    }
+    init() {
+        try {
+            const test = '__storage_test__';
+            const storage = window['localStorage'];
+            storage.setItem(test, test);
+            storage.removeItem(test);
+            return storage;
+        }
+        catch {
+            return null;
+        }
+    }
+}