@tracelog/lib 0.4.0 → 0.5.0

package/dist/cjs/api.d.ts

@@ -1,60 +1,8 @@
 import { MetadataType, AppConfig, EmitterCallback, EmitterMap } from './types';
 import './types/window.types';
-/**
- * Initializes the tracelog app with the provided configuration.
- * If already initialized, this function returns early without error.
- * @param appConfig - The configuration object for the app
- * @throws {Error} If initialization fails or environment is invalid
- * @example
- * await tracelog.init({ id: 'my-project-id' });
- */
 export declare const init: (appConfig: AppConfig) => Promise<void>;
-/**
- * Sends a custom event with the specified name and metadata.
- * @param name - The name of the custom event.
- * @param metadata - Optional metadata to attach to the event.
- * @example
- * // Send a custom event with metadata
- * tracelog.event('user_signup', { method: 'email', plan: 'premium' });
- * @example
- * // Send a custom event without metadata
- * tracelog.event('user_login');
- * @remarks
- * This function should be called after the app has been initialized using the `tracelog.init` function.
- */
-export declare const event: (name: string, metadata?: Record<string, MetadataType>) => void;
-/**
- * Subscribe to events emitted by TraceLog
- * @param event - Event name to listen to
- * @param callback - Function to call when event is emitted
- * @example
- * // Listen for tracked events
- * tracelog.on('event', (data) => {
- *   console.log('Event tracked:', data.type);
- * });
- *
- * // Listen for event queues being sent
- * tracelog.on('queue', (data) => {
- *   console.log('Events sent:', data.events.length);
- * });
- */
+export declare const event: (name: string, metadata?: Record<string, MetadataType> | Record<string, MetadataType>[]) => void;
 export declare const on: <K extends keyof EmitterMap>(event: K, callback: EmitterCallback<EmitterMap[K]>) => void;
-/**
- * Unsubscribe from events emitted by TraceLog
- * @param event - Event name to stop listening to
- * @param callback - The same function reference that was used in on()
- * @example
- * // Remove a specific listener
- * tracelog.off('event', myCallback);
- */
 export declare const off: <K extends keyof EmitterMap>(event: K, callback: EmitterCallback<EmitterMap[K]>) => void;
-/**
- * Checks if the app has been initialized.
- * @returns true if the app is initialized, false otherwise
- */
 export declare const isInitialized: () => boolean;
-/**
- * Destroys the current app instance and cleans up resources.
- * @throws {Error} If not initialized or already destroying
- */
 export declare const destroy: () => Promise<void>;

package/dist/cjs/api.js

@@ -8,29 +8,17 @@ require("./types/window.types");
 let app = null;
 let isInitializing = false;
 let isDestroying = false;
