@tracelog/lib 0.0.1

package/dist/esm/types/mode.types.js

@@ -0,0 +1,8 @@
+/**
+ * App modes for the TraceLog Library
+ */
+export var Mode;
+(function (Mode) {
+    Mode["QA"] = "qa";
+    Mode["DEBUG"] = "debug";
+})(Mode || (Mode = {}));

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

@@ -0,0 +1,23 @@
+import { MetadataType } from './common.types';
+import { DeviceType } from './device.types';
+import { EventData } from './event.types';
+export interface BaseEventsQueueDto {
+    user_id: string;
+    session_id: string;
+    device: DeviceType;
+    events: EventData[];
+    global_metadata?: Record<string, MetadataType>;
+}
+export interface ExtendedEventsQueueDto extends BaseEventsQueueDto {
+    project: string;
+    source: string;
+    ip: string;
+}
+export interface PersistedQueueData {
+    userId: string;
+    sessionId: string;
+    device: BaseEventsQueueDto['device'];
+    events: BaseEventsQueueDto['events'];
+    timestamp: number;
+    global_metadata?: BaseEventsQueueDto['global_metadata'];
+}

package/dist/esm/types/queue.types.js

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

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

@@ -0,0 +1,65 @@
+export type SessionEndReason = 'inactivity' | 'page_unload' | 'manual_stop' | 'orphaned_cleanup' | 'tab_closed';
+export interface SessionEndConfig {
+    enablePageUnloadHandlers: boolean;
+    syncTimeoutMs: number;
+    maxRetries: number;
+    debugMode: boolean;
+}
+export interface SessionEndResult {
+    success: boolean;
+    reason: SessionEndReason;
+    timestamp: number;
+    eventsFlushed: number;
+    method: 'async' | 'sync';
+}
+export interface SessionEndStats {
+    totalSessionEnds: number;
+    successfulEnds: number;
+    failedEnds: number;
+    duplicatePrevented: number;
+    reasonCounts: Record<SessionEndReason, number>;
+}
+export interface CrossTabSessionConfig {
+    tabHeartbeatIntervalMs: number;
+    tabElectionTimeoutMs: number;
+    debugMode: boolean;
+}
+export interface TabInfo {
+    id: string;
+    lastHeartbeat: number;
+    isLeader: boolean;
+    sessionId: string;
+    startTime: number;
+}
+export interface CrossTabMessage {
+    type: 'heartbeat' | 'session_start' | 'session_end' | 'tab_closing' | 'election_request' | 'election_response';
+    tabId: string;
+    sessionId?: string;
+    timestamp: number;
+    data?: Record<string, unknown>;
+}
+export interface SessionRecoveryConfig {
+    recoveryWindowMs: number;
+    maxRecoveryAttempts: number;
+    contextPreservation: boolean;
+}
+export interface SessionContext {
+    sessionId: string;
+    startTime: number;
+    lastActivity: number;
+    tabCount: number;
+    recoveryAttempts: number;
+    metadata?: Record<string, unknown>;
+}
+export interface RecoveryAttempt {
+    sessionId: string;
+    timestamp: number;
+    attempt: number;
+    context: SessionContext;
+}
+export interface SessionHealth {
+    recoveryAttempts: number;
+    sessionTimeouts: number;
+    crossTabConflicts: number;
+    lastHealthCheck: number;
+}

package/dist/esm/types/session.types.js

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

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

@@ -0,0 +1,12 @@
+import { Config } from './config.types';
+import { DeviceType } from './device.types';
+export interface State {
+    apiUrl: string;
+    config: Config;
+    sessionId: string | null;
+    userId: string;
+    device: DeviceType;
+    pageUrl: string;
+    hasStartSession: boolean;
+    suppressNextScroll: boolean;
+}

package/dist/esm/types/state.types.js

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

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

