@tracelog/lib 0.5.4 → 0.6.0

package/dist/cjs/utils/network/fetch-with-timeout.utils.d.ts

@@ -1,4 +0,0 @@
-export interface FetchWithTimeoutOptions extends RequestInit {
-    timeout?: number;
-}
-export declare function fetchWithTimeout(url: string, options?: FetchWithTimeoutOptions): Promise<Response>;

package/dist/cjs/utils/network/fetch-with-timeout.utils.js

@@ -1,25 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.fetchWithTimeout = fetchWithTimeout;
-async function fetchWithTimeout(url, options = {}) {
-    const { timeout = 10000, ...fetchOptions } = options;
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => {
-        controller.abort();
-    }, timeout);
-    try {
-        const response = await fetch(url, {
-            ...fetchOptions,
-            signal: controller.signal,
-        });
-        clearTimeout(timeoutId);
-        return response;
-    }
-    catch (error) {
-        clearTimeout(timeoutId);
-        if (error instanceof Error && error.name === 'AbortError') {
-            throw new Error(`Request timeout after ${timeout}ms`);
-        }
-        throw error;
-    }
-}

package/dist/cjs/utils/validations/url-validations.utils.d.ts

@@ -1,15 +0,0 @@
-/**
- * Validates if a URL is valid and optionally allows HTTP URLs
- * @param url - The URL to validate
- * @param allowHttp - Whether to allow HTTP URLs (default: false)
- * @returns True if the URL is valid, false otherwise
- */
-export declare const isValidUrl: (url: string, allowHttp?: boolean) => boolean;
-/**
- * Validates a URL field in configuration
- * @param url - The URL to validate
- * @param allowHttp - Whether to allow HTTP URLs
- * @param fieldName - The name of the field being validated
- * @param errors - Array to push errors to
- */
-export declare const validateUrl: (url: unknown, allowHttp: boolean | undefined, fieldName: string, errors: string[]) => void;

package/dist/cjs/utils/validations/url-validations.utils.js

@@ -1,47 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateUrl = exports.isValidUrl = void 0;
-/**
- * Validates if a URL is valid and optionally allows HTTP URLs
- * @param url - The URL to validate
- * @param allowHttp - Whether to allow HTTP URLs (default: false)
- * @returns True if the URL is valid, false otherwise
- */
-const isValidUrl = (url, allowHttp = false) => {
-    try {
-        const parsed = new URL(url);
-        const isHttps = parsed.protocol === 'https:';
-        const isHttp = parsed.protocol === 'http:';
-        return isHttps || (allowHttp && isHttp);
-    }
-    catch {
-        return false;
-    }
-};
-exports.isValidUrl = isValidUrl;
-/**
- * Validates a URL field in configuration
- * @param url - The URL to validate
- * @param allowHttp - Whether to allow HTTP URLs
- * @param fieldName - The name of the field being validated
- * @param errors - Array to push errors to
- */
-const validateUrl = (url, allowHttp, fieldName, errors) => {
-    if (url !== undefined) {
-        if (typeof url === 'string') {
-            try {
-                const parsed = new URL(url);
-                if (parsed.protocol === 'http:' && !allowHttp) {
-                    errors.push(`${fieldName} using http requires allowHttp=true`);
-                }
-            }
-            catch {
-                errors.push(`${fieldName} must be a valid URL`);
-            }
-        }
-        else {
-            errors.push(`${fieldName} must be a string`);
-        }
-    }
-};
-exports.validateUrl = validateUrl;

package/dist/esm/app.types.d.ts

@@ -1,2 +0,0 @@
-export { Mode, EventType, DeviceType, ScrollDirection, ErrorType, TagConditionOperator, TagLogicalOperator, TagConditionType, } from './types';
-export type { ScrollData, ClickData, CustomEventData, MetadataType, WebVitalsData, ErrorData, PageViewData, UTM, EventLocation, EventData, AppConfig, ApiConfig, ExtendedEventsQueueDto, TagConfig, BaseEventsQueueDto, WebVitalType, SessionEndReason, } from './types';

package/dist/esm/app.types.js

@@ -1 +0,0 @@
-export { Mode, EventType, DeviceType, ScrollDirection, ErrorType, TagConditionOperator, TagLogicalOperator, TagConditionType, } from './types';

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

@@ -1,6 +0,0 @@
-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;

package/dist/esm/constants/api.constants.js

@@ -1,11 +0,0 @@
-import { DEFAULT_SAMPLING_RATE } from './config.constants';
-/**
- * Default API configuration values
- * Used as fallback when API config is not available or incomplete
- */
-export const DEFAULT_API_CONFIG = {
-    samplingRate: DEFAULT_SAMPLING_RATE,
-    excludedUrlPaths: [],
-    tags: [],
-    ipExcluded: false,
-};

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

