@tracelog/lib 0.0.1

package/dist/esm/app.js

@@ -0,0 +1,268 @@
+import { ApiManager } from './managers/api.manager';
+import { ConfigManager } from './managers/config.manager';
+import { EventManager } from './managers/event.manager';
+import { UserManager } from './managers/user.manager';
+import { StateManager } from './managers/state.manager';
+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 { GoogleAnalyticsIntegration } from './integrations/google-analytics.integration';
+import { getDeviceType, normalizeUrl } from './utils';
+import { StorageManager } from './managers/storage.manager';
+import { SCROLL_DEBOUNCE_TIME_MS, SCROLL_SUPPRESSION_CONSTANTS } from './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';
+export class App extends StateManager {
+    constructor() {
+        super(...arguments);
+        this.isInitialized = false;
+        this.googleAnalytics = null;
+        this.suppressNextScrollTimer = null;
+    }
+    /**
+     * 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);
+        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,
+            });
+        }
+        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');
+        }
+    }
+    sendCustomEvent(name, metadata) {
+        if (!this.eventManager) {
+            debugLog.warn('App', 'Custom event attempted before eventManager initialization', { eventName: name });
+            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.`);
+            }
+        }
+    }
+    destroy() {
+        if (!this.isInitialized) {
+            debugLog.warn('App', 'Destroy called but app was not initialized');
+            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();
+        }
+        if (this.suppressNextScrollTimer) {
+            clearTimeout(this.suppressNextScrollTimer);
+            this.suppressNextScrollTimer = null;
+        }
+        if (this.eventManager) {
+            this.eventManager.stop();
+        }
+        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();
+    }
+    setApiUrl(id, allowHttp = false) {
+        const apiManager = new ApiManager();
+        this.set('apiUrl', apiManager.getUrl(id, allowHttp));
+    }
+    async setConfig(appConfig) {
+        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();
+        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');
+        }
+        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();
+    }
+}

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

@@ -0,0 +1,6 @@
+export * from './types/common.types';
+export * from './types/config.types';
+export * from './types/device.types';
+export * from './types/event.types';
+export * from './types/queue.types';
+export * from './types/tag.types';

package/dist/esm/app.types.js

@@ -0,0 +1,6 @@
+export * from './types/common.types';
+export * from './types/config.types';
+export * from './types/device.types';
+export * from './types/event.types';
+export * from './types/queue.types';
+export * from './types/tag.types';

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

@@ -0,0 +1,4 @@
+import { ApiConfig, Config } from '../types';
+export declare const API_BASE_URL = "https://api.tracelog.io";
+export declare const DEFAULT_API_CONFIG: ApiConfig;
+export declare const DEFAULT_CONFIG: (config: Config) => Config;

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

@@ -0,0 +1,14 @@
+import { DEFAULT_SAMPLING_RATE } from './limits.constants';
+import { DEFAULT_SESSION_TIMEOUT_MS } from './timing.constants';
+export const API_BASE_URL = 'https://api.tracelog.io';
+export const DEFAULT_API_CONFIG = {
+    samplingRate: DEFAULT_SAMPLING_RATE,
+    tags: [],
+    excludedUrlPaths: [],
+};
+export const DEFAULT_CONFIG = (config) => ({
+    ...DEFAULT_API_CONFIG,
+    ...config,
+    sessionTimeout: DEFAULT_SESSION_TIMEOUT_MS,
+    allowHttp: false,
+});

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

@@ -0,0 +1,3 @@
+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[];

package/dist/esm/constants/browser.constants.js

@@ -0,0 +1,38 @@
+// Click tracking constants
+export const HTML_DATA_ATTR_PREFIX = 'data-tl';
+// Interactive element selectors for click tracking
+export const INTERACTIVE_SELECTORS = [
+    '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"]',
+];
+// UTM parameters for tracking
+export const UTM_PARAMS = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content'];

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

@@ -0,0 +1,8 @@
+export * from './api.constants';
+export * from './browser.constants';
+export * from './initialization.constants';
+export * from './limits.constants';
+export * from './security.constants';
+export * from './storage.constants';
+export * from './timing.constants';
+export * from './validation.constants';

package/dist/esm/constants/index.js

@@ -0,0 +1,8 @@
+export * from './api.constants';
+export * from './browser.constants';
+export * from './initialization.constants';
+export * from './limits.constants';
+export * from './security.constants';
+export * from './storage.constants';
+export * from './timing.constants';
+export * from './validation.constants';

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

@@ -0,0 +1,40 @@
+/**
+ * Constants for initialization and reliability patterns
+ * These values control initialization behavior, retry logic, and circuit breaker patterns
+ */
+export declare const INITIALIZATION_CONSTANTS: {
+    /** Maximum number of retries when waiting for concurrent initialization */
+    readonly MAX_CONCURRENT_RETRIES: 20;
+    /** Delay between retries when waiting for concurrent initialization (ms) */
+    readonly CONCURRENT_RETRY_DELAY_MS: 50;
+    /** Timeout for overall initialization process (ms) */
+    readonly INITIALIZATION_TIMEOUT_MS: 10000;
+};
+export declare const CIRCUIT_BREAKER_CONSTANTS: {
+    /** Maximum number of consecutive failures before opening circuit */
+    readonly MAX_FAILURES: 10;
+    /** Initial backoff delay when circuit opens (ms) */
+    readonly INITIAL_BACKOFF_DELAY_MS: 1000;
+    /** Maximum backoff delay (ms) */
+    readonly MAX_BACKOFF_DELAY_MS: 30000;
+    /** Backoff multiplier for exponential backoff */
+    readonly BACKOFF_MULTIPLIER: 2;
+    /** Time-based recovery period for circuit breaker (ms) */
+    readonly RECOVERY_TIME_MS: 30000;
+};
+export declare const SESSION_SYNC_CONSTANTS: {
+    /** Timeout for session synchronization operations (ms) */
+    readonly SYNC_TIMEOUT_MS: 2000;
+    /** Maximum retry attempts for session operations */
+    readonly MAX_RETRY_ATTEMPTS: 3;
+    /** Delay before cleanup operations (ms) */
+    readonly CLEANUP_DELAY_MS: 100;
+};
+export declare const CROSS_TAB_CONSTANTS: {
+    /** Flag to prevent concurrent cross-tab manager initialization */
+    readonly INITIALIZATION_LOCK_TIMEOUT_MS: 5000;
+};
+export declare const SCROLL_SUPPRESSION_CONSTANTS: {
+    /** Multiplier for scroll debounce time when suppressing scroll events */
+    readonly SUPPRESS_MULTIPLIER: 2;
+};

package/dist/esm/constants/initialization.constants.js

@@ -0,0 +1,45 @@
+/**
+ * Constants for initialization and reliability patterns
+ * These values control initialization behavior, retry logic, and circuit breaker patterns
+ */
+// Initialization retry constants
+export const INITIALIZATION_CONSTANTS = {
+    /** Maximum number of retries when waiting for concurrent initialization */
+    MAX_CONCURRENT_RETRIES: 20,
+    /** Delay between retries when waiting for concurrent initialization (ms) */
+    CONCURRENT_RETRY_DELAY_MS: 50,
+    /** Timeout for overall initialization process (ms) */
+    INITIALIZATION_TIMEOUT_MS: 10000,
+};
+// Circuit breaker constants
+export const CIRCUIT_BREAKER_CONSTANTS = {
+    /** Maximum number of consecutive failures before opening circuit */
+    MAX_FAILURES: 10,
+    /** Initial backoff delay when circuit opens (ms) */
+    INITIAL_BACKOFF_DELAY_MS: 1000,
+    /** Maximum backoff delay (ms) */
+    MAX_BACKOFF_DELAY_MS: 30000,
+    /** Backoff multiplier for exponential backoff */
+    BACKOFF_MULTIPLIER: 2,
+    /** Time-based recovery period for circuit breaker (ms) */
+    RECOVERY_TIME_MS: 30000, // 30 seconds
+};
+// Session management constants
+export const SESSION_SYNC_CONSTANTS = {
+    /** Timeout for session synchronization operations (ms) */
+    SYNC_TIMEOUT_MS: 2000,
+    /** Maximum retry attempts for session operations */
+    MAX_RETRY_ATTEMPTS: 3,
+    /** Delay before cleanup operations (ms) */
+    CLEANUP_DELAY_MS: 100,
+};
+// Cross-tab coordination constants
+export const CROSS_TAB_CONSTANTS = {
+    /** Flag to prevent concurrent cross-tab manager initialization */
+    INITIALIZATION_LOCK_TIMEOUT_MS: 5000,
+};
+// Scroll suppression constants
+export const SCROLL_SUPPRESSION_CONSTANTS = {
+    /** Multiplier for scroll debounce time when suppressing scroll events */
+    SUPPRESS_MULTIPLIER: 2,
+};

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

@@ -0,0 +1,25 @@
+export declare const DEFAULT_MOTION_THRESHOLD = 2;
+export declare const SIGNIFICANT_SCROLL_DELTA = 10;
+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 MAX_EVENTS_QUEUE_LENGTH = 500;
+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 PRECISION_FOUR_DECIMALS: 4;
+export declare const WEB_VITALS_SAMPLING: 0.75;
+export declare const WEB_VITALS_LONG_TASK_SAMPLING: 0.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 CLICK_COORDINATE_PRECISION = 10;

package/dist/esm/constants/limits.constants.js

@@ -0,0 +1,37 @@
+// Motion and interaction thresholds
+export const DEFAULT_MOTION_THRESHOLD = 2;
+export const SIGNIFICANT_SCROLL_DELTA = 10;
+// Sampling and rate limits
+export const DEFAULT_SAMPLING_RATE = 1;
+export const MIN_SAMPLING_RATE = 0;
+export const MAX_SAMPLING_RATE = 1;
+// Queue and batch limits
+export const BATCH_SIZE_THRESHOLD = 50;
+export const MAX_EVENTS_QUEUE_LENGTH = 500;
+// Session timeout validation limits
+export const MIN_SESSION_TIMEOUT_MS = 30000; // 30 seconds minimum
+export const MAX_SESSION_TIMEOUT_MS = 86400000; // 24 hours maximum
+// Custom event validation limits
+export const MAX_CUSTOM_EVENT_NAME_LENGTH = 120;
+export const MAX_CUSTOM_EVENT_STRING_SIZE = 8 * 1024; // 8KB
+export const MAX_CUSTOM_EVENT_KEYS = 10;
+export const MAX_CUSTOM_EVENT_ARRAY_SIZE = 10;
+// Text content limits
+export const MAX_TEXT_LENGTH = 255; // For click tracking text content
+// Data sanitization limits
+export const MAX_STRING_LENGTH = 1000;
+export const MAX_ARRAY_LENGTH = 100;
+export const MAX_OBJECT_DEPTH = 3;
+// Precision for numeric metrics
+export const PRECISION_TWO_DECIMALS = 2;
+export const PRECISION_FOUR_DECIMALS = 4;
+// Web vitals sampling
+export const WEB_VITALS_SAMPLING = 0.75;
+export const WEB_VITALS_LONG_TASK_SAMPLING = 0.2;
+// Sync XHR timeout
+export const SYNC_XHR_TIMEOUT_MS = 2000; // 2 seconds
+// Event fingerprint management
+export const MAX_FINGERPRINTS = 1000; // Maximum fingerprints stored before cleanup
+export const FINGERPRINT_CLEANUP_MULTIPLIER = 10; // Cleanup fingerprints older than 10x threshold
+// Click coordinate precision
+export const CLICK_COORDINATE_PRECISION = 10; // Round click coordinates to nearest 10px

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

@@ -0,0 +1 @@
+export declare const XSS_PATTERNS: readonly [RegExp, RegExp, RegExp, RegExp, RegExp, RegExp];

package/dist/esm/constants/security.constants.js

@@ -0,0 +1,9 @@
+// XSS protection patterns
+export const XSS_PATTERNS = [
+    /<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi,
+    /javascript:/gi,
+    /on\w+\s*=/gi,
+    /<iframe\b[^<]*(?:(?!<\/iframe>)<[^<]*)*<\/iframe>/gi,
+    /<embed\b[^>]*>/gi,
+    /<object\b[^<]*(?:(?!<\/object>)<[^<]*)*<\/object>/gi,
+];

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

@@ -0,0 +1,9 @@
+export declare const STORAGE_BASE_KEY = "tl";
+export declare const USER_ID_KEY: (id: string) => string;
+export declare const QUEUE_KEY: (id: string) => string;
+export declare const SESSION_STORAGE_KEY: (id: string) => string;
+export declare const CROSS_TAB_SESSION_KEY: (id: string) => string;
+export declare const TAB_INFO_KEY: (id: string) => string;
+export declare const TAB_SPECIFIC_INFO_KEY: (projectId: string, tabId: string) => string;
+export declare const SESSION_RECOVERY_KEY: (id: string) => string;
+export declare const BROADCAST_CHANNEL_NAME: (id: string) => string;

package/dist/esm/constants/storage.constants.js

@@ -0,0 +1,11 @@
+export const STORAGE_BASE_KEY = 'tl';
+export const USER_ID_KEY = (id) => (id ? `${STORAGE_BASE_KEY}:${id}:uid` : `${STORAGE_BASE_KEY}:uid`);
+export const QUEUE_KEY = (id) => (id ? `${STORAGE_BASE_KEY}:${id}:queue` : `${STORAGE_BASE_KEY}:queue`);
+export const SESSION_STORAGE_KEY = (id) => id ? `${STORAGE_BASE_KEY}:${id}:session` : `${STORAGE_BASE_KEY}:session`;
+// Cross-tab session management storage keys
+export const CROSS_TAB_SESSION_KEY = (id) => id ? `${STORAGE_BASE_KEY}:${id}:cross_tab_session` : `${STORAGE_BASE_KEY}:cross_tab_session`;
+export const TAB_INFO_KEY = (id) => id ? `${STORAGE_BASE_KEY}:${id}:tab_info` : `${STORAGE_BASE_KEY}:tab_info`;
+export const TAB_SPECIFIC_INFO_KEY = (projectId, tabId) => `${STORAGE_BASE_KEY}:${projectId}:tab:${tabId}:info`;
+export const SESSION_RECOVERY_KEY = (id) => id ? `${STORAGE_BASE_KEY}:${id}:recovery` : `${STORAGE_BASE_KEY}:recovery`;
+// BroadcastChannel name for cross-tab communication
+export const BROADCAST_CHANNEL_NAME = (id) => id ? `${STORAGE_BASE_KEY}:${id}:broadcast` : `${STORAGE_BASE_KEY}:broadcast`;

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

@@ -0,0 +1,22 @@
+export declare const DEFAULT_SESSION_TIMEOUT_MS: number;
+export declare const SESSION_HEARTBEAT_INTERVAL_MS = 30000;
+export declare const DEFAULT_THROTTLE_DELAY_MS = 1000;
+export declare const SCROLL_DEBOUNCE_TIME_MS = 250;
+export declare const DEFAULT_VISIBILITY_TIMEOUT_MS = 2000;
+export declare const DUPLICATE_EVENT_THRESHOLD_MS = 1000;
+export declare const EVENT_SENT_INTERVAL_MS = 10000;
+export declare const EVENT_SENT_INTERVAL_TEST_MS = 2500;
+export declare const RETRY_BACKOFF_INITIAL = 1000;
+export declare const RETRY_BACKOFF_MAX = 30000;
+export declare const RATE_LIMIT_INTERVAL = 1000;
+export declare const EVENT_EXPIRY_HOURS = 24;
+export declare const EVENT_PERSISTENCE_MAX_AGE_MS: number;
+export declare const LONG_TASK_THROTTLE_MS = 1000;
+export declare const SESSION_END_PRIORITY_DELAY_MS = 100;
+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;

package/dist/esm/constants/timing.constants.js

@@ -0,0 +1,31 @@
+// Session and timeout constants
+export const DEFAULT_SESSION_TIMEOUT_MS = 15 * 60 * 1000;
+export const SESSION_HEARTBEAT_INTERVAL_MS = 30000;
+// Throttling and debouncing constants
+export const DEFAULT_THROTTLE_DELAY_MS = 1000;
+export const SCROLL_DEBOUNCE_TIME_MS = 250;
+export const DEFAULT_VISIBILITY_TIMEOUT_MS = 2000;
+export const DUPLICATE_EVENT_THRESHOLD_MS = 1000;
+// Event processing intervals
+export const EVENT_SENT_INTERVAL_MS = 10000;
+export const EVENT_SENT_INTERVAL_TEST_MS = 2500;
+// Network timing
+export const RETRY_BACKOFF_INITIAL = 1000; // 1 second
+export const RETRY_BACKOFF_MAX = 30000; // 30 seconds
+export const RATE_LIMIT_INTERVAL = 1000; // 1 second
+// Event expiry
+export const EVENT_EXPIRY_HOURS = 24;
+export const EVENT_PERSISTENCE_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24 hours
+// Performance metrics
+export const LONG_TASK_THROTTLE_MS = DEFAULT_THROTTLE_DELAY_MS;
+// Session end coordination
+export const SESSION_END_PRIORITY_DELAY_MS = 100;
+// Cross-tab session management
+export const TAB_HEARTBEAT_INTERVAL_MS = 5000; // 5 seconds
+export const TAB_ELECTION_TIMEOUT_MS = 2000; // 2 seconds
+export const TAB_CLEANUP_DELAY_MS = 1000; // 1 second
+// Session recovery
+export const SESSION_RECOVERY_WINDOW_MULTIPLIER = 2; // 2x session timeout
+export const MAX_SESSION_RECOVERY_ATTEMPTS = 3;
+export const MAX_SESSION_RECOVERY_WINDOW_MS = 24 * 60 * 60 * 1000; // 24 hours max
+export const MIN_SESSION_RECOVERY_WINDOW_MS = 2 * 60 * 1000; // 2 minutes minimum

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

@@ -0,0 +1,13 @@
+import { ApiConfig } from '../types';
+export declare const ALLOWED_API_CONFIG_KEYS: Set<keyof ApiConfig>;
+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 between 0 and 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";
+};

