@tracelog/lib 0.0.1

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

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageManager = void 0;
+const logging_1 = require("../utils/logging");
+class StorageManager {
+    constructor() {
+        this.storage = null;
+        this.fallbackStorage = new Map();
+        this.storageAvailable = false;
+        this.storage = this.init();
+        this.storageAvailable = this.storage !== null;
+        if (!this.storageAvailable) {
+            logging_1.debugLog.warn('StorageManager', 'localStorage not available, using memory fallback');
+        }
+    }
+    getItem(key) {
+        if (!this.storageAvailable) {
+            return this.fallbackStorage.get(key) ?? null;
+        }
+        try {
+            if (this.storage) {
+                return this.storage.getItem(key);
+            }
+            return this.fallbackStorage.get(key) ?? null;
+        }
+        catch (error) {
+            logging_1.debugLog.warn('StorageManager', 'Storage getItem failed, using memory fallback', { key, error });
+            this.storageAvailable = false;
+            return this.fallbackStorage.get(key) ?? null;
+        }
+    }
+    setItem(key, value) {
+        if (!this.storageAvailable) {
+            this.fallbackStorage.set(key, value);
+            return;
+        }
+        try {
+            if (this.storage) {
+                this.storage.setItem(key, value);
+                return;
+            }
+            this.fallbackStorage.set(key, value);
+        }
+        catch (error) {
+            logging_1.debugLog.warn('StorageManager', 'Storage setItem failed, using memory fallback', { key, error });
+            this.storageAvailable = false;
+            this.fallbackStorage.set(key, value);
+        }
+    }
+    removeItem(key) {
+        if (!this.storageAvailable) {
+            this.fallbackStorage.delete(key);
+            return;
+        }
+        try {
+            if (this.storage) {
+                this.storage.removeItem(key);
+                return;
+            }
+            this.fallbackStorage.delete(key);
+        }
+        catch (error) {
+            logging_1.debugLog.warn('StorageManager', 'Storage removeItem failed, using memory fallback', { key, error });
+            this.storageAvailable = false;
+            this.fallbackStorage.delete(key);
+        }
+    }
+    init() {
+        try {
+            const test = '__storage_test__';
+            const storage = window['localStorage'];
+            storage.setItem(test, test);
+            storage.removeItem(test);
+            return storage;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+exports.StorageManager = StorageManager;

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

@@ -0,0 +1,12 @@
+import { DeviceType, EventData } from '../types';
+import { StateManager } from './state.manager';
+export declare class TagsManager extends StateManager {
+    getEventTagsIds(event: EventData, deviceType: DeviceType): string[];
+    private checkEventTypePageView;
+    private checkEventTypeClick;
+    private matchUrlMatches;
+    private matchDeviceType;
+    private matchElementSelector;
+    private matchUtmCondition;
+    private checkElementFieldEquals;
+}

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

@@ -0,0 +1,289 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TagsManager = void 0;
+const types_1 = require("../types");
+const state_manager_1 = require("./state.manager");
+class TagsManager extends state_manager_1.StateManager {
+    getEventTagsIds(event, deviceType) {
+        switch (event.type) {
+            case types_1.EventType.PAGE_VIEW: {
+                return this.checkEventTypePageView(event, deviceType);
+            }
+            case types_1.EventType.CLICK: {
+                return this.checkEventTypeClick(event, deviceType);
+            }
+            default: {
+                return [];
+            }
+        }
+    }
+    checkEventTypePageView(event, deviceType) {
+        const tags = this.get('config')?.tags?.filter((tag) => tag.triggerType === types_1.EventType.PAGE_VIEW) ?? [];
+        if (tags.length === 0) {
+            return [];
+        }
+        const matchedTagIds = [];
+        for (const tag of tags) {
+            const { id, logicalOperator, conditions } = tag;
+            const results = [];
+            for (const condition of conditions) {
+                switch (condition.type) {
+                    case types_1.TagConditionType.URL_MATCHES: {
+                        results.push(this.matchUrlMatches(condition, event.page_url));
+                        break;
+                    }
+                    case types_1.TagConditionType.DEVICE_TYPE: {
+                        results.push(this.matchDeviceType(condition, deviceType));
+                        break;
+                    }
+                    case types_1.TagConditionType.UTM_SOURCE: {
+                        results.push(this.matchUtmCondition(condition, event.utm?.source));
+                        break;
+                    }
+                    case types_1.TagConditionType.UTM_MEDIUM: {
+                        results.push(this.matchUtmCondition(condition, event.utm?.medium));
+                        break;
+                    }
+                    case types_1.TagConditionType.UTM_CAMPAIGN: {
+                        results.push(this.matchUtmCondition(condition, event.utm?.campaign));
+                        break;
+                    }
+                }
+            }
+            let isMatch = false;
+            isMatch = logicalOperator === types_1.TagLogicalOperator.AND ? results.every(Boolean) : results.some(Boolean);
+            if (isMatch) {
+                matchedTagIds.push(id);
+            }
+        }
+        return matchedTagIds;
+    }
+    checkEventTypeClick(event, deviceType) {
+        const tags = this.get('config')?.tags?.filter((tag) => tag.triggerType === types_1.EventType.CLICK) ?? [];
+        if (tags.length === 0) {
+            return [];
+        }
+        const matchedTagIds = [];
+        for (const tag of tags) {
+            const { id, logicalOperator, conditions } = tag;
+            const results = [];
+            for (const condition of conditions) {
+                if (!event.click_data) {
+                    results.push(false);
+                    continue;
+                }
+                const clickData = event.click_data;
+                switch (condition.type) {
+                    case types_1.TagConditionType.ELEMENT_MATCHES: {
+                        results.push(this.matchElementSelector(condition, clickData));
+                        break;
+                    }
+                    case types_1.TagConditionType.DEVICE_TYPE: {
+                        results.push(this.matchDeviceType(condition, deviceType));
+                        break;
+                    }
+                    case types_1.TagConditionType.URL_MATCHES: {
+                        results.push(this.matchUrlMatches(condition, event.page_url));
+                        break;
+                    }
+                    case types_1.TagConditionType.UTM_SOURCE: {
+                        results.push(this.matchUtmCondition(condition, event.utm?.source));
+                        break;
+                    }
+                    case types_1.TagConditionType.UTM_MEDIUM: {
+                        results.push(this.matchUtmCondition(condition, event.utm?.medium));
+                        break;
+                    }
+                    case types_1.TagConditionType.UTM_CAMPAIGN: {
+                        results.push(this.matchUtmCondition(condition, event.utm?.campaign));
+                        break;
+                    }
+                }
+            }
+            let isMatch = false;
+            isMatch = logicalOperator === types_1.TagLogicalOperator.AND ? results.every(Boolean) : results.some(Boolean);
+            if (isMatch) {
+                matchedTagIds.push(id);
+            }
+        }
+        return matchedTagIds;
+    }
+    matchUrlMatches(condition, url) {
+        if (condition.type !== types_1.TagConditionType.URL_MATCHES) {
+            return false;
+        }
+        const targetValue = condition.value.toLowerCase();
+        const targetUrl = url.toLowerCase();
+        switch (condition.operator) {
+            case types_1.TagConditionOperator.EQUALS: {
+                return targetUrl === targetValue;
+            }
+            case types_1.TagConditionOperator.CONTAINS: {
+                return targetUrl.includes(targetValue);
+            }
+            case types_1.TagConditionOperator.STARTS_WITH: {
+                return targetUrl.startsWith(targetValue);
+            }
+            case types_1.TagConditionOperator.ENDS_WITH: {
+                return targetUrl.endsWith(targetValue);
+            }
+            case types_1.TagConditionOperator.REGEX: {
+                try {
+                    const regex = new RegExp(targetValue, 'gi');
+                    return regex.test(targetUrl);
+                }
+                catch {
+                    return false;
+                }
+            }
+            default: {
+                return false;
+            }
+        }
+    }
+    matchDeviceType(condition, deviceType) {
+        if (condition.type !== types_1.TagConditionType.DEVICE_TYPE) {
+            return false;
+        }
+        const targetValue = condition.value.toLowerCase();
+        const targetDevice = deviceType.toLowerCase();
+        switch (condition.operator) {
+            case types_1.TagConditionOperator.EQUALS: {
+                return targetDevice === targetValue;
+            }
+            case types_1.TagConditionOperator.CONTAINS: {
+                return targetDevice.includes(targetValue);
+            }
+            case types_1.TagConditionOperator.STARTS_WITH: {
+                return targetDevice.startsWith(targetValue);
+            }
+            case types_1.TagConditionOperator.ENDS_WITH: {
+                return targetDevice.endsWith(targetValue);
+            }
+            case types_1.TagConditionOperator.REGEX: {
+                try {
+                    const regex = new RegExp(targetValue, 'gi');
+                    return regex.test(targetDevice);
+                }
+                catch {
+                    return false;
+                }
+            }
+            default: {
+                return false;
+            }
+        }
+    }
+    matchElementSelector(condition, clickData) {
+        if (condition.type !== types_1.TagConditionType.ELEMENT_MATCHES) {
+            return false;
+        }
+        const elementData = [
+            clickData.id ?? '',
+            clickData.class ?? '',
+            clickData.tag ?? '',
+            clickData.text ?? '',
+            clickData.href ?? '',
+            clickData.title ?? '',
+            clickData.alt ?? '',
+            clickData.role ?? '',
+            clickData.ariaLabel ?? '',
+            ...Object.values(clickData.dataAttributes ?? {}),
+        ].join(' ');
+        const targetValue = condition.value.toLowerCase();
+        const targetElementData = elementData.toLowerCase();
+        switch (condition.operator) {
+            case types_1.TagConditionOperator.EQUALS: {
+                return this.checkElementFieldEquals(clickData, targetValue);
+            }
+            case types_1.TagConditionOperator.CONTAINS: {
+                return targetElementData.includes(targetValue);
+            }
+            case types_1.TagConditionOperator.STARTS_WITH: {
+                return targetElementData.startsWith(targetValue);
+            }
+            case types_1.TagConditionOperator.ENDS_WITH: {
+                return targetElementData.endsWith(targetValue);
+            }
+            case types_1.TagConditionOperator.REGEX: {
+                try {
+                    const regex = new RegExp(targetValue, 'gi');
+                    return regex.test(targetElementData);
+                }
+                catch {
+                    return false;
+                }
+            }
+            default: {
+                return false;
+            }
+        }
+    }
+    matchUtmCondition(condition, utmValue) {
+        if (![types_1.TagConditionType.UTM_SOURCE, types_1.TagConditionType.UTM_MEDIUM, types_1.TagConditionType.UTM_CAMPAIGN].includes(condition.type)) {
+            return false;
+        }
+        const value = utmValue ?? '';
+        const targetValue = condition.value.toLowerCase();
+        const targetUtmValue = value.toLowerCase();
+        switch (condition.operator) {
+            case types_1.TagConditionOperator.EQUALS: {
+                return targetUtmValue === targetValue;
+            }
+            case types_1.TagConditionOperator.CONTAINS: {
+                return targetUtmValue.includes(targetValue);
+            }
+            case types_1.TagConditionOperator.STARTS_WITH: {
+                return targetUtmValue.startsWith(targetValue);
+            }
+            case types_1.TagConditionOperator.ENDS_WITH: {
+                return targetUtmValue.endsWith(targetValue);
+            }
+            case types_1.TagConditionOperator.REGEX: {
+                try {
+                    const regex = new RegExp(targetValue, 'gi');
+                    return regex.test(targetUtmValue);
+                }
+                catch {
+                    return false;
+                }
+            }
+            default: {
+                return false;
+            }
+        }
+    }
+    checkElementFieldEquals(clickData, targetValue) {
+        const fields = [
+            clickData.id,
+            clickData.class,
+            clickData.tag,
+            clickData.text,
+            clickData.href,
+            clickData.title,
+            clickData.alt,
+            clickData.role,
+            clickData.ariaLabel,
+        ];
+        for (const field of fields) {
+            if (field) {
+                const fieldValue = field.toLowerCase();
+                const target = targetValue.toLowerCase();
+                if (fieldValue === target) {
+                    return true;
+                }
+            }
+        }
+        if (clickData.dataAttributes) {
+            for (const dataValue of Object.values(clickData.dataAttributes)) {
+                const fieldValue = dataValue.toLowerCase();
+                const target = targetValue.toLowerCase();
+                if (fieldValue === target) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+}
+exports.TagsManager = TagsManager;

package/dist/cjs/managers/user.manager.d.ts

@@ -0,0 +1,7 @@
+import { StateManager } from './state.manager';
+import { StorageManager } from './storage.manager';
+export declare class UserManager extends StateManager {
+    private readonly storageManager;
+    constructor(storageManager: StorageManager);
+    getId(): string;
+}

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

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserManager = void 0;
+const constants_1 = require("../constants");
+const utils_1 = require("../utils");
+const state_manager_1 = require("./state.manager");
+class UserManager extends state_manager_1.StateManager {
+    constructor(storageManager) {
+        super();
+        this.storageManager = storageManager;
+    }
+    getId() {
+        const storedUserId = this.storageManager.getItem((0, constants_1.USER_ID_KEY)(this.get('config')?.id));
+        if (storedUserId) {
+            return storedUserId;
+        }
+        const newUserId = (0, utils_1.generateUUID)();
+        this.storageManager.setItem((0, constants_1.USER_ID_KEY)(this.get('config')?.id), newUserId);
+        return newUserId;
+    }
+}
+exports.UserManager = UserManager;

package/dist/cjs/public-api.d.ts

@@ -0,0 +1 @@
+export * as TraceLog from './api';

package/dist/cjs/public-api.js

@@ -0,0 +1,37 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TraceLog = void 0;
+exports.TraceLog = __importStar(require("./api"));

package/dist/cjs/types/api.types.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Special project IDs for testing and development
+ *
+ * Both automatically force mode: 'debug' but differ in HTTP behavior:
+ * - HttpSkip: NO network calls (pure offline testing)
+ * - HttpLocal: Makes network calls to local server (integration testing)
+ */
+export declare enum SpecialProjectId {
+    /**
+     * Skips ALL HTTP calls - no config fetch, no event sending
+     * Uses default local config, forces debug mode
+     * Perfect for pure offline E2E testing
+     */
+    HttpSkip = "http-skip",
+    /**
+     * Makes HTTP calls to window.location.origin instead of production API
+     * Fetches config and sends events to local server, forces debug mode
+     * Perfect for local development with running middleware
+     */
+    HttpLocal = "http-local"
+}

package/dist/cjs/types/api.types.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpecialProjectId = void 0;
+/**
+ * Special project IDs for testing and development
+ *
+ * Both automatically force mode: 'debug' but differ in HTTP behavior:
+ * - HttpSkip: NO network calls (pure offline testing)
+ * - HttpLocal: Makes network calls to local server (integration testing)
+ */
+var SpecialProjectId;
+(function (SpecialProjectId) {
+    /**
+     * Skips ALL HTTP calls - no config fetch, no event sending
+     * Uses default local config, forces debug mode
+     * Perfect for pure offline E2E testing
+     */
+    SpecialProjectId["HttpSkip"] = "http-skip";
+    /**
+     * Makes HTTP calls to window.location.origin instead of production API
+     * Fetches config and sends events to local server, forces debug mode
+     * Perfect for local development with running middleware
+     */
+    SpecialProjectId["HttpLocal"] = "http-local";
+})(SpecialProjectId || (exports.SpecialProjectId = SpecialProjectId = {}));

package/dist/cjs/types/common.types.d.ts

@@ -0,0 +1 @@
+export type MetadataType = string | number | boolean | string[];

package/dist/cjs/types/common.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/types/config.types.d.ts

@@ -0,0 +1,104 @@
+import { MetadataType } from './common.types';
+import { TagConfig } from './tag.types';
+import { Mode } from './mode.types';
+export type Config = ApiConfig & AppConfig;
+export interface ApiConfig {
+    /**
+     * Logging mode for the library.
+     * - 'qa': Shows client-facing logs only (INFO, CLIENT_WARN, CLIENT_ERROR)
+     * - 'debug': Shows all logs including internal library errors
+     */
+    mode?: Mode;
+    /**
+     * Sampling rate as a percentage (0-1) to control how many events are sent.
+     * A value of 1 means all events are sent, while 0.5 means only half of events are sent.
+     */
+    samplingRate?: number;
+    /**
+     * Array of tag configurations for categorizing and filtering events.
+     * Tags help organize and segment tracking data for analysis.
+     */
+    tags?: TagConfig[];
+    /**
+     * Array of URL path patterns to exclude from tracking.
+     * Events will not be sent for pages matching these patterns.
+     */
+    excludedUrlPaths?: string[];
+    /**
+     * Flag to indicate if IP addresses should be excluded from tracking.
+     * When true, IP addresses will not be collected or sent with events.
+     * This is useful for privacy compliance and reducing data exposure.
+     */
+    ipExcluded?: boolean;
+}
+export interface AppConfig {
+    /**
+     * Unique project identifier.
+     */
+    id: string;
+    /**
+     * Session timeout in milliseconds. After this period of inactivity,
+     * a new session will be started for subsequent events.
+     *
+     * **Timeout Guidelines:**
+     * - **15 minutes (default)**: Recommended for most applications, aligns with security best practices
+     * - **30 minutes**: Standard for content-heavy sites (matches Google Analytics default)
+     * - **45-60 minutes**: Consider for sites with long-form content, videos, or documentation
+     * - **5-10 minutes**: Use for security-sensitive applications requiring frequent re-authentication
+     *
+     * **Impact on Analytics:**
+     * - Shorter timeouts = Higher session count, higher bounce rate, potentially lower conversion rates
+     * - Longer timeouts = Lower session count, more accurate user journey tracking, better conversion attribution
+     *
+     * **When to Adjust:**
+     * - Match your application's auto-logout timeout if applicable
+     * - Increase for content where users frequently pause (tutorials, long articles, videos)
+     * - Decrease for applications with sensitive data or frequent security requirements
+     * - Monitor bounce rates and conversion funnels when changing this value
+     *
+     * @default 900000 (15 minutes)
+     * @min 30000 (30 seconds)
+     * @max 86400000 (24 hours)
+     */
+    sessionTimeout?: number;
+    /**
+     * Metadata that will be automatically attached to all tracking events.
+     * These key-value pairs provide additional context for every event sent.
+     */
+    globalMetadata?: Record<string, MetadataType>;
+    /**
+     * CSS selectors for custom scroll containers. Can be a single selector string
+     * or an array of selectors. Used to track scroll events within specific elements
+     * instead of the default window scroll.
+     */
+    scrollContainerSelectors?: string | string[];
+    /**
+     * Allow HTTP requests to be made. This is useful for testing and development.
+     */
+    allowHttp?: boolean;
+    /**
+     * Array of query parameters to be removed from the URL.
+     */
+    sensitiveQueryParams?: string[];
+    /**
+     * Sampling rate for error events (0-1).
+     * Controls how many error and network error events are captured.
+     * @default 0.1 for production, 1.0 for qa/debug mode
+     */
+    errorSampling?: number;
+    /**
+     * Optional integrations configuration.
+     */
+    integrations?: {
+        /**
+         * Google Analytics integration configuration.
+         */
+        googleAnalytics?: {
+            /**
+             * Google Analytics measurement ID.
+             * Required for initializing the Google Analytics integration.
+             */
+            measurementId: string;
+        };
+    };
+}

package/dist/cjs/types/config.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/types/device.types.d.ts

@@ -0,0 +1,6 @@
+export declare enum DeviceType {
+    Mobile = "mobile",
+    Tablet = "tablet",
+    Desktop = "desktop",
+    Unknown = "unknown"
+}

package/dist/cjs/types/device.types.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeviceType = void 0;
+var DeviceType;
+(function (DeviceType) {
+    DeviceType["Mobile"] = "mobile";
+    DeviceType["Tablet"] = "tablet";
+    DeviceType["Desktop"] = "desktop";
+    DeviceType["Unknown"] = "unknown";
+})(DeviceType || (exports.DeviceType = DeviceType = {}));