@tracelog/lib 0.1.0 → 0.2.1

package/dist/esm/listeners/input-listener-managers.js

@@ -1,53 +1,44 @@
 import { debugLog } from '../utils/logging';
-export class MouseListenerManager {
+/**
+ * Base class for input listener managers to reduce code duplication
+ */
+class BaseInputListenerManager {
     constructor(onActivity) {
         this.options = { passive: true };
         this.onActivity = onActivity;
     }
     setup() {
         try {
-            window.addEventListener('mousemove', this.onActivity, this.options);
-            window.addEventListener('mousedown', this.onActivity, this.options);
-            window.addEventListener('wheel', this.onActivity, this.options);
+            this.events.forEach((event) => {
+                window.addEventListener(event, this.onActivity, this.options);
+            });
         }
         catch (error) {
-            debugLog.error('MouseListenerManager', 'Failed to setup mouse listeners', { error });
-            throw error;
+            debugLog.error(this.logPrefix, `Failed to setup ${this.logPrefix.toLowerCase()} listeners`, { error });
         }
     }
     cleanup() {
         try {
-            window.removeEventListener('mousemove', this.onActivity);
-            window.removeEventListener('mousedown', this.onActivity);
-            window.removeEventListener('wheel', this.onActivity);
+            this.events.forEach((event) => {
+                window.removeEventListener(event, this.onActivity);
+            });
         }
         catch (error) {
-            debugLog.warn('MouseListenerManager', 'Error during mouse listeners cleanup', { error });
+            debugLog.warn(this.logPrefix, `Error during ${this.logPrefix.toLowerCase()} listeners cleanup`, { error });
         }
     }
 }
-export class KeyboardListenerManager {
-    constructor(onActivity) {
-        this.options = { passive: true };
-        this.onActivity = onActivity;
+export class MouseListenerManager extends BaseInputListenerManager {
+    constructor() {
+        super(...arguments);
+        this.events = ['mousemove', 'mousedown', 'wheel'];
+        this.logPrefix = 'MouseListenerManager';
     }
-    setup() {
-        try {
-            window.addEventListener('keydown', this.onActivity, this.options);
-            window.addEventListener('keypress', this.onActivity, this.options);
-        }
-        catch (error) {
-            debugLog.error('KeyboardListenerManager', 'Failed to setup keyboard listeners', { error });
-            throw error;
-        }
-    }
-    cleanup() {
-        try {
-            window.removeEventListener('keydown', this.onActivity);
-            window.removeEventListener('keypress', this.onActivity);
-        }
-        catch (error) {
-            debugLog.warn('KeyboardListenerManager', 'Error during keyboard listeners cleanup', { error });
-        }
+}
+export class KeyboardListenerManager extends BaseInputListenerManager {
+    constructor() {
+        super(...arguments);
+        this.events = ['keydown'];
+        this.logPrefix = 'KeyboardListenerManager';
     }
 }

package/dist/esm/listeners/touch-listener-manager.d.ts

@@ -2,9 +2,7 @@ import { EventListenerManager } from './listeners.types';
 export declare class TouchListenerManager implements EventListenerManager {
     private readonly onActivity;
     private readonly options;
-    private readonly motionThreshold;
-    constructor(onActivity: () => void, motionThreshold: number);
+    constructor(onActivity: () => void);
     setup(): void;
     cleanup(): void;
-    private readonly handleDeviceMotion;
 }

package/dist/esm/listeners/touch-listener-manager.js

@@ -1,23 +1,8 @@
 import { debugLog } from '../utils/logging';
 export class TouchListenerManager {
-    constructor(onActivity, motionThreshold) {
+    constructor(onActivity) {
         this.options = { passive: true };
-        this.handleDeviceMotion = (event) => {
-            try {
-                const acceleration = event.acceleration;
-                if (acceleration) {
-                    const totalAcceleration = Math.abs(acceleration.x ?? 0) + Math.abs(acceleration.y ?? 0) + Math.abs(acceleration.z ?? 0);
-                    if (totalAcceleration > this.motionThreshold) {
-                        this.onActivity();
-                    }
-                }
-            }
-            catch (error) {
-                debugLog.warn('TouchListenerManager', 'Error handling device motion event', { error });
-            }
-        };
         this.onActivity = onActivity;
-        this.motionThreshold = motionThreshold;
     }
     setup() {
         try {
@@ -25,10 +10,6 @@ export class TouchListenerManager {
             window.addEventListener('touchmove', this.onActivity, this.options);
             window.addEventListener('touchend', this.onActivity, this.options);
             window.addEventListener('orientationchange', this.onActivity, this.options);
-            const hasDeviceMotion = 'DeviceMotionEvent' in window;
-            if (hasDeviceMotion) {
-                window.addEventListener('devicemotion', this.handleDeviceMotion, this.options);
-            }
         }
         catch (error) {
             debugLog.error('TouchListenerManager', 'Failed to setup touch listeners', { error });
@@ -41,9 +22,6 @@ export class TouchListenerManager {
             window.removeEventListener('touchmove', this.onActivity);
             window.removeEventListener('touchend', this.onActivity);
             window.removeEventListener('orientationchange', this.onActivity);
-            if ('DeviceMotionEvent' in window) {
-                window.removeEventListener('devicemotion', this.handleDeviceMotion);
-            }
         }
         catch (error) {
             debugLog.warn('TouchListenerManager', 'Error during touch listeners cleanup', { error });

package/dist/esm/listeners/visibility-listener-manager.d.ts

@@ -2,11 +2,8 @@ import { EventListenerManager } from './listeners.types';
 export declare class VisibilityListenerManager implements EventListenerManager {
     private readonly onActivity;
     private readonly onVisibilityChange;
-    private readonly isMobile;
     private readonly options;
-    constructor(onActivity: () => void, onVisibilityChange: () => void, isMobile: boolean);
+    constructor(onActivity: () => void, onVisibilityChange: () => void);
     setup(): void;
     cleanup(): void;
-    private setupMobileEvents;
-    private cleanupMobileEvents;
 }

package/dist/esm/listeners/visibility-listener-manager.js

@@ -1,31 +1,27 @@
 import { debugLog } from '../utils/logging';
 export class VisibilityListenerManager {
-    constructor(onActivity, onVisibilityChange, isMobile) {
+    constructor(onActivity, onVisibilityChange) {
         this.options = { passive: true };
         this.onActivity = onActivity;
         this.onVisibilityChange = onVisibilityChange;
-        this.isMobile = isMobile;
     }
     setup() {
         try {
-            const hasVisibilityAPI = 'visibilityState' in document;
-            if (hasVisibilityAPI) {
+            // Core visibility API support
+            if ('visibilityState' in document) {
                 document.addEventListener('visibilitychange', this.onVisibilityChange, this.options);
             }
+            // Window focus/blur events
             window.addEventListener('blur', this.onVisibilityChange, this.options);
             window.addEventListener('focus', this.onActivity, this.options);
-            const hasNetworkAPI = 'onLine' in navigator;
-            if (hasNetworkAPI) {
+            // Basic network status detection
+            if ('onLine' in navigator) {
                 window.addEventListener('online', this.onActivity, this.options);
                 window.addEventListener('offline', this.onVisibilityChange, this.options);
             }
-            if (this.isMobile) {
-                this.setupMobileEvents();
-            }
         }
         catch (error) {
             debugLog.error('VisibilityListenerManager', 'Failed to setup visibility listeners', { error });
-            throw error;
         }
     }
     cleanup() {
@@ -39,41 +35,9 @@ export class VisibilityListenerManager {
                 window.removeEventListener('online', this.onActivity);
                 window.removeEventListener('offline', this.onVisibilityChange);
             }
-            if (this.isMobile) {
-                this.cleanupMobileEvents();
-            }
         }
         catch (error) {
             debugLog.warn('VisibilityListenerManager', 'Error during visibility listeners cleanup', { error });
         }
     }
-    setupMobileEvents() {
-        try {
-            document.addEventListener('pause', this.onVisibilityChange, this.options);
-            document.addEventListener('resume', this.onActivity, this.options);
-            const hasOrientationAPI = 'orientation' in screen;
-            if (hasOrientationAPI) {
-                screen.orientation.addEventListener('change', this.onActivity, this.options);
-            }
-            window.addEventListener('pageshow', this.onActivity, this.options);
-            window.addEventListener('pagehide', this.onActivity, this.options);
-        }
-        catch (error) {
-            debugLog.warn('VisibilityListenerManager', 'Failed to setup mobile listeners', { error });
-        }
-    }
-    cleanupMobileEvents() {
-        try {
-            document.removeEventListener('pause', this.onVisibilityChange);
-            document.removeEventListener('resume', this.onActivity);
-            if ('orientation' in screen) {
-                screen.orientation.removeEventListener('change', this.onActivity);
-            }
-            window.removeEventListener('pageshow', this.onActivity);
-            window.removeEventListener('pagehide', this.onActivity);
-        }
-        catch (error) {
-            debugLog.warn('VisibilityListenerManager', 'Error during mobile listeners cleanup', { error });
-        }
-    }
 }

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

@@ -1,3 +1,13 @@
-export declare class ApiManager {
-    getUrl(id: string, allowHttp?: boolean): string;
-}
+/**
+ * Generates API URL for TraceLog service based on project ID
+ *
+ * Handles two special cases:
+ * - 'localhost:PORT' - for local development (generates http://localhost:PORT)
+ * - Regular project IDs - generates subdomain URLs via getApiUrl utility
+ *
+ * @param id Project ID or localhost address
+ * @param allowHttp Whether to allow HTTP protocol (default: false)
+ * @returns Generated API URL
+ * @throws Error if URL generation or validation fails
+ */
+export declare function getApiUrlForProject(id: string, allowHttp?: boolean): string;

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

@@ -1,10 +1,41 @@
 import { getApiUrl, isValidUrl } from '../utils';
-export class ApiManager {
-    getUrl(id, allowHttp = false) {
+import { SpecialProjectId } from '../types';
+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)
+ * - Regular project IDs - generates subdomain URLs via getApiUrl utility
+ *
+ * @param id Project ID or localhost address
+ * @param allowHttp Whether to allow HTTP protocol (default: false)
+ * @returns Generated API URL
+ * @throws Error if URL generation or validation fails
+ */
+export function getApiUrlForProject(id, allowHttp = false) {
+    try {
+        // Handle localhost development case
+        if (id.startsWith(SpecialProjectId.Localhost)) {
+            const url = `http://${id}`;
+            if (!isValidUrl(url, true)) {
+                throw new Error(`Invalid localhost URL format: ${id}`);
+            }
+            return url;
+        }
+        // Handle regular project ID case
         const url = getApiUrl(id, allowHttp);
         if (!isValidUrl(url, allowHttp)) {
-            throw new Error('Invalid URL');
+            throw new Error(`Generated API URL failed validation: ${url}`);
         }
         return url;
     }
+    catch (error) {
+        debugLog.error('ApiManager', 'API URL generation failed', {
+            projectId: id,
+            allowHttp,
+            error: error instanceof Error ? error.message : error,
+        });
+        throw error;
+    }
 }

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

@@ -1,7 +1,57 @@
 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)
+ *
+ * Supports special project IDs for development and testing:
+ * - 'skip': Bypasses all network calls, uses defaults
+ * - 'localhost:PORT': 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.
+     *
+     * @param apiUrl - Base URL for the configuration API
+     * @param appConfig - Client-side configuration from init()
+     * @returns Promise<Config> - Merged configuration object
+     */
     get(apiUrl: string, appConfig: AppConfig): Promise<Config>;
-    private load;
-    private getUrl;
-    private getDefaultConfig;
+    /**
+     * Loads configuration from API and merges with app config.
+     */
+    private loadFromApi;
+    /**
+     * Builds the configuration URL based on project type and QA mode.
+     */
+    private buildConfigUrl;
+    /**
+     * Builds request headers based on project configuration.
+     */
+    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.
+     */
+    private mergeConfigurations;
+    /**
+     * Creates default configuration for skip mode and fallback scenarios.
+     */
+    private createDefaultConfig;
 }

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$/];