@tracelog/lib 0.0.1

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

@@ -0,0 +1,37 @@
+"use strict";
+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) => {
+        const value = urlParams.get(param);
+        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/index.d.ts

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

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

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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("./uuid.utils"), exports);

package/dist/cjs/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/cjs/utils/data/uuid.utils.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateUUID = void 0;
+const logging_1 = require("../logging");
+/**
+ * Generates a RFC4122 compliant UUID v4
+ * @returns A UUID string
+ */
+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);
+    });
+    logging_1.debugLog.verbose('UUIDUtils', 'Generated new UUID', { uuid });
+    return uuid;
+};
+exports.generateUUID = generateUUID;

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

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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("./browser"), exports);
+__exportStar(require("./data"), exports);
+__exportStar(require("./logging"), exports);
+__exportStar(require("./network"), exports);
+__exportStar(require("./security"), exports);
+__exportStar(require("./validations"), exports);

package/dist/cjs/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 {};

package/dist/cjs/utils/logging/debug-logger.utils.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.debugLog = void 0;
+const state_manager_1 = require("../../managers/state.manager");
+/**
+ * Debug logger class that extends StateManager for clean access to global state
+ */
+class DebugLogger extends state_manager_1.StateManager {
+    /**
+     * Client-facing error - Configuration/usage errors by the client
+     * Console: qa and debug modes | Events: NODE_ENV=dev
+     */
+    clientError(namespace, message, data) {
+        this.logMessage('CLIENT_ERROR', namespace, message, data);
+    }
+    /**
+     * Client-facing warning - Configuration/usage warnings by the client
+     * Console: qa and debug modes | Events: NODE_ENV=dev
+     */
+    clientWarn(namespace, message, data) {
+        this.logMessage('CLIENT_WARN', namespace, message, data);
+    }
+    /**
+     * General operational information
+     * Console: qa and debug modes | Events: NODE_ENV=dev
+     */
+    info(namespace, message, data) {
+        this.logMessage('INFO', namespace, message, data);
+    }
+    /**
+     * Internal library errors
+     * Console: debug mode only | Events: NODE_ENV=dev
+     */
+    error(namespace, message, data) {
+        this.logMessage('ERROR', namespace, message, data);
+    }
+    /**
+     * Internal library warnings
+     * Console: debug mode only | Events: NODE_ENV=dev
+     */
+    warn(namespace, message, data) {
+        this.logMessage('WARN', namespace, message, data);
+    }
+    /**
+     * Strategic debug information
+     * Console: debug mode only | Events: NODE_ENV=dev
+     */
+    debug(namespace, message, data) {
+        this.logMessage('DEBUG', namespace, message, data);
+    }
+    /**
+     * Detailed trace information
+     * Console: debug mode only | Events: NODE_ENV=dev
+     */
+    verbose(namespace, message, data) {
+        this.logMessage('VERBOSE', namespace, message, data);
+    }
+    getCurrentMode() {
+        try {
+            return this.get('config')?.mode;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    shouldShowLog(level) {
+        const mode = this.getCurrentMode();
+        switch (mode) {
+            case 'qa':
+                return ['INFO', 'CLIENT_ERROR', 'CLIENT_WARN'].includes(level);
+            case 'debug':
+                return true;
+            default:
+                return false;
+        }
+    }
+    formatMessage(namespace, message) {
+        return `[TraceLog:${namespace}] ${message}`;
+    }
+    getConsoleMethod(level) {
+        switch (level) {
+            case 'CLIENT_ERROR':
+            case 'ERROR':
+                return 'error';
+            case 'CLIENT_WARN':
+            case 'WARN':
+                return 'warn';
+            case 'INFO':
+            case 'DEBUG':
+            case 'VERBOSE':
+            default:
+                return 'log';
+        }
+    }
+    logMessage(level, namespace, message, data) {
+        if (!this.shouldShowLog(level)) {
+            return;
+        }
+        const formattedMessage = this.formatMessage(namespace, message);
+        const consoleMethod = this.getConsoleMethod(level);
+        if (data !== undefined) {
+            console[consoleMethod](formattedMessage, data);
+        }
+        else {
+            console[consoleMethod](formattedMessage);
+        }
+        if (process.env.NODE_ENV === 'dev') {
+            this.dispatchEvent(level, namespace, message, data);
+        }
+    }
+    /**
+     * Dispatches tracelog:log events for E2E testing and development debugging
+     */
+    dispatchEvent(level, namespace, message, data) {
+        if (typeof window === 'undefined' || typeof CustomEvent === 'undefined') {
+            return;
+        }
+        try {
+            const event = new CustomEvent('tracelog:log', {
+                detail: {
+                    timestamp: new Date().toISOString(),
+                    level,
+                    namespace,
+                    message,
+                    data,
+                },
+            });
+            window.dispatchEvent(event);
+        }
+        catch {
+            console.log(`[TraceLog:${namespace}] ${message}`, data);
+        }
+    }
+}
+/**
+ * Singleton debug logger instance
+ * Provides the same API as before: debugLog.clientError(), debugLog.info(), etc.
+ */
+exports.debugLog = new DebugLogger();

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

@@ -0,0 +1 @@
+export { debugLog } from './debug-logger.utils';

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

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.debugLog = void 0;
+var debug_logger_utils_1 = require("./debug-logger.utils");
+Object.defineProperty(exports, "debugLog", { enumerable: true, get: function () { return debug_logger_utils_1.debugLog; } });

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

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

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

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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("./url.utils"), exports);

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

@@ -0,0 +1,20 @@
+/**
+ * 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;
+/**
+ * Normalizes a URL by removing sensitive query parameters
+ * @param url - The URL to normalize
+ * @param sensitiveQueryParams - Array of parameter names to remove
+ * @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/cjs/utils/network/url.utils.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isUrlPathExcluded = exports.normalizeUrl = exports.getApiUrl = void 0;
+const validations_1 = require("../validations");
+const logging_1 = require("../logging");
+/**
+ * Generates an API URL based on project ID and current domain
+ * @param id - The project ID
+ * @returns The generated API URL
+ */
+const getApiUrl = (id, allowHttp = false) => {
+    logging_1.debugLog.debug('URLUtils', 'Generating API URL', { projectId: id, allowHttp });
+    const url = new URL(window.location.href);
+    const host = url.hostname;
+    const parts = host.split('.');
+    if (parts.length === 0) {
+        logging_1.debugLog.clientError('URLUtils', 'Invalid hostname - no domain parts found', { hostname: host });
+        throw new Error('Invalid URL');
+    }
+    const cleanDomain = parts.slice(-2).join('.');
+    const protocol = allowHttp && url.protocol === 'http:' ? 'http' : 'https';
+    const apiUrl = `${protocol}://${id}.${cleanDomain}`;
+    logging_1.debugLog.debug('URLUtils', 'Generated API URL', {
+        originalUrl: window.location.href,
+        hostname: host,
+        domainParts: parts.length,
+        cleanDomain,
+        protocol,
+        generatedUrl: apiUrl,
+    });
+    const isValid = (0, validations_1.isValidUrl)(apiUrl, allowHttp);
+    if (!isValid) {
+        logging_1.debugLog.clientError('URLUtils', 'Generated API URL failed validation', {
+            apiUrl,
+            allowHttp,
+        });
+        throw new Error('Invalid URL');
+    }
+    logging_1.debugLog.debug('URLUtils', 'API URL generation completed successfully', { apiUrl });
+    return apiUrl;
+};
+exports.getApiUrl = getApiUrl;
+/**
+ * Normalizes a URL by removing sensitive query parameters
+ * @param url - The URL to normalize
+ * @param sensitiveQueryParams - Array of parameter names to remove
+ * @returns The normalized URL
+ */
+const normalizeUrl = (url, sensitiveQueryParams = []) => {
+    logging_1.debugLog.debug('URLUtils', 'Normalizing URL', {
+        urlLength: url.length,
+        sensitiveParamsCount: sensitiveQueryParams.length,
+    });
+    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) => {
+            if (searchParams.has(param)) {
+                searchParams.delete(param);
+                hasChanged = true;
+                removedParams.push(param);
+            }
+        });
+        if (hasChanged) {
+            logging_1.debugLog.debug('URLUtils', 'Sensitive parameters removed from URL', {
+                removedParams,
+                originalParamCount,
+                finalParamCount: Array.from(searchParams.keys()).length,
+            });
+        }
+        if (!hasChanged && url.includes('?')) {
+            logging_1.debugLog.debug('URLUtils', 'URL normalization - no changes needed');
+            return url;
+        }
+        urlObject.search = searchParams.toString();
+        const result = urlObject.toString();
+        logging_1.debugLog.debug('URLUtils', 'URL normalization completed', {
+            hasChanged,
+            originalLength: url.length,
+            normalizedLength: result.length,
+        });
+        return result;
+    }
+    catch (error) {
+        logging_1.debugLog.warn('URLUtils', 'URL normalization failed, returning original', {
+            url: url.slice(0, 100),
+            error: error instanceof Error ? error.message : error,
+        });
+        return url;
+    }
+};
+exports.normalizeUrl = normalizeUrl;
+/**
+ * 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
+ */
+const isUrlPathExcluded = (url, excludedPaths = []) => {
+    logging_1.debugLog.debug('URLUtils', 'Checking if URL path is excluded', {
+        urlLength: url.length,
+        excludedPathsCount: excludedPaths.length,
+    });
+    if (excludedPaths.length === 0) {
+        logging_1.debugLog.debug('URLUtils', 'No excluded paths configured');
+        return false;
+    }
+    let path;
+    try {
+        path = new URL(url, window.location.origin).pathname;
+        logging_1.debugLog.debug('URLUtils', 'Extracted path from URL', { path });
+    }
+    catch (error) {
+        logging_1.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);
+                if (matches) {
+                    logging_1.debugLog.debug('URLUtils', 'Path matched regex pattern', { path, pattern: pattern.toString() });
+                }
+                return matches;
+            }
+            if (pattern.includes('*')) {
+                const regex = wildcardToRegex(pattern);
+                const matches = regex.test(path);
+                if (matches) {
+                    logging_1.debugLog.debug('URLUtils', 'Path matched wildcard pattern', { path, pattern, regex: regex.toString() });
+                }
+                return matches;
+            }
+            const matches = pattern === path;
+            if (matches) {
+                logging_1.debugLog.debug('URLUtils', 'Path matched exact pattern', { path, pattern });
+            }
+            return matches;
+        }
+        catch (error) {
+            logging_1.debugLog.warn('URLUtils', 'Error testing exclusion pattern', {
+                pattern,
+                path,
+                error: error instanceof Error ? error.message : error,
+            });
+            return false;
+        }
+    });
+    const isExcluded = !!matchedPattern;
+    logging_1.debugLog.debug('URLUtils', 'URL path exclusion check completed', {
+        path,
+        isExcluded,
+        matchedPattern: matchedPattern ?? null,
+        totalPatternsChecked: excludedPaths.length,
+    });
+    return isExcluded;
+};
+exports.isUrlPathExcluded = isUrlPathExcluded;

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

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

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

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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("./sanitize.utils"), exports);

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

@@ -0,0 +1,32 @@
+import { MetadataType } from '../../types/common.types';
+import { ApiConfig } from '../../types/config.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
+ * @returns The sanitized metadata
+ */
+export declare const sanitizeMetadata: (metadata: unknown) => Record<string, MetadataType>;
+/**
+ * Sanitizes URL strings for tracking
+ * @param url - The URL to sanitize
+ * @returns The sanitized URL
+ */
+export declare const sanitizeUrl: (url: string) => string;