@@ -1,13 +0,0 @@
-/**
- * Generates API URL for TraceLog service based on project ID
- *
- * Handles two special cases:
- * - '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
- * @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,41 +0,0 @@
-import { getApiUrl, isValidUrl } from '../utils';
-import { SpecialProjectId } from '../types';
-import { debugLog } from '../utils/logging';
-/**
- * Generates API URL for TraceLog service based on project ID
- *
- * Handles two special cases:
- * - '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
- * @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 (localhost:8080 or localhost:9999)
-        if (id === SpecialProjectId.Localhost || id === SpecialProjectId.Fail) {
-            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(`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.builder.d.ts

@@ -1,33 +0,0 @@
-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;
-}

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

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

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

@@ -1,56 +0,0 @@
-import { AppConfig, Config } from '../types';
-/**
- * Configuration manager responsible for loading and merging application configuration.
- *
- * 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:8080': Loads config from local development server
- */
-export declare class ConfigManager {
-    private static readonly PRODUCTION_DOMAINS;
-    /**
-     * 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
-     */
-    get(apiUrl: string, appConfig: AppConfig): Promise<Config>;
-    /**
-     * Loads configuration from API and returns sanitized API config.
-     * Only returns values explicitly provided by the API.
-     */
-    private loadFromApi;
-    /**
-     * Builds the configuration URL based on project type and QA mode.
-     */
-    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;
-    /**
-     * Checks if QA mode is enabled via URL parameter.
-     */
-    private isQaModeEnabled;
-    /**
-     * Applies QA mode to API config if enabled via URL parameter.
-     */
-    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/esm/managers/config.manager.js

@@ -1,153 +0,0 @@
-import { DEFAULT_API_CONFIG, REQUEST_TIMEOUT_MS } from '../constants';
-import { Mode, SpecialProjectId } from '../types';
-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 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:8080': Loads config from local development server
- */
-export class ConfigManager {
-    /**
-     * 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 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 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: config.id,
-            mode: config.mode,
-            hasTags: !!config.tags?.length,
-            hasExclusions: !!config.excludedUrlPaths?.length,
-        });
-        return config;
-    }
-    /**
-     * Loads configuration from API and returns sanitized API config.
-     * Only returns values explicitly provided by the API.
-     */
-    async loadFromApi(apiUrl, appConfig) {
-        try {
-            const configUrl = this.buildConfigUrl(apiUrl, appConfig);
-            const headers = this.buildHeaders(appConfig);
-            const response = await fetchWithTimeout(configUrl, {
-                method: 'GET',
-                headers,
-                timeout: REQUEST_TIMEOUT_MS,
-            });
-            if (!response.ok) {
-                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-            }
-            const rawData = await this.parseJsonResponse(response);
-            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';
-            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 === SpecialProjectId.Localhost || appConfig.id === SpecialProjectId.Fail;
-        if (isLocalhost) {
-            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.
-     * Always includes X-TraceLog-Project header for consistent identification.
-     */
-    buildHeaders(appConfig) {
-        return {
-            'Content-Type': 'application/json',
-            'X-TraceLog-Project': appConfig.id,
-        };
-    }
-    /**
-     * 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;
-    }
-    /**
-     * Checks if QA mode is enabled via URL parameter.
-     */
-    isQaModeEnabled() {
-        const params = new URLSearchParams(window.location.search);
-        return params.get('qaMode') === 'true';
-    }
-    /**
-     * Applies QA mode to API config if enabled via URL parameter.
-     */
-    applyQaModeIfEnabled(apiConfig) {
-        if (this.isQaModeEnabled() && !apiConfig.mode) {
-            debugLog.info('ConfigManager', 'QA mode enabled via URL parameter');
-            return { ...apiConfig, mode: Mode.QA };
-        }
-        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) {
-        // 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.PRODUCTION_DOMAINS = [/^https:\/\/.*\.tracelog\.app$/, /^https:\/\/.*\.tracelog\.dev$/];

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

@@ -1,36 +0,0 @@
-import { DeviceType, EventData } from '../types';
-import { StateManager } from './state.manager';
-export declare class TagsManager extends StateManager {
-    /**
-     * Gets matching tag IDs for an event based on configured tag conditions
-     */
-    getEventTagsIds(event: EventData, deviceType: DeviceType): string[];
-    /**
-     * Evaluates all conditions for a tag using logical operators
-     */
-    private evaluateTagConditions;
-    /**
-     * Evaluates a single tag condition
-     */
-    private evaluateCondition;
-    /**
-     * Unified string matching logic for all string-based conditions
-     */
-    private matchStringCondition;
-    /**
-     * Element-specific matching logic with optimized data extraction
-     */
-    private matchElementCondition;
-    /**
-     * Exact field matching for element EQUALS operations
-     */
-    private matchElementFieldExact;
-    /**
-     * Builds searchable element data string with null safety
-     */
-    private buildElementDataString;
-    /**
-     * Safe regex testing with error handling
-     */
-    private testRegex;
-}