@tracelog/lib 0.0.1

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

@@ -0,0 +1,300 @@
+import { QUEUE_KEY, RETRY_BACKOFF_INITIAL, RETRY_BACKOFF_MAX, RATE_LIMIT_INTERVAL, EVENT_EXPIRY_HOURS, SYNC_XHR_TIMEOUT_MS, API_BASE_URL, } from '../constants';
+import { SpecialProjectId, Mode } from '../types';
+import { debugLog } from '../utils/logging';
+import { StateManager } from './state.manager';
+export class SenderManager extends StateManager {
+    constructor(storeManager) {
+        super();
+        this.retryDelay = RETRY_BACKOFF_INITIAL;
+        this.retryTimeoutId = null;
+        this.lastAsyncSend = 0;
+        this.lastSyncSend = 0;
+        this.storeManager = storeManager;
+        this.queueStorageKey = `${QUEUE_KEY(this.get('config')?.id)}:${this.get('userId')}`;
+        this.recoverPersistedEvents();
+    }
+    async sendEventsQueueAsync(body) {
+        return this.executeSend(body, () => this.sendQueueAsync(body));
+    }
+    sendEventsQueueSync(body) {
+        return this.executeSendSync(body, () => this.sendQueueSync(body));
+    }
+    sendEventsQueue(body) {
+        return this.executeSendSync(body, () => this.sendQueue(body));
+    }
+    recoverPersistedEvents() {
+        try {
+            const persistedData = this.getPersistedData();
+            if (!persistedData || !this.isDataRecent(persistedData) || persistedData.events.length === 0) {
+                this.clearPersistedEvents();
+                return;
+            }
+            const recoveryBody = this.createRecoveryBody(persistedData);
+            const success = this.sendRecoveredEvents(recoveryBody);
+            if (success) {
+                debugLog.info('SenderManager', 'Persisted events recovered successfully', {
+                    eventsCount: persistedData.events.length,
+                    sessionId: persistedData.sessionId,
+                });
+                this.clearPersistedEvents();
+            }
+            else {
+                debugLog.warn('SenderManager', 'Failed to recover persisted events, scheduling retry', {
+                    eventsCount: persistedData.events.length,
+                });
+                this.scheduleRetryForRecoveredEvents(recoveryBody);
+            }
+        }
+        catch (error) {
+            debugLog.error('SenderManager', 'Failed to recover persisted events', { error });
+        }
+    }
+    stop() {
+        this.clearRetryTimeout();
+        this.resetRetryState();
+    }
+    /**
+     * Sends recovered events without re-deduplication since they were already processed
+     */
+    sendRecoveredEvents(body) {
+        return this.executeSendSync(body, () => this.sendQueue(body));
+    }
+    /**
+     * Schedules retry for recovered events using the specific recovery method
+     */
+    scheduleRetryForRecoveredEvents(body) {
+        if (this.retryTimeoutId !== null) {
+            return;
+        }
+        this.retryTimeoutId = window.setTimeout(() => {
+            this.retryTimeoutId = null;
+            this.sendRecoveredEvents(body);
+        }, this.retryDelay);
+        this.retryDelay = Math.min(this.retryDelay * 2, RETRY_BACKOFF_MAX);
+    }
+    canSendAsync() {
+        return Date.now() - this.lastAsyncSend >= RATE_LIMIT_INTERVAL;
+    }
+    canSendSync() {
+        return Date.now() - this.lastSyncSend >= RATE_LIMIT_INTERVAL;
+    }
+    async sendQueueAsync(body) {
+        const { url, payload } = this.prepareRequest(body);
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: payload,
+            });
+            return response.ok;
+        }
+        catch (error) {
+            debugLog.error('SenderManager', 'Failed to send events async', { error });
+            return false;
+        }
+    }
+    sendQueueSync(body) {
+        const { url, payload } = this.prepareRequest(body);
+        if (this.isSendBeaconAvailable() && navigator.sendBeacon(url, payload)) {
+            return true;
+        }
+        return this.sendSyncXHR(url, payload);
+    }
+    sendQueue(body) {
+        if (!this.isSendBeaconAvailable()) {
+            return false;
+        }
+        const { url, payload } = this.prepareRequest(body);
+        return navigator.sendBeacon(url, payload);
+    }
+    sendSyncXHR(url, payload) {
+        try {
+            const xhr = new XMLHttpRequest();
+            xhr.open('POST', url, false);
+            xhr.setRequestHeader('Content-Type', 'application/json');
+            xhr.timeout = SYNC_XHR_TIMEOUT_MS;
+            xhr.send(payload);
+            return xhr.status >= 200 && xhr.status < 300;
+        }
+        catch (error) {
+            debugLog.error('SenderManager', 'Sync XHR failed', { error });
+            return false;
+        }
+    }
+    prepareRequest(body) {
+        const useLocalServer = this.get('config').id === SpecialProjectId.HttpLocal;
+        const baseUrl = useLocalServer ? window.location.origin : (this.get('apiUrl') ?? API_BASE_URL);
+        return {
+            url: `${baseUrl}/events`,
+            payload: JSON.stringify(body),
+        };
+    }
+    getPersistedData() {
+        const persistedDataString = this.storeManager.getItem(this.queueStorageKey);
+        return persistedDataString ? JSON.parse(persistedDataString) : null;
+    }
+    isDataRecent(data) {
+        const ageInHours = (Date.now() - data.timestamp) / (1000 * 60 * 60);
+        return ageInHours < EVENT_EXPIRY_HOURS;
+    }
+    createRecoveryBody(data) {
+        return {
+            user_id: data.userId,
+            session_id: data.sessionId,
+            device: data.device,
+            events: data.events,
+            ...(data.global_metadata && { global_metadata: data.global_metadata }),
+        };
+    }
+    logQueue(queue) {
+        debugLog.info('SenderManager', ` ⏩ Queue snapshot`, queue);
+    }
+    handleSendFailure(body) {
+        this.persistFailedEvents(body);
+        this.scheduleRetry(body);
+    }
+    persistFailedEvents(body) {
+        try {
+            const persistedData = {
+                userId: body.user_id,
+                sessionId: body.session_id,
+                device: body.device,
+                events: body.events,
+                timestamp: Date.now(),
+                ...(body.global_metadata && { global_metadata: body.global_metadata }),
+            };
+            this.storeManager.setItem(this.queueStorageKey, JSON.stringify(persistedData));
+        }
+        catch (error) {
+            debugLog.error('SenderManager', 'Failed to persist events', { error });
+        }
+    }
+    clearPersistedEvents() {
+        this.storeManager.removeItem(this.queueStorageKey);
+    }
+    resetRetryState() {
+        this.retryDelay = RETRY_BACKOFF_INITIAL;
+        this.clearRetryTimeout();
+    }
+    scheduleRetry(body) {
+        if (this.retryTimeoutId !== null) {
+            return;
+        }
+        this.retryTimeoutId = window.setTimeout(() => {
+            this.retryTimeoutId = null;
+            this.sendEventsQueue(body);
+        }, this.retryDelay);
+        this.retryDelay = Math.min(this.retryDelay * 2, RETRY_BACKOFF_MAX);
+    }
+    async executeSend(body, sendFn) {
+        if (this.shouldSkipSend()) {
+            this.logQueue(body);
+            return true;
+        }
+        if (!this.canSendAsync()) {
+            debugLog.info('SenderManager', `⏱️ Rate limited - skipping async send`, {
+                eventsCount: body.events.length,
+                timeSinceLastSend: Date.now() - this.lastAsyncSend,
+            });
+            return false;
+        }
+        debugLog.info('SenderManager', `🌐 Sending events to server (async)`, {
+            eventsCount: body.events.length,
+            sessionId: body.session_id,
+            userId: body.user_id,
+        });
+        this.lastAsyncSend = Date.now();
+        try {
+            const success = await sendFn();
+            if (success) {
+                debugLog.info('SenderManager', `✅ Successfully sent events to server`, {
+                    eventsCount: body.events.length,
+                    method: 'async',
+                });
+                this.resetRetryState();
+                this.clearPersistedEvents();
+            }
+            else {
+                debugLog.warn('SenderManager', 'Failed to send events', {
+                    eventsCount: body.events.length,
+                    method: 'async',
+                });
+                this.handleSendFailure(body);
+            }
+            return success;
+        }
+        catch {
+            this.handleSendFailure(body);
+            return false;
+        }
+    }
+    executeSendSync(body, sendFn) {
+        if (this.shouldSkipSend()) {
+            this.logQueue(body);
+            return true;
+        }
+        if (!this.canSendSync()) {
+            debugLog.info('SenderManager', `⏱️ Rate limited - skipping sync send`, {
+                eventsCount: body.events.length,
+                timeSinceLastSend: Date.now() - this.lastSyncSend,
+            });
+            return false;
+        }
+        debugLog.info('SenderManager', `🌐 Sending events to server (sync)`, {
+            eventsCount: body.events.length,
+            sessionId: body.session_id,
+            userId: body.user_id,
+            method: 'sendBeacon/XHR',
+        });
+        this.lastSyncSend = Date.now();
+        try {
+            const success = sendFn();
+            if (success) {
+                debugLog.info('SenderManager', `✅ Successfully sent events to server`, {
+                    eventsCount: body.events.length,
+                    method: 'sync',
+                });
+                this.resetRetryState();
+                this.clearPersistedEvents();
+            }
+            else {
+                debugLog.warn('SenderManager', 'Failed to send events', {
+                    eventsCount: body.events.length,
+                    method: 'sync',
+                });
+                this.handleSendFailure(body);
+            }
+            return success;
+        }
+        catch {
+            debugLog.info('SenderManager', `💥 Exception during event sending`, {
+                eventsCount: body.events.length,
+                method: 'sync',
+            });
+            this.handleSendFailure(body);
+            return false;
+        }
+    }
+    shouldSkipSend() {
+        const { id, mode } = this.get('config');
+        const specialModes = [Mode.QA, Mode.DEBUG];
+        if (id === SpecialProjectId.HttpSkip) {
+            return true;
+        }
+        return !!mode && specialModes.includes(mode) && id !== SpecialProjectId.HttpLocal;
+    }
+    isSendBeaconAvailable() {
+        if (typeof navigator.sendBeacon !== 'function') {
+            return false;
+        }
+        return true;
+    }
+    clearRetryTimeout() {
+        if (this.retryTimeoutId !== null) {
+            clearTimeout(this.retryTimeoutId);
+            this.retryTimeoutId = null;
+        }
+    }
+}

