@tracelog/lib 0.0.8 → 0.2.0

package/dist/esm/constants/config.constants.js

@@ -0,0 +1,174 @@
+/**
+ * Consolidated configuration constants for TraceLog
+ * This file centralizes all timing, limits, browser, and initialization constants
+ */
+// ============================================================================
+// SESSION & TIMING
+// ============================================================================
+export const DEFAULT_SESSION_TIMEOUT = 15 * 60 * 1000; // 15 minutes
+export const DUPLICATE_EVENT_THRESHOLD_MS = 1000; // 1 second
+export const EVENT_SENT_INTERVAL_MS = 10000; // 10 seconds
+// Throttling and debouncing
+export const SCROLL_DEBOUNCE_TIME_MS = 250;
+export const DEFAULT_VISIBILITY_TIMEOUT_MS = 2000;
+// Event expiry
+export const EVENT_EXPIRY_HOURS = 24;
+export const EVENT_PERSISTENCE_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24 hours
+// ============================================================================
+// LIMITS & RETRIES
+// ============================================================================
+export const MAX_EVENTS_QUEUE_LENGTH = 500;
+export const MAX_RETRIES = 3;
+export const RETRY_DELAY_MS = 5000;
+export const REQUEST_TIMEOUT_MS = 10000;
+export const MAX_METADATA_SIZE = 5000;
+// Motion and interaction thresholds
+export const DEFAULT_MOTION_THRESHOLD = 2;
+export const SIGNIFICANT_SCROLL_DELTA = 10;
+export const MIN_SCROLL_DEPTH_CHANGE = 5;
+export const SCROLL_MIN_EVENT_INTERVAL_MS = 500;
+export const MAX_SCROLL_EVENTS_PER_SESSION = 120;
+// 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;
+// 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;
+// 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
+export const MAX_FINGERPRINTS_HARD_LIMIT = 2000; // Hard limit for aggressive cleanup
+// ============================================================================
+// BROWSER & HTML
+// ============================================================================
+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'];
+// ============================================================================
+// ============================================================================
+// INITIALIZATION
+// ============================================================================
+export const INITIALIZATION_MAX_CONCURRENT_RETRIES = 20;
+export const INITIALIZATION_CONCURRENT_RETRY_DELAY_MS = 50;
+export const INITIALIZATION_TIMEOUT_MS = 10000;
+// ============================================================================
+// SESSION MANAGEMENT
+// ============================================================================
+export const SESSION_SYNC_TIMEOUT_MS = 2000;
+export const SESSION_MAX_RETRY_ATTEMPTS = 3;
+export const SESSION_CLEANUP_DELAY_MS = 100;
+// Cross-tab coordination
+export const CROSS_TAB_INITIALIZATION_LOCK_TIMEOUT_MS = 5000;
+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
+// ============================================================================
+// SCROLL SUPPRESSION
+// ============================================================================
+export const SCROLL_SUPPRESS_MULTIPLIER = 2;
+// ============================================================================
+// 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
+export const MAX_RETRY_ATTEMPTS = 10;
+// ============================================================================
+// VALIDATION
+// ============================================================================
+// 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 greater than 0 and less than or equal to 1',
+    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',
+};
+// ============================================================================
+// SECURITY
+// ============================================================================
+// 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/error.constants.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Error handling and PII sanitization constants for TraceLog
+ * Centralizes patterns and limits for error tracking and data protection
+ */
+/**
+ * Regular expressions for detecting and sanitizing Personally Identifiable Information (PII)
+ * These patterns are used to replace sensitive information with [REDACTED] in error messages
+ */
+export declare const PII_PATTERNS: readonly [RegExp, RegExp, RegExp, RegExp];
+/**
+ * Maximum length for error messages before truncation
+ * Prevents extremely long error messages from consuming excessive storage
+ */
+export declare const MAX_ERROR_MESSAGE_LENGTH = 500;
+/**
+ * Time window for error suppression in milliseconds
+ * Prevents duplicate errors from flooding the system within this timeframe
+ */
+export declare const ERROR_SUPPRESSION_WINDOW_MS = 60000;
+/**
+ * Maximum number of unique errors to track for suppression
+ * Prevents memory usage from growing indefinitely
+ */
+export declare const MAX_TRACKED_ERRORS = 50;
+/**
+ * Default error sampling rate
+ * Controls what percentage of errors are actually reported
+ */
+export declare const DEFAULT_ERROR_SAMPLING_RATE = 0.1;