package/dist/esm/constants/validation.constants.js

@@ -0,0 +1,28 @@
+import { MIN_SESSION_TIMEOUT_MS, MAX_SESSION_TIMEOUT_MS, MIN_SAMPLING_RATE, MAX_SAMPLING_RATE, } from './limits.constants';
+// Allowed API config keys for runtime validation
+export const ALLOWED_API_CONFIG_KEYS = new Set([
+    'mode',
+    'tags',
+    'samplingRate',
+    'excludedUrlPaths',
+    'ipExcluded',
+]);
+// Validation error messages - standardized across all layers
+export const VALIDATION_MESSAGES = {
+    // Project ID validation - consistent message across all layers
+    MISSING_PROJECT_ID: 'Project ID is required',
+    PROJECT_ID_EMPTY_AFTER_TRIM: 'Project ID is required',
+    // Session timeout validation
+    INVALID_SESSION_TIMEOUT: `Session timeout must be between ${MIN_SESSION_TIMEOUT_MS}ms (30 seconds) and ${MAX_SESSION_TIMEOUT_MS}ms (24 hours)`,
+    // Sampling rate validation
+    INVALID_SAMPLING_RATE: `Sampling rate must be between ${MIN_SAMPLING_RATE} and ${MAX_SAMPLING_RATE}`,
+    INVALID_ERROR_SAMPLING_RATE: 'Error sampling must be between 0 and 1',
+    // Integration validation
+    INVALID_GOOGLE_ANALYTICS_ID: 'Google Analytics measurement ID is required when integration is enabled',
+    // UI validation
+    INVALID_SCROLL_CONTAINER_SELECTORS: 'Scroll container selectors must be valid CSS selectors',
+    // Global metadata validation
+    INVALID_GLOBAL_METADATA: 'Global metadata must be an object',
+    // Array validation
+    INVALID_SENSITIVE_QUERY_PARAMS: 'Sensitive query params must be an array of strings',
+};