@@ -0,0 +1,43 @@
+import { EventType } from './event.types';
+export declare enum TagLogicalOperator {
+    AND = "AND",
+    OR = "OR"
+}
+export declare enum TagConditionType {
+    URL_MATCHES = "url_matches",
+    ELEMENT_MATCHES = "element_matches",
+    DEVICE_TYPE = "device_type",
+    ELEMENT_TEXT = "element_text",
+    ELEMENT_ATTRIBUTE = "element_attribute",
+    UTM_SOURCE = "utm_source",
+    UTM_MEDIUM = "utm_medium",
+    UTM_CAMPAIGN = "utm_campaign"
+}
+export declare enum TagConditionOperator {
+    EQUALS = "equals",
+    CONTAINS = "contains",
+    STARTS_WITH = "starts_with",
+    ENDS_WITH = "ends_with",
+    REGEX = "regex",
+    GREATER_THAN = "greater_than",
+    LESS_THAN = "less_than",
+    EXISTS = "exists",
+    NOT_EXISTS = "not_exists"
+}
+export type TagConfig = Pick<Tag, 'key' | 'triggerType' | 'logicalOperator' | 'conditions'> & {
+    id: string;
+};
+export interface Tag {
+    key: string;
+    name: string;
+    description?: string;
+    active: boolean;
+    triggerType: EventType;
+    logicalOperator?: TagLogicalOperator;
+    conditions: TagCondition[];
+}
+export interface TagCondition {
+    type: TagConditionType;
+    operator: TagConditionOperator;
+    value: string;
+}

package/dist/esm/types/tag.types.js

@@ -0,0 +1,28 @@
+export var TagLogicalOperator;
+(function (TagLogicalOperator) {
+    TagLogicalOperator["AND"] = "AND";
+    TagLogicalOperator["OR"] = "OR";
+})(TagLogicalOperator || (TagLogicalOperator = {}));
+export var TagConditionType;
+(function (TagConditionType) {
+    TagConditionType["URL_MATCHES"] = "url_matches";
+    TagConditionType["ELEMENT_MATCHES"] = "element_matches";
+    TagConditionType["DEVICE_TYPE"] = "device_type";
+    TagConditionType["ELEMENT_TEXT"] = "element_text";
+    TagConditionType["ELEMENT_ATTRIBUTE"] = "element_attribute";
+    TagConditionType["UTM_SOURCE"] = "utm_source";
+    TagConditionType["UTM_MEDIUM"] = "utm_medium";
+    TagConditionType["UTM_CAMPAIGN"] = "utm_campaign";
+})(TagConditionType || (TagConditionType = {}));
+export var TagConditionOperator;
+(function (TagConditionOperator) {
+    TagConditionOperator["EQUALS"] = "equals";
+    TagConditionOperator["CONTAINS"] = "contains";
+    TagConditionOperator["STARTS_WITH"] = "starts_with";
+    TagConditionOperator["ENDS_WITH"] = "ends_with";
+    TagConditionOperator["REGEX"] = "regex";
+    TagConditionOperator["GREATER_THAN"] = "greater_than";
+    TagConditionOperator["LESS_THAN"] = "less_than";
+    TagConditionOperator["EXISTS"] = "exists";
+    TagConditionOperator["NOT_EXISTS"] = "not_exists";
+})(TagConditionOperator || (TagConditionOperator = {}));

package/dist/esm/types/validation-error.types.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Custom error classes for TraceLog validation errors
+ * Provides better error handling and consistency across validation layers
+ */
+/**
+ * Base class for all TraceLog validation errors
+ */
+export declare abstract class TraceLogValidationError extends Error {
+    readonly errorCode: string;
+    readonly layer: 'config' | 'app' | 'runtime';
+    constructor(message: string, errorCode: string, layer: 'config' | 'app' | 'runtime');
+}
+/**
+ * Thrown when project ID validation fails
+ */
+export declare class ProjectIdValidationError extends TraceLogValidationError {
+    constructor(message?: string, layer?: 'config' | 'app' | 'runtime');
+}
+/**
+ * Thrown when app configuration validation fails
+ */
+export declare class AppConfigValidationError extends TraceLogValidationError {
+    constructor(message: string, layer?: 'config' | 'app' | 'runtime');
+}
+/**
+ * Thrown when session timeout validation fails
+ */
+export declare class SessionTimeoutValidationError extends TraceLogValidationError {
+    constructor(message: string, layer?: 'config' | 'app' | 'runtime');
+}
+/**
+ * Thrown when sampling rate validation fails
+ */
+export declare class SamplingRateValidationError extends TraceLogValidationError {
+    constructor(message: string, layer?: 'config' | 'app' | 'runtime');
+}
+/**
+ * Thrown when integrations validation fails
+ */
+export declare class IntegrationValidationError extends TraceLogValidationError {
+    constructor(message: string, layer?: 'config' | 'app' | 'runtime');
+}