package/dist/esm/constants/error.constants.js

@@ -0,0 +1,47 @@
+/**
+ * Error handling and PII sanitization constants for TraceLog
+ * Centralizes patterns and limits for error tracking and data protection
+ */
+// ============================================================================
+// PII SANITIZATION PATTERNS
+// ============================================================================
+/**
+ * Regular expressions for detecting and sanitizing Personally Identifiable Information (PII)
+ * These patterns are used to replace sensitive information with [REDACTED] in error messages
+ */
+export const PII_PATTERNS = [
+    // Email addresses
+    /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/gi,
+    // US Phone numbers (various formats)
+    /\b\d{3}[-.]?\d{3}[-.]?\d{4}\b/g,
+    // Credit card numbers (16 digits with optional separators)
+    /\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/g,
+    // IBAN (International Bank Account Number)
+    /\b[A-Z]{2}\d{2}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/gi,
+];
+// ============================================================================
+// ERROR TRACKING LIMITS
+// ============================================================================
+/**
+ * Maximum length for error messages before truncation
+ * Prevents extremely long error messages from consuming excessive storage
+ */
+export const MAX_ERROR_MESSAGE_LENGTH = 500;
+/**
+ * Time window for error suppression in milliseconds
+ * Prevents duplicate errors from flooding the system within this timeframe
+ */
+export const ERROR_SUPPRESSION_WINDOW_MS = 60000; // 1 minute
+/**
+ * Maximum number of unique errors to track for suppression
+ * Prevents memory usage from growing indefinitely
+ */
+export const MAX_TRACKED_ERRORS = 50;
+// ============================================================================
+// ERROR SAMPLING
+// ============================================================================
+/**
+ * Default error sampling rate
+ * Controls what percentage of errors are actually reported
+ */
+export const DEFAULT_ERROR_SAMPLING_RATE = 0.1; // 10% of errors

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

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

package/dist/esm/constants/index.js

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

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

@@ -0,0 +1,28 @@
+/**
+ * Performance monitoring and web vitals constants for TraceLog
+ * Centralizes thresholds and configuration for performance tracking
+ */
+import { WebVitalType } from '../types';
+/**
+ * Web Vitals thresholds in milliseconds (except CLS which is unitless)
+ * These define the minimum values required to report a web vital metric
+ *
+ * Based on Core Web Vitals standards:
+ * - LCP (Largest Contentful Paint): 4000ms threshold
+ * - FCP (First Contentful Paint): 1800ms threshold
+ * - CLS (Cumulative Layout Shift): 0.25 threshold (unitless)
+ * - INP (Interaction to Next Paint): 200ms threshold
+ * - TTFB (Time to First Byte): 600ms threshold
+ * - LONG_TASK: 50ms threshold for long task detection
+ */
+export declare const WEB_VITALS_THRESHOLDS: Record<WebVitalType, number>;
+/**
+ * Long task throttling interval in milliseconds
+ * Prevents excessive long task events from being sent
+ */
+export declare const LONG_TASK_THROTTLE_MS = 1000;
+/**
+ * Precision for performance metric values
+ * All performance metrics are rounded to 2 decimal places
+ */
+export declare const PERFORMANCE_PRECISION_DECIMALS: 2;

package/dist/esm/constants/performance.constants.js

@@ -0,0 +1,40 @@
+/**
+ * Performance monitoring and web vitals constants for TraceLog
+ * Centralizes thresholds and configuration for performance tracking
+ */
+// ============================================================================
+// WEB VITALS THRESHOLDS
+// ============================================================================
+/**
+ * Web Vitals thresholds in milliseconds (except CLS which is unitless)
+ * These define the minimum values required to report a web vital metric
+ *
+ * Based on Core Web Vitals standards:
+ * - LCP (Largest Contentful Paint): 4000ms threshold
+ * - FCP (First Contentful Paint): 1800ms threshold
+ * - CLS (Cumulative Layout Shift): 0.25 threshold (unitless)
+ * - INP (Interaction to Next Paint): 200ms threshold
+ * - TTFB (Time to First Byte): 600ms threshold
+ * - LONG_TASK: 50ms threshold for long task detection
+ */
+export const WEB_VITALS_THRESHOLDS = {
+    LCP: 4000,
+    FCP: 1800,
+    CLS: 0.25,
+    INP: 200,
+    TTFB: 600,
+    LONG_TASK: 50,
+};
+// ============================================================================
+// PERFORMANCE MONITORING LIMITS
+// ============================================================================
+/**
+ * Long task throttling interval in milliseconds
+ * Prevents excessive long task events from being sent
+ */
+export const LONG_TASK_THROTTLE_MS = 1000;
+/**
+ * Precision for performance metric values
+ * All performance metrics are rounded to 2 decimal places
+ */
+export const PERFORMANCE_PRECISION_DECIMALS = 2;

