@tracelog/lib 0.5.5 → 0.6.1

package/dist/esm/utils/validations/type-guards.utils.js

@@ -1,7 +1,38 @@
+import { MAX_NESTED_OBJECT_KEYS } from '../../constants';
 /**
- * Checks if an object contains only primitive fields (string, number, boolean, or string arrays)
+ * Validates if an item in an array is a valid nested object
+ * @param item - The item to validate
+ * @returns True if the item is a valid nested object
+ */
+const isValidArrayItem = (item) => {
+    if (typeof item === 'string') {
+        return true;
+    }
+    // Allow objects with primitive fields only (one level deep)
+    if (typeof item === 'object' && item !== null && !Array.isArray(item)) {
+        const entries = Object.entries(item);
+        // Check key count limit
+        if (entries.length > MAX_NESTED_OBJECT_KEYS) {
+            return false;
+        }
+        // All values must be primitives (no nested objects or arrays)
+        for (const [, value] of entries) {
+            if (value === null || value === undefined) {
+                continue;
+            }
+            const type = typeof value;
+            if (type !== 'string' && type !== 'number' && type !== 'boolean') {
+                return false;
+            }
+        }
+        return true;
+    }
+    return false;
+};
+/**
+ * Checks if an object contains only primitive fields, string arrays, or arrays of flat objects
  * @param object - The object to check
- * @returns True if the object contains only primitive fields
+ * @returns True if the object contains only valid fields
  */
 export const isOnlyPrimitiveFields = (object) => {
     if (typeof object !== 'object' || object === null) {
@@ -16,8 +47,23 @@ export const isOnlyPrimitiveFields = (object) => {
             continue;
         }
         if (Array.isArray(value)) {
-            if (!value.every((item) => typeof item === 'string')) {
-                return false;
+            if (value.length === 0) {
+                continue;
+            }
+            // Determine array type from first item
+            const firstItem = value[0];
+            const isStringArray = typeof firstItem === 'string';
+            // All items must be of the same type (all strings OR all objects)
+            if (isStringArray) {
+                if (!value.every((item) => typeof item === 'string')) {
+                    return false;
+                }
+            }
+            else {
+                // Must be all objects
+                if (!value.every((item) => isValidArrayItem(item))) {
+                    return false;
+                }
             }
             continue;
         }

package/package.json

@@ -2,7 +2,7 @@
   "name": "@tracelog/lib",
   "description": "JavaScript library for web analytics and real-time event tracking",
   "license": "MIT",
-  "version": "0.5.5",
+  "version": "0.6.1",
   "main": "./dist/cjs/public-api.js",
   "module": "./dist/esm/public-api.js",
   "types": "./dist/esm/public-api.d.ts",
@@ -43,6 +43,7 @@
     "serve": "http-server playground -p 3000 --cors",
     "playground:setup": "npm run build:browser:dev && cp dist/browser/tracelog.esm.js playground/tracelog.js",
     "playground:dev": "npm run playground:setup && npm run serve",
+    "playground:gh-pages": "npm run build:browser && cp dist/browser/tracelog.esm.js playground/tracelog.js",
     "test:e2e": "npm run build:browser:dev && cp dist/browser/tracelog.esm.js playground/tracelog.js && NODE_ENV=dev playwright test",
     "ci:build": "npm run build:all",
     "prepare": "husky",
@@ -55,7 +56,7 @@
     "changelog:preview": "node scripts/generate-changelog.js --dry-run"
   },
   "dependencies": {
-    "web-vitals": "^4.2.4"
+    "web-vitals": "4.2.4"
   },
   "devDependencies": {
     "@commitlint/config-conventional": "^19.8.1",

package/dist/cjs/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/cjs/app.types.js

@@ -1,12 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TagConditionType = exports.TagLogicalOperator = exports.TagConditionOperator = exports.ErrorType = exports.ScrollDirection = exports.DeviceType = exports.EventType = exports.Mode = void 0;
-var types_1 = require("./types");
-Object.defineProperty(exports, "Mode", { enumerable: true, get: function () { return types_1.Mode; } });
-Object.defineProperty(exports, "EventType", { enumerable: true, get: function () { return types_1.EventType; } });
-Object.defineProperty(exports, "DeviceType", { enumerable: true, get: function () { return types_1.DeviceType; } });
-Object.defineProperty(exports, "ScrollDirection", { enumerable: true, get: function () { return types_1.ScrollDirection; } });
-Object.defineProperty(exports, "ErrorType", { enumerable: true, get: function () { return types_1.ErrorType; } });
-Object.defineProperty(exports, "TagConditionOperator", { enumerable: true, get: function () { return types_1.TagConditionOperator; } });
-Object.defineProperty(exports, "TagLogicalOperator", { enumerable: true, get: function () { return types_1.TagLogicalOperator; } });
-Object.defineProperty(exports, "TagConditionType", { enumerable: true, get: function () { return types_1.TagConditionType; } });

package/dist/cjs/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/cjs/constants/api.constants.js

@@ -1,14 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_API_CONFIG = void 0;
-const config_constants_1 = require("./config.constants");
-/**
- * Default API configuration values
- * Used as fallback when API config is not available or incomplete
- */
-exports.DEFAULT_API_CONFIG = {
-    samplingRate: config_constants_1.DEFAULT_SAMPLING_RATE,
-    excludedUrlPaths: [],
-    tags: [],
-    ipExcluded: false,
-};

package/dist/cjs/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/cjs/managers/api.manager.js

@@ -1,44 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getApiUrlForProject = getApiUrlForProject;
-const utils_1 = require("../utils");
-const types_1 = require("../types");
-const logging_1 = require("../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
- */
-function getApiUrlForProject(id, allowHttp = false) {
-    try {
-        // Handle localhost development case (localhost:8080 or localhost:9999)
-        if (id === types_1.SpecialProjectId.Localhost || id === types_1.SpecialProjectId.Fail) {
-            const url = `http://${id}`;
-            if (!(0, utils_1.isValidUrl)(url, true)) {
-                throw new Error(`Invalid localhost URL format: ${id}`);
-            }
-            return url;
-        }
-        // Handle regular project ID case
-        const url = (0, utils_1.getApiUrl)(id, allowHttp);
-        if (!(0, utils_1.isValidUrl)(url, allowHttp)) {
-            throw new Error(`Generated API URL failed validation: ${url}`);
-        }
-        return url;
-    }
-    catch (error) {
-        logging_1.debugLog.error('ApiManager', 'API URL generation failed', {
-            projectId: id,
-            allowHttp,
-            error: error instanceof Error ? error.message : error,
-        });
-        throw error;
-    }
-}

package/dist/cjs/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/cjs/managers/config.builder.js

@@ -1,116 +0,0 @@
-"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

@@ -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/cjs/managers/config.manager.js

@@ -1,157 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ConfigManager = void 0;
-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 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
- */
-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 === types_1.SpecialProjectId.Skip ||
-            appConfig.id === types_1.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 = config_builder_1.ConfigBuilder.build(appConfig, finalApiConfig);
-        logging_1.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 (0, utils_1.fetchWithTimeout)(configUrl, {
-                method: 'GET',
-                headers,
-                timeout: constants_1.REQUEST_TIMEOUT_MS,
-            });
-            if (!response.ok) {
-                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-            }
-            const rawData = await this.parseJsonResponse(response);
-            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';
-            logging_1.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 === types_1.SpecialProjectId.Localhost || appConfig.id === types_1.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) {
-            logging_1.debugLog.info('ConfigManager', 'QA mode enabled via URL parameter');
-            return { ...apiConfig, mode: types_1.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: 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.PRODUCTION_DOMAINS = [/^https:\/\/.*\.tracelog\.app$/, /^https:\/\/.*\.tracelog\.dev$/];

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