package/dist/esm/types/validation-error.types.js

@@ -0,0 +1,59 @@
+/**
+ * Custom error classes for TraceLog validation errors
+ * Provides better error handling and consistency across validation layers
+ */
+/**
+ * Base class for all TraceLog validation errors
+ */
+export class TraceLogValidationError extends Error {
+    constructor(message, errorCode, layer) {
+        super(message);
+        this.errorCode = errorCode;
+        this.layer = layer;
+        this.name = this.constructor.name;
+        // Maintains proper stack trace for where error was thrown (only available on V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+}
+/**
+ * Thrown when project ID validation fails
+ */
+export class ProjectIdValidationError extends TraceLogValidationError {
+    constructor(message = 'Project ID is required', layer = 'config') {
+        super(message, 'PROJECT_ID_INVALID', layer);
+    }
+}
+/**
+ * Thrown when app configuration validation fails
+ */
+export class AppConfigValidationError extends TraceLogValidationError {
+    constructor(message, layer = 'config') {
+        super(message, 'APP_CONFIG_INVALID', layer);
+    }
+}
+/**
+ * Thrown when session timeout validation fails
+ */
+export class SessionTimeoutValidationError extends TraceLogValidationError {
+    constructor(message, layer = 'config') {
+        super(message, 'SESSION_TIMEOUT_INVALID', layer);
+    }
+}
+/**
+ * Thrown when sampling rate validation fails
+ */
+export class SamplingRateValidationError extends TraceLogValidationError {
+    constructor(message, layer = 'config') {
+        super(message, 'SAMPLING_RATE_INVALID', layer);
+    }
+}
+/**
+ * Thrown when integrations validation fails
+ */
+export class IntegrationValidationError extends TraceLogValidationError {
+    constructor(message, layer = 'config') {
+        super(message, 'INTEGRATION_INVALID', layer);
+    }
+}

package/dist/esm/types/web-vitals.types.d.ts

@@ -0,0 +1,6 @@
+import { WebVitalType } from './event.types';
+export type NavigationId = string;
+export interface VitalSample {
+    type: WebVitalType;
+    value: number;
+}

package/dist/esm/types/web-vitals.types.js

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

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

@@ -0,0 +1,17 @@
+import type { App } from '../app';
+/**
+ * Testing bridge interface for E2E tests
+ * Only available when NODE_ENV=dev
+ */
+export interface TraceLogTestBridge extends App {
+    isInitializing(): boolean;
+}
+declare global {
+    interface Window {
+        /**
+         * Testing bridge for E2E tests
+         * Only available when NODE_ENV=dev
+         */
+        __traceLogBridge?: TraceLogTestBridge;
+    }
+}

package/dist/esm/types/window.types.js

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

package/dist/esm/utils/browser/device-detector.utils.d.ts

@@ -0,0 +1,6 @@
+import { DeviceType } from '../../types/device.types';
+/**
+ * Detects the device type based on screen size, user agent, and browser capabilities
+ * @returns The detected device type
+ */
+export declare const getDeviceType: () => DeviceType;

package/dist/esm/utils/browser/device-detector.utils.js

@@ -0,0 +1,67 @@
+import { DeviceType } from '../../types/device.types';
+import { debugLog } from '../logging';
+let coarsePointerQuery;
+let noHoverQuery;
+const initMediaQueries = () => {
+    if (typeof window !== 'undefined' && !coarsePointerQuery) {
+        coarsePointerQuery = window.matchMedia('(pointer: coarse)');
+        noHoverQuery = window.matchMedia('(hover: none)');
+    }
+};
+/**
+ * Detects the device type based on screen size, user agent, and browser capabilities
+ * @returns The detected device type
+ */
+export const getDeviceType = () => {
+    try {
+        debugLog.debug('DeviceDetector', 'Starting device detection');
+        const nav = navigator;
+        if (nav.userAgentData && typeof nav.userAgentData.mobile === 'boolean') {
+            debugLog.debug('DeviceDetector', 'Using modern User-Agent Client Hints API', {
+                mobile: nav.userAgentData.mobile,
+                platform: nav.userAgentData.platform,
+            });
+            if (nav.userAgentData.platform && /ipad|tablet/i.test(nav.userAgentData.platform)) {
+                debugLog.debug('DeviceDetector', 'Device detected as tablet via platform hint');
+                return DeviceType.Tablet;
+            }
+            const result = nav.userAgentData.mobile ? DeviceType.Mobile : DeviceType.Desktop;
+            debugLog.debug('DeviceDetector', 'Device detected via User-Agent hints', { result });
+            return result;
+        }
+        debugLog.debug('DeviceDetector', 'Using fallback detection methods');
+        initMediaQueries();
+        const width = window.innerWidth;
+        const hasCoarsePointer = coarsePointerQuery?.matches ?? false;
+        const hasNoHover = noHoverQuery?.matches ?? false;
+        const hasTouchSupport = 'ontouchstart' in window || navigator.maxTouchPoints > 0;
+        const ua = navigator.userAgent.toLowerCase();
+        const isMobileUA = /mobile|android|iphone|ipod|blackberry|iemobile|opera mini/.test(ua);
+        const isTabletUA = /tablet|ipad|android(?!.*mobile)/.test(ua);
+        const detectionData = {
+            width,
+            hasCoarsePointer,
+            hasNoHover,
+            hasTouchSupport,
+            isMobileUA,
+            isTabletUA,
+            maxTouchPoints: navigator.maxTouchPoints,
+        };
+        if (width <= 767 || (isMobileUA && hasTouchSupport)) {
+            debugLog.debug('DeviceDetector', 'Device detected as mobile', detectionData);
+            return DeviceType.Mobile;
+        }
+        if ((width >= 768 && width <= 1024) || isTabletUA || (hasCoarsePointer && hasNoHover && hasTouchSupport)) {
+            debugLog.debug('DeviceDetector', 'Device detected as tablet', detectionData);
+            return DeviceType.Tablet;
+        }
+        debugLog.debug('DeviceDetector', 'Device detected as desktop', detectionData);
+        return DeviceType.Desktop;
+    }
+    catch (error) {
+        debugLog.warn('DeviceDetector', 'Device detection failed, defaulting to desktop', {
+            error: error instanceof Error ? error.message : error,
+        });
+        return DeviceType.Desktop;
+    }
+};

package/dist/esm/utils/browser/index.d.ts

@@ -0,0 +1,2 @@
+export * from './device-detector.utils';
+export * from './utm-params.utils';

package/dist/esm/utils/browser/index.js

@@ -0,0 +1,2 @@
+export * from './device-detector.utils';
+export * from './utm-params.utils';

package/dist/esm/utils/browser/utm-params.utils.d.ts

@@ -0,0 +1,6 @@
+import { UTM } from '../../types/event.types';
+/**
+ * Extracts UTM parameters from the current URL
+ * @returns UTM parameters object or undefined if none found
+ */
+export declare const getUTMParameters: () => UTM | undefined;

package/dist/esm/utils/browser/utm-params.utils.js

@@ -0,0 +1,33 @@
+import { UTM_PARAMS } from '../../constants';
+import { debugLog } from '../logging';
+/**
+ * Extracts UTM parameters from the current URL
+ * @returns UTM parameters object or undefined if none found
+ */
+export const getUTMParameters = () => {
+    debugLog.debug('UTMParams', 'Extracting UTM parameters from URL', {
+        url: window.location.href,
+        search: window.location.search,
+    });
+    const urlParams = new URLSearchParams(window.location.search);
+    const utmParams = {};
+    UTM_PARAMS.forEach((param) => {
+        const value = urlParams.get(param);
+        if (value) {
+            const key = param.split('utm_')[1];
+            utmParams[key] = value;
+            debugLog.debug('UTMParams', 'Found UTM parameter', { param, key, value });
+        }
+    });
+    const result = Object.keys(utmParams).length ? utmParams : undefined;
+    if (result) {
+        debugLog.debug('UTMParams', 'UTM parameters extracted successfully', {
+            parameterCount: Object.keys(result).length,
+            parameters: Object.keys(result),
+        });
+    }
+    else {
+        debugLog.debug('UTMParams', 'No UTM parameters found in URL');
+    }
+    return result;
+};

package/dist/esm/utils/data/index.d.ts

@@ -0,0 +1 @@
+export * from './uuid.utils';

package/dist/esm/utils/data/index.js

@@ -0,0 +1 @@
+export * from './uuid.utils';

package/dist/esm/utils/data/uuid.utils.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generates a RFC4122 compliant UUID v4
+ * @returns A UUID string
+ */
+export declare const generateUUID: () => string;

package/dist/esm/utils/data/uuid.utils.js

@@ -0,0 +1,14 @@
+import { debugLog } from '../logging';
+/**
+ * Generates a RFC4122 compliant UUID v4
+ * @returns A UUID string
+ */
+export const generateUUID = () => {
+    const uuid = 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+    debugLog.verbose('UUIDUtils', 'Generated new UUID', { uuid });
+    return uuid;
+};

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

@@ -0,0 +1,6 @@
+export * from './browser';
+export * from './data';
+export * from './logging';
+export * from './network';
+export * from './security';
+export * from './validations';

package/dist/esm/utils/index.js

@@ -0,0 +1,6 @@
+export * from './browser';
+export * from './data';
+export * from './logging';
+export * from './network';
+export * from './security';
+export * from './validations';

package/dist/esm/utils/logging/debug-logger.utils.d.ts

@@ -0,0 +1,56 @@
+import { StateManager } from '../../managers/state.manager';
+/**
+ * Debug logger class that extends StateManager for clean access to global state
+ */
+declare class DebugLogger extends StateManager {
+    /**
+     * Client-facing error - Configuration/usage errors by the client
+     * Console: qa and debug modes | Events: NODE_ENV=dev
+     */
+    clientError(namespace: string, message: string, data?: unknown): void;
+    /**
+     * Client-facing warning - Configuration/usage warnings by the client
+     * Console: qa and debug modes | Events: NODE_ENV=dev
+     */
+    clientWarn(namespace: string, message: string, data?: unknown): void;
+    /**
+     * General operational information
+     * Console: qa and debug modes | Events: NODE_ENV=dev
+     */
+    info(namespace: string, message: string, data?: unknown): void;
+    /**
+     * Internal library errors
+     * Console: debug mode only | Events: NODE_ENV=dev
+     */
+    error(namespace: string, message: string, data?: unknown): void;
+    /**
+     * Internal library warnings
+     * Console: debug mode only | Events: NODE_ENV=dev
+     */
+    warn(namespace: string, message: string, data?: unknown): void;
+    /**
+     * Strategic debug information
+     * Console: debug mode only | Events: NODE_ENV=dev
+     */
+    debug(namespace: string, message: string, data?: unknown): void;
+    /**
+     * Detailed trace information
+     * Console: debug mode only | Events: NODE_ENV=dev
+     */
+    verbose(namespace: string, message: string, data?: unknown): void;
+    private getCurrentMode;
+    private shouldShowLog;
+    private formatMessage;
+    private getConsoleMethod;
+    private logMessage;
+    /**
+     * Dispatches tracelog:log events for E2E testing and development debugging
+     */
+    private dispatchEvent;
+}
+/**
+ * Singleton debug logger instance
+ * Provides the same API as before: debugLog.clientError(), debugLog.info(), etc.
+ */
+export declare const debugLog: DebugLogger;
+export {};