@tracelog/lib 0.0.1

package/dist/esm/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/esm/managers/tags.manager.js

@@ -0,0 +1,285 @@
+import { EventType, TagConditionOperator, TagConditionType, TagLogicalOperator, } from '../types';
+import { StateManager } from './state.manager';
+export class TagsManager extends StateManager {
+    getEventTagsIds(event, deviceType) {
+        switch (event.type) {
+            case EventType.PAGE_VIEW: {
+                return this.checkEventTypePageView(event, deviceType);
+            }
+            case EventType.CLICK: {
+                return this.checkEventTypeClick(event, deviceType);
+            }
+            default: {
+                return [];
+            }
+        }
+    }
+    checkEventTypePageView(event, deviceType) {
+        const tags = this.get('config')?.tags?.filter((tag) => tag.triggerType === 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 TagConditionType.URL_MATCHES: {
+                        results.push(this.matchUrlMatches(condition, event.page_url));
+                        break;
+                    }
+                    case TagConditionType.DEVICE_TYPE: {
+                        results.push(this.matchDeviceType(condition, deviceType));
+                        break;
+                    }
+                    case TagConditionType.UTM_SOURCE: {
+                        results.push(this.matchUtmCondition(condition, event.utm?.source));
+                        break;
+                    }
+                    case TagConditionType.UTM_MEDIUM: {
+                        results.push(this.matchUtmCondition(condition, event.utm?.medium));
+                        break;
+                    }
+                    case TagConditionType.UTM_CAMPAIGN: {
+                        results.push(this.matchUtmCondition(condition, event.utm?.campaign));
+                        break;
+                    }
+                }
+            }
+            let isMatch = false;
+            isMatch = logicalOperator === 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 === 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 TagConditionType.ELEMENT_MATCHES: {
+                        results.push(this.matchElementSelector(condition, clickData));
+                        break;
+                    }
+                    case TagConditionType.DEVICE_TYPE: {
+                        results.push(this.matchDeviceType(condition, deviceType));
+                        break;
+                    }
+                    case TagConditionType.URL_MATCHES: {
+                        results.push(this.matchUrlMatches(condition, event.page_url));
+                        break;
+                    }
+                    case TagConditionType.UTM_SOURCE: {
+                        results.push(this.matchUtmCondition(condition, event.utm?.source));
+                        break;
+                    }
+                    case TagConditionType.UTM_MEDIUM: {
+                        results.push(this.matchUtmCondition(condition, event.utm?.medium));
+                        break;
+                    }
+                    case TagConditionType.UTM_CAMPAIGN: {
+                        results.push(this.matchUtmCondition(condition, event.utm?.campaign));
+                        break;
+                    }
+                }
+            }
+            let isMatch = false;
+            isMatch = logicalOperator === TagLogicalOperator.AND ? results.every(Boolean) : results.some(Boolean);
+            if (isMatch) {
+                matchedTagIds.push(id);
+            }
+        }
+        return matchedTagIds;
+    }
+    matchUrlMatches(condition, url) {
+        if (condition.type !== TagConditionType.URL_MATCHES) {
+            return false;
+        }
+        const targetValue = condition.value.toLowerCase();
+        const targetUrl = url.toLowerCase();
+        switch (condition.operator) {
+            case TagConditionOperator.EQUALS: {
+                return targetUrl === targetValue;
+            }
+            case TagConditionOperator.CONTAINS: {
+                return targetUrl.includes(targetValue);
+            }
+            case TagConditionOperator.STARTS_WITH: {
+                return targetUrl.startsWith(targetValue);
+            }
+            case TagConditionOperator.ENDS_WITH: {
+                return targetUrl.endsWith(targetValue);
+            }
+            case 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 !== TagConditionType.DEVICE_TYPE) {
+            return false;
+        }
+        const targetValue = condition.value.toLowerCase();
+        const targetDevice = deviceType.toLowerCase();
+        switch (condition.operator) {
+            case TagConditionOperator.EQUALS: {
+                return targetDevice === targetValue;
+            }
+            case TagConditionOperator.CONTAINS: {
+                return targetDevice.includes(targetValue);
+            }
+            case TagConditionOperator.STARTS_WITH: {
+                return targetDevice.startsWith(targetValue);
+            }
+            case TagConditionOperator.ENDS_WITH: {
+                return targetDevice.endsWith(targetValue);
+            }
+            case 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 !== 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 TagConditionOperator.EQUALS: {
+                return this.checkElementFieldEquals(clickData, targetValue);
+            }
+            case TagConditionOperator.CONTAINS: {
+                return targetElementData.includes(targetValue);
+            }
+            case TagConditionOperator.STARTS_WITH: {
+                return targetElementData.startsWith(targetValue);
+            }
+            case TagConditionOperator.ENDS_WITH: {
+                return targetElementData.endsWith(targetValue);
+            }
+            case TagConditionOperator.REGEX: {
+                try {
+                    const regex = new RegExp(targetValue, 'gi');
+                    return regex.test(targetElementData);
+                }
+                catch {
+                    return false;
+                }
+            }
+            default: {
+                return false;
+            }
+        }
+    }
+    matchUtmCondition(condition, utmValue) {
+        if (![TagConditionType.UTM_SOURCE, TagConditionType.UTM_MEDIUM, TagConditionType.UTM_CAMPAIGN].includes(condition.type)) {
+            return false;
+        }
+        const value = utmValue ?? '';
+        const targetValue = condition.value.toLowerCase();
+        const targetUtmValue = value.toLowerCase();
+        switch (condition.operator) {
+            case TagConditionOperator.EQUALS: {
+                return targetUtmValue === targetValue;
+            }
+            case TagConditionOperator.CONTAINS: {
+                return targetUtmValue.includes(targetValue);
+            }
+            case TagConditionOperator.STARTS_WITH: {
+                return targetUtmValue.startsWith(targetValue);
+            }
+            case TagConditionOperator.ENDS_WITH: {
+                return targetUtmValue.endsWith(targetValue);
+            }
+            case 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;
+    }
+}

