@tracelog/lib 0.0.8 → 0.2.0

package/dist/esm/app.js

@@ -1,4 +1,4 @@
-import { ApiManager } from './managers/api.manager';
+import { getApiUrlForProject } from './managers/api.manager';
 import { ConfigManager } from './managers/config.manager';
 import { EventManager } from './managers/event.manager';
 import { UserManager } from './managers/user.manager';
@@ -7,262 +7,164 @@ 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 { isEventValid } from './utils/validations';
-import { EventType } from './types/event.types';
+import { EventType } from './types';
 import { GoogleAnalyticsIntegration } from './integrations/google-analytics.integration';
-import { getDeviceType, normalizeUrl } from './utils';
+import { isEventValid, getDeviceType, normalizeUrl, debugLog, Emitter, normalizeConfig } from './utils';
 import { StorageManager } from './managers/storage.manager';
-import { SCROLL_DEBOUNCE_TIME_MS, SCROLL_SUPPRESSION_CONSTANTS } from './constants';
+import { SCROLL_DEBOUNCE_TIME_MS, SCROLL_SUPPRESS_MULTIPLIER } from './constants/config.constants';
 import { PerformanceHandler } from './handlers/performance.handler';
 import { ErrorHandler } from './handlers/error.handler';
-import { NetworkHandler } from './handlers/network.handler';
-import { ProjectIdValidationError } from './types/validation-error.types';
-import { debugLog } from './utils/logging';
+/**
+ * Main application class for TraceLog analytics
+ * Orchestrates event tracking, session management, and integrations
+ */
 export class App extends StateManager {
     constructor() {
         super(...arguments);
         this.isInitialized = false;
-        this.googleAnalytics = null;
         this.suppressNextScrollTimer = null;
+        this.emitter = new Emitter();
+        this.managers = {};
+        this.handlers = {};
+        this.integrations = {};
     }
-    /**
-     * Returns the initialization status of the app
-     * @returns true if the app is fully initialized, false otherwise
-     */
     get initialized() {
         return this.isInitialized;
     }
     async init(appConfig) {
         if (this.isInitialized) {
-            debugLog.debug('App', 'App already initialized, skipping re-initialization', { projectId: appConfig.id });
             return;
         }
-        debugLog.info('App', 'App initialization started', { projectId: appConfig.id });
-        this.validateAppReadiness(appConfig);
+        if (!appConfig.id?.trim()) {
+            throw new Error('Project ID is required');
+        }
+        this.managers.storage = new StorageManager();
         try {
-            this.initStorage();
-            await this.setState(appConfig);
-            await this.setIntegrations();
-            this.setEventManager();
-            await this.initHandlers();
-            this.isInitialized = true;
-            debugLog.info('App', 'App initialization completed successfully', {
-                projectId: appConfig.id,
+            await this.setupState(appConfig);
+            await this.setupIntegrations();
+            this.managers.event = new EventManager(this.managers.storage, this.integrations.googleAnalytics, this.emitter);
+            this.initializeHandlers();
+            await this.managers.event.recoverPersistedEvents().catch(() => {
+                debugLog.warn('App', 'Failed to recover persisted events');
             });
+            this.isInitialized = true;
         }
         catch (error) {
-            this.isInitialized = false;
-            debugLog.error('App', 'App initialization failed', { projectId: appConfig.id, error });
-            throw error;
-        }
-    }
-    /**
-     * Validates that the app is ready to initialize with the provided config
-     * This is a lightweight runtime validation layer that ensures the app receives proper config
-     * @param appConfig - The validated and normalized configuration
-     * @throws {ProjectIdValidationError} If project ID is invalid at runtime
-     */
-    validateAppReadiness(appConfig) {
-        // Lightweight validation - config should already be validated and normalized by api.ts
-        if (!appConfig?.id) {
-            debugLog.clientError('App', 'Configuration integrity check failed - missing project ID', {
-                hasConfig: !!appConfig,
-                hasId: !!appConfig?.id,
-            });
-            throw new ProjectIdValidationError('Configuration integrity check failed', 'app');
+            await this.destroy(true);
+            throw new Error(`TraceLog initialization failed: ${error}`);
         }
     }
     sendCustomEvent(name, metadata) {
-        if (!this.eventManager) {
-            debugLog.warn('App', 'Custom event attempted before eventManager initialization', { eventName: name });
+        if (!this.managers.event) {
             return;
         }
         const { valid, error, sanitizedMetadata } = isEventValid(name, metadata);
-        if (valid) {
-            debugLog.debug('App', 'Custom event validated and queued', { eventName: name, hasMetadata: !!sanitizedMetadata });
-            this.eventManager.track({
-                type: EventType.CUSTOM,
-                custom_event: {
-                    name,
-                    ...(sanitizedMetadata && { metadata: sanitizedMetadata }),
-                },
-            });
-        }
-        else {
-            const currentMode = this.get('config')?.mode;
-            debugLog.clientError('App', `Custom event validation failed: ${error ?? 'unknown error'}`, {
-                eventName: name,
-                validationError: error,
-                hasMetadata: !!metadata,
-                mode: currentMode,
-            });
-            if (currentMode === 'qa' || currentMode === 'debug') {
-                throw new Error(`custom event "${name}" validation failed (${error ?? 'unknown error'}). Please, review your event data and try again.`);
+        if (!valid) {
+            const config = this.get('config');
+            if (config?.mode === 'qa' || config?.mode === 'debug') {
+                throw new Error(`Custom event "${name}" validation failed: ${error}`);
             }
+            return;
         }
+        this.managers.event.track({
+            type: EventType.CUSTOM,
+            custom_event: {
+                name,
+                ...(sanitizedMetadata && { metadata: sanitizedMetadata }),
+            },
+        });
+    }
+    on(event, callback) {
+        this.emitter.on(event, callback);
+    }
+    off(event, callback) {
+        this.emitter.off(event, callback);
     }
-    destroy() {
-        if (!this.isInitialized) {
-            debugLog.warn('App', 'Destroy called but app was not initialized');
+    async destroy(force = false) {
+        if (!this.isInitialized && !force) {
             return;
         }
-        debugLog.info('App', 'App cleanup started');
-        if (this.googleAnalytics) {
-            this.googleAnalytics.cleanup();
-        }
-        if (this.sessionHandler) {
-            this.sessionHandler.stopTracking();
-        }
-        if (this.pageViewHandler) {
-            this.pageViewHandler.stopTracking();
-        }
-        if (this.clickHandler) {
-            this.clickHandler.stopTracking();
-        }
-        if (this.scrollHandler) {
-            this.scrollHandler.stopTracking();
-        }
-        if (this.performanceHandler) {
-            this.performanceHandler.stopTracking();
-        }
-        if (this.errorHandler) {
-            this.errorHandler.stopTracking();
-        }
-        if (this.networkHandler) {
-            this.networkHandler.stopTracking();
-        }
+        this.integrations.googleAnalytics?.cleanup();
+        const handlerCleanups = Object.values(this.handlers)
+            .filter(Boolean)
+            .map(async (handler) => {
+            try {
+                await handler.stopTracking();
+            }
+            catch {
+                debugLog.warn('App', 'Failed to stop tracking');
+            }
+        });
+        await Promise.allSettled(handlerCleanups);
         if (this.suppressNextScrollTimer) {
             clearTimeout(this.suppressNextScrollTimer);
             this.suppressNextScrollTimer = null;
         }
-        if (this.eventManager) {
-            this.eventManager.stop();
-        }
+        this.managers.event?.stop();
+        this.emitter.removeAllListeners();
         this.set('hasStartSession', false);
         this.set('suppressNextScroll', false);
         this.set('sessionId', null);
         this.isInitialized = false;
-        debugLog.info('App', 'App cleanup completed successfully');
-    }
-    async setState(appConfig) {
-        this.setApiUrl(appConfig.id, appConfig.allowHttp);
-        await this.setConfig(appConfig);
-        this.setUserId();
-        this.setDevice();
-        this.setPageUrl();
+        this.handlers = {};
     }
-    setApiUrl(id, allowHttp = false) {
-        const apiManager = new ApiManager();
-        this.set('apiUrl', apiManager.getUrl(id, allowHttp));
-    }
-    async setConfig(appConfig) {
+    async setupState(appConfig) {
+        // Set API URL
+        const apiUrl = getApiUrlForProject(appConfig.id, appConfig.allowHttp);
+        this.set('apiUrl', apiUrl);
+        // Get remote configuration
         const configManager = new ConfigManager();
-        const config = await configManager.get(this.get('apiUrl'), appConfig);
-        this.set('config', config);
-    }
-    setUserId() {
-        const userManager = new UserManager(this.storageManager);
-        const userId = userManager.getId();
+        const config = await configManager.get(apiUrl, appConfig);
+        const { config: normalizedConfig } = normalizeConfig(config);
+        this.set('config', normalizedConfig);
+        // Set user ID
+        const userId = UserManager.getId(this.managers.storage, normalizedConfig.id);
         this.set('userId', userId);
-    }
-    setDevice() {
-        const device = getDeviceType();
-        this.set('device', device);
-    }
-    setPageUrl() {
-        const initialUrl = normalizeUrl(window.location.href, this.get('config').sensitiveQueryParams);
-        this.set('pageUrl', initialUrl);
-    }
-    async setIntegrations() {
-        const isIPExcluded = this.get('config').ipExcluded;
-        const measurementId = this.get('config').integrations?.googleAnalytics?.measurementId;
-        if (!isIPExcluded && measurementId?.trim()) {
-            this.googleAnalytics = new GoogleAnalyticsIntegration();
-            await this.googleAnalytics.initialize();
-        }
-    }
-    async initHandlers() {
-        if (!this.eventManager) {
-            throw new Error('EventManager must be initialized before handlers');
-        }
-        if (!this.storageManager) {
-            throw new Error('StorageManager must be initialized before handlers');
-        }
-        this.initSessionHandler();
-        this.initPageViewHandler();
-        this.initClickHandler();
-        this.initScrollHandler();
-        await this.initPerformanceHandler();
-        this.initErrorHandler();
-        this.initNetworkHandler();
-    }
-    initStorage() {
-        this.storageManager = new StorageManager();
-    }
-    setEventManager() {
-        if (!this.storageManager) {
-            throw new Error('StorageManager must be initialized before EventManager');
-        }
-        this.eventManager = new EventManager(this.storageManager, this.googleAnalytics);
-    }
-    initSessionHandler() {
-        if (!this.storageManager || !this.eventManager) {
-            throw new Error('StorageManager and EventManager must be initialized before SessionHandler');
-        }
-        this.sessionHandler = new SessionHandler(this.storageManager, this.eventManager);
-        this.sessionHandler.startTracking();
-    }
-    initPageViewHandler() {
-        if (!this.eventManager) {
-            throw new Error('EventManager must be initialized before PageViewHandler');
-        }
-        const onPageViewTrack = () => this.onPageViewTrack();
-        this.pageViewHandler = new PageViewHandler(this.eventManager, onPageViewTrack);
-        this.pageViewHandler.startTracking();
-    }
-    onPageViewTrack() {
-        this.set('suppressNextScroll', true);
-        if (this.suppressNextScrollTimer) {
-            clearTimeout(this.suppressNextScrollTimer);
-            this.suppressNextScrollTimer = null;
-        }
-        this.suppressNextScrollTimer = window.setTimeout(() => {
-            this.set('suppressNextScroll', false);
-        }, SCROLL_DEBOUNCE_TIME_MS * SCROLL_SUPPRESSION_CONSTANTS.SUPPRESS_MULTIPLIER);
-    }
-    initClickHandler() {
-        if (!this.eventManager) {
-            throw new Error('EventManager must be initialized before ClickHandler');
-        }
-        this.clickHandler = new ClickHandler(this.eventManager);
-        this.clickHandler.startTracking();
-    }
-    initScrollHandler() {
-        if (!this.eventManager) {
-            throw new Error('EventManager must be initialized before ScrollHandler');
-        }
-        this.scrollHandler = new ScrollHandler(this.eventManager);
-        this.scrollHandler.startTracking();
-    }
-    async initPerformanceHandler() {
-        if (!this.eventManager) {
-            throw new Error('EventManager must be initialized before PerformanceHandler');
-        }
-        this.performanceHandler = new PerformanceHandler(this.eventManager);
-        await this.performanceHandler.startTracking();
-    }
-    initErrorHandler() {
-        if (!this.eventManager) {
-            throw new Error('EventManager must be initialized before ErrorHandler');
+        // Set device and page info
+        this.set('device', getDeviceType());
+        const pageUrl = normalizeUrl(window.location.href, normalizedConfig.sensitiveQueryParams);
+        this.set('pageUrl', pageUrl);
+    }
+    async setupIntegrations() {
+        const config = this.get('config');
+        const measurementId = config.integrations?.googleAnalytics?.measurementId;
+        if (!config.ipExcluded && measurementId?.trim()) {
+            try {
+                this.integrations.googleAnalytics = new GoogleAnalyticsIntegration();
+                await this.integrations.googleAnalytics.initialize();
+            }
+            catch {
+                this.integrations.googleAnalytics = undefined;
+            }
         }
-        this.errorHandler = new ErrorHandler(this.eventManager);
-        this.errorHandler.startTracking();
     }
-    initNetworkHandler() {
-        if (!this.eventManager) {
-            throw new Error('EventManager must be initialized before NetworkHandler');
-        }
-        this.networkHandler = new NetworkHandler(this.eventManager);
-        this.networkHandler.startTracking();
+    initializeHandlers() {
+        this.handlers.session = new SessionHandler(this.managers.storage, this.managers.event);
+        this.handlers.session.startTracking().catch((error) => {
+            debugLog.error('App', 'Session handler failed to start', {
+                message: error instanceof Error ? error.message : 'Unknown error',
+            });
+        });
+        const onPageView = () => {
+            this.set('suppressNextScroll', true);
+            if (this.suppressNextScrollTimer) {
+                clearTimeout(this.suppressNextScrollTimer);
+            }
+            this.suppressNextScrollTimer = window.setTimeout(() => {
+                this.set('suppressNextScroll', false);
+            }, SCROLL_DEBOUNCE_TIME_MS * SCROLL_SUPPRESS_MULTIPLIER);
+        };
+        this.handlers.pageView = new PageViewHandler(this.managers.event, onPageView);
+        this.handlers.pageView.startTracking();
+        this.handlers.click = new ClickHandler(this.managers.event);
+        this.handlers.click.startTracking();
+        this.handlers.scroll = new ScrollHandler(this.managers.event);
+        this.handlers.scroll.startTracking();
+        this.handlers.performance = new PerformanceHandler(this.managers.event);
+        this.handlers.performance.startTracking().catch(() => {
+            debugLog.warn('App', 'Failed to start performance tracking');
+        });
+        this.handlers.error = new ErrorHandler(this.managers.event);
+        this.handlers.error.startTracking();
     }
 }

package/dist/esm/app.types.d.ts

@@ -1,7 +1,2 @@
-export * from './types/common.types';
-export * from './types/config.types';
-export * from './types/device.types';
-export * from './types/event.types';
-export * from './types/mode.types';
-export * from './types/queue.types';
-export * from './types/tag.types';
+export { Mode, EventType, DeviceType, ScrollDirection, ErrorType, TagConditionOperator, TagLogicalOperator, TagConditionType, } from './types';
+export type { ScrollData, ClickData, CustomEventData, MetadataType, WebVitalsData, ErrorData, PageViewData, UTM, EventData, AppConfig, ApiConfig, ExtendedEventsQueueDto, TagConfig, BaseEventsQueueDto, WebVitalType, SessionEndReason, } from './types';

package/dist/esm/app.types.js

@@ -1,7 +1 @@
-export * from './types/common.types';
-export * from './types/config.types';
-export * from './types/device.types';
-export * from './types/event.types';
-export * from './types/mode.types';
-export * from './types/queue.types';
-export * from './types/tag.types';
+export { Mode, EventType, DeviceType, ScrollDirection, ErrorType, TagConditionOperator, TagLogicalOperator, TagConditionType, } from './types';

package/dist/esm/constants/api.constants.js

@@ -1,13 +1,19 @@
-import { DEFAULT_SAMPLING_RATE } from './limits.constants';
-import { DEFAULT_SESSION_TIMEOUT_MS } from './timing.constants';
+import { DEFAULT_SAMPLING_RATE, DEFAULT_SESSION_TIMEOUT, MAX_SAMPLING_RATE, MIN_SAMPLING_RATE, } from './config.constants';
 export const DEFAULT_API_CONFIG = {
     samplingRate: DEFAULT_SAMPLING_RATE,
-    tags: [],
     excludedUrlPaths: [],
+    tags: [],
+    ipExcluded: false,
 };
 export const DEFAULT_CONFIG = (config) => ({
     ...DEFAULT_API_CONFIG,
     ...config,
-    sessionTimeout: DEFAULT_SESSION_TIMEOUT_MS,
     allowHttp: false,
+    sessionTimeout: DEFAULT_SESSION_TIMEOUT,
+    samplingRate: config.samplingRate && config.samplingRate > MIN_SAMPLING_RATE && config.samplingRate <= MAX_SAMPLING_RATE
+        ? config.samplingRate
+        : DEFAULT_SAMPLING_RATE,
+    excludedUrlPaths: config.excludedUrlPaths ?? [],
+    tags: config.tags ?? [],
+    ipExcluded: config.ipExcluded ?? false,
 });

package/dist/esm/constants/config.constants.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Consolidated configuration constants for TraceLog
+ * This file centralizes all timing, limits, browser, and initialization constants
+ */
+export declare const DEFAULT_SESSION_TIMEOUT: number;
+export declare const DUPLICATE_EVENT_THRESHOLD_MS = 1000;
+export declare const EVENT_SENT_INTERVAL_MS = 10000;
+export declare const SCROLL_DEBOUNCE_TIME_MS = 250;
+export declare const DEFAULT_VISIBILITY_TIMEOUT_MS = 2000;
+export declare const EVENT_EXPIRY_HOURS = 24;
+export declare const EVENT_PERSISTENCE_MAX_AGE_MS: number;
+export declare const MAX_EVENTS_QUEUE_LENGTH = 500;
+export declare const MAX_RETRIES = 3;
+export declare const RETRY_DELAY_MS = 5000;
+export declare const REQUEST_TIMEOUT_MS = 10000;
+export declare const MAX_METADATA_SIZE = 5000;
+export declare const DEFAULT_MOTION_THRESHOLD = 2;
+export declare const SIGNIFICANT_SCROLL_DELTA = 10;
+export declare const MIN_SCROLL_DEPTH_CHANGE = 5;
+export declare const SCROLL_MIN_EVENT_INTERVAL_MS = 500;
+export declare const MAX_SCROLL_EVENTS_PER_SESSION = 120;
+export declare const DEFAULT_SAMPLING_RATE = 1;
+export declare const MIN_SAMPLING_RATE = 0;
+export declare const MAX_SAMPLING_RATE = 1;
+export declare const BATCH_SIZE_THRESHOLD = 50;
+export declare const MIN_SESSION_TIMEOUT_MS = 30000;
+export declare const MAX_SESSION_TIMEOUT_MS = 86400000;
+export declare const MAX_CUSTOM_EVENT_NAME_LENGTH = 120;
+export declare const MAX_CUSTOM_EVENT_STRING_SIZE: number;
+export declare const MAX_CUSTOM_EVENT_KEYS = 10;
+export declare const MAX_CUSTOM_EVENT_ARRAY_SIZE = 10;
+export declare const MAX_TEXT_LENGTH = 255;
+export declare const MAX_STRING_LENGTH = 1000;
+export declare const MAX_ARRAY_LENGTH = 100;
+export declare const MAX_OBJECT_DEPTH = 3;
+export declare const PRECISION_TWO_DECIMALS: 2;
+export declare const SYNC_XHR_TIMEOUT_MS = 2000;
+export declare const MAX_FINGERPRINTS = 1000;
+export declare const FINGERPRINT_CLEANUP_MULTIPLIER = 10;
+export declare const MAX_FINGERPRINTS_HARD_LIMIT = 2000;
+export declare const HTML_DATA_ATTR_PREFIX = "data-tl";
+export declare const INTERACTIVE_SELECTORS: readonly ["button", "a", "input[type=\"button\"]", "input[type=\"submit\"]", "input[type=\"reset\"]", "input[type=\"checkbox\"]", "input[type=\"radio\"]", "select", "textarea", "[role=\"button\"]", "[role=\"link\"]", "[role=\"tab\"]", "[role=\"menuitem\"]", "[role=\"option\"]", "[role=\"checkbox\"]", "[role=\"radio\"]", "[role=\"switch\"]", "[routerLink]", "[ng-click]", "[data-action]", "[data-click]", "[data-navigate]", "[data-toggle]", "[onclick]", ".btn", ".button", ".clickable", ".nav-link", ".menu-item", "[data-testid]", "[tabindex=\"0\"]"];
+export declare const UTM_PARAMS: string[];
+export declare const INITIALIZATION_MAX_CONCURRENT_RETRIES = 20;
+export declare const INITIALIZATION_CONCURRENT_RETRY_DELAY_MS = 50;
+export declare const INITIALIZATION_TIMEOUT_MS = 10000;
+export declare const SESSION_SYNC_TIMEOUT_MS = 2000;
+export declare const SESSION_MAX_RETRY_ATTEMPTS = 3;
+export declare const SESSION_CLEANUP_DELAY_MS = 100;
+export declare const CROSS_TAB_INITIALIZATION_LOCK_TIMEOUT_MS = 5000;
+export declare const TAB_HEARTBEAT_INTERVAL_MS = 5000;
+export declare const TAB_ELECTION_TIMEOUT_MS = 2000;
+export declare const TAB_CLEANUP_DELAY_MS = 1000;
+export declare const SESSION_RECOVERY_WINDOW_MULTIPLIER = 2;
+export declare const MAX_SESSION_RECOVERY_ATTEMPTS = 3;
+export declare const MAX_SESSION_RECOVERY_WINDOW_MS: number;
+export declare const MIN_SESSION_RECOVERY_WINDOW_MS: number;
+export declare const SCROLL_SUPPRESS_MULTIPLIER = 2;
+export declare const RETRY_BACKOFF_INITIAL = 1000;
+export declare const RETRY_BACKOFF_MAX = 30000;
+export declare const RATE_LIMIT_INTERVAL = 1000;
+export declare const MAX_RETRY_ATTEMPTS = 10;
+export declare const ALLOWED_API_CONFIG_KEYS: Set<"mode" | "samplingRate" | "excludedUrlPaths" | keyof import("../types").ExclusiveApiConfig>;
+export declare const VALIDATION_MESSAGES: {
+    readonly MISSING_PROJECT_ID: "Project ID is required";
+    readonly PROJECT_ID_EMPTY_AFTER_TRIM: "Project ID is required";
+    readonly INVALID_SESSION_TIMEOUT: "Session timeout must be between 30000ms (30 seconds) and 86400000ms (24 hours)";
+    readonly INVALID_SAMPLING_RATE: "Sampling rate must be greater than 0 and less than or equal to 1";
+    readonly INVALID_ERROR_SAMPLING_RATE: "Error sampling must be between 0 and 1";
+    readonly INVALID_GOOGLE_ANALYTICS_ID: "Google Analytics measurement ID is required when integration is enabled";
+    readonly INVALID_SCROLL_CONTAINER_SELECTORS: "Scroll container selectors must be valid CSS selectors";
+    readonly INVALID_GLOBAL_METADATA: "Global metadata must be an object";
+    readonly INVALID_SENSITIVE_QUERY_PARAMS: "Sensitive query params must be an array of strings";
+};
+export declare const XSS_PATTERNS: readonly [RegExp, RegExp, RegExp, RegExp, RegExp, RegExp];