@tracelog/lib 0.5.5 → 0.6.1

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,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;

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

@@ -0,0 +1,81 @@
+export const formatLogMsg = (msg, error) => {
+    if (error) {
+        // In production, sanitize error messages to avoid exposing sensitive paths
+        if (process.env.NODE_ENV !== 'dev' && error instanceof Error) {
+            // Remove file paths and line numbers from error messages
+            const sanitizedMessage = error.message.replace(/\s+at\s+.*$/gm, '').replace(/\(.*?:\d+:\d+\)/g, '');
+            return `[TraceLog] ${msg}: ${sanitizedMessage}`;
+        }
+        return `[TraceLog] ${msg}: ${error instanceof Error ? error.message : 'Unknown error'}`;
+    }
+    return `[TraceLog] ${msg}`;
+};
+/**
+ * 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 const log = (type, msg, extra) => {
+    const { error, data, showToClient = false } = extra ?? {};
+    const formattedMsg = error ? formatLogMsg(msg, error) : `[TraceLog] ${msg}`;
+    const method = type === 'error' ? 'error' : type === 'warn' ? 'warn' : 'log';
+    // Production logging strategy:
+    // - Development: Log everything
+    // - Production:
+    //   - debug: never logged
+    //   - info: only if showToClient=true
+    //   - warn: always logged (critical for debugging)
+    //   - error: always logged
+    const isProduction = process.env.NODE_ENV !== 'dev';
+    if (isProduction) {
+        // Never log debug in production
+        if (type === 'debug') {
+            return;
+        }
+        // Log info only if explicitly flagged
+        if (type === 'info' && !showToClient) {
+            return;
+        }
+        // warn and error always logged in production
+    }
+    // In production, sanitize data to avoid exposing sensitive information
+    if (isProduction && data !== undefined) {
+        const sanitizedData = sanitizeLogData(data);
+        console[method](formattedMsg, sanitizedData);
+    }
+    else if (data !== undefined) {
+        console[method](formattedMsg, data);
+    }
+    else {
+        console[method](formattedMsg);
+    }
+};
+/**
+ * Sanitizes log data in production to prevent sensitive information leakage
+ * Simple approach: redact sensitive keys only
+ */
+const sanitizeLogData = (data) => {
+    const sanitized = {};
+    const sensitiveKeys = ['token', 'password', 'secret', 'key', 'apikey', 'api_key', 'sessionid', 'session_id'];
+    for (const [key, value] of Object.entries(data)) {
+        const lowerKey = key.toLowerCase();
+        // Redact sensitive keys
+        if (sensitiveKeys.some((sensitiveKey) => lowerKey.includes(sensitiveKey))) {
+            sanitized[key] = '[REDACTED]';
+        }
+        else {
+            sanitized[key] = value;
+        }
+    }
+    return sanitized;
+};

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;

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

@@ -1,30 +1,53 @@
-import { isValidUrl } from '../validations';
-import { debugLog } from '../logging';
+import { log } from '../logging.utils';
+/**
+ * Validates if a URL is valid and optionally allows HTTP URLs
+ * @param url - The URL to validate
+ * @param allowHttp - Whether to allow HTTP URLs (default: false)
+ * @returns True if the URL is valid, false otherwise
+ */
+const isValidUrl = (url, allowHttp = false) => {
+    try {
+        const parsed = new URL(url);
+        const isHttps = parsed.protocol === 'https:';
+        const isHttp = parsed.protocol === 'http:';
+        return isHttps || (allowHttp && isHttp);
+    }
+    catch {
+        return false;
+    }
+};
 /**
  * Generates an API URL based on project ID and current domain
  * @param id - The project ID
  * @returns The generated API URL
  */