package/dist/esm/handlers/click.handler.d.ts

@@ -8,6 +8,7 @@ export declare class ClickHandler extends StateManager {
     stopTracking(): void;
     private findTrackingElement;
     private getRelevantClickElement;
+    private clamp;
     private calculateClickCoordinates;
     private extractTrackingData;
     private generateClickData;

package/dist/esm/handlers/click.handler.js

@@ -9,10 +9,8 @@ export class ClickHandler extends StateManager {
     }
     startTracking() {
         if (this.clickHandler) {
-            debugLog.debug('ClickHandler', 'Click tracking already active');
             return;
         }
-        debugLog.debug('ClickHandler', 'Starting click tracking');
         this.clickHandler = (event) => {
             const mouseEvent = event;
             const target = mouseEvent.target;
@@ -25,11 +23,6 @@ export class ClickHandler extends StateManager {
                 debugLog.warn('ClickHandler', 'Click target not found or not an element');
                 return;
             }
-            debugLog.info('ClickHandler', '🖱️ Click detected on element', {
-                tagName: clickedElement.tagName,
-                className: clickedElement.className || 'none',
-                textContent: clickedElement.textContent?.slice(0, 50) ?? 'empty',
-            });
             const trackingElement = this.findTrackingElement(clickedElement);
             const relevantClickElement = this.getRelevantClickElement(clickedElement);
             const coordinates = this.calculateClickCoordinates(mouseEvent, clickedElement);
@@ -70,27 +63,18 @@ export class ClickHandler extends StateManager {
     getRelevantClickElement(element) {
         for (const selector of INTERACTIVE_SELECTORS) {
             try {
+                // First check if the element itself matches
                 if (element.matches(selector)) {
                     return element;
                 }
-            }
-            catch (error) {
-                debugLog.warn('ClickHandler', 'Invalid selector in interactive elements check', {
-                    selector,
-                    error: error instanceof Error ? error.message : 'Unknown error',
-                });
-                continue;
-            }
-        }
-        for (const selector of INTERACTIVE_SELECTORS) {
-            try {
+                // If not, search for matching ancestors
                 const parent = element.closest(selector);
                 if (parent) {
                     return parent;
                 }
             }
             catch (error) {
-                debugLog.warn('ClickHandler', 'Invalid selector in parent element search', {
+                debugLog.warn('ClickHandler', 'Invalid selector in element search', {
                     selector,
                     error: error instanceof Error ? error.message : 'Unknown error',
                 });
@@ -99,12 +83,15 @@ export class ClickHandler extends StateManager {
         }
         return element;
     }
+    clamp(value) {
+        return Math.max(0, Math.min(1, Number(value.toFixed(3))));
+    }
     calculateClickCoordinates(event, element) {
         const rect = element.getBoundingClientRect();
         const x = event.clientX;
         const y = event.clientY;
-        const relativeX = rect.width > 0 ? Math.max(0, Math.min(1, Number(((x - rect.left) / rect.width).toFixed(3)))) : 0;
-        const relativeY = rect.height > 0 ? Math.max(0, Math.min(1, Number(((y - rect.top) / rect.height).toFixed(3)))) : 0;
+        const relativeX = rect.width > 0 ? this.clamp((x - rect.left) / rect.width) : 0;
+        const relativeY = rect.height > 0 ? this.clamp((y - rect.top) / rect.height) : 0;
         return { x, y, relativeX, relativeY };
     }
     extractTrackingData(trackingElement) {
@@ -123,12 +110,6 @@ export class ClickHandler extends StateManager {
         const { x, y, relativeX, relativeY } = coordinates;
         const text = this.getRelevantText(clickedElement, relevantElement);
         const attributes = this.extractElementAttributes(relevantElement);
-        const href = relevantElement.getAttribute('href');
-        const title = relevantElement.getAttribute('title');
-        const alt = relevantElement.getAttribute('alt');
-        const role = relevantElement.getAttribute('role');
-        const ariaLabel = relevantElement.getAttribute('aria-label');
-        const className = typeof relevantElement.className === 'string' ? relevantElement.className : String(relevantElement.className);
         return {
             x,
             y,
@@ -136,47 +117,47 @@ export class ClickHandler extends StateManager {
             relativeY,
             tag: relevantElement.tagName.toLowerCase(),
             ...(relevantElement.id && { id: relevantElement.id }),
-            ...(relevantElement.className && { class: className }),
+            ...(relevantElement.className && { class: relevantElement.className }),
             ...(text && { text }),
-            ...(href && { href }),
-            ...(title && { title }),
-            ...(alt && { alt }),
-            ...(role && { role }),
-            ...(ariaLabel && { ariaLabel }),
+            ...(attributes.href && { href: attributes.href }),
+            ...(attributes.title && { title: attributes.title }),
+            ...(attributes.alt && { alt: attributes.alt }),
+            ...(attributes.role && { role: attributes.role }),
+            ...(attributes['aria-label'] && { ariaLabel: attributes['aria-label'] }),
             ...(Object.keys(attributes).length > 0 && { dataAttributes: attributes }),
         };
     }
     getRelevantText(clickedElement, relevantElement) {
-        const LARGE_CONTAINER_TAGS = ['main', 'section', 'article', 'body', 'html', 'header', 'footer', 'aside', 'nav'];
         const clickedText = clickedElement.textContent?.trim() ?? '';
         const relevantText = relevantElement.textContent?.trim() ?? '';
+        // No text available
         if (!clickedText && !relevantText) {
             return '';
         }
-        // Strategy 1: If clicked element has reasonable text, use it
+        // Prefer clicked element text if it's reasonable length
         if (clickedText && clickedText.length <= MAX_TEXT_LENGTH) {
             return clickedText;
         }
-        // Strategy 2: For large containers with excessive text, avoid using container text
-        const isLargeContainer = LARGE_CONTAINER_TAGS.includes(relevantElement.tagName.toLowerCase());
-        const hasExcessiveText = relevantText.length > MAX_TEXT_LENGTH * 2; // 510 chars
-        if (isLargeContainer && hasExcessiveText) {
-            // Use clicked element text if available and reasonable, otherwise empty
-            return clickedText && clickedText.length <= MAX_TEXT_LENGTH ? clickedText : '';
-        }
-        // Strategy 3: Use relevant text but truncate if needed
+        // Use relevant element text if it fits
         if (relevantText.length <= MAX_TEXT_LENGTH) {
             return relevantText;
         }
-        // Strategy 4: If clicked text is much shorter than relevant text, prefer clicked text
-        if (clickedText && clickedText.length < relevantText.length * 0.1) {
-            return clickedText.length <= MAX_TEXT_LENGTH ? clickedText : clickedText.slice(0, MAX_TEXT_LENGTH - 3) + '...';
-        }
-        // Fallback: truncate relevant text to exactly MAX_TEXT_LENGTH including ellipsis
+        // Truncate relevant text if too long
         return relevantText.slice(0, MAX_TEXT_LENGTH - 3) + '...';
     }
     extractElementAttributes(element) {
-        const commonAttributes = ['id', 'class', 'data-testid', 'aria-label', 'title', 'href', 'type', 'name'];
+        const commonAttributes = [
+            'id',
+            'class',
+            'data-testid',
+            'aria-label',
+            'title',
+            'href',
+            'type',
+            'name',
+            'alt',
+            'role',
+        ];
         const result = {};
         for (const attributeName of commonAttributes) {
             const value = element.getAttribute(attributeName);

package/dist/esm/handlers/error.handler.d.ts

@@ -1,15 +1,20 @@
 import { EventManager } from '../managers/event.manager';
 import { StateManager } from '../managers/state.manager';
+/**
+ * Simplified error handler for tracking JavaScript errors and unhandled promise rejections
+ * Includes PII sanitization and sampling support
+ */
 export declare class ErrorHandler extends StateManager {
     private readonly eventManager;
-    private readonly piiPatterns;
+    private readonly recentErrors;
     constructor(eventManager: EventManager);
     startTracking(): void;
     stopTracking(): void;
-    private setupErrorListener;
-    private setupUnhandledRejectionListener;
-    private readonly handleError;
-    private readonly handleUnhandledRejection;
-    private sanitizeText;
     private shouldSample;
+    private readonly handleError;
+    private readonly handleRejection;
+    private extractRejectionMessage;
+    private sanitize;
+    private shouldSuppressError;
+    private pruneOldErrors;
 }