@tracelog/lib 0.5.5 → 0.6.1

package/dist/cjs/test-bridge.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TestBridge = void 0;
 const app_1 = require("./app");
+const api_1 = require("./api");
+const constants_1 = require("./constants");
 /**
  * Test bridge for E2E testing
  */
@@ -12,6 +14,34 @@ class TestBridge extends app_1.App {
         this._isInitializing = isInitializing;
         this._isDestroying = isDestroying;
     }
+    async init(config) {
+        // Guard: TestBridge should only be used in development
+        if (process.env.NODE_ENV !== 'dev') {
+            throw new Error('[TraceLog] TestBridge is only available in development mode');
+        }
+        // First sync with window.tracelog BEFORE initializing
+        // This ensures both APIs point to the same instance from the start
+        if (!api_1.__setAppInstance) {
+            throw new Error('[TraceLog] __setAppInstance is not available (production build?)');
+        }
+        try {
+            (0, api_1.__setAppInstance)(this);
+        }
+        catch {
+            // If __setAppInstance fails (e.g., already initialized), throw clear error
+            throw new Error('[TraceLog] TestBridge cannot sync with existing tracelog instance. Call destroy() first.');
+        }
+        try {
+            await super.init(config);
+        }
+        catch (error) {
+            // If init fails, clear the sync
+            if (api_1.__setAppInstance) {
+                (0, api_1.__setAppInstance)(null);
+            }
+            throw error;
+        }
+    }
     isInitializing() {
         return this._isInitializing;
     }