package/dist/esm/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/esm/managers/user.manager.js

@@ -0,0 +1,18 @@
+import { USER_ID_KEY } from '../constants';
+import { generateUUID } from '../utils';
+import { StateManager } from './state.manager';
+export class UserManager extends StateManager {
+    constructor(storageManager) {
+        super();
+        this.storageManager = storageManager;
+    }
+    getId() {
+        const storedUserId = this.storageManager.getItem(USER_ID_KEY(this.get('config')?.id));
+        if (storedUserId) {
+            return storedUserId;
+        }
+        const newUserId = generateUUID();
+        this.storageManager.setItem(USER_ID_KEY(this.get('config')?.id), newUserId);
+        return newUserId;
+    }
+}

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

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

package/dist/esm/public-api.js

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

package/dist/esm/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/esm/types/api.types.js

@@ -0,0 +1,22 @@
+/**
+ * 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 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 || (SpecialProjectId = {}));

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

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

package/dist/esm/types/common.types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/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/esm/types/config.types.js

@@ -0,0 +1 @@
+export {};

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

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

package/dist/esm/types/device.types.js

@@ -0,0 +1,7 @@
+export var DeviceType;
+(function (DeviceType) {
+    DeviceType["Mobile"] = "mobile";
+    DeviceType["Tablet"] = "tablet";
+    DeviceType["Desktop"] = "desktop";
+    DeviceType["Unknown"] = "unknown";
+})(DeviceType || (DeviceType = {}));

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

@@ -0,0 +1,104 @@
+import { MetadataType } from './common.types';
+import { SessionEndReason } from './session.types';
+export type WebVitalType = 'LCP' | 'CLS' | 'INP' | 'FCP' | 'TTFB' | 'LONG_TASK';
+export declare enum EventType {
+    PAGE_VIEW = "page_view",
+    CLICK = "click",
+    SCROLL = "scroll",
+    SESSION_START = "session_start",
+    SESSION_END = "session_end",
+    CUSTOM = "custom",
+    WEB_VITALS = "web_vitals",
+    ERROR = "error"
+}
+export declare enum ScrollDirection {
+    UP = "up",
+    DOWN = "down"
+}
+export declare enum ErrorType {
+    JS_ERROR = "js_error",
+    PROMISE_REJECTION = "promise_rejection",
+    NETWORK_ERROR = "network_error"
+}
+export interface ScrollData {
+    depth: number;
+    direction: ScrollDirection;
+}
+export interface ClickData {
+    x: number;
+    y: number;
+    relativeX: number;
+    relativeY: number;
+    id?: string;
+    class?: string;
+    tag?: string;
+    text?: string;
+    href?: string;
+    title?: string;
+    alt?: string;
+    role?: string;
+    ariaLabel?: string;
+    dataAttributes?: Record<string, string>;
+}
+export interface ClickCoordinates {
+    x: number;
+    y: number;
+    relativeX: number;
+    relativeY: number;
+}
+export interface ClickTrackingElementData {
+    element: HTMLElement;
+    name: string;
+    value?: string;
+}
+export interface CustomEventData {
+    name: string;
+    metadata?: Record<string, MetadataType>;
+}
+export interface WebVitalsData {
+    type: WebVitalType;
+    value: number;
+}
+export interface ErrorData {
+    type: ErrorType;
+    message: string;
+    method?: string;
+    url?: string;
+    status?: number;
+    statusText?: string;
+    duration?: number;
+}
+export interface UTM {
+    source?: string;
+    medium?: string;
+    campaign?: string;
+    term?: string;
+    content?: string;
+}
+export interface PageViewData {
+    referrer?: string;
+    title?: string;
+    pathname?: string;
+    search?: string;
+    hash?: string;
+}
+export interface EventData {
+    type: EventType;
+    page_url: string;
+    timestamp: number;
+    referrer?: string;
+    from_page_url?: string;
+    scroll_data?: ScrollData;
+    click_data?: ClickData;
+    custom_event?: CustomEventData;
+    web_vitals?: WebVitalsData;
+    page_view?: PageViewData;
+    session_start_recovered?: boolean;
+    session_end_reason?: SessionEndReason;
+    error_data?: ErrorData;
+    utm?: UTM;
+    tags?: string[] | {
+        id: string;
+        key: string;
+    }[];
+}

package/dist/esm/types/event.types.js

@@ -0,0 +1,22 @@
+export var EventType;
+(function (EventType) {
+    EventType["PAGE_VIEW"] = "page_view";
+    EventType["CLICK"] = "click";
+    EventType["SCROLL"] = "scroll";
+    EventType["SESSION_START"] = "session_start";
+    EventType["SESSION_END"] = "session_end";
+    EventType["CUSTOM"] = "custom";
+    EventType["WEB_VITALS"] = "web_vitals";
+    EventType["ERROR"] = "error";
+})(EventType || (EventType = {}));
+export var ScrollDirection;
+(function (ScrollDirection) {
+    ScrollDirection["UP"] = "up";
+    ScrollDirection["DOWN"] = "down";
+})(ScrollDirection || (ScrollDirection = {}));
+export var ErrorType;
+(function (ErrorType) {
+    ErrorType["JS_ERROR"] = "js_error";
+    ErrorType["PROMISE_REJECTION"] = "promise_rejection";
+    ErrorType["NETWORK_ERROR"] = "network_error";
+})(ErrorType || (ErrorType = {}));

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

@@ -0,0 +1,13 @@
+export * from './api.types';
+export * from './common.types';
+export * from './config.types';
+export * from './device.types';
+export * from './event.types';
+export * from './log.types';
+export * from './mode.types';
+export * from './queue.types';
+export * from './state.types';
+export * from './tag.types';
+export * from './validation-error.types';
+export * from './web-vitals.types';
+export * from './window.types';

package/dist/esm/types/index.js

@@ -0,0 +1,13 @@
+export * from './api.types';
+export * from './common.types';
+export * from './config.types';
+export * from './device.types';
+export * from './event.types';
+export * from './log.types';
+export * from './mode.types';
+export * from './queue.types';
+export * from './state.types';
+export * from './tag.types';
+export * from './validation-error.types';
+export * from './web-vitals.types';
+export * from './window.types';

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

@@ -0,0 +1,4 @@
+/**
+ * Log levels for the dual logging system
+ */
+export type LogLevel = 'CLIENT_ERROR' | 'CLIENT_WARN' | 'INFO' | 'ERROR' | 'WARN' | 'DEBUG' | 'VERBOSE';

package/dist/esm/types/log.types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,7 @@
+/**
+ * App modes for the TraceLog Library
+ */
+export declare enum Mode {
+    QA = "qa",
+    DEBUG = "debug"
+}