-export const getApiUrl = (id, allowHttp = false) => {
-    const url = new URL(window.location.href);
-    const host = url.hostname;
-    const parts = host.split('.');
-    if (parts.length === 0) {
-        debugLog.clientError('URLUtils', 'Invalid hostname - no domain parts found', { hostname: host });
-        throw new Error('Invalid URL');
+export const getApiUrl = (config) => {
+    if (config.integrations?.tracelog?.projectId) {
+        const url = new URL(window.location.href);
+        const host = url.hostname;
+        const parts = host.split('.');
+        if (parts.length === 0) {
+            throw new Error('Invalid URL');
+        }
+        const projectId = config.integrations.tracelog.projectId;
+        const cleanDomain = parts.slice(-2).join('.');
+        const apiUrl = `https://${projectId}.${cleanDomain}`;
+        const isValid = isValidUrl(apiUrl);
+        if (!isValid) {
+            throw new Error('Invalid URL');
+        }
+        return apiUrl;
     }
-    const cleanDomain = parts.slice(-2).join('.');
-    const protocol = allowHttp && url.protocol === 'http:' ? 'http' : 'https';
-    const apiUrl = `${protocol}://${id}.${cleanDomain}`;
-    const isValid = isValidUrl(apiUrl, allowHttp);
-    if (!isValid) {
-        debugLog.clientError('URLUtils', 'Generated API URL failed validation', {
-            apiUrl,
-            allowHttp,
-        });
-        throw new Error('Invalid URL');
+    if (config.integrations?.custom?.apiUrl) {
+        const apiUrl = config.integrations.custom.apiUrl;
+        const allowHttp = config.integrations?.custom?.allowHttp ?? false;
+        const isValid = isValidUrl(apiUrl, allowHttp);
+        if (!isValid) {
+            throw new Error('Invalid URL');
+        }
+        return apiUrl;
     }
-    return apiUrl;
+    return '';
 };
 /**
  * Normalizes a URL by removing sensitive query parameters
@@ -36,7 +59,6 @@ export const normalizeUrl = (url, sensitiveQueryParams = []) => {
     try {
         const urlObject = new URL(url);
         const searchParams = urlObject.searchParams;
-        const originalParamCount = Array.from(searchParams.keys()).length;
         let hasChanged = false;
         const removedParams = [];
         sensitiveQueryParams.forEach((param) => {
@@ -46,13 +68,6 @@ export const normalizeUrl = (url, sensitiveQueryParams = []) => {
                 removedParams.push(param);
             }
         });
-        if (hasChanged) {
-            debugLog.debug('URLUtils', 'Sensitive parameters removed from URL', {
-                removedParams,
-                originalParamCount,
-                finalParamCount: Array.from(searchParams.keys()).length,
-            });
-        }
         if (!hasChanged && url.includes('?')) {
             return url;
         }
@@ -61,66 +76,7 @@ export const normalizeUrl = (url, sensitiveQueryParams = []) => {
         return result;
     }
     catch (error) {
-        debugLog.warn('URLUtils', 'URL normalization failed, returning original', {
-            url: url.slice(0, 100),
-            error: error instanceof Error ? error.message : error,
-        });
+        log('warn', 'URL normalization failed, returning original', { error, data: { url: url.slice(0, 100) } });
         return url;
     }
 };
-/**
- * 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 const isUrlPathExcluded = (url, excludedPaths = []) => {
-    if (excludedPaths.length === 0) {
-        return false;
-    }
-    let path;
-    try {
-        const parsedUrl = new URL(url, window.location.origin);
-        path = parsedUrl.pathname + (parsedUrl.hash ?? '');
-    }
-    catch (error) {
-        debugLog.warn('URLUtils', 'Failed to parse URL for path exclusion check', {
-            url: url.slice(0, 100),
-            error: error instanceof Error ? error.message : error,
-        });
-        return false;
-    }
-    const isRegularExpression = (value) => typeof value === 'object' && value !== undefined && typeof value.test === 'function';
-    const escapeRegexString = (string_) => string_.replaceAll(/[$()*+.?[\\\]^{|}]/g, '\\$&');
-    const wildcardToRegex = (string_) => new RegExp('^' +
-        string_
-            .split('*')
-            .map((element) => escapeRegexString(element))
-            .join('.+') +
-        '$');
-    const matchedPattern = excludedPaths.find((pattern) => {
-        try {
-            if (isRegularExpression(pattern)) {
-                const matches = pattern.test(path);
-                return matches;
-            }
-            if (pattern.includes('*')) {
-                const regex = wildcardToRegex(pattern);
-                const matches = regex.test(path);
-                return matches;
-            }
-            const matches = pattern === path;
-            return matches;
-        }
-        catch (error) {
-            debugLog.warn('URLUtils', 'Error testing exclusion pattern', {
-                pattern,
-                path,
-                error: error instanceof Error ? error.message : error,
-            });
-            return false;
-        }
-    });
-    const isExcluded = !!matchedPattern;
-    return isExcluded;
-};

package/dist/esm/utils/security/sanitize.utils.d.ts

@@ -1,22 +1,10 @@
-import { MetadataType, ApiConfig } from '../../types';
+import { MetadataType } from '../../types';
 /**
  * Sanitizes a string value to prevent XSS attacks
  * @param value - The string to sanitize
  * @returns The sanitized string
  */
 export declare const sanitizeString: (value: string) => string;
-/**
- * Sanitizes a path string for route exclusion checks
- * @param value - The path string to sanitize
- * @returns The sanitized path string
- */
-export declare const sanitizePathString: (value: string) => string;
-/**
- * Sanitizes API configuration data with strict validation
- * @param data - The API config data to sanitize
- * @returns The sanitized API config
- */
-export declare const sanitizeApiConfig: (data: unknown) => ApiConfig;
 /**
  * Sanitizes user metadata for custom events
  * @param metadata - The metadata to sanitize