@tracelog/lib 0.0.8 → 0.2.0

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

@@ -1,90 +1,159 @@
-import { DEFAULT_API_CONFIG, DEFAULT_CONFIG } from '../constants';
+import { DEFAULT_API_CONFIG, DEFAULT_CONFIG, REQUEST_TIMEOUT_MS } from '../constants';
 import { Mode, SpecialProjectId } from '../types';
-import { isValidUrl, sanitizeApiConfig } from '../utils';
+import { sanitizeApiConfig, fetchWithTimeout, normalizeConfig } from '../utils';
 import { debugLog } from '../utils/logging';
+/**
+ * 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)
+ *
+ * Supports special project IDs for development and testing:
+ * - 'skip': Bypasses all network calls, uses defaults
+ * - 'localhost:PORT': Loads config from local development server
+ */
 export class ConfigManager {
+    /**
+     * Gets complete configuration by merging default, API, and app configurations.
+     *
+     * @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) {
-        if (appConfig.id === SpecialProjectId.HttpSkip) {
-            debugLog.debug('ConfigManager', 'Using special project id');
-            return this.getDefaultConfig(appConfig);
+        // Handle skip mode - no network calls
+        if (appConfig.id === SpecialProjectId.Skip) {
+            return this.createDefaultConfig(appConfig);
         }
-        debugLog.debug('ConfigManager', 'Loading config from API', { apiUrl, projectId: appConfig.id });
-        const config = await this.load(apiUrl, appConfig, appConfig.id === SpecialProjectId.HttpLocal);
-        debugLog.info('ConfigManager', 'Config loaded successfully', {
+        const config = await this.loadFromApi(apiUrl, appConfig);
+        const { config: normalizedConfig } = normalizeConfig(config);
+        debugLog.info('ConfigManager', 'Configuration loaded', {
             projectId: appConfig.id,
-            mode: config.mode,
-            hasExcludedPaths: !!config.excludedUrlPaths?.length,
-            hasGlobalMetadata: !!config.globalMetadata,
+            mode: normalizedConfig.mode,
+            hasTags: !!normalizedConfig.tags?.length,
+            hasExclusions: !!normalizedConfig.excludedUrlPaths?.length,
         });
-        return config;
+        return normalizedConfig;
     }
-    async load(apiUrl, appConfig, useLocalServer) {
+    /**
+     * Loads configuration from API and merges with app config.
+     */
+    async loadFromApi(apiUrl, appConfig) {
         try {
-            const configUrl = useLocalServer ? `${window.location.origin}/config` : this.getUrl(apiUrl);
-            if (!configUrl) {
-                throw new Error('Config URL is not valid or not allowed');
-            }
-            const response = await fetch(configUrl, {
+            const configUrl = this.buildConfigUrl(apiUrl, appConfig);
+            const headers = this.buildHeaders(appConfig);
+            const response = await fetchWithTimeout(configUrl, {
                 method: 'GET',
-                headers: { 'Content-Type': 'application/json' },
+                headers,
+                timeout: REQUEST_TIMEOUT_MS,
             });
             if (!response.ok) {
-                const error = `HTTP ${response.status}: ${response.statusText}`;
-                debugLog.error('ConfigManager', 'Config API request failed', {
-                    status: response.status,
-                    statusText: response.statusText,
-                    configUrl,
-                });
-                throw new Error(error);
-            }
-            const rawData = await response.json();
-            if (rawData === undefined || rawData === null || typeof rawData !== 'object' || Array.isArray(rawData)) {
-                debugLog.error('ConfigManager', 'Invalid config API response format', {
-                    responseType: typeof rawData,
-                    isArray: Array.isArray(rawData),
-                });
-                throw new Error('Invalid config API response: expected object');
-            }
-            const safeApiConfig = sanitizeApiConfig(rawData);
-            const apiConfig = { ...DEFAULT_API_CONFIG, ...safeApiConfig };
-            const mergedConfig = { ...apiConfig, ...appConfig };
-            // Check if qaMode=true is in URL and automatically set mode to 'qa'
-            const urlParameters = new URLSearchParams(window.location.search);
-            const isQaMode = urlParameters.get('qaMode') === 'true';
-            if (isQaMode && !mergedConfig.mode) {
-                mergedConfig.mode = Mode.QA;
-                debugLog.info('ConfigManager', 'QA mode enabled via URL parameter');
+                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
             }
-            const errorSampling = Object.values(Mode).includes(mergedConfig.mode)
-                ? 1
-                : (mergedConfig.errorSampling ?? 0.1);
-            const finalConfig = { ...mergedConfig, errorSampling };
-            return finalConfig;
+            const rawData = await this.parseJsonResponse(response);
+            return this.mergeConfigurations(rawData, appConfig);
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-            debugLog.error('ConfigManager', 'Failed to load config', { error: errorMessage, apiUrl });
-            throw new Error(`Failed to load config: ${errorMessage}`);
+            debugLog.error('ConfigManager', 'Failed to load configuration', {
+                error: errorMessage,
+                apiUrl,
+                projectId: appConfig.id,
+            });
+            throw new Error(`Configuration load failed: ${errorMessage}`);
+        }
+    }
+    /**
+     * Builds the configuration URL based on project type and QA mode.
+     */
+    buildConfigUrl(apiUrl, appConfig) {
+        const isLocalhost = appConfig.id.startsWith(SpecialProjectId.Localhost);
+        if (isLocalhost) {
+            this.validateLocalhostProjectId(appConfig.id);
+            return `http://${appConfig.id}/config`;
+        }
+        const baseUrl = `${apiUrl}/config`;
+        const isQaMode = this.isQaModeEnabled();
+        return isQaMode ? `${baseUrl}?qaMode=true` : baseUrl;
+    }
+    /**
+     * Builds request headers based on project configuration.
+     */
+    buildHeaders(appConfig) {
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        if (appConfig.id.startsWith(SpecialProjectId.Localhost)) {
+            headers['X-TraceLog-Project'] = appConfig.id;
+        }
+        return headers;
+    }
+    /**
+     * Parses and validates JSON response from config API.
+     */
+    async parseJsonResponse(response) {
+        const contentType = response.headers.get('content-type');
+        if (!contentType?.includes('application/json')) {
+            throw new Error('Invalid response content-type, expected JSON');
+        }
+        const rawData = await response.json();
+        if (!rawData || typeof rawData !== 'object' || Array.isArray(rawData)) {
+            throw new Error('Invalid response format, expected object');
         }
+        return rawData;
     }
-    getUrl(apiUrl) {
-        const urlParameters = new URLSearchParams(window.location.search);
-        const isQaMode = urlParameters.get('qaMode') === 'true';
-        let configUrl = `${apiUrl}/config`;
-        if (isQaMode) {
-            configUrl += '?qaMode=true';
+    /**
+     * 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}'`);
         }
-        if (!isValidUrl(configUrl)) {
-            debugLog.clientError('ConfigManager', 'Invalid config URL provided', { configUrl });
-            throw new Error('Config URL is not valid or not allowed');
+        const port = parseInt(projectId.split(':')[1], 10);
+        if (port < 1 || port > 65535) {
+            throw new Error(`Port must be between 1 and 65535, got ${port}`);
         }
-        return configUrl;
     }
-    getDefaultConfig(appConfig) {
-        return DEFAULT_CONFIG({
+    /**
+     * Checks if QA mode is enabled via URL parameter.
+     */
+    isQaModeEnabled() {
+        const params = new URLSearchParams(window.location.search);
+        return params.get('qaMode') === 'true';
+    }
+    /**
+     * Merges API configuration with app configuration and applies mode-specific settings.
+     */
+    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;
+            debugLog.info('ConfigManager', 'QA mode enabled via URL parameter');
+        }
+        // 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 };
+    }
+    /**
+     * Creates default configuration for skip mode and fallback scenarios.
+     */
+    createDefaultConfig(appConfig) {
+        const defaultConfig = DEFAULT_CONFIG({
             ...appConfig,
             errorSampling: 1,
-            ...(Object.values(SpecialProjectId).includes(appConfig.id) && { mode: Mode.DEBUG }),
+            ...(appConfig.id === SpecialProjectId.Skip && { mode: Mode.DEBUG }),
         });
+        const { config } = normalizeConfig(defaultConfig);
+        return config;
     }
 }
+ConfigManager.LOCALHOST_PATTERN = /^localhost:\d{1,5}$/;
+ConfigManager.PRODUCTION_DOMAINS = [/^https:\/\/.*\.tracelog\.app$/, /^https:\/\/.*\.tracelog\.dev$/];

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

@@ -1,61 +1,82 @@
 import { EventData } from '../types';
+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 samplingManager;
-    private readonly tagsManager;
     private readonly dataSender;
-    private readonly storageManager;
+    private readonly emitter;
     private eventsQueue;
-    private lastEvent;
-    private eventsQueueIntervalId;
-    private intervalActive;
-    private failureCount;
-    private readonly MAX_FAILURES;
-    private circuitOpen;
-    private circuitOpenTime;
-    private backoffDelay;
-    private circuitResetTimeoutId;
-    private readonly eventFingerprints;
-    private readonly PERSISTENCE_KEY;
-    constructor(storeManager: StorageManager, googleAnalytics?: GoogleAnalyticsIntegration | null);
-    track({ type, page_url, from_page_url, scroll_data, click_data, custom_event, web_vitals, session_end_reason, session_start_recovered, }: Partial<EventData>): void;
+    private lastEventFingerprint;
+    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, session_start_recovered, }: Partial<EventData>): void;
     stop(): void;