@@ -46,7 +76,8 @@ class TestBridge extends app_1.App {
         if (!storageManager) {
             throw new Error('Storage manager not available');
         }
-        const projectId = this.get('config')?.id;
+        const config = this.get('config');
+        const projectId = config?.integrations?.tracelog?.projectId ?? config?.integrations?.custom?.apiUrl ?? 'test';
         const userId = this.get('userId');
         const sessionId = this.get('sessionId');
         if (!projectId || !userId) {
@@ -61,7 +92,7 @@ class TestBridge extends app_1.App {
             timestamp: Date.now(),
         };
         // Store in the same format as SenderManager.persistEvents()
-        const storageKey = `tl:${projectId}:queue:${userId}`;
+        const storageKey = `${constants_1.STORAGE_BASE_KEY}:${projectId}:queue:${userId}`;
         storageManager.setItem(storageKey, JSON.stringify(persistedData));
     }
     get(key) {
@@ -106,6 +137,10 @@ class TestBridge extends app_1.App {
         this._isDestroying = true;
         try {
             await super.destroy(force);
+            // Clear window.tracelog API reference (only in dev mode)
+            if (api_1.__setAppInstance) {
+                (0, api_1.__setAppInstance)(null);
+            }
         }
         finally {
             this._isDestroying = false;

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

@@ -1,38 +1,31 @@
 import { MetadataType } from './common.types';
-import { TagConfig } from './tag.types';
-import { Mode } from './mode.types';
-export type Config = AppConfig & ExclusiveApiConfig;
-export type ApiConfig = SharedConfig & ExclusiveApiConfig;
-export type SharedConfig = Pick<AppConfig, 'mode' | 'samplingRate' | 'excludedUrlPaths'>;
-export interface ExclusiveApiConfig {
-    /** Tag definitions used to categorize tracked events. */
-    tags?: TagConfig[];
-    /** Determines if IP address is excluded from tracking. */
-    ipExcluded?: boolean;
-}
-export interface AppConfig {
-    /** Project identifier used for tracing. */
-    id: string;
+export interface Config {
     /** Session inactivity timeout in milliseconds. @default 900000 */
     sessionTimeout?: number;
     /** Metadata appended to every tracked event. */
     globalMetadata?: Record<string, MetadataType>;
     /** Selectors defining custom scroll containers to monitor. */
     scrollContainerSelectors?: string | string[];
-    /** Enables HTTP requests for testing and development flows. */
-    allowHttp?: boolean;
     /** Query parameters to remove before tracking URLs. */
     sensitiveQueryParams?: string[];
     /** Error event sampling rate between 0 and 1. */
     errorSampling?: number;
-    /** Logging mode controlling verbosity of client logs. */
-    mode?: Mode;
     /** Event sampling rate between 0 and 1. */
     samplingRate?: number;
-    /** URL path patterns that should be ignored by tracking. */
-    excludedUrlPaths?: string[];
     /** Optional configuration for third-party integrations. */
     integrations?: {
+        /** TraceLog integration options. */
+        tracelog?: {
+            /** Required project ID TraceLog SaaS integration. */
+            projectId: string;
+        };
+        /** Custom integration options. */
+        custom?: {
+            /** Required API URL for custom integration. */
+            apiUrl: string;
+            /** Allow HTTP URLs (not recommended for production). @default false */
+            allowHttp?: boolean;
+        };
         /** Google Analytics integration options. */
         googleAnalytics?: {
             /** Required measurement ID for Google Analytics. */
@@ -40,3 +33,7 @@ export interface AppConfig {
         };
     };
 }
+export declare enum SpecialApiUrl {
+    Localhost = "localhost:8080",
+    Fail = "localhost:9999"
+}

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

@@ -1,2 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpecialApiUrl = void 0;
+var SpecialApiUrl;
+(function (SpecialApiUrl) {
+    SpecialApiUrl["Localhost"] = "localhost:8080";
+    SpecialApiUrl["Fail"] = "localhost:9999";
+})(SpecialApiUrl || (exports.SpecialApiUrl = SpecialApiUrl = {}));

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

@@ -74,15 +74,8 @@ export interface PageViewData {
     search?: string;
     hash?: string;
 }
-export interface EventLocation {
-    country: string;
-    country_code: string;
-}
-export interface VitalSample {
-    type: WebVitalType;
-    value: number;
-}
 export interface EventData {
+    id: string;
     type: EventType;
     page_url: string;
     timestamp: number;
@@ -96,9 +89,4 @@ export interface EventData {
     session_end_reason?: SessionEndReason;
     error_data?: ErrorData;
     utm?: UTM;
-    location?: EventLocation;
-    tags?: string[] | {
-        id: string;
-        key: string;
-    }[];
 }

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

@@ -1,4 +1,3 @@
-export * from './api.types';
 export * from './common.types';
 export * from './config.types';
 export * from './device.types';
@@ -9,7 +8,6 @@ export * from './mode.types';
 export * from './queue.types';
 export * from './session.types';
 export * from './state.types';
-export * from './tag.types';
 export * from './test-bridge.types';
 export * from './validation-error.types';
 export * from './window.types';

package/dist/cjs/types/index.js

@@ -14,7 +14,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./api.types"), exports);
 __exportStar(require("./common.types"), exports);
 __exportStar(require("./config.types"), exports);
 __exportStar(require("./device.types"), exports);
@@ -25,7 +24,6 @@ __exportStar(require("./mode.types"), exports);
 __exportStar(require("./queue.types"), exports);
 __exportStar(require("./session.types"), exports);
 __exportStar(require("./state.types"), exports);
-__exportStar(require("./tag.types"), exports);
 __exportStar(require("./test-bridge.types"), exports);
 __exportStar(require("./validation-error.types"), exports);
 __exportStar(require("./window.types"), exports);

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

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

package/dist/cjs/types/mode.types.js

@@ -7,5 +7,4 @@ exports.Mode = void 0;
 var Mode;
 (function (Mode) {
     Mode["QA"] = "qa";
-    Mode["DEBUG"] = "debug";
 })(Mode || (exports.Mode = Mode = {}));

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

@@ -8,11 +8,6 @@ export interface BaseEventsQueueDto {
     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;
@@ -20,5 +15,4 @@ export interface PersistedQueueData {
     events: BaseEventsQueueDto['events'];
     timestamp: number;
     global_metadata?: BaseEventsQueueDto['global_metadata'];
-    fallbackMode?: boolean;
 }

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

@@ -1,6 +1,8 @@
 import { Config } from './config.types';
 import { DeviceType } from './device.types';
+import { Mode } from './mode.types';
 export interface State {
+    mode?: Mode;
     apiUrl: string;
     config: Config;
     sessionId: string | null;

package/dist/cjs/types/test-bridge.types.d.ts

@@ -7,7 +7,7 @@ import { SessionHandler } from '@/handlers/session.handler';
 import { GoogleAnalyticsIntegration } from '@/integrations/google-analytics.integration';
 import { EventManager } from '@/managers/event.manager';
 import { StorageManager as TraceLogStorageManager } from '@/managers/storage.manager';
-import { AppConfig } from './config.types';
+import { Config } from './config.types';
 import { State } from './state.types';
 /**
  * Testing bridge interface for E2E tests
@@ -15,7 +15,7 @@ import { State } from './state.types';
  */
 export interface TraceLogTestBridge {
     readonly initialized: boolean;
-    init(config: AppConfig): Promise<void>;
+    init(config: Config): Promise<void>;
     destroy(): Promise<void>;
     isInitializing(): boolean;
     sendCustomEvent(name: string, data?: Record<string, unknown> | Record<string, unknown>[]): void;

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

@@ -10,12 +10,6 @@ export declare abstract class TraceLogValidationError extends Error {
     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
  */

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

@@ -4,7 +4,7 @@
  * Provides better error handling and consistency across validation layers
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.InitializationTimeoutError = exports.IntegrationValidationError = exports.SamplingRateValidationError = exports.SessionTimeoutValidationError = exports.AppConfigValidationError = exports.ProjectIdValidationError = exports.TraceLogValidationError = void 0;
+exports.InitializationTimeoutError = exports.IntegrationValidationError = exports.SamplingRateValidationError = exports.SessionTimeoutValidationError = exports.AppConfigValidationError = exports.TraceLogValidationError = void 0;
 /**
  * Base class for all TraceLog validation errors
  */
@@ -21,15 +21,6 @@ class TraceLogValidationError extends Error {
     }
 }
 exports.TraceLogValidationError = TraceLogValidationError;
-/**
- * Thrown when project ID validation fails
- */
-class ProjectIdValidationError extends TraceLogValidationError {
-    constructor(message = 'Project ID is required', layer = 'config') {
-        super(message, 'PROJECT_ID_INVALID', layer);
-    }
-}
-exports.ProjectIdValidationError = ProjectIdValidationError;
 /**
  * Thrown when app configuration validation fails
  */

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

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getDeviceType = void 0;
 const device_types_1 = require("../../types/device.types");
-const logging_1 = require("../logging");
+const logging_utils_1 = require("../logging.utils");
 let coarsePointerQuery;
 let noHoverQuery;
 const initMediaQueries = () => {
@@ -17,22 +17,14 @@ const initMediaQueries = () => {
  */
 const getDeviceType = () => {
     try {
-        logging_1.debugLog.debug('DeviceDetector', 'Starting device detection');
         const nav = navigator;
         if (nav.userAgentData && typeof nav.userAgentData.mobile === 'boolean') {
-            logging_1.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)) {
-                logging_1.debugLog.debug('DeviceDetector', 'Device detected as tablet via platform hint');
                 return device_types_1.DeviceType.Tablet;
             }
             const result = nav.userAgentData.mobile ? device_types_1.DeviceType.Mobile : device_types_1.DeviceType.Desktop;
-            logging_1.debugLog.debug('DeviceDetector', 'Device detected via User-Agent hints', { result });
             return result;
         }
-        logging_1.debugLog.debug('DeviceDetector', 'Using fallback detection methods');
         initMediaQueries();
         const width = window.innerWidth;
         const hasCoarsePointer = coarsePointerQuery?.matches ?? false;
@@ -41,30 +33,16 @@ const getDeviceType = () => {
         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)) {
-            logging_1.debugLog.debug('DeviceDetector', 'Device detected as mobile', detectionData);
             return device_types_1.DeviceType.Mobile;
         }
         if ((width >= 768 && width <= 1024) || isTabletUA || (hasCoarsePointer && hasNoHover && hasTouchSupport)) {
-            logging_1.debugLog.debug('DeviceDetector', 'Device detected as tablet', detectionData);
             return device_types_1.DeviceType.Tablet;
         }
-        logging_1.debugLog.debug('DeviceDetector', 'Device detected as desktop', detectionData);
         return device_types_1.DeviceType.Desktop;
     }
     catch (error) {
-        logging_1.debugLog.warn('DeviceDetector', 'Device detection failed, defaulting to desktop', {
-            error: error instanceof Error ? error.message : error,
-        });
+        (0, logging_utils_1.log)('warn', 'Device detection failed, defaulting to desktop', { error });
         return device_types_1.DeviceType.Desktop;
     }
 };

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

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

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

@@ -15,4 +15,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./device-detector.utils"), exports);
+__exportStar(require("./qa-mode.utils"), exports);
 __exportStar(require("./utm-params.utils"), exports);

package/dist/cjs/utils/browser/qa-mode.utils.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Detects if QA mode should be active based on URL query parameter or sessionStorage
+ *
+ * Detection flow:
+ * 1. Check if already active in sessionStorage
+ * 2. Check for ?tlog_mode=qa query parameter
+ * 3. If found in URL:
+ *    - Persist to sessionStorage
+ *    - Clean param from URL
+ *
+ * @returns True if QA mode is active, false otherwise
+ */
+export declare const detectQaMode: () => boolean;

package/dist/cjs/utils/browser/qa-mode.utils.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectQaMode = void 0;
+const constants_1 = require("@/constants");
+const logging_utils_1 = require("../logging.utils");
+const QA_MODE_PARAM = 'tlog_mode';
+const QA_MODE_VALUE = 'qa';
+/**
+ * Detects if QA mode should be active based on URL query parameter or sessionStorage
+ *
+ * Detection flow:
+ * 1. Check if already active in sessionStorage
+ * 2. Check for ?tlog_mode=qa query parameter
+ * 3. If found in URL:
+ *    - Persist to sessionStorage
+ *    - Clean param from URL
+ *
+ * @returns True if QA mode is active, false otherwise
+ */
+const detectQaMode = () => {
+    const stored = sessionStorage.getItem(constants_1.QA_MODE_KEY);
+    if (stored === 'true') {
+        return true;
+    }
+    const params = new URLSearchParams(window.location.search);
+    const modeParam = params.get(QA_MODE_PARAM);
+    const isQaMode = modeParam === QA_MODE_VALUE;
+    if (isQaMode) {
+        sessionStorage.setItem(constants_1.QA_MODE_KEY, 'true');
+        params.delete(QA_MODE_PARAM);
+        const newSearch = params.toString();
+        const newUrl = `${window.location.pathname}${newSearch ? '?' + newSearch : ''}${window.location.hash}`;
+        try {
+            window.history.replaceState({}, '', newUrl);
+        }
+        catch (error) {
+            (0, logging_utils_1.log)('warn', 'History API not available, cannot replace URL', { error });
+        }
+        console.log('%c[TraceLog] QA Mode ACTIVE', 'background: #ff9800; color: white; font-weight: bold; padding: 2px 8px; border-radius: 3px;');
+    }
+    return isQaMode;
+};
+exports.detectQaMode = detectQaMode;

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

@@ -2,16 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getUTMParameters = void 0;
 const constants_1 = require("../../constants");
-const logging_1 = require("../logging");
 /**
  * Extracts UTM parameters from the current URL
  * @returns UTM parameters object or undefined if none found
  */
 const getUTMParameters = () => {
-    logging_1.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 = {};
     constants_1.UTM_PARAMS.forEach((param) => {
@@ -19,19 +14,9 @@ const getUTMParameters = () => {
         if (value) {
             const key = param.split('utm_')[1];
             utmParams[key] = value;
-            logging_1.debugLog.debug('UTMParams', 'Found UTM parameter', { param, key, value });
         }
     });
     const result = Object.keys(utmParams).length ? utmParams : undefined;
-    if (result) {
-        logging_1.debugLog.debug('UTMParams', 'UTM parameters extracted successfully', {
-            parameterCount: Object.keys(result).length,
-            parameters: Object.keys(result),
-        });
-    }
-    else {
-        logging_1.debugLog.debug('UTMParams', 'No UTM parameters found in URL');
-    }
     return result;
 };
 exports.getUTMParameters = getUTMParameters;

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

@@ -3,3 +3,16 @@
  * @returns A UUID string
  */
 export declare const generateUUID: () => string;
+/**
+ * Generates a unique event ID optimized for high-frequency event tracking
+ *
+ * Uses a simple hybrid approach:
+ * - Timestamp for temporal ordering
+ * - Random component for uniqueness across tabs/processes
+ *
+ * Format: {timestamp}-{random}
+ * Example: "1704067200000-a3f9c2b1"
+ *
+ * @returns Unique event ID string
+ */
+export declare const generateEventId: () => string;

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateUUID = void 0;
+exports.generateEventId = exports.generateUUID = void 0;
 /**
  * Generates a RFC4122 compliant UUID v4 using native crypto API with fallback
  * @returns A UUID string
@@ -18,3 +18,39 @@ const generateUUID = () => {
     });
 };
 exports.generateUUID = generateUUID;
+/**
+ * Generates a unique event ID optimized for high-frequency event tracking
+ *
+ * Uses a simple hybrid approach:
+ * - Timestamp for temporal ordering
+ * - Random component for uniqueness across tabs/processes
+ *
+ * Format: {timestamp}-{random}
+ * Example: "1704067200000-a3f9c2b1"
+ *
+ * @returns Unique event ID string
+ */
+const generateEventId = () => {
+    const timestamp = Date.now();
+    // Generate 8 random hex chars (32 bits entropy)
+    let random = '';
+    try {
+        if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+            const bytes = crypto.getRandomValues(new Uint8Array(4));
+            if (bytes) {
+                random = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+            }
+        }
+    }
+    catch {
+        // crypto failed, use fallback
+    }
+    // Fallback to Math.random if crypto unavailable
+    if (!random) {
+        random = Math.floor(Math.random() * 0xffffffff)
+            .toString(16)
+            .padStart(8, '0');
+    }
+    return `${timestamp}-${random}`;
+};
+exports.generateEventId = generateEventId;

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

@@ -1,7 +1,7 @@
 export * from './browser';
 export * from './data';
-export * from './logging';
 export * from './network';
 export * from './security';
 export * from './validations';
 export * from './emitter.utils';
+export * from './logging.utils';

package/dist/cjs/utils/index.js

@@ -16,8 +16,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./browser"), exports);
 __exportStar(require("./data"), exports);
-__exportStar(require("./logging"), exports);
 __exportStar(require("./network"), exports);
 __exportStar(require("./security"), exports);
 __exportStar(require("./validations"), exports);
 __exportStar(require("./emitter.utils"), exports);
+__exportStar(require("./logging.utils"), exports);

package/dist/cjs/utils/logging.utils.d.ts

@@ -0,0 +1,21 @@
+export declare const formatLogMsg: (msg: string, error?: unknown) => string;
+/**
+ * Safe logging utility that respects production environment
+ *
+ * @param type - Log level (info, warn, error, debug)
+ * @param msg - Message to log
+ * @param extra - Optional extra data
+ *
+ * Production behavior:
+ * - debug: Never logged in production
+ * - info: Only logged if showToClient=true
+ * - warn: Always logged (important for debugging production issues)
+ * - error: Always logged
+ * - Stack traces are sanitized
+ * - Data objects are sanitized
+ */
+export declare const log: (type: "info" | "warn" | "error" | "debug", msg: string, extra?: {
+    error?: unknown;
+    data?: Record<string, unknown>;
+    showToClient?: boolean;
+}) => void;