@tracelog/lib 0.0.1

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

@@ -0,0 +1,136 @@
+import { StateManager } from '../../managers/state.manager';
+/**
+ * Debug logger class that extends StateManager for clean access to global state
+ */
+class DebugLogger extends 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.
+ */
+export const debugLog = new DebugLogger();

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,166 @@
+import { isValidUrl } from '../validations';
+import { debugLog } from '../logging';
+/**
+ * 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) => {
+    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) {
+        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}`;
+    debugLog.debug('URLUtils', 'Generated API URL', {
+        originalUrl: window.location.href,
+        hostname: host,
+        domainParts: parts.length,
+        cleanDomain,
+        protocol,
+        generatedUrl: apiUrl,
+    });
+    const isValid = isValidUrl(apiUrl, allowHttp);
+    if (!isValid) {
+        debugLog.clientError('URLUtils', 'Generated API URL failed validation', {
+            apiUrl,
+            allowHttp,
+        });
+        throw new Error('Invalid URL');
+    }
+    debugLog.debug('URLUtils', 'API URL generation completed successfully', { apiUrl });
+    return apiUrl;
+};
+/**
+ * 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 const normalizeUrl = (url, sensitiveQueryParams = []) => {
+    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) {
+            debugLog.debug('URLUtils', 'Sensitive parameters removed from URL', {
+                removedParams,
+                originalParamCount,
+                finalParamCount: Array.from(searchParams.keys()).length,
+            });
+        }
+        if (!hasChanged && url.includes('?')) {
+            debugLog.debug('URLUtils', 'URL normalization - no changes needed');
+            return url;
+        }
+        urlObject.search = searchParams.toString();
+        const result = urlObject.toString();
+        debugLog.debug('URLUtils', 'URL normalization completed', {
+            hasChanged,
+            originalLength: url.length,
+            normalizedLength: result.length,
+        });
+        return result;
+    }
+    catch (error) {
+        debugLog.warn('URLUtils', 'URL normalization failed, returning original', {
+            url: url.slice(0, 100),
+            error: error instanceof Error ? error.message : error,
+        });
+        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 = []) => {
+    debugLog.debug('URLUtils', 'Checking if URL path is excluded', {
+        urlLength: url.length,
+        excludedPathsCount: excludedPaths.length,
+    });
+    if (excludedPaths.length === 0) {
+        debugLog.debug('URLUtils', 'No excluded paths configured');
+        return false;
+    }
+    let path;
+    try {
+        path = new URL(url, window.location.origin).pathname;
+        debugLog.debug('URLUtils', 'Extracted path from URL', { path });
+    }
+    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);
+                if (matches) {
+                    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) {
+                    debugLog.debug('URLUtils', 'Path matched wildcard pattern', { path, pattern, regex: regex.toString() });
+                }
+                return matches;
+            }
+            const matches = pattern === path;
+            if (matches) {
+                debugLog.debug('URLUtils', 'Path matched exact pattern', { path, pattern });
+            }
+            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;
+    debugLog.debug('URLUtils', 'URL path exclusion check completed', {
+        path,
+        isExcluded,
+        matchedPattern: matchedPattern ?? null,
+        totalPatternsChecked: excludedPaths.length,
+    });
+    return isExcluded;
+};

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

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

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

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

package/dist/esm/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;

package/dist/esm/utils/security/sanitize.utils.js

@@ -0,0 +1,311 @@
+import { ALLOWED_API_CONFIG_KEYS, MAX_ARRAY_LENGTH, MAX_OBJECT_DEPTH, MAX_STRING_LENGTH, XSS_PATTERNS, } from '../../constants';
+import { debugLog } from '../logging';
+/**
+ * Sanitizes a string value to prevent XSS attacks
+ * @param value - The string to sanitize
+ * @returns The sanitized string
+ */
+export const sanitizeString = (value) => {
+    if (!value || typeof value !== 'string' || value.trim().length === 0) {
+        debugLog.debug('Sanitize', 'String sanitization skipped - empty or invalid input', { value, type: typeof value });
+        return '';
+    }
+    const originalLength = value.length;
+    let sanitized = value;
+    // Limit string length
+    if (value.length > MAX_STRING_LENGTH) {
+        sanitized = value.slice(0, Math.max(0, MAX_STRING_LENGTH));
+        debugLog.warn('Sanitize', 'String truncated due to length limit', {
+            originalLength,
+            maxLength: MAX_STRING_LENGTH,
+            truncatedLength: sanitized.length,
+        });
+    }
+    // Remove potential XSS patterns
+    let xssPatternMatches = 0;
+    for (const pattern of XSS_PATTERNS) {
+        const beforeReplace = sanitized;
+        sanitized = sanitized.replace(pattern, '');
+        if (beforeReplace !== sanitized) {
+            xssPatternMatches++;
+        }
+    }
+    if (xssPatternMatches > 0) {
+        debugLog.warn('Sanitize', 'XSS patterns detected and removed', {
+            patternMatches: xssPatternMatches,
+            originalValue: value.slice(0, 100), // Log first 100 chars for debugging
+        });
+    }
+    // Basic HTML entity encoding for critical characters
+    sanitized = sanitized
+        .replaceAll('&', '&')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&#x27;')
+        .replaceAll('/', '&#x2F;');
+    const result = sanitized.trim();
+    if (originalLength > 50 || xssPatternMatches > 0) {
+        debugLog.debug('Sanitize', 'String sanitization completed', {
+            originalLength,
+            sanitizedLength: result.length,
+            xssPatternMatches,
+            wasTruncated: originalLength > MAX_STRING_LENGTH,
+        });
+    }
+    return result;
+};
+/**
+ * Sanitizes a path string for route exclusion checks
+ * @param value - The path string to sanitize
+ * @returns The sanitized path string
+ */
+export const sanitizePathString = (value) => {
+    if (typeof value !== 'string') {
+        return '';
+    }
+    if (value.length > MAX_STRING_LENGTH) {
+        value = value.slice(0, Math.max(0, MAX_STRING_LENGTH));
+    }
+    let sanitized = value;
+    for (const pattern of XSS_PATTERNS) {
+        sanitized = sanitized.replace(pattern, '');
+    }
+    sanitized = sanitized
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&#x27;');
+    return sanitized.trim();
+};
+/**
+ * Sanitizes any value recursively with depth protection
+ * @param value - The value to sanitize
+ * @param depth - Current recursion depth
+ * @returns The sanitized value
+ */
+const sanitizeValue = (value, depth = 0) => {
+    // Prevent infinite recursion
+    if (depth > MAX_OBJECT_DEPTH) {
+        debugLog.warn('Sanitize', 'Maximum object depth exceeded during sanitization', {
+            depth,
+            maxDepth: MAX_OBJECT_DEPTH,
+        });
+        return null;
+    }
+    if (value === null || value === undefined) {
+        return null;
+    }
+    if (typeof value === 'string') {
+        return sanitizeString(value);
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value) || value < -Number.MAX_SAFE_INTEGER || value > Number.MAX_SAFE_INTEGER) {
+            debugLog.warn('Sanitize', 'Invalid number sanitized to 0', { value, isFinite: Number.isFinite(value) });
+            return 0;
+        }
+        return value;
+    }
+    if (typeof value === 'boolean') {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        const originalLength = value.length;
+        const limitedArray = value.slice(0, MAX_ARRAY_LENGTH);
+        if (originalLength > MAX_ARRAY_LENGTH) {
+            debugLog.warn('Sanitize', 'Array truncated due to length limit', {
+                originalLength,
+                maxLength: MAX_ARRAY_LENGTH,
+                depth,
+            });
+        }
+        const sanitizedArray = limitedArray.map((item) => sanitizeValue(item, depth + 1)).filter((item) => item !== null);
+        if (originalLength > 0 && sanitizedArray.length === 0) {
+            debugLog.warn('Sanitize', 'All array items were filtered out during sanitization', { originalLength, depth });
+        }
+        return sanitizedArray;
+    }
+    if (typeof value === 'object') {
+        const sanitizedObject = {};
+        const entries = Object.entries(value);
+        const originalKeysCount = entries.length;
+        const limitedEntries = entries.slice(0, 20);
+        if (originalKeysCount > 20) {
+            debugLog.warn('Sanitize', 'Object keys truncated due to limit', {
+                originalKeys: originalKeysCount,
+                maxKeys: 20,
+                depth,
+            });
+        }
+        let filteredKeysCount = 0;
+        for (const [key, value_] of limitedEntries) {
+            const sanitizedKey = sanitizeString(key);
+            if (sanitizedKey) {
+                const sanitizedValue = sanitizeValue(value_, depth + 1);
+                if (sanitizedValue !== null) {
+                    sanitizedObject[sanitizedKey] = sanitizedValue;
+                }
+                else {
+                    filteredKeysCount++;
+                }
+            }
+            else {
+                filteredKeysCount++;
+            }
+        }
+        if (filteredKeysCount > 0) {
+            debugLog.debug('Sanitize', 'Object properties filtered during sanitization', {
+                filteredKeysCount,
+                remainingKeys: Object.keys(sanitizedObject).length,
+                depth,
+            });
+        }
+        return sanitizedObject;
+    }
+    debugLog.debug('Sanitize', 'Unknown value type sanitized to null', { type: typeof value, depth });
+    return null;
+};
+/**
+ * Sanitizes API configuration data with strict validation
+ * @param data - The API config data to sanitize
+ * @returns The sanitized API config
+ */
+export const sanitizeApiConfig = (data) => {
+    debugLog.debug('Sanitize', 'Starting API config sanitization');
+    const safeData = {};
+    if (typeof data !== 'object' || data === null) {
+        debugLog.warn('Sanitize', 'API config data is not an object', { data, type: typeof data });
+        return safeData;
+    }
+    try {
+        const originalKeys = Object.keys(data);
+        let processedKeys = 0;
+        let filteredKeys = 0;
+        for (const key of originalKeys) {
+            if (ALLOWED_API_CONFIG_KEYS.has(key)) {
+                const value = data[key];
+                if (key === 'excludedUrlPaths') {
+                    const paths = Array.isArray(value) ? value : typeof value === 'string' ? [value] : [];
+                    const originalPathsCount = paths.length;
+                    safeData.excludedUrlPaths = paths.map((path) => sanitizePathString(String(path))).filter(Boolean);
+                    const filteredPathsCount = originalPathsCount - safeData.excludedUrlPaths.length;
+                    if (filteredPathsCount > 0) {
+                        debugLog.warn('Sanitize', 'Some excluded URL paths were filtered during sanitization', {
+                            originalCount: originalPathsCount,
+                            filteredCount: filteredPathsCount,
+                        });
+                    }
+                }
+                else if (key === 'tags') {
+                    if (Array.isArray(value)) {
+                        safeData.tags = value;
+                        debugLog.debug('Sanitize', 'Tags processed', { count: value.length });
+                    }
+                    else {
+                        debugLog.warn('Sanitize', 'Tags value is not an array', { value, type: typeof value });
+                    }
+                }
+                else {
+                    const sanitizedValue = sanitizeValue(value);
+                    if (sanitizedValue !== null) {
+                        safeData[key] = sanitizedValue;
+                    }
+                    else {
+                        debugLog.warn('Sanitize', 'API config value sanitized to null', { key, originalValue: value });
+                    }
+                }
+                processedKeys++;
+            }
+            else {
+                filteredKeys++;
+                debugLog.debug('Sanitize', 'API config key not allowed', { key });
+            }
+        }
+        debugLog.info('Sanitize', 'API config sanitization completed', {
+            originalKeys: originalKeys.length,
+            processedKeys,
+            filteredKeys,
+            finalKeys: Object.keys(safeData).length,
+        });
+    }
+    catch (error) {
+        debugLog.error('Sanitize', 'API config sanitization failed', {
+            error: error instanceof Error ? error.message : error,
+        });
+        throw new Error(`API config sanitization failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+    return safeData;
+};
+/**
+ * Sanitizes user metadata for custom events
+ * @param metadata - The metadata to sanitize
+ * @returns The sanitized metadata
+ */
+export const sanitizeMetadata = (metadata) => {
+    debugLog.debug('Sanitize', 'Starting metadata sanitization', { hasMetadata: metadata != null });
+    if (typeof metadata !== 'object' || metadata === null) {
+        debugLog.debug('Sanitize', 'Metadata is not an object, returning empty object', {
+            metadata,
+            type: typeof metadata,
+        });
+        return {};
+    }
+    try {
+        const originalKeys = Object.keys(metadata).length;
+        const sanitized = sanitizeValue(metadata);
+        const result = typeof sanitized === 'object' && sanitized !== null ? sanitized : {};
+        const finalKeys = Object.keys(result).length;
+        debugLog.debug('Sanitize', 'Metadata sanitization completed', {
+            originalKeys,
+            finalKeys,
+            keysFiltered: originalKeys - finalKeys,
+        });
+        return result;
+    }
+    catch (error) {
+        debugLog.error('Sanitize', 'Metadata sanitization failed', {
+            error: error instanceof Error ? error.message : error,
+        });
+        throw new Error(`Metadata sanitization failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+};
+/**
+ * Sanitizes URL strings for tracking
+ * @param url - The URL to sanitize
+ * @returns The sanitized URL
+ */
+export const sanitizeUrl = (url) => {
+    debugLog.debug('Sanitize', 'Starting URL sanitization', { urlLength: typeof url === 'string' ? url.length : 0 });
+    if (typeof url !== 'string') {
+        debugLog.warn('Sanitize', 'URL is not a string', { url, type: typeof url });
+        return '';
+    }
+    try {
+        // Basic URL validation
+        const urlObject = new URL(url);
+        // Only allow http/https protocols
+        if (!['http:', 'https:'].includes(urlObject.protocol)) {
+            debugLog.warn('Sanitize', 'URL protocol not allowed', {
+                protocol: urlObject.protocol,
+                allowedProtocols: ['http:', 'https:'],
+            });
+            return '';
+        }
+        // Sanitize the URL string
+        const result = sanitizeString(urlObject.href);
+        debugLog.debug('Sanitize', 'URL sanitization completed via URL object', {
+            originalLength: url.length,
+            sanitizedLength: result.length,
+            protocol: urlObject.protocol,
+        });
+        return result;
+    }
+    catch {
+        // If URL parsing fails, sanitize as string
+        debugLog.warn('Sanitize', 'URL parsing failed, falling back to string sanitization', {
+            urlPreview: url.slice(0, 100),
+        });
+        return sanitizeString(url);
+    }
+};