-    private processAndSend;
-    private trackGoogleAnalyticsEvent;
-    private initEventsQueueInterval;
+    /**
+     * 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 sendEventsQueue;
-    private buildEventsPayload;
-    private clearQueueInterval;
-    private getEventFingerprint;
-    private isDuplicatedEvent;
+    private clearSendInterval;
     /**
-     * Cleans up old fingerprints to prevent memory leaks
+     * Shared flush implementation for both sync and async modes
      */
-    private cleanupOldFingerprints;
+    private flushEvents;
     /**
-     * Opens the circuit breaker with time-based recovery and event persistence
+     * Send queued events to the API
      */
-    private openCircuitBreaker;
+    private sendEventsQueue;
     /**
-     * Resets the circuit breaker and attempts to restore persisted events
+     * Build the payload for sending events to the API
+     * Includes basic deduplication and sorting
      */
-    private resetCircuitBreaker;
+    private buildEventsPayload;
     /**
-     * Persists current events queue to localStorage for recovery
+     * Helper methods for event processing
      */
-    private persistEventsToStorage;
+    private buildEventPayload;
+    private isEventExcluded;
+    private isDuplicateEvent;
+    private createEventFingerprint;
+    private createEventSignature;
+    private addToQueue;
+    private startSendInterval;
+    private handleGoogleAnalyticsIntegration;
+    private shouldSample;
+    private removeProcessedEvents;
     /**
-     * Restores events from localStorage if available and not expired
+     * Emit event for external listeners
      */
-    private restoreEventsFromStorage;
+    private emitEvent;
     /**
-     * Clears persisted events from localStorage
+     * Emit events queue for external listeners
      */
-    private clearPersistedEvents;
+    private emitEventsQueue;
 }