@tracelog/lib 0.4.0 → 0.5.0

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

@@ -3,13 +3,13 @@
  * 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 DUPLICATE_EVENT_THRESHOLD_MS = 500;
 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_EVENTS_QUEUE_LENGTH = 100;
 export declare const MAX_RETRIES = 3;
 export declare const RETRY_DELAY_MS = 5000;
 export declare const REQUEST_TIMEOUT_MS = 10000;
@@ -65,7 +65,7 @@ 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_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";

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

@@ -6,7 +6,7 @@
 // SESSION & TIMING
 // ============================================================================
 export const DEFAULT_SESSION_TIMEOUT = 15 * 60 * 1000; // 15 minutes
-export const DUPLICATE_EVENT_THRESHOLD_MS = 1000; // 1 second
+export const DUPLICATE_EVENT_THRESHOLD_MS = 500; // 500ms
 export const EVENT_SENT_INTERVAL_MS = 10000; // 10 seconds
 // Throttling and debouncing
 export const SCROLL_DEBOUNCE_TIME_MS = 250;
@@ -17,7 +17,7 @@ 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_EVENTS_QUEUE_LENGTH = 100;
 export const MAX_RETRIES = 3;
 export const RETRY_DELAY_MS = 5000;
 export const REQUEST_TIMEOUT_MS = 10000;
@@ -149,7 +149,7 @@ export const VALIDATION_MESSAGES = {
     // 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_SAMPLING_RATE: 'Sampling rate must be between 0 and 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',

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

@@ -6,7 +6,7 @@
  * 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];
+export declare const PII_PATTERNS: readonly [RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp];
 /**
  * Maximum length for error messages before truncation
  * Prevents extremely long error messages from consuming excessive storage
@@ -16,12 +16,17 @@ 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;
+export declare const ERROR_SUPPRESSION_WINDOW_MS = 5000;
 /**
  * Maximum number of unique errors to track for suppression
  * Prevents memory usage from growing indefinitely
  */
 export declare const MAX_TRACKED_ERRORS = 50;
+/**
+ * Hard limit for error tracking before aggressive cleanup
+ * If this limit is exceeded, the entire error map is cleared
+ */
+export declare const MAX_TRACKED_ERRORS_HARD_LIMIT: number;
 /**
  * Default error sampling rate
  * Controls what percentage of errors are actually reported

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

@@ -18,6 +18,12 @@ export const PII_PATTERNS = [
     /\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,
+    // API keys/tokens (sk_test_, sk_live_, pk_test_, pk_live_, etc.)
+    /\b[sp]k_(test|live)_[a-zA-Z0-9]{10,}\b/gi,
+    // Bearer tokens (JWT-like patterns - matches complete and partial tokens)
+    /Bearer\s+[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)?(?:\.[A-Za-z0-9_-]+)?/gi,
+    // Passwords in connection strings (protocol://user:password@host)
+    /:\/\/[^:/]+:([^@]+)@/gi,
 ];
 // ============================================================================
 // ERROR TRACKING LIMITS
@@ -31,12 +37,17 @@ 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
+export const ERROR_SUPPRESSION_WINDOW_MS = 5000; // 5 seconds
 /**
  * Maximum number of unique errors to track for suppression
  * Prevents memory usage from growing indefinitely
  */
 export const MAX_TRACKED_ERRORS = 50;
+/**
+ * Hard limit for error tracking before aggressive cleanup
+ * If this limit is exceeded, the entire error map is cleared
+ */
+export const MAX_TRACKED_ERRORS_HARD_LIMIT = MAX_TRACKED_ERRORS * 2;
 // ============================================================================
 // ERROR SAMPLING
 // ============================================================================

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

@@ -63,11 +63,9 @@ 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;
                 }
