@tracelog/lib 0.4.1 → 0.5.1

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

@@ -1,44 +1,53 @@
-import { DEFAULT_API_CONFIG, DEFAULT_CONFIG, REQUEST_TIMEOUT_MS } from '../constants';
+import { DEFAULT_API_CONFIG, REQUEST_TIMEOUT_MS } from '../constants';
 import { Mode, SpecialProjectId } from '../types';
-import { sanitizeApiConfig, fetchWithTimeout, normalizeConfig } from '../utils';
+import { sanitizeApiConfig, fetchWithTimeout } from '../utils';
 import { debugLog } from '../utils/logging';
+import { ConfigBuilder } from './config.builder';
 /**
  * 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 class ConfigManager {
     /**
-     * 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()
      * @returns Promise<Config> - Merged configuration object
      */
     async get(apiUrl, appConfig) {
-        // Handle skip mode - no network calls
-        if (appConfig.id === SpecialProjectId.Skip) {
+        // Handle skip mode - no network calls for config
+        // Support 'skip' or any ID starting with 'skip-' (e.g., 'skip-1', 'skip-2')
+        // Also handle 'fail' mode (SpecialProjectId.Fail) - skip config but fail event sends
+        if (appConfig.id === SpecialProjectId.Skip ||
+            appConfig.id === SpecialProjectId.Fail ||
+            appConfig.id.toLowerCase().startsWith('skip-')) {
             return this.createDefaultConfig(appConfig);
         }
-        const config = await this.loadFromApi(apiUrl, appConfig);
-        const { config: normalizedConfig } = normalizeConfig(config);
+        const apiConfig = await this.loadFromApi(apiUrl, appConfig);
+        // Apply QA mode from URL parameter if set
+        const finalApiConfig = this.applyQaModeIfEnabled(apiConfig);
+        const config = ConfigBuilder.build(appConfig, finalApiConfig);
         debugLog.info('ConfigManager', 'Configuration loaded', {
-            projectId: appConfig.id,
-            mode: normalizedConfig.mode,
-            hasTags: !!normalizedConfig.tags?.length,
-            hasExclusions: !!normalizedConfig.excludedUrlPaths?.length,
+            projectId: config.id,
+            mode: config.mode,
+            hasTags: !!config.tags?.length,
+            hasExclusions: !!config.excludedUrlPaths?.length,
         });
-        return normalizedConfig;
+        return 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.
      */
     async loadFromApi(apiUrl, appConfig) {
         try {
@@ -53,7 +62,13 @@ export class ConfigManager {
                 throw new Error(`HTTP ${response.status}: ${response.statusText}`);
             }
             const rawData = await this.parseJsonResponse(response);
-            return this.mergeConfigurations(rawData, appConfig);
+            const apiConfig = sanitizeApiConfig(rawData);
+            // Only merge defaults for fields that are arrays (to ensure they're never undefined)
+            return {
+                ...apiConfig,
+                excludedUrlPaths: apiConfig.excludedUrlPaths ?? DEFAULT_API_CONFIG.excludedUrlPaths,
+                tags: apiConfig.tags ?? DEFAULT_API_CONFIG.tags,
+            };
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : 'Unknown error';
@@ -69,9 +84,8 @@ export class ConfigManager {
      * Builds the configuration URL based on project type and QA mode.
      */
     buildConfigUrl(apiUrl, appConfig) {
-        const isLocalhost = appConfig.id.startsWith(SpecialProjectId.Localhost);
+        const isLocalhost = appConfig.id === SpecialProjectId.Localhost || appConfig.id === SpecialProjectId.Fail;
         if (isLocalhost) {
-            this.validateLocalhostProjectId(appConfig.id);
             return `http://${appConfig.id}/config`;
         }
         const baseUrl = `${apiUrl}/config`;
@@ -80,15 +94,13 @@ export class ConfigManager {
     }
     /**
      * Builds request headers based on project configuration.
+     * Always includes X-TraceLog-Project header for consistent identification.
      */
     buildHeaders(appConfig) {
-        const headers = {
+        return {
             'Content-Type': 'application/json',
+            'X-TraceLog-Project': appConfig.id,
         };
-        if (appConfig.id.startsWith(SpecialProjectId.Localhost)) {
-            headers['X-TraceLog-Project'] = appConfig.id;
-        }
-        return headers;
     }
     /**
      * Parses and validates JSON response from config API.
@@ -104,18 +116,6 @@ export class ConfigManager {
         }
         return rawData;
     }
-    /**
-     * Validates localhost project ID format and port range.
-     */
-    validateLocalhostProjectId(projectId) {
-        if (!ConfigManager.LOCALHOST_PATTERN.test(projectId)) {
-            throw new Error(`Invalid localhost format. Expected 'localhost:PORT', got '${projectId}'`);
-        }
-        const port = parseInt(projectId.split(':')[1], 10);
-        if (port < 1 || port > 65535) {
-            throw new Error(`Port must be between 1 and 65535, got ${port}`);
-        }
-    }
     /**
      * Checks if QA mode is enabled via URL parameter.
      */
@@ -124,36 +124,30 @@ export class ConfigManager {
         return params.get('qaMode') === 'true';
     }
     /**
-     * Merges API configuration with app configuration and applies mode-specific settings.
+     * Applies QA mode to API config if enabled via URL parameter.
      */
-    mergeConfigurations(rawApiConfig, appConfig) {
-        const safeApiConfig = sanitizeApiConfig(rawApiConfig);
-        const apiConfig = { ...DEFAULT_API_CONFIG, ...safeApiConfig };
-        const mergedConfig = DEFAULT_CONFIG({ ...appConfig, ...apiConfig });
-        const { config: normalizedConfig } = normalizeConfig(mergedConfig);
-        // Apply QA mode if enabled via URL parameter
-        if (this.isQaModeEnabled() && !normalizedConfig.mode) {
-            normalizedConfig.mode = Mode.QA;
+    applyQaModeIfEnabled(apiConfig) {
+        if (this.isQaModeEnabled() && !apiConfig.mode) {
             debugLog.info('ConfigManager', 'QA mode enabled via URL parameter');
+            return { ...apiConfig, mode: Mode.QA };
         }
-        // Set error sampling based on mode
-        const errorSampling = Object.values(Mode).includes(normalizedConfig.mode)
-            ? 1 // Full sampling for debug/qa modes
-            : (normalizedConfig.errorSampling ?? 0.1); // Default sampling for production
-        return { ...normalizedConfig, errorSampling };
+        return apiConfig;
     }
     /**
      * Creates default configuration for skip mode and fallback scenarios.
+     * Only uses API defaults for fields not provided by the app config.
      */
     createDefaultConfig(appConfig) {
-        const defaultConfig = DEFAULT_CONFIG({
-            ...appConfig,
-            errorSampling: 1,
-            ...(appConfig.id === SpecialProjectId.Skip && { mode: Mode.DEBUG }),
-        });
-        const { config } = normalizeConfig(defaultConfig);
-        return config;
+        // Only use DEFAULT_API_CONFIG for fields not provided in appConfig
+        const apiConfig = {
+            // Only use defaults if app config doesn't provide these values
+            tags: DEFAULT_API_CONFIG.tags,
+            ipExcluded: DEFAULT_API_CONFIG.ipExcluded,
+            ...(appConfig.samplingRate === undefined && { samplingRate: DEFAULT_API_CONFIG.samplingRate }),
+            // Don't override excludedUrlPaths if provided by app config
+            // ConfigBuilder will handle the fallback to [] if both are undefined
+        };
+        return ConfigBuilder.build(appConfig, apiConfig);
     }
 }
-ConfigManager.LOCALHOST_PATTERN = /^localhost:\d{1,5}$/;
 ConfigManager.PRODUCTION_DOMAINS = [/^https:\/\/.*\.tracelog\.app$/, /^https:\/\/.*\.tracelog\.dev$/];

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

@@ -3,16 +3,6 @@ import { Emitter } from '../utils';
 import { StateManager } from './state.manager';
 import { StorageManager } from './storage.manager';
 import { GoogleAnalyticsIntegration } from '../integrations/google-analytics.integration';
-/**
- * EventManager - Core event tracking and queue management
- *
- * Responsibilities:
- * - Track user events (clicks, scrolls, page views, custom events)
- * - Queue events and batch send them to the analytics API
- * - Handle deduplication of similar events
- * - Manage event sending intervals and retry logic
- * - Integrate with Google Analytics when configured
- */
 export declare class EventManager extends StateManager {
     private readonly googleAnalytics;
     private readonly dataSender;
@@ -22,45 +12,16 @@ export declare class EventManager extends StateManager {
     private lastEventTime;
     private sendIntervalId;
     constructor(storeManager: StorageManager, googleAnalytics?: GoogleAnalyticsIntegration | null, emitter?: Emitter | null);
-    /**
-     * Recovers persisted events from localStorage
-     * Should be called after initialization to recover any events that failed to send
-     */
     recoverPersistedEvents(): Promise<void>;
-    /**
-     * Track user events with automatic deduplication and queueing
-     */
     track({ type, page_url, from_page_url, scroll_data, click_data, custom_event, web_vitals, error_data, session_end_reason, }: Partial<EventData>): void;
     stop(): void;
-    /**
-     * Flush all queued events immediately (async)
-     */
     flushImmediately(): Promise<boolean>;
-    /**
-     * Flush all queued events immediately (sync)
-     */
     flushImmediatelySync(): boolean;
-    /**
-     * Queue management and sending intervals
-     */
     getQueueLength(): number;
     private clearSendInterval;
-    /**
-     * Shared flush implementation for both sync and async modes
-     */
     private flushEvents;
-    /**
-     * Send queued events to the API
-     */
     private sendEventsQueue;
-    /**
-     * Build the payload for sending events to the API
-     * Includes basic deduplication and sorting
-     */
     private buildEventsPayload;
-    /**
-     * Helper methods for event processing
-     */
     private buildEventPayload;
     private isEventExcluded;
     private isDuplicateEvent;
@@ -71,12 +32,6 @@ export declare class EventManager extends StateManager {
     private handleGoogleAnalyticsIntegration;
     private shouldSample;
     private removeProcessedEvents;
-    /**
-     * Emit event for external listeners
-     */
     private emitEvent;
-    /**
-     * Emit events queue for external listeners
-     */
     private emitEventsQueue;
 }

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

@@ -3,16 +3,6 @@ import { EmitterEvent, EventType } from '../types';
 import { getUTMParameters, isUrlPathExcluded, debugLog } from '../utils';
 import { SenderManager } from './sender.manager';
 import { StateManager } from './state.manager';
-/**
- * EventManager - Core event tracking and queue management
- *
- * Responsibilities:
- * - Track user events (clicks, scrolls, page views, custom events)
- * - Queue events and batch send them to the analytics API
- * - Handle deduplication of similar events
- * - Manage event sending intervals and retry logic
- * - Integrate with Google Analytics when configured
- */
 export class EventManager extends StateManager {
     constructor(storeManager, googleAnalytics = null, emitter = null) {
         super();
@@ -24,16 +14,15 @@ export class EventManager extends StateManager {
         this.dataSender = new SenderManager(storeManager);
         this.emitter = emitter;
     }
-    /**
-     * Recovers persisted events from localStorage
-     * Should be called after initialization to recover any events that failed to send
-     */
     async recoverPersistedEvents() {
         await this.dataSender.recoverPersistedEvents({
-            onSuccess: (_eventCount, recoveredEvents) => {
+            onSuccess: (_eventCount, recoveredEvents, body) => {
                 if (recoveredEvents && recoveredEvents.length > 0) {
                     const eventIds = recoveredEvents.map((e) => e.timestamp + '_' + e.type);
                     this.removeProcessedEvents(eventIds);
+                    if (body) {
+                        this.emitEventsQueue(body);
+                    }
                 }
             },
             onFailure: async () => {
@@ -41,9 +30,6 @@ export class EventManager extends StateManager {
             },
         });
     }
-    /**
-     * Track user events with automatic deduplication and queueing
-     */
     track({ type, page_url, from_page_url, scroll_data, click_data, custom_event, web_vitals, error_data, session_end_reason, }) {
         if (!type) {
             debugLog.warn('EventManager', 'Event type is required');
@@ -53,7 +39,6 @@ export class EventManager extends StateManager {
         const isSessionStart = eventType === EventType.SESSION_START;
         const isSessionEnd = eventType === EventType.SESSION_END;
         const isCriticalEvent = isSessionStart || isSessionEnd;
-        // Build event payload
         const currentPageUrl = page_url || this.get('pageUrl');
         const payload = this.buildEventPayload({
             type: eventType,
@@ -66,11 +51,9 @@ export class EventManager extends StateManager {
             error_data,
             session_end_reason,
         });
-        // Check URL exclusions
         if (this.isEventExcluded(payload)) {
             return;
         }
-        // Skip sampling for critical events, apply for the rest
         if (!isCriticalEvent && !this.shouldSample()) {
             return;
         }
@@ -88,41 +71,27 @@ export class EventManager extends StateManager {
             }
             this.set('hasStartSession', true);
         }
-        // Check for duplicates
         if (this.isDuplicateEvent(payload)) {
             return;
         }
-        // Add to queue and schedule sending
         this.addToQueue(payload);
     }
     stop() {
-        // Clear interval
         if (this.sendIntervalId) {
             clearInterval(this.sendIntervalId);
             this.sendIntervalId = null;
         }
-        // Reset state
         this.eventsQueue = [];
         this.lastEventFingerprint = null;
         this.lastEventTime = 0;
-        // Stop sender
         this.dataSender.stop();
     }
-    /**
-     * Flush all queued events immediately (async)
-     */
     async flushImmediately() {
         return this.flushEvents(false);
     }
-    /**
-     * Flush all queued events immediately (sync)
-     */
     flushImmediatelySync() {
         return this.flushEvents(true);
     }
-    /**
-     * Queue management and sending intervals
-     */
     getQueueLength() {
         return this.eventsQueue.length;
     }
@@ -132,9 +101,6 @@ export class EventManager extends StateManager {
             this.sendIntervalId = null;
         }
     }
-    /**
-     * Shared flush implementation for both sync and async modes
-     */
     flushEvents(isSync) {
         if (this.eventsQueue.length === 0) {
             return isSync ? true : Promise.resolve(true);
@@ -147,6 +113,7 @@ export class EventManager extends StateManager {
             if (success) {
                 this.removeProcessedEvents(eventIds);
                 this.clearSendInterval();
+                this.emitEventsQueue(body);
             }
             return success;
         }
@@ -165,9 +132,6 @@ export class EventManager extends StateManager {
             });
         }
     }
-    /**
-     * Send queued events to the API
-     */
     async sendEventsQueue() {
         if (!this.get('sessionId') || this.eventsQueue.length === 0) {
             return;
@@ -187,10 +151,6 @@ export class EventManager extends StateManager {
             },
         });
     }
-    /**
-     * Build the payload for sending events to the API
-     * Includes basic deduplication and sorting
-     */
     buildEventsPayload() {
         const eventMap = new Map();
         const order = [];
@@ -213,9 +173,6 @@ export class EventManager extends StateManager {
             ...(this.get('config')?.globalMetadata && { global_metadata: this.get('config')?.globalMetadata }),
         };
     }
-    /**
-     * Helper methods for event processing
-     */
     buildEventPayload(data) {
         const isSessionStart = data.type === EventType.SESSION_START;
         const currentPageUrl = data.page_url ?? this.get('pageUrl');
@@ -233,7 +190,6 @@ export class EventManager extends StateManager {
             ...(data.session_end_reason && { session_end_reason: data.session_end_reason }),
             ...(isSessionStart && getUTMParameters() && { utm: getUTMParameters() }),
         };
-        // Add project tags
         const projectTags = this.get('config')?.tags;
         if (projectTags?.length) {
             payload.tags = projectTags;
@@ -254,11 +210,9 @@ export class EventManager extends StateManager {
     isDuplicateEvent(event) {
         const now = Date.now();
         const fingerprint = this.createEventFingerprint(event);
-        // Check if this is a duplicate within the threshold
         if (this.lastEventFingerprint === fingerprint && now - this.lastEventTime < DUPLICATE_EVENT_THRESHOLD_MS) {
             return true;
         }
-        // Update tracking
         this.lastEventFingerprint = fingerprint;
         this.lastEventTime = now;
         return false;
@@ -266,7 +220,6 @@ export class EventManager extends StateManager {
     createEventFingerprint(event) {
         let fingerprint = `${event.type}_${event.page_url}`;
         if (event.click_data) {
-            // Round coordinates to reduce false duplicates
             const x = Math.round((event.click_data.x || 0) / 10) * 10;
             const y = Math.round((event.click_data.y || 0) / 10) * 10;
             fingerprint += `_click_${x}_${y}`;
@@ -280,6 +233,9 @@ export class EventManager extends StateManager {
         if (event.web_vitals) {
             fingerprint += `_vitals_${event.web_vitals.type}`;
         }
+        if (event.error_data) {
+            fingerprint += `_error_${event.error_data.type}_${event.error_data.message}`;
+        }
         return fingerprint;
     }
     createEventSignature(event) {
@@ -287,21 +243,20 @@ export class EventManager extends StateManager {
     }
     addToQueue(event) {
         this.eventsQueue.push(event);
-        debugLog.info('EventManager', 'Event added to queue', event);
         this.emitEvent(event);
-        // Prevent queue overflow
         if (this.eventsQueue.length > MAX_EVENTS_QUEUE_LENGTH) {
-            const removedEvent = this.eventsQueue.shift();
-            debugLog.warn('EventManager', 'Event queue overflow, oldest event removed', {
+            const nonCriticalIndex = this.eventsQueue.findIndex((e) => e.type !== EventType.SESSION_START && e.type !== EventType.SESSION_END);
+            const removedEvent = nonCriticalIndex >= 0 ? this.eventsQueue.splice(nonCriticalIndex, 1)[0] : this.eventsQueue.shift();
+            debugLog.warn('EventManager', 'Event queue overflow, oldest non-critical event removed', {
                 maxLength: MAX_EVENTS_QUEUE_LENGTH,
                 currentLength: this.eventsQueue.length,
                 removedEventType: removedEvent?.type,
+                wasCritical: removedEvent?.type === EventType.SESSION_START || removedEvent?.type === EventType.SESSION_END,
             });
         }
         if (!this.sendIntervalId) {
             this.startSendInterval();
         }
-        // Google Analytics integration
         this.handleGoogleAnalyticsIntegration(event);
     }
     startSendInterval() {
@@ -314,11 +269,9 @@ export class EventManager extends StateManager {
     handleGoogleAnalyticsIntegration(event) {
         if (this.googleAnalytics && event.type === EventType.CUSTOM && event.custom_event) {
             if (this.get('config')?.mode === 'qa' || this.get('config')?.mode === 'debug') {
-                // Skip GA tracking in QA/debug modes
-            }
-            else {
-                this.googleAnalytics.trackEvent(event.custom_event.name, event.custom_event.metadata ?? {});
+                return;
             }
+            this.googleAnalytics.trackEvent(event.custom_event.name, event.custom_event.metadata ?? {});
         }
     }
     shouldSample() {
@@ -332,17 +285,11 @@ export class EventManager extends StateManager {
             return !eventIdSet.has(eventId);
         });
     }
-    /**
-     * Emit event for external listeners
-     */
     emitEvent(eventData) {
         if (this.emitter) {
             this.emitter.emit(EmitterEvent.EVENT, eventData);
         }
     }
-    /**
-     * Emit events queue for external listeners
-     */
     emitEventsQueue(queue) {
         if (this.emitter) {
             this.emitter.emit(EmitterEvent.QUEUE, queue);

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

@@ -2,7 +2,7 @@ import { BaseEventsQueueDto } from '../types';
 import { StorageManager } from './storage.manager';
 import { StateManager } from './state.manager';
 interface SendCallbacks {
-    onSuccess?: (eventCount?: number, events?: any[]) => void;
+    onSuccess?: (eventCount?: number, events?: any[], body?: BaseEventsQueueDto) => void;
     onFailure?: () => void;
 }
 export declare class SenderManager extends StateManager {
@@ -12,38 +12,15 @@ export declare class SenderManager extends StateManager {
     private isRetrying;
     constructor(storeManager: StorageManager);
     private getQueueStorageKey;
-    /**
-     * Send events synchronously using sendBeacon or XHR fallback
-     * Used primarily for page unload scenarios
-     */
     sendEventsQueueSync(body: BaseEventsQueueDto): boolean;
-    /**
-     * Send events asynchronously with persistence and retry logic
-     * Main method for sending events during normal operation
-     */
     sendEventsQueue(body: BaseEventsQueueDto, callbacks?: SendCallbacks): Promise<boolean>;
-    /**
-     * Recover and send previously persisted events
-     * Called during initialization to handle events from previous session
-     */
     recoverPersistedEvents(callbacks?: SendCallbacks): Promise<void>;
-    /**
-     * Persist events for recovery in case of failure
-     */
     persistEventsForRecovery(body: BaseEventsQueueDto): boolean;
-    /**
-     * Legacy method for backward compatibility
-     * @deprecated Use sendEventsQueue instead
-     */
     sendEventsQueueAsync(body: BaseEventsQueueDto): Promise<boolean>;
-    /**
-     * Stop the sender manager and clean up resources
-     */
     stop(): void;
     private send;
     private sendWithTimeout;
     private sendQueueSyncInternal;
-    private sendSyncXHR;
     private prepareRequest;
     private getPersistedData;
     private isDataRecent;
@@ -53,10 +30,6 @@ export declare class SenderManager extends StateManager {
     private resetRetryState;
     private scheduleRetry;
     private shouldSkipSend;
-    /**
-     * Simulate a successful send operation for skip mode
-     * Provides realistic timing and behavior without making HTTP requests
-     */
     private simulateSuccessfulSend;
     private isSendBeaconAvailable;
     private clearRetryTimeout;