@tracelog/lib 0.5.4 → 0.6.0

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

@@ -1,18 +1,5 @@
 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. */
@@ -25,14 +12,20 @@ export interface AppConfig {
     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;
+        };
         /** 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/esm/types/config.types.js

@@ -1 +1,5 @@
-export {};
+export var SpecialApiUrl;
+(function (SpecialApiUrl) {
+    SpecialApiUrl["Localhost"] = "localhost:8080";
+    SpecialApiUrl["Fail"] = "localhost:9999";
+})(SpecialApiUrl || (SpecialApiUrl = {}));

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

@@ -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/esm/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/esm/types/mode.types.js

@@ -4,5 +4,4 @@
 export var Mode;
 (function (Mode) {
     Mode["QA"] = "qa";
-    Mode["DEBUG"] = "debug";
 })(Mode || (Mode = {}));

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

@@ -17,14 +17,6 @@ export class TraceLogValidationError extends Error {
         }
     }
 }
-/**
- * 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
  */

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

@@ -1,5 +1,5 @@
 import { DeviceType } from '../../types/device.types';
-import { debugLog } from '../logging';
+import { log } from '../logging.utils';
 let coarsePointerQuery;
 let noHoverQuery;
 const initMediaQueries = () => {
@@ -14,22 +14,14 @@ const initMediaQueries = () => {
  */
 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;
@@ -38,30 +30,16 @@ export 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)) {
-            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,
-        });
+        log('warn', 'Device detection failed, defaulting to desktop', { error });
         return DeviceType.Desktop;
     }
 };

package/dist/esm/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/esm/utils/browser/index.js

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

package/dist/esm/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/esm/utils/browser/qa-mode.utils.js

@@ -0,0 +1,39 @@
+import { QA_MODE_KEY } from '@/constants';
+import { log } from '../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
+ */
+export const detectQaMode = () => {
+    const stored = sessionStorage.getItem(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(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) {
+            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;
+};

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

@@ -1,14 +1,9 @@
 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) => {
@@ -16,18 +11,8 @@ export const getUTMParameters = () => {
         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/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/esm/utils/data/uuid.utils.js

@@ -14,3 +14,38 @@ export const generateUUID = () => {
         return v.toString(16);
     });
 };
+/**
+ * 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 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}`;
+};

package/dist/esm/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/esm/utils/index.js

@@ -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/esm/utils/logging.utils.d.ts

@@ -0,0 +1,6 @@
+export declare const formatLogMsg: (msg: string, error?: unknown) => string;
+export declare const log: (type: "info" | "warn" | "error", msg: string, extra?: {
+    error?: unknown;
+    data?: Record<string, unknown>;
+    showToClient?: boolean;
+}) => void;

package/dist/esm/utils/logging.utils.js

@@ -0,0 +1,20 @@
+export const formatLogMsg = (msg, error) => {
+    if (error) {
+        return `[TraceLog] ${msg}: ${error instanceof Error ? error.message : 'Unknown error'}`;
+    }
+    return `[TraceLog] ${msg}`;
+};
+export const log = (type, msg, extra) => {
+    const { error, data, showToClient } = extra ?? {};
+    const formattedMsg = error ? formatLogMsg(msg, error) : `[TraceLog] ${msg}`;
+    const method = type === 'error' ? 'error' : type === 'warn' ? 'warn' : 'log';
+    if (process.env.NODE_ENV !== 'dev' && !showToClient) {
+        return;
+    }
+    if (data !== undefined) {
+        console[method](formattedMsg, data);
+    }
+    else {
+        console[method](formattedMsg);
+    }
+};

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

@@ -1,2 +1 @@
 export * from './url.utils';
-export * from './fetch-with-timeout.utils';

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

@@ -1,2 +1 @@
 export * from './url.utils';
-export * from './fetch-with-timeout.utils';

package/dist/esm/utils/network/url.utils.d.ts

@@ -1,9 +1,10 @@
+import { Config } from '@/types';
 /**
  * Generates an API URL based on project ID and current domain
  * @param id - The project ID
  * @returns The generated API URL
  */
-export declare const getApiUrl: (id: string, allowHttp?: boolean) => string;
+export declare const getApiUrl: (config: Config) => string;
 /**
  * Normalizes a URL by removing sensitive query parameters
  * @param url - The URL to normalize
@@ -11,10 +12,3 @@ export declare const getApiUrl: (id: string, allowHttp?: boolean) => string;
  * @returns The normalized URL
  */
 export declare const normalizeUrl: (url: string, sensitiveQueryParams?: string[]) => string;
-/**
- * Checks if a URL path should be excluded from tracking
- * @param url - The URL to check
- * @param excludedPaths - Array of patterns to match against
- * @returns True if the URL should be excluded
- */
-export declare const isUrlPathExcluded: (url: string, excludedPaths?: string[]) => boolean;