package/dist/esm/managers/session-recovery.manager.d.ts

@@ -0,0 +1,65 @@
+import { SessionRecoveryConfig, SessionContext } from '../types/session.types';
+import { StateManager } from './state.manager';
+import { StorageManager } from './storage.manager';
+import { EventManager } from './event.manager';
+export declare class SessionRecoveryManager extends StateManager {
+    private readonly config;
+    private readonly storageManager;
+    private readonly eventManager;
+    private readonly projectId;
+    private readonly debugMode;
+    constructor(storageManager: StorageManager, projectId: string, eventManager?: EventManager, config?: Partial<SessionRecoveryConfig>);
+    /**
+     * Attempt to recover a session
+     */
+    attemptSessionRecovery(currentSessionId?: string): {
+        recovered: boolean;
+        recoveredSessionId?: string;
+        context?: SessionContext;
+    };
+    /**
+     * Calculate the recovery window with bounds checking
+     */
+    private calculateRecoveryWindow;
+    /**
+     * Check if session recovery can be attempted
+     */
+    private canAttemptRecovery;
+    /**
+     * Store session context for potential recovery
+     */
+    storeSessionContextForRecovery(sessionContext: SessionContext): void;
+    /**
+     * Get stored recovery attempts
+     */
+    private getStoredRecoveryAttempts;
+    /**
+     * Store recovery attempts
+     */
+    private storeRecoveryAttempts;
+    /**
+     * Get the last recovery attempt
+     */
+    private getLastRecoveryAttempt;
+    /**
+     * Clean up old recovery attempts
+     */
+    cleanupOldRecoveryAttempts(): void;
+    /**
+     * Check if there's a recoverable session.
+     * Returns false when no recovery attempts are stored.
+     */
+    hasRecoverableSession(): boolean;
+    /**
+     * Get recovery window in milliseconds
+     */
+    getRecoveryWindowMs(): number;
+    /**
+     * Get max recovery attempts
+     */
+    getMaxRecoveryAttempts(): number;
+    /**
+     * Clear all stored recovery data
+     */
+    clearRecoveryData(): void;
+}

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