-                // If not, search for matching ancestors
                 const parent = element.closest(selector);
                 if (parent) {
                     return parent;
@@ -130,19 +128,15 @@ export class ClickHandler extends StateManager {
     getRelevantText(clickedElement, relevantElement) {
         const clickedText = clickedElement.textContent?.trim() ?? '';
         const relevantText = relevantElement.textContent?.trim() ?? '';
-        // No text available
         if (!clickedText && !relevantText) {
             return '';
         }
-        // Prefer clicked element text if it's reasonable length
         if (clickedText && clickedText.length <= MAX_TEXT_LENGTH) {
             return clickedText;
         }
-        // Use relevant element text if it fits
         if (relevantText.length <= MAX_TEXT_LENGTH) {
             return relevantText;
         }
-        // Truncate relevant text if too long
         return relevantText.slice(0, MAX_TEXT_LENGTH - 3) + '...';
     }
     extractElementAttributes(element) {

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

@@ -1,6 +1,6 @@
 import { StateManager } from '../managers/state.manager';
 import { ErrorType, EventType } from '../types';
-import { PII_PATTERNS, MAX_ERROR_MESSAGE_LENGTH, ERROR_SUPPRESSION_WINDOW_MS, MAX_TRACKED_ERRORS, } from '../constants/error.constants';
+import { PII_PATTERNS, MAX_ERROR_MESSAGE_LENGTH, ERROR_SUPPRESSION_WINDOW_MS, MAX_TRACKED_ERRORS, MAX_TRACKED_ERRORS_HARD_LIMIT, } from '../constants/error.constants';
 import { debugLog } from '../utils/logging';
 /**
  * Simplified error handler for tracking JavaScript errors and unhandled promise rejections
@@ -106,6 +106,15 @@ export class ErrorHandler extends StateManager {
             return true;
         }
         this.recentErrors.set(key, now);
+        if (this.recentErrors.size > MAX_TRACKED_ERRORS_HARD_LIMIT) {
+            debugLog.warn('ErrorHandler', 'Hard limit exceeded, clearing all tracked errors', {
+                size: this.recentErrors.size,
+                limit: MAX_TRACKED_ERRORS_HARD_LIMIT,
+            });
+            this.recentErrors.clear();
+            this.recentErrors.set(key, now);
+            return false;
+        }
         if (this.recentErrors.size > MAX_TRACKED_ERRORS) {
             this.pruneOldErrors();
         }

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

@@ -61,7 +61,6 @@ export class ScrollHandler extends StateManager {
         }
     }
     setupScrollContainer(element) {
-        // Skip setup for non-scrollable elements
         if (element !== window && !this.isElementScrollable(element)) {
             return;
         }
@@ -173,12 +172,10 @@ export class ScrollHandler extends StateManager {
     calculateScrollData(container) {
         const { element, lastScrollPos } = container;
         const scrollTop = this.getScrollTop(element);
-        // Early return: check significant movement first (cheapest check)
         const positionDelta = Math.abs(scrollTop - lastScrollPos);
         if (positionDelta < SIGNIFICANT_SCROLL_DELTA) {
             return null;
         }
-        // Early return: check if window is scrollable
         if (element === window && !this.isWindowScrollable()) {
             return null;
         }
@@ -206,7 +203,6 @@ export class ScrollHandler extends StateManager {
             style.overflowX === 'scroll' ||
             style.overflow === 'auto' ||
             style.overflow === 'scroll';
-        // Element must have scrollable overflow AND content that exceeds the container
         const hasOverflowContent = element.scrollHeight > element.clientHeight || element.scrollWidth > element.clientWidth;
         return hasScrollableOverflow && hasOverflowContent;
     }
@@ -215,7 +211,6 @@ export class ScrollHandler extends StateManager {
             return document.querySelector(selector);
         }
         catch (error) {
-            // Invalid CSS selector - log warning and continue
             debugLog.clientWarn('ScrollHandler', 'Invalid CSS selector', {
                 selector,
                 error: error instanceof Error ? error.message : 'Unknown error',

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

@@ -17,12 +17,15 @@ export class SessionHandler extends StateManager {
             debugLog.warn('SessionHandler', 'Cannot start tracking on destroyed handler');
             return;
         }
+        const projectId = this.get('config')?.id;
+        if (!projectId) {
+            throw new Error('Cannot start session tracking: config not available');
+        }
         try {
-            this.sessionManager = new SessionManager(this.storageManager, this.eventManager);
+            this.sessionManager = new SessionManager(this.storageManager, this.eventManager, projectId);
             await this.sessionManager.startTracking();
         }
         catch (error) {
-            // Cleanup on failure
             if (this.sessionManager) {
                 try {
                     this.sessionManager.destroy();

package/dist/esm/integrations/google-analytics.integration.d.ts

@@ -9,7 +9,7 @@ declare global {
 export declare class GoogleAnalyticsIntegration extends StateManager {
     private isInitialized;
     initialize(): Promise<void>;
-    trackEvent(eventName: string, metadata: Record<string, MetadataType>): void;
+    trackEvent(eventName: string, metadata: Record<string, MetadataType> | Record<string, MetadataType>[]): void;
     cleanup(): void;
     private isScriptAlreadyLoaded;
     private loadScript;

package/dist/esm/integrations/google-analytics.integration.js

@@ -34,7 +34,8 @@ export class GoogleAnalyticsIntegration extends StateManager {
             return;
         }
         try {
-            window.gtag('event', eventName, metadata);
+            const normalizedMetadata = Array.isArray(metadata) ? { items: metadata } : metadata;
+            window.gtag('event', eventName, normalizedMetadata);
         }
         catch (error) {
             debugLog.error('GoogleAnalyticsIntegration', 'Event tracking failed', {

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

@@ -2,7 +2,7 @@
  * Generates API URL for TraceLog service based on project ID
  *
  * Handles two special cases:
- * - 'localhost:PORT' - for local development (generates http://localhost:PORT)
+ * - 'localhost:8080' or 'localhost:9999' - for local development (generates http://localhost:PORT)
  * - Regular project IDs - generates subdomain URLs via getApiUrl utility
  *
  * @param id Project ID or localhost address

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

@@ -5,7 +5,7 @@ import { debugLog } from '../utils/logging';
  * Generates API URL for TraceLog service based on project ID
  *
  * Handles two special cases:
- * - 'localhost:PORT' - for local development (generates http://localhost:PORT)
+ * - 'localhost:8080' or 'localhost:9999' - for local development (generates http://localhost:PORT)
  * - Regular project IDs - generates subdomain URLs via getApiUrl utility
  *
  * @param id Project ID or localhost address
@@ -15,8 +15,8 @@ import { debugLog } from '../utils/logging';
  */
 export function getApiUrlForProject(id, allowHttp = false) {
     try {
-        // Handle localhost development case
-        if (id.startsWith(SpecialProjectId.Localhost)) {
+        // Handle localhost development case (localhost:8080 or localhost:9999)
+        if (id === SpecialProjectId.Localhost || id === SpecialProjectId.Fail) {
             const url = `http://${id}`;
             if (!isValidUrl(url, true)) {
                 throw new Error(`Invalid localhost URL format: ${id}`);

package/dist/esm/managers/config.builder.d.ts

@@ -0,0 +1,33 @@
+import { AppConfig, ApiConfig, Config } from '../types';
+/**
+ * Centralized configuration builder
+ * Single source of truth for merging and building final configuration
+ */
+export declare class ConfigBuilder {
+    /**
+     * Builds final configuration from app config and API config
+     * Applies clear precedence: API overrides client, with defaults as fallback
+     */
+    static build(appConfig: AppConfig, apiConfig?: ApiConfig): Config;
+    /**
+     * Resolves session timeout with validation
+     * Returns default if undefined or out of valid range
+     */
+    private static resolveSessionTimeout;
+    /**
+     * Resolves sampling rate with validation
+     * Priority: API config > app config > default
+     */
+    private static resolveSamplingRate;
+    /**
+     * Resolves error sampling rate based on mode
+     * In debug/qa modes: uses provided value or defaults to full sampling (1.0)
+     * In production: uses provided value or defaults to 10% sampling (0.1)
+     */
+    private static resolveErrorSampling;
+    /**
+     * Resolves mode with special project ID handling
+     * Priority: Special project ID > API mode > app mode
+     */
+    private static resolveMode;
+}

package/dist/esm/managers/config.builder.js

@@ -0,0 +1,112 @@
+import { DEFAULT_SESSION_TIMEOUT, DEFAULT_SAMPLING_RATE, MIN_SAMPLING_RATE, MAX_SAMPLING_RATE, MIN_SESSION_TIMEOUT_MS, MAX_SESSION_TIMEOUT_MS, } from '../constants/config.constants';
+import { Mode, SpecialProjectId } from '../types';
+import { debugLog } from '../utils/logging';
+/**
+ * Centralized configuration builder
+ * Single source of truth for merging and building final configuration
+ */
+export class ConfigBuilder {
+    /**
+     * Builds final configuration from app config and API config
+     * Applies clear precedence: API overrides client, with defaults as fallback
+     */
+    static build(appConfig, apiConfig = {}) {
+        // Resolve mode first as it affects other settings (like errorSampling)
+        const finalMode = this.resolveMode(appConfig, apiConfig.mode);
+        const config = {
+            // Core identifiers
+            id: appConfig.id,
+            // Session configuration
+            sessionTimeout: this.resolveSessionTimeout(appConfig.sessionTimeout),
+            // Mode configuration (resolved first)
+            mode: finalMode,
+            // Sampling configuration (depends on mode)
+            samplingRate: this.resolveSamplingRate(apiConfig.samplingRate, appConfig.samplingRate),
+            errorSampling: this.resolveErrorSampling(appConfig.errorSampling, finalMode),
+            // Filtering configuration
+            excludedUrlPaths: apiConfig.excludedUrlPaths ?? appConfig.excludedUrlPaths ?? [],
+            tags: apiConfig.tags ?? [],
+            ipExcluded: apiConfig.ipExcluded ?? false,
+            // Client-only configuration
+            globalMetadata: appConfig.globalMetadata ?? {},
+            scrollContainerSelectors: appConfig.scrollContainerSelectors,
+            sensitiveQueryParams: appConfig.sensitiveQueryParams ?? [],
+            integrations: appConfig.integrations,
+            // Security configuration
+            allowHttp: appConfig.allowHttp ?? false,
+        };
+        debugLog.debug('ConfigBuilder', 'Configuration built', {
+            projectId: config.id,
+            mode: config.mode,
+            samplingRate: config.samplingRate,
+            errorSampling: config.errorSampling,
+            hasTags: !!config.tags?.length,
+            hasExclusions: !!config.excludedUrlPaths?.length,
+        });
+        return config;
+    }
+    /**
+     * Resolves session timeout with validation
+     * Returns default if undefined or out of valid range
+     */
+    static resolveSessionTimeout(timeout) {
+        if (timeout === undefined) {
+            return DEFAULT_SESSION_TIMEOUT;
+        }
+        if (timeout < MIN_SESSION_TIMEOUT_MS || timeout > MAX_SESSION_TIMEOUT_MS) {
+            debugLog.warn('ConfigBuilder', 'Invalid session timeout, using default', {
+                provided: timeout,
+                min: MIN_SESSION_TIMEOUT_MS,
+                max: MAX_SESSION_TIMEOUT_MS,
+                default: DEFAULT_SESSION_TIMEOUT,
+            });
+            return DEFAULT_SESSION_TIMEOUT;
+        }
+        return timeout;
+    }
+    /**
+     * Resolves sampling rate with validation
+     * Priority: API config > app config > default
+     */
+    static resolveSamplingRate(apiRate, appRate) {
+        const rate = apiRate ?? appRate;
+        if (rate === undefined) {
+            return DEFAULT_SAMPLING_RATE;
+        }
+        if (rate < MIN_SAMPLING_RATE || rate > MAX_SAMPLING_RATE) {
+            debugLog.warn('ConfigBuilder', 'Invalid sampling rate, using default', {
+                provided: rate,
+                default: DEFAULT_SAMPLING_RATE,
+            });
+            return DEFAULT_SAMPLING_RATE;
+        }
+        return rate;
+    }
+    /**
+     * Resolves error sampling rate based on mode
+     * In debug/qa modes: uses provided value or defaults to full sampling (1.0)
+     * In production: uses provided value or defaults to 10% sampling (0.1)
+     */
+    static resolveErrorSampling(appErrorSampling, apiMode) {
+        const isDebugMode = apiMode === Mode.DEBUG || apiMode === Mode.QA;
+        if (isDebugMode) {
+            // In debug mode, respect explicit value or default to full sampling
+            return appErrorSampling ?? 1;
+        }
+        return appErrorSampling ?? 0.1; // Default to 10% sampling in production
+    }
+    /**
+     * Resolves mode with special project ID handling
+     * Priority: Special project ID > API mode > app mode
+     */
+    static resolveMode(appConfig, apiMode) {
+        // Force DEBUG mode for special project IDs
+        if (appConfig.id === SpecialProjectId.Skip ||
+            appConfig.id === SpecialProjectId.Fail ||
+            appConfig.id.toLowerCase().startsWith('skip-')) {
+            return Mode.DEBUG;
+        }
+        // API mode takes precedence over app mode
+        return apiMode ?? appConfig.mode;
+    }
+}

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

@@ -2,20 +2,20 @@ import { AppConfig, Config } from '../types';
 /**
  * Configuration manager responsible for loading and merging application configuration.
  *
- * Handles three configuration sources:
- * 1. Default configuration (fallback values)
- * 2. API configuration (server-side settings)
- * 3. App configuration (client initialization settings)
+ * Handles configuration from two sources:
+ * 1. API configuration (server-side settings)
+ * 2. App configuration (client initialization settings)
+ *
+ * Uses ConfigBuilder for centralized merge logic.
  *
  * Supports special project IDs for development and testing:
  * - 'skip': Bypasses all network calls, uses defaults
- * - 'localhost:PORT': Loads config from local development server
+ * - 'localhost:8080': Loads config from local development server
  */
 export declare class ConfigManager {
-    private static readonly LOCALHOST_PATTERN;
     private static readonly PRODUCTION_DOMAINS;
     /**
-     * Gets complete configuration by merging default, API, and app configurations.
+     * Gets complete configuration by loading API config and building final config.
      *
      * @param apiUrl - Base URL for the configuration API
      * @param appConfig - Client-side configuration from init()
@@ -23,7 +23,8 @@ export declare class ConfigManager {
      */
     get(apiUrl: string, appConfig: AppConfig): Promise<Config>;
     /**
-     * Loads configuration from API and merges with app config.
+     * Loads configuration from API and returns sanitized API config.
+     * Only returns values explicitly provided by the API.
      */
     private loadFromApi;
     /**
@@ -32,26 +33,24 @@ export declare class ConfigManager {
     private buildConfigUrl;
     /**
      * Builds request headers based on project configuration.
+     * Always includes X-TraceLog-Project header for consistent identification.
      */
     private buildHeaders;
     /**
      * Parses and validates JSON response from config API.
      */
     private parseJsonResponse;
-    /**
-     * Validates localhost project ID format and port range.
-     */
-    private validateLocalhostProjectId;
     /**
      * Checks if QA mode is enabled via URL parameter.
      */
     private isQaModeEnabled;
     /**
-     * Merges API configuration with app configuration and applies mode-specific settings.
+     * Applies QA mode to API config if enabled via URL parameter.
      */
-    private mergeConfigurations;
+    private applyQaModeIfEnabled;
     /**
      * Creates default configuration for skip mode and fallback scenarios.
+     * Only uses API defaults for fields not provided by the app config.
      */
     private createDefaultConfig;
 }