@tracelog/lib 0.4.0 → 0.5.0

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

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigBuilder = void 0;
+const config_constants_1 = require("../constants/config.constants");
+const types_1 = require("../types");
+const logging_1 = require("../utils/logging");
+/**
+ * Centralized configuration builder
+ * Single source of truth for merging and building final configuration
+ */
+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,
+        };
+        logging_1.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 config_constants_1.DEFAULT_SESSION_TIMEOUT;
+        }
+        if (timeout < config_constants_1.MIN_SESSION_TIMEOUT_MS || timeout > config_constants_1.MAX_SESSION_TIMEOUT_MS) {
+            logging_1.debugLog.warn('ConfigBuilder', 'Invalid session timeout, using default', {
+                provided: timeout,
+                min: config_constants_1.MIN_SESSION_TIMEOUT_MS,
+                max: config_constants_1.MAX_SESSION_TIMEOUT_MS,
+                default: config_constants_1.DEFAULT_SESSION_TIMEOUT,
+            });
+            return config_constants_1.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 config_constants_1.DEFAULT_SAMPLING_RATE;
+        }
+        if (rate < config_constants_1.MIN_SAMPLING_RATE || rate > config_constants_1.MAX_SAMPLING_RATE) {
+            logging_1.debugLog.warn('ConfigBuilder', 'Invalid sampling rate, using default', {
+                provided: rate,
+                default: config_constants_1.DEFAULT_SAMPLING_RATE,
+            });
+            return config_constants_1.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 === types_1.Mode.DEBUG || apiMode === types_1.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 === types_1.SpecialProjectId.Skip ||
+            appConfig.id === types_1.SpecialProjectId.Fail ||
+            appConfig.id.toLowerCase().startsWith('skip-')) {
+            return types_1.Mode.DEBUG;
+        }
+        // API mode takes precedence over app mode
+        return apiMode ?? appConfig.mode;
+    }
+}
+exports.ConfigBuilder = ConfigBuilder;

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

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

@@ -5,43 +5,52 @@ const constants_1 = require("../constants");
 const types_1 = require("../types");
 const utils_1 = require("../utils");
 const logging_1 = require("../utils/logging");
+const config_builder_1 = require("./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
  */
 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 === types_1.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 === types_1.SpecialProjectId.Skip ||
+            appConfig.id === types_1.SpecialProjectId.Fail ||
+            appConfig.id.toLowerCase().startsWith('skip-')) {
             return this.createDefaultConfig(appConfig);
         }
-        const config = await this.loadFromApi(apiUrl, appConfig);
-        const { config: normalizedConfig } = (0, utils_1.normalizeConfig)(config);
+        const apiConfig = await this.loadFromApi(apiUrl, appConfig);
+        // Apply QA mode from URL parameter if set
+        const finalApiConfig = this.applyQaModeIfEnabled(apiConfig);
+        const config = config_builder_1.ConfigBuilder.build(appConfig, finalApiConfig);
         logging_1.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 {
@@ -56,7 +65,13 @@ class ConfigManager {
                 throw new Error(`HTTP ${response.status}: ${response.statusText}`);
             }
             const rawData = await this.parseJsonResponse(response);
-            return this.mergeConfigurations(rawData, appConfig);
+            const apiConfig = (0, utils_1.sanitizeApiConfig)(rawData);
+            // Only merge defaults for fields that are arrays (to ensure they're never undefined)
+            return {
+                ...apiConfig,
+                excludedUrlPaths: apiConfig.excludedUrlPaths ?? constants_1.DEFAULT_API_CONFIG.excludedUrlPaths,
+                tags: apiConfig.tags ?? constants_1.DEFAULT_API_CONFIG.tags,
+            };
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : 'Unknown error';
@@ -72,9 +87,8 @@ class ConfigManager {
      * Builds the configuration URL based on project type and QA mode.
      */
     buildConfigUrl(apiUrl, appConfig) {
-        const isLocalhost = appConfig.id.startsWith(types_1.SpecialProjectId.Localhost);
+        const isLocalhost = appConfig.id === types_1.SpecialProjectId.Localhost || appConfig.id === types_1.SpecialProjectId.Fail;
         if (isLocalhost) {
-            this.validateLocalhostProjectId(appConfig.id);
             return `http://${appConfig.id}/config`;
         }
         const baseUrl = `${apiUrl}/config`;
@@ -83,15 +97,13 @@ 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(types_1.SpecialProjectId.Localhost)) {
-            headers['X-TraceLog-Project'] = appConfig.id;
-        }
-        return headers;
     }
     /**
      * Parses and validates JSON response from config API.
@@ -107,18 +119,6 @@ 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.
      */
@@ -127,37 +127,31 @@ 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 = (0, utils_1.sanitizeApiConfig)(rawApiConfig);
-        const apiConfig = { ...constants_1.DEFAULT_API_CONFIG, ...safeApiConfig };
-        const mergedConfig = (0, constants_1.DEFAULT_CONFIG)({ ...appConfig, ...apiConfig });
-        const { config: normalizedConfig } = (0, utils_1.normalizeConfig)(mergedConfig);
-        // Apply QA mode if enabled via URL parameter
-        if (this.isQaModeEnabled() && !normalizedConfig.mode) {
-            normalizedConfig.mode = types_1.Mode.QA;
+    applyQaModeIfEnabled(apiConfig) {
+        if (this.isQaModeEnabled() && !apiConfig.mode) {
             logging_1.debugLog.info('ConfigManager', 'QA mode enabled via URL parameter');
+            return { ...apiConfig, mode: types_1.Mode.QA };
         }
-        // Set error sampling based on mode
-        const errorSampling = Object.values(types_1.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 = (0, constants_1.DEFAULT_CONFIG)({
-            ...appConfig,
-            errorSampling: 1,
-            ...(appConfig.id === types_1.SpecialProjectId.Skip && { mode: types_1.Mode.DEBUG }),
-        });
-        const { config } = (0, utils_1.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: constants_1.DEFAULT_API_CONFIG.tags,
+            ipExcluded: constants_1.DEFAULT_API_CONFIG.ipExcluded,
+            ...(appConfig.samplingRate === undefined && { samplingRate: constants_1.DEFAULT_API_CONFIG.samplingRate }),
+            // Don't override excludedUrlPaths if provided by app config
+            // ConfigBuilder will handle the fallback to [] if both are undefined
+        };
+        return config_builder_1.ConfigBuilder.build(appConfig, apiConfig);
     }
 }
 exports.ConfigManager = ConfigManager;
-ConfigManager.LOCALHOST_PATTERN = /^localhost:\d{1,5}$/;
 ConfigManager.PRODUCTION_DOMAINS = [/^https:\/\/.*\.tracelog\.app$/, /^https:\/\/.*\.tracelog\.dev$/];

package/dist/cjs/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, session_start_recovered, }: Partial<EventData>): void;
+    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;
 }