@@ -0,0 +1,233 @@
+import { DEFAULT_SESSION_TIMEOUT_MS, SESSION_RECOVERY_WINDOW_MULTIPLIER, MAX_SESSION_RECOVERY_ATTEMPTS, MAX_SESSION_RECOVERY_WINDOW_MS, MIN_SESSION_RECOVERY_WINDOW_MS, } from '../constants';
+import { SESSION_RECOVERY_KEY } from '../constants/storage.constants';
+import { debugLog } from '../utils/logging';
+import { StateManager } from './state.manager';
+export class SessionRecoveryManager extends StateManager {
+    constructor(storageManager, projectId, eventManager, config) {
+        super();
+        this.storageManager = storageManager;
+        this.eventManager = eventManager ?? null;
+        this.projectId = projectId;
+        this.debugMode = (this.get('config')?.mode === 'qa' || this.get('config')?.mode === 'debug') ?? false;
+        this.config = {
+            recoveryWindowMs: this.calculateRecoveryWindow(),
+            maxRecoveryAttempts: MAX_SESSION_RECOVERY_ATTEMPTS,
+            contextPreservation: true,
+            ...config,
+        };
+    }
+    /**
+     * Attempt to recover a session
+     */
+    attemptSessionRecovery(currentSessionId) {
+        if (this.debugMode) {
+            debugLog.debug('SessionRecovery', 'Attempting session recovery');
+        }
+        // Get stored recovery attempts
+        const recoveryAttempts = this.getStoredRecoveryAttempts();
+        const lastAttempt = this.getLastRecoveryAttempt();
+        // Check if we can recover
+        if (!this.canAttemptRecovery(lastAttempt)) {
+            if (this.debugMode) {
+                debugLog.debug('SessionRecovery', 'Session recovery not possible - outside recovery window or max attempts reached');
+            }
+            return {
+                recovered: false,
+            };
+        }
+        // Get the last session context
+        const lastSessionContext = lastAttempt?.context;
+        if (!lastSessionContext) {
+            if (this.debugMode) {
+                debugLog.debug('SessionRecovery', 'No session context available for recovery');
+            }
+            return {
+                recovered: false,
+            };
+        }
+        // Check if recovery is possible
+        const now = Date.now();
+        const timeSinceLastActivity = now - lastSessionContext.lastActivity;
+        if (timeSinceLastActivity > this.config.recoveryWindowMs) {
+            if (this.debugMode) {
+                debugLog.debug('SessionRecovery', 'Session recovery failed - outside recovery window');
+            }
+            return {
+                recovered: false,
+            };
+        }
+        // Perform recovery
+        const recoveredSessionId = lastSessionContext.sessionId;
+        const attemptNumber = (lastAttempt?.attempt ?? 0) + 1;
+        // Create recovery attempt record
+        const recoveryAttempt = {
+            sessionId: currentSessionId ?? recoveredSessionId,
+            timestamp: now,
+            attempt: attemptNumber,
+            context: {
+                ...lastSessionContext,
+                recoveryAttempts: attemptNumber,
+                lastActivity: now,
+            },
+        };
+        recoveryAttempts.push(recoveryAttempt);
+        this.storeRecoveryAttempts(recoveryAttempts);
+        if (this.debugMode) {
+            debugLog.debug('SessionRecovery', `Session recovery successful: recovery of session ${recoveredSessionId}`);
+        }
+        return {
+            recovered: true,
+            recoveredSessionId,
+            context: recoveryAttempt.context,
+        };
+    }
+    /**
+     * Calculate the recovery window with bounds checking
+     */
+    calculateRecoveryWindow() {
+        const sessionTimeout = this.get('config')?.sessionTimeout ?? DEFAULT_SESSION_TIMEOUT_MS;
+        const calculatedRecoveryWindow = sessionTimeout * SESSION_RECOVERY_WINDOW_MULTIPLIER;
+        const boundedRecoveryWindow = Math.max(Math.min(calculatedRecoveryWindow, MAX_SESSION_RECOVERY_WINDOW_MS), MIN_SESSION_RECOVERY_WINDOW_MS);
+        if (this.debugMode) {
+            if (calculatedRecoveryWindow > MAX_SESSION_RECOVERY_WINDOW_MS) {
+                debugLog.warn('SessionRecovery', `Recovery window capped at ${MAX_SESSION_RECOVERY_WINDOW_MS}ms (24h). Calculated: ${calculatedRecoveryWindow}ms`);
+            }
+            else if (calculatedRecoveryWindow < MIN_SESSION_RECOVERY_WINDOW_MS) {
+                debugLog.warn('SessionRecovery', `Recovery window increased to minimum ${MIN_SESSION_RECOVERY_WINDOW_MS}ms (2min). Calculated: ${calculatedRecoveryWindow}ms`);
+            }
+        }
+        return boundedRecoveryWindow;
+    }
+    /**
+     * Check if session recovery can be attempted
+     */
+    canAttemptRecovery(lastAttempt) {
+        if (!lastAttempt) {
+            return true; // First recovery attempt
+        }
+        const now = Date.now();
+        const timeSinceLastActivity = now - lastAttempt.context.lastActivity;
+        // Check if within recovery window
+        if (timeSinceLastActivity > this.config.recoveryWindowMs) {
+            return false;
+        }
+        // Check max attempts
+        if (lastAttempt.attempt >= this.config.maxRecoveryAttempts) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Store session context for potential recovery
+     */
+    storeSessionContextForRecovery(sessionContext) {
+        try {
+            const recoveryAttempts = this.getStoredRecoveryAttempts();
+            // Create a recovery attempt record
+            const recoveryAttempt = {
+                sessionId: sessionContext.sessionId,
+                timestamp: Date.now(),
+                attempt: 0,
+                context: sessionContext,
+            };
+            // Add to recovery attempts (keep only the latest few)
+            recoveryAttempts.push(recoveryAttempt);
+            const maxStoredRecoveryAttempts = 5;
+            if (recoveryAttempts.length > maxStoredRecoveryAttempts) {
+                recoveryAttempts.splice(0, recoveryAttempts.length - maxStoredRecoveryAttempts);
+            }
+            this.storeRecoveryAttempts(recoveryAttempts);
+            if (this.debugMode) {
+                debugLog.debug('SessionRecovery', `Stored session context for recovery: ${sessionContext.sessionId}`);
+            }
+        }
+        catch (error) {
+            if (this.debugMode) {
+                debugLog.warn('SessionRecovery', 'Failed to store session context for recovery', { error });
+            }
+        }
+    }
+    /**
+     * Get stored recovery attempts
+     */
+    getStoredRecoveryAttempts() {
+        try {
+            const stored = this.storageManager.getItem(SESSION_RECOVERY_KEY(this.projectId));
+            return stored ? JSON.parse(stored) : [];
+        }
+        catch (error) {
+            if (this.debugMode) {
+                const stored = this.storageManager.getItem(SESSION_RECOVERY_KEY(this.projectId));
+                debugLog.warn('SessionRecovery', `Failed to parse stored recovery attempts for projectId ${this.projectId}. Data: ${stored}`, { error });
+            }
+            return [];
+        }
+    }
+    /**
+     * Store recovery attempts
+     */
+    storeRecoveryAttempts(attempts) {
+        try {
+            this.storageManager.setItem(SESSION_RECOVERY_KEY(this.projectId), JSON.stringify(attempts));
+        }
+        catch (error) {
+            if (this.debugMode) {
+                debugLog.warn('SessionRecovery', 'Failed to store recovery attempts', { error });
+            }
+        }
+    }
+    /**
+     * Get the last recovery attempt
+     */
+    getLastRecoveryAttempt() {
+        const attempts = this.getStoredRecoveryAttempts();
+        return attempts.length > 0 ? attempts[attempts.length - 1] : null;
+    }
+    /**
+     * Clean up old recovery attempts
+     */
+    cleanupOldRecoveryAttempts() {
+        const attempts = this.getStoredRecoveryAttempts();
+        const now = Date.now();
+        // Remove attempts older than recovery window
+        const validAttempts = attempts.filter((attempt) => now - attempt.timestamp <= this.config.recoveryWindowMs);
+        if (validAttempts.length !== attempts.length) {
+            this.storeRecoveryAttempts(validAttempts);
+            if (this.debugMode) {
+                debugLog.debug('SessionRecovery', `Cleaned up ${attempts.length - validAttempts.length} old recovery attempts`);
+            }
+        }
+    }
+    /**
+     * Check if there's a recoverable session.
+     * Returns false when no recovery attempts are stored.
+     */
+    hasRecoverableSession() {
+        const lastAttempt = this.getLastRecoveryAttempt();
+        if (!lastAttempt) {
+            return false;
+        }
+        return this.canAttemptRecovery(lastAttempt);
+    }
+    /**
+     * Get recovery window in milliseconds
+     */
+    getRecoveryWindowMs() {
+        return this.config.recoveryWindowMs;
+    }
+    /**
+     * Get max recovery attempts
+     */
+    getMaxRecoveryAttempts() {
+        return this.config.maxRecoveryAttempts;
+    }
+    /**
+     * Clear all stored recovery data
+     */
+    clearRecoveryData() {
+        this.storageManager.removeItem(SESSION_RECOVERY_KEY(this.projectId));
+        if (this.debugMode) {
+            debugLog.debug('SessionRecovery', 'Cleared all recovery data');
+        }
+    }
+}

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

@@ -0,0 +1,72 @@
+import { SessionEndReason, SessionEndConfig, SessionEndResult } from '../types/session.types';
+import { StateManager } from './state.manager';
+import { EventManager } from './event.manager';
+import { StorageManager } from './storage.manager';
+export declare class SessionManager extends StateManager {
+    private readonly config;
+    private readonly eventManager;
+    private readonly storageManager;
+    private readonly listenerManagers;
+    private readonly deviceCapabilities;
+    private readonly onActivity;
+    private readonly onInactivity;
+    private recoveryManager;
+    private isSessionActive;
+    private lastActivityTime;
+    private inactivityTimer;
+    private sessionStartTime;
+    private throttleTimeout;
+    private visibilityChangeTimeout;
+    private pendingSessionEnd;
+    private sessionEndPromise;
+    private sessionEndLock;
+    private cleanupHandlers;
+    private readonly sessionEndConfig;
+    private sessionEndReason;
+    private readonly sessionEndPriority;
+    private readonly sessionEndStats;
+    private readonly sessionHealth;
+    constructor(onActivity: () => void, onInactivity: () => void, eventManager?: EventManager, storageManager?: StorageManager, sessionEndConfig?: Partial<SessionEndConfig>);
+    /**
+     * Initialize recovery manager
+     */
+    private initializeRecoveryManager;
+    /**
+     * Store session context for recovery
+     */
+    private storeSessionContextForRecovery;
+    startSession(): {
+        sessionId: string;
+        recovered?: boolean;
+    };
+    endSession(): number;
+    destroy(): void;
+    private detectDeviceCapabilities;
+    private initializeListenerManagers;
+    private setupAllListeners;
+    private cleanupAllListeners;
+    private clearTimers;
+    private resetState;
+    private readonly handleActivity;
+    private readonly handleInactivity;
+    private readonly handleVisibilityChange;
+    private readonly resetInactivityTimer;
+    clearInactivityTimer(): void;
+    private shouldProceedWithSessionEnd;
+    private waitForCompletion;
+    endSessionManaged(reason: SessionEndReason): Promise<SessionEndResult>;
+    endSessionSafely(reason: SessionEndReason, options?: {
+        forceSync?: boolean;
+        allowSync?: boolean;
+    }): Promise<SessionEndResult> | SessionEndResult;
+    isPendingSessionEnd(): boolean;
+    /**
+     * Track session health events for monitoring and diagnostics
+     */
+    trackSessionHealth(event: 'recovery' | 'timeout' | 'conflict'): void;
+    private performSessionEnd;
+    private cleanupSession;
+    private endSessionManagedSync;
+    private performSessionEndSync;
+    private setupPageUnloadHandlers;
+}