-/**
- * Initializes the tracelog app with the provided configuration.
- * If already initialized, this function returns early without error.
- * @param appConfig - The configuration object for the app
- * @throws {Error} If initialization fails or environment is invalid
- * @example
- * await tracelog.init({ id: 'my-project-id' });
- */
 const init = async (appConfig) => {
-    // Browser environment check
     if (typeof window === 'undefined' || typeof document === 'undefined') {
         throw new Error('This library can only be used in a browser environment');
     }
-    // Check if TraceLog is disabled
     if (window.__traceLogDisabled) {
         return;
     }
-    // Already initialized - safe to return
     if (app) {
         utils_1.debugLog.debug('API', 'Library already initialized, skipping duplicate initialization');
         return;
     }
-    // Prevent concurrent initialization
     if (isInitializing) {
         utils_1.debugLog.warn('API', 'Initialization already in progress');
         throw new Error('Initialization already in progress');
@@ -65,19 +53,6 @@ const init = async (appConfig) => {
     }
 };
 exports.init = init;
-/**
- * Sends a custom event with the specified name and metadata.
- * @param name - The name of the custom event.
- * @param metadata - Optional metadata to attach to the event.
- * @example
- * // Send a custom event with metadata
- * tracelog.event('user_signup', { method: 'email', plan: 'premium' });
- * @example
- * // Send a custom event without metadata
- * tracelog.event('user_login');
- * @remarks
- * This function should be called after the app has been initialized using the `tracelog.init` function.
- */
 const event = (name, metadata) => {
     if (!app) {
         throw new Error('TraceLog not initialized. Please call init() first.');
@@ -91,21 +66,6 @@ const event = (name, metadata) => {
     }
 };
 exports.event = event;
-/**
- * Subscribe to events emitted by TraceLog
- * @param event - Event name to listen to
- * @param callback - Function to call when event is emitted
- * @example
- * // Listen for tracked events
- * tracelog.on('event', (data) => {
- *   console.log('Event tracked:', data.type);
- * });
- *
- * // Listen for event queues being sent
- * tracelog.on('queue', (data) => {
- *   console.log('Events sent:', data.events.length);
- * });
- */
 const on = (event, callback) => {
     if (!app) {
         throw new Error('TraceLog not initialized. Please call init() first.');
@@ -113,14 +73,6 @@ const on = (event, callback) => {
     app.on(event, callback);
 };
 exports.on = on;
-/**
- * Unsubscribe from events emitted by TraceLog
- * @param event - Event name to stop listening to
- * @param callback - The same function reference that was used in on()
- * @example
- * // Remove a specific listener
- * tracelog.off('event', myCallback);
- */
 const off = (event, callback) => {
     if (!app) {
         throw new Error('TraceLog not initialized. Please call init() first.');
@@ -128,24 +80,14 @@ const off = (event, callback) => {
     app.off(event, callback);
 };
 exports.off = off;
-/**
- * Checks if the app has been initialized.
- * @returns true if the app is initialized, false otherwise
- */
 const isInitialized = () => {
     return app !== null;
 };
 exports.isInitialized = isInitialized;
-/**
- * Destroys the current app instance and cleans up resources.
- * @throws {Error} If not initialized or already destroying
- */
 const destroy = async () => {
-    // Check if app was never initialized
     if (!app) {
         throw new Error('App not initialized');
     }
-    // Prevent concurrent destroy operations
     if (isDestroying) {
         throw new Error('Destroy operation already in progress');
     }
@@ -169,7 +111,6 @@ const destroy = async () => {
     }
 };
 exports.destroy = destroy;
-// Auto-inject testing bridge in development environments
 if (process.env.NODE_ENV === 'dev' && typeof window !== 'undefined') {
     const injectTestingBridge = () => {
         window.__traceLogBridge = new test_bridge_1.TestBridge(isInitializing, isDestroying);

package/dist/cjs/app.constants.d.ts

@@ -2,7 +2,7 @@ export declare const PERFORMANCE_CONFIG: {
     readonly WEB_VITALS_THRESHOLDS: Record<import("./types").WebVitalType, number>;
 };
 export declare const DATA_PROTECTION: {
-    readonly PII_PATTERNS: readonly [RegExp, RegExp, RegExp, RegExp];
+    readonly PII_PATTERNS: readonly [RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp];
 };
 export declare const ENGAGEMENT_THRESHOLDS: {
     readonly LOW_ACTIVITY_EVENT_COUNT: 50;

package/dist/cjs/app.d.ts

@@ -9,10 +9,6 @@ import { GoogleAnalyticsIntegration } from './integrations/google-analytics.inte
 import { StorageManager } from './managers/storage.manager';
 import { PerformanceHandler } from './handlers/performance.handler';
 import { ErrorHandler } from './handlers/error.handler';
-/**
- * Main application class for TraceLog analytics
- * Orchestrates event tracking, session management, and integrations
- */
 export declare class App extends StateManager {
     private isInitialized;
     private suppressNextScrollTimer;
@@ -34,7 +30,7 @@ export declare class App extends StateManager {
     };
     get initialized(): boolean;
     init(appConfig: AppConfig): Promise<void>;
-    sendCustomEvent(name: string, metadata?: Record<string, unknown>): void;
+    sendCustomEvent(name: string, metadata?: Record<string, unknown> | Record<string, unknown>[]): void;
     on<K extends keyof EmitterMap>(event: K, callback: EmitterCallback<EmitterMap[K]>): void;
     off<K extends keyof EmitterMap>(event: K, callback: EmitterCallback<EmitterMap[K]>): void;
     destroy(force?: boolean): Promise<void>;

package/dist/cjs/app.js

@@ -17,10 +17,6 @@ const storage_manager_1 = require("./managers/storage.manager");
 const config_constants_1 = require("./constants/config.constants");
 const performance_handler_1 = require("./handlers/performance.handler");
 const error_handler_1 = require("./handlers/error.handler");
-/**
- * Main application class for TraceLog analytics
- * Orchestrates event tracking, session management, and integrations
- */
 class App extends state_manager_1.StateManager {
     constructor() {
         super(...arguments);
@@ -103,6 +99,7 @@ class App extends state_manager_1.StateManager {
             clearTimeout(this.suppressNextScrollTimer);
             this.suppressNextScrollTimer = null;
         }
+        this.managers.event?.flushImmediatelySync();
         this.managers.event?.stop();
         this.emitter.removeAllListeners();
         this.set('hasStartSession', false);
@@ -112,20 +109,15 @@ class App extends state_manager_1.StateManager {
         this.handlers = {};
     }
     async setupState(appConfig) {
-        // Set API URL
         const apiUrl = (0, api_manager_1.getApiUrlForProject)(appConfig.id, appConfig.allowHttp);
         this.set('apiUrl', apiUrl);
-        // Get remote configuration
         const configManager = new config_manager_1.ConfigManager();
         const config = await configManager.get(apiUrl, appConfig);
-        const { config: normalizedConfig } = (0, utils_1.normalizeConfig)(config);
-        this.set('config', normalizedConfig);
-        // Set user ID
-        const userId = user_manager_1.UserManager.getId(this.managers.storage, normalizedConfig.id);
+        this.set('config', config);
+        const userId = user_manager_1.UserManager.getId(this.managers.storage, config.id);
         this.set('userId', userId);
-        // Set device and page info
         this.set('device', (0, utils_1.getDeviceType)());
-        const pageUrl = (0, utils_1.normalizeUrl)(window.location.href, normalizedConfig.sensitiveQueryParams);
+        const pageUrl = (0, utils_1.normalizeUrl)(window.location.href, config.sensitiveQueryParams);
         this.set('pageUrl', pageUrl);
     }
     async setupIntegrations() {

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

@@ -1,3 +1,6 @@
-import { ApiConfig, Config } from '../types';
+import { ApiConfig } from '../types';
+/**
+ * Default API configuration values
+ * Used as fallback when API config is not available or incomplete
+ */
 export declare const DEFAULT_API_CONFIG: ApiConfig;
-export declare const DEFAULT_CONFIG: (config: Config) => Config;

package/dist/cjs/constants/api.constants.js

@@ -1,23 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_CONFIG = exports.DEFAULT_API_CONFIG = void 0;
+exports.DEFAULT_API_CONFIG = void 0;
 const config_constants_1 = require("./config.constants");
+/**
+ * Default API configuration values
+ * Used as fallback when API config is not available or incomplete
+ */
 exports.DEFAULT_API_CONFIG = {
     samplingRate: config_constants_1.DEFAULT_SAMPLING_RATE,
     excludedUrlPaths: [],
     tags: [],
     ipExcluded: false,
 };
-const DEFAULT_CONFIG = (config) => ({
-    ...exports.DEFAULT_API_CONFIG,
-    ...config,
-    allowHttp: false,
-    sessionTimeout: config_constants_1.DEFAULT_SESSION_TIMEOUT,
-    samplingRate: config.samplingRate && config.samplingRate > config_constants_1.MIN_SAMPLING_RATE && config.samplingRate <= config_constants_1.MAX_SAMPLING_RATE
-        ? config.samplingRate
-        : config_constants_1.DEFAULT_SAMPLING_RATE,
-    excludedUrlPaths: config.excludedUrlPaths ?? [],
-    tags: config.tags ?? [],
-    ipExcluded: config.ipExcluded ?? false,
-});
-exports.DEFAULT_CONFIG = DEFAULT_CONFIG;

package/dist/cjs/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/cjs/constants/config.constants.js

@@ -10,7 +10,7 @@ exports.XSS_PATTERNS = exports.VALIDATION_MESSAGES = exports.ALLOWED_API_CONFIG_
 // SESSION & TIMING
 // ============================================================================
 exports.DEFAULT_SESSION_TIMEOUT = 15 * 60 * 1000; // 15 minutes
-exports.DUPLICATE_EVENT_THRESHOLD_MS = 1000; // 1 second
+exports.DUPLICATE_EVENT_THRESHOLD_MS = 500; // 500ms
 exports.EVENT_SENT_INTERVAL_MS = 10000; // 10 seconds
 // Throttling and debouncing
 exports.SCROLL_DEBOUNCE_TIME_MS = 250;
@@ -21,7 +21,7 @@ exports.EVENT_PERSISTENCE_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24 hours
 // ============================================================================
 // LIMITS & RETRIES
 // ============================================================================
-exports.MAX_EVENTS_QUEUE_LENGTH = 500;
+exports.MAX_EVENTS_QUEUE_LENGTH = 100;
 exports.MAX_RETRIES = 3;
 exports.RETRY_DELAY_MS = 5000;
 exports.REQUEST_TIMEOUT_MS = 10000;
@@ -153,7 +153,7 @@ exports.VALIDATION_MESSAGES = {
     // Session timeout validation
     INVALID_SESSION_TIMEOUT: `Session timeout must be between ${exports.MIN_SESSION_TIMEOUT_MS}ms (30 seconds) and ${exports.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/cjs/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/cjs/constants/error.constants.js

@@ -4,7 +4,7 @@
  * Centralizes patterns and limits for error tracking and data protection
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_ERROR_SAMPLING_RATE = exports.MAX_TRACKED_ERRORS = exports.ERROR_SUPPRESSION_WINDOW_MS = exports.MAX_ERROR_MESSAGE_LENGTH = exports.PII_PATTERNS = void 0;
+exports.DEFAULT_ERROR_SAMPLING_RATE = exports.MAX_TRACKED_ERRORS_HARD_LIMIT = exports.MAX_TRACKED_ERRORS = exports.ERROR_SUPPRESSION_WINDOW_MS = exports.MAX_ERROR_MESSAGE_LENGTH = exports.PII_PATTERNS = void 0;
 // ============================================================================
 // PII SANITIZATION PATTERNS
 // ============================================================================
@@ -21,6 +21,12 @@ exports.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
@@ -34,12 +40,17 @@ exports.MAX_ERROR_MESSAGE_LENGTH = 500;
  * Time window for error suppression in milliseconds
  * Prevents duplicate errors from flooding the system within this timeframe
  */
-exports.ERROR_SUPPRESSION_WINDOW_MS = 60000; // 1 minute
+exports.ERROR_SUPPRESSION_WINDOW_MS = 5000; // 5 seconds
 /**
  * Maximum number of unique errors to track for suppression
  * Prevents memory usage from growing indefinitely
  */
 exports.MAX_TRACKED_ERRORS = 50;
+/**
+ * Hard limit for error tracking before aggressive cleanup
+ * If this limit is exceeded, the entire error map is cleared
+ */
+exports.MAX_TRACKED_ERRORS_HARD_LIMIT = exports.MAX_TRACKED_ERRORS * 2;
 // ============================================================================
 // ERROR SAMPLING
 // ============================================================================

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

@@ -66,11 +66,9 @@ class ClickHandler extends state_manager_1.StateManager {
     getRelevantClickElement(element) {
         for (const selector of constants_1.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;
@@ -133,19 +131,15 @@ class ClickHandler extends state_manager_1.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 <= constants_1.MAX_TEXT_LENGTH) {
             return clickedText;
         }
-        // Use relevant element text if it fits
         if (relevantText.length <= constants_1.MAX_TEXT_LENGTH) {
             return relevantText;
         }
-        // Truncate relevant text if too long
         return relevantText.slice(0, constants_1.MAX_TEXT_LENGTH - 3) + '...';
     }
     extractElementAttributes(element) {

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

@@ -109,6 +109,15 @@ class ErrorHandler extends state_manager_1.StateManager {
             return true;
         }
         this.recentErrors.set(key, now);
+        if (this.recentErrors.size > error_constants_1.MAX_TRACKED_ERRORS_HARD_LIMIT) {
+            logging_1.debugLog.warn('ErrorHandler', 'Hard limit exceeded, clearing all tracked errors', {
+                size: this.recentErrors.size,
+                limit: error_constants_1.MAX_TRACKED_ERRORS_HARD_LIMIT,
+            });
+            this.recentErrors.clear();
+            this.recentErrors.set(key, now);
+            return false;
+        }
         if (this.recentErrors.size > error_constants_1.MAX_TRACKED_ERRORS) {
             this.pruneOldErrors();
         }

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

@@ -64,7 +64,6 @@ class ScrollHandler extends state_manager_1.StateManager {
         }
     }
     setupScrollContainer(element) {
-        // Skip setup for non-scrollable elements
         if (element !== window && !this.isElementScrollable(element)) {
             return;
         }
@@ -176,12 +175,10 @@ class ScrollHandler extends state_manager_1.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 < constants_1.SIGNIFICANT_SCROLL_DELTA) {
             return null;
         }
-        // Early return: check if window is scrollable
         if (element === window && !this.isWindowScrollable()) {
             return null;
         }
@@ -209,7 +206,6 @@ class ScrollHandler extends state_manager_1.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;
     }
@@ -218,7 +214,6 @@ class ScrollHandler extends state_manager_1.StateManager {
             return document.querySelector(selector);
         }
         catch (error) {
-            // Invalid CSS selector - log warning and continue
             logging_1.debugLog.clientWarn('ScrollHandler', 'Invalid CSS selector', {
                 selector,
                 error: error instanceof Error ? error.message : 'Unknown error',

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

@@ -20,12 +20,15 @@ class SessionHandler extends state_manager_1.StateManager {
             logging_1.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 session_manager_1.SessionManager(this.storageManager, this.eventManager);
+            this.sessionManager = new session_manager_1.SessionManager(this.storageManager, this.eventManager, projectId);
             await this.sessionManager.startTracking();
         }
         catch (error) {
-            // Cleanup on failure
             if (this.sessionManager) {
                 try {
                     this.sessionManager.destroy();

package/dist/cjs/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/cjs/integrations/google-analytics.integration.js

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

package/dist/cjs/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/cjs/managers/api.manager.js

@@ -8,7 +8,7 @@ const logging_1 = require("../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
@@ -18,8 +18,8 @@ const logging_1 = require("../utils/logging");
  */
 function getApiUrlForProject(id, allowHttp = false) {
     try {
-        // Handle localhost development case
-        if (id.startsWith(types_1.SpecialProjectId.Localhost)) {
+        // Handle localhost development case (localhost:8080 or localhost:9999)
+        if (id === types_1.SpecialProjectId.Localhost || id === types_1.SpecialProjectId.Fail) {
             const url = `http://${id}`;
             if (!(0, utils_1.isValidUrl)(url, true)) {
                 throw new Error(`Invalid localhost URL format: ${id}`);

package/dist/cjs/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;
+}