@tracelog/lib 0.0.1

package/dist/esm/utils/validations/config-validations.utils.d.ts

@@ -0,0 +1,42 @@
+import { AppConfig, Config, ApiConfig } from '../../types';
+/**
+ * Validates the app configuration object (before normalization)
+ * This validates the structure and basic types but allows for normalization afterward
+ * @param config - The app configuration to validate
+ * @throws {ProjectIdValidationError} If project ID validation fails
+ * @throws {AppConfigValidationError} If other configuration validation fails
+ */
+export declare const validateAppConfig: (config: AppConfig) => void;
+/**
+ * Validates and normalizes the app configuration
+ * This is the primary validation entry point that ensures consistent behavior
+ * @param config - The app configuration to validate and normalize
+ * @returns The normalized configuration
+ * @throws {ProjectIdValidationError} If project ID validation fails after normalization
+ * @throws {AppConfigValidationError} If other configuration validation fails
+ */
+export declare const validateAndNormalizeConfig: (config: AppConfig) => AppConfig;
+/**
+ * Validates a complete configuration object
+ * @param config - The configuration to validate
+ * @returns Validation result with errors and warnings
+ */
+export declare const validateConfig: (config: Config) => {
+    errors: string[];
+    warnings: string[];
+};
+/**
+ * Validates the final configuration
+ * @param config - The configuration to validate
+ * @returns Validation result with errors and warnings
+ */
+export declare const validateFinalConfig: (config: Config) => {
+    errors: string[];
+    warnings: string[];
+};
+/**
+ * Type guard to check if a JSON response is a valid API config
+ * @param json - The JSON to validate
+ * @returns True if the JSON is a valid API config
+ */
+export declare const isValidConfigApiResponse: (json: unknown) => json is ApiConfig;

package/dist/esm/utils/validations/config-validations.utils.js

@@ -0,0 +1,289 @@
+import { MAX_SESSION_TIMEOUT_MS, MIN_SESSION_TIMEOUT_MS, VALIDATION_MESSAGES } from '../../constants';
+import { Mode } from '../../types';
+import { ProjectIdValidationError, AppConfigValidationError, SessionTimeoutValidationError, SamplingRateValidationError, IntegrationValidationError, } from '../../types/validation-error.types';
+import { debugLog } from '../logging';
+/**
+ * Validates the app configuration object (before normalization)
+ * This validates the structure and basic types but allows for normalization afterward
+ * @param config - The app configuration to validate
+ * @throws {ProjectIdValidationError} If project ID validation fails
+ * @throws {AppConfigValidationError} If other configuration validation fails
+ */
+export const validateAppConfig = (config) => {
+    // Validate config exists and has id property
+    if (!config || typeof config !== 'object') {
+        debugLog.clientError('ConfigValidation', 'Configuration must be an object', { config });
+        throw new AppConfigValidationError('Configuration must be an object', 'config');
+    }
+    // Check if id property exists (allow falsy values to be handled by normalization)
+    if (!('id' in config)) {
+        debugLog.clientError('ConfigValidation', 'Project ID is missing from configuration');
+        throw new ProjectIdValidationError(VALIDATION_MESSAGES.MISSING_PROJECT_ID, 'config');
+    }
+    // Check basic type - null, undefined, or non-string values should fail here
+    if (config.id === null || config.id === undefined || typeof config.id !== 'string') {
+        debugLog.clientError('ConfigValidation', 'Project ID must be a non-empty string', {
+            providedId: config.id,
+            type: typeof config.id,
+        });
+        throw new ProjectIdValidationError(VALIDATION_MESSAGES.MISSING_PROJECT_ID, 'config');
+    }
+    if (config.sessionTimeout !== undefined) {
+        if (typeof config.sessionTimeout !== 'number' ||
+            config.sessionTimeout < MIN_SESSION_TIMEOUT_MS ||
+            config.sessionTimeout > MAX_SESSION_TIMEOUT_MS) {
+            debugLog.clientError('ConfigValidation', 'Invalid session timeout', {
+                provided: config.sessionTimeout,
+                min: MIN_SESSION_TIMEOUT_MS,
+                max: MAX_SESSION_TIMEOUT_MS,
+            });
+            throw new SessionTimeoutValidationError(VALIDATION_MESSAGES.INVALID_SESSION_TIMEOUT, 'config');
+        }
+    }
+    if (config.globalMetadata !== undefined) {
+        if (typeof config.globalMetadata !== 'object' || config.globalMetadata === null) {
+            debugLog.clientError('ConfigValidation', 'Global metadata must be an object', {
+                provided: config.globalMetadata,
+                type: typeof config.globalMetadata,
+            });
+            throw new AppConfigValidationError(VALIDATION_MESSAGES.INVALID_GLOBAL_METADATA, 'config');
+        }
+    }
+    if (config.scrollContainerSelectors !== undefined) {
+        validateScrollContainerSelectors(config.scrollContainerSelectors);
+    }
+    if (config.integrations) {
+        validateIntegrations(config.integrations);
+    }
+    if (config.sensitiveQueryParams !== undefined) {
+        if (!Array.isArray(config.sensitiveQueryParams)) {
+            debugLog.clientError('ConfigValidation', 'Sensitive query params must be an array', {
+                provided: config.sensitiveQueryParams,
+                type: typeof config.sensitiveQueryParams,
+            });
+            throw new AppConfigValidationError(VALIDATION_MESSAGES.INVALID_SENSITIVE_QUERY_PARAMS, 'config');
+        }
+        for (const param of config.sensitiveQueryParams) {
+            if (typeof param !== 'string') {
+                debugLog.clientError('ConfigValidation', 'All sensitive query params must be strings', {
+                    param,
+                    type: typeof param,
+                });
+                throw new AppConfigValidationError('All sensitive query params must be strings', 'config');
+            }
+        }
+    }
+    if (config.errorSampling !== undefined) {
+        if (typeof config.errorSampling !== 'number' || config.errorSampling < 0 || config.errorSampling > 1) {
+            debugLog.clientError('ConfigValidation', 'Invalid error sampling rate', {
+                provided: config.errorSampling,
+                expected: '0-1',
+            });
+            throw new SamplingRateValidationError(VALIDATION_MESSAGES.INVALID_ERROR_SAMPLING_RATE, 'config');
+        }
+    }
+};
+/**
+ * Validates scroll container selectors
+ * @param selectors - CSS selectors to validate
+ */
+const validateScrollContainerSelectors = (selectors) => {
+    const selectorsArray = Array.isArray(selectors) ? selectors : [selectors];
+    for (const selector of selectorsArray) {
+        if (typeof selector !== 'string' || selector.trim() === '') {
+            debugLog.clientError('ConfigValidation', 'Invalid scroll container selector', {
+                selector,
+                type: typeof selector,
+                isEmpty: selector === '' || (typeof selector === 'string' && selector.trim() === ''),
+            });
+            throw new AppConfigValidationError(VALIDATION_MESSAGES.INVALID_SCROLL_CONTAINER_SELECTORS, 'config');
+        }
+        // Validate CSS selector syntax but handle invalid selectors gracefully
+        if (typeof document !== 'undefined') {
+            try {
+                document.querySelector(selector);
+            }
+            catch {
+                // Invalid CSS selectors are handled gracefully
+                // they will be ignored by the ScrollHandler and it will fall back to window scrolling
+                debugLog.clientWarn('ConfigValidation', `Invalid CSS selector will be ignored: "${selector}"`);
+            }
+        }
+    }
+};
+/**
+ * Validates integrations configuration
+ * @param integrations - Integrations configuration to validate
+ */
+const validateIntegrations = (integrations) => {
+    if (!integrations)
+        return;
+    if (integrations.googleAnalytics) {
+        if (!integrations.googleAnalytics.measurementId ||
+            typeof integrations.googleAnalytics.measurementId !== 'string' ||
+            integrations.googleAnalytics.measurementId.trim() === '') {
+            debugLog.clientError('ConfigValidation', 'Invalid Google Analytics measurement ID', {
+                provided: integrations.googleAnalytics.measurementId,
+                type: typeof integrations.googleAnalytics.measurementId,
+            });
+            throw new IntegrationValidationError(VALIDATION_MESSAGES.INVALID_GOOGLE_ANALYTICS_ID, 'config');
+        }
+        const measurementId = integrations.googleAnalytics.measurementId.trim();
+        if (!measurementId.match(/^(G-|UA-)/)) {
+            debugLog.clientError('ConfigValidation', 'Google Analytics measurement ID must start with "G-" or "UA-"', {
+                provided: measurementId,
+            });
+            throw new IntegrationValidationError('Google Analytics measurement ID must start with "G-" or "UA-"', 'config');
+        }
+    }
+};
+/**
+ * Validates and normalizes the app configuration
+ * This is the primary validation entry point that ensures consistent behavior
+ * @param config - The app configuration to validate and normalize
+ * @returns The normalized configuration
+ * @throws {ProjectIdValidationError} If project ID validation fails after normalization
+ * @throws {AppConfigValidationError} If other configuration validation fails
+ */
+export const validateAndNormalizeConfig = (config) => {
+    // First validate the structure and basic types
+    validateAppConfig(config);
+    // Normalize string values
+    const normalizedConfig = {
+        ...config,
+        id: config.id.trim(),
+        globalMetadata: config.globalMetadata ?? {},
+        sensitiveQueryParams: config.sensitiveQueryParams ?? [],
+    };
+    // Validate normalized values - this catches whitespace-only IDs
+    if (!normalizedConfig.id) {
+        debugLog.clientError('ConfigValidation', 'Project ID is empty after trimming whitespace', {
+            originalId: config.id,
+            normalizedId: normalizedConfig.id,
+        });
+        throw new ProjectIdValidationError(VALIDATION_MESSAGES.PROJECT_ID_EMPTY_AFTER_TRIM, 'config');
+    }
+    return normalizedConfig;
+};
+/**
+ * Validates sampling rate
+ * @param samplingRate - The sampling rate to validate
+ * @param errors - Array to push errors to
+ */
+const validateSamplingRate = (samplingRate, errors) => {
+    if (samplingRate !== undefined) {
+        if (typeof samplingRate !== 'number') {
+            errors.push('samplingRate must be a number');
+        }
+        else if (samplingRate < 0 || samplingRate > 1) {
+            errors.push('samplingRate must be between 0 and 1');
+        }
+    }
+};
+/**
+ * Validates excluded URL paths
+ * @param excludedUrlPaths - The excluded URL paths to validate
+ * @param errors - Array to push errors to
+ * @param prefix - Optional prefix for error messages
+ */
+const validateExcludedUrlPaths = (excludedUrlPaths, errors, prefix = '') => {
+    if (excludedUrlPaths !== undefined) {
+        if (Array.isArray(excludedUrlPaths)) {
+            for (const [index, path] of excludedUrlPaths.entries()) {
+                if (typeof path === 'string') {
+                    try {
+                        new RegExp(path);
+                    }
+                    catch {
+                        errors.push(`${prefix}excludedUrlPaths[${index}] is not a valid regex pattern`);
+                    }
+                }
+                else {
+                    errors.push(`${prefix}excludedUrlPaths[${index}] must be a string`);
+                }
+            }
+        }
+        else {
+            errors.push(`${prefix}excludedUrlPaths must be an array`);
+        }
+    }
+};
+/**
+ * Validates a complete configuration object
+ * @param config - The configuration to validate
+ * @returns Validation result with errors and warnings
+ */
+export const validateConfig = (config) => {
+    const errors = [];
+    const warnings = [];
+    if (config.sessionTimeout !== undefined) {
+        if (typeof config.sessionTimeout !== 'number') {
+            errors.push('sessionTimeout must be a number');
+        }
+        else if (config.sessionTimeout < MIN_SESSION_TIMEOUT_MS) {
+            errors.push('sessionTimeout must be at least 30 seconds (30000ms)');
+        }
+        else if (config.sessionTimeout > MAX_SESSION_TIMEOUT_MS) {
+            warnings.push('sessionTimeout is very long (>24 hours), consider reducing it');
+        }
+    }
+    if (config.globalMetadata !== undefined) {
+        if (typeof config.globalMetadata !== 'object' || config.globalMetadata === null) {
+            errors.push('globalMetadata must be an object');
+        }
+        else {
+            const metadataSize = JSON.stringify(config.globalMetadata).length;
+            if (metadataSize > 10240) {
+                errors.push('globalMetadata is too large (max 10KB)');
+            }
+            if (Object.keys(config.globalMetadata).length > 12) {
+                errors.push('globalMetadata has too many keys (max 12)');
+            }
+        }
+    }
+    // No custom API endpoints supported
+    validateSamplingRate(config.samplingRate, errors);
+    if (config.tags !== undefined && !Array.isArray(config.tags)) {
+        errors.push('tags must be an array');
+    }
+    validateExcludedUrlPaths(config.excludedUrlPaths, errors);
+    return { errors, warnings };
+};
+/**
+ * Validates the final configuration
+ * @param config - The configuration to validate
+ * @returns Validation result with errors and warnings
+ */
+export const validateFinalConfig = (config) => {
+    const errors = [];
+    const warnings = [];
+    validateSamplingRate(config.samplingRate, errors);
+    validateExcludedUrlPaths(config.excludedUrlPaths, errors);
+    // No custom API endpoints supported
+    return { errors, warnings };
+};
+/**
+ * Type guard to check if a JSON response is a valid API config
+ * @param json - The JSON to validate
+ * @returns True if the JSON is a valid API config
+ */
+export const isValidConfigApiResponse = (json) => {
+    try {
+        if (typeof json !== 'object' || !json) {
+            return false;
+        }
+        const response = json;
+        const result = {
+            mode: response['mode'] === undefined || [Mode.QA, Mode.DEBUG].includes(response['mode']),
+            samplingRate: response['samplingRate'] === undefined ||
+                (typeof response['samplingRate'] === 'number' && response['samplingRate'] > 0 && response['samplingRate'] <= 1),
+            tags: response['tags'] === undefined || Array.isArray(response['tags']),
+            excludedUrlPaths: response['excludedUrlPaths'] === undefined || Array.isArray(response['excludedUrlPaths']),
+            ipExcluded: response['ipExcluded'] === undefined || typeof response['ipExcluded'] === 'boolean',
+        };
+        return Object.values(result).every(Boolean);
+    }
+    catch {
+        return false;
+    }
+};

package/dist/esm/utils/validations/event-validations.utils.d.ts

@@ -0,0 +1,12 @@
+import { MetadataType } from '../../types';
+/**
+ * Validates a complete event with name and optional metadata
+ * @param eventName - The event name to validate
+ * @param metadata - Optional metadata to validate
+ * @returns Validation result with sanitized metadata if valid
+ */
+export declare const isEventValid: (eventName: string, metadata?: Record<string, unknown>) => {
+    valid: boolean;
+    error?: string;
+    sanitizedMetadata?: Record<string, MetadataType>;
+};

package/dist/esm/utils/validations/event-validations.utils.js

@@ -0,0 +1,26 @@
+import { isValidEventName, isValidMetadata } from './metadata-validations.utils';
+import { debugLog } from '../logging';
+/**
+ * Validates a complete event with name and optional metadata
+ * @param eventName - The event name to validate
+ * @param metadata - Optional metadata to validate
+ * @returns Validation result with sanitized metadata if valid
+ */
+export const isEventValid = (eventName, metadata) => {
+    const nameValidation = isValidEventName(eventName);
+    if (!nameValidation.valid) {
+        debugLog.clientError('EventValidation', 'Event name validation failed', { eventName, error: nameValidation.error });
+        return nameValidation;
+    }
+    if (!metadata) {
+        return { valid: true };
+    }
+    const metadataValidation = isValidMetadata(eventName, metadata, 'customEvent');
+    if (!metadataValidation.valid) {
+        debugLog.clientError('EventValidation', 'Event metadata validation failed', {
+            eventName,
+            error: metadataValidation.error,
+        });
+    }
+    return metadataValidation;
+};

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

@@ -0,0 +1,5 @@
+export * from './config-validations.utils';
+export * from './event-validations.utils';
+export * from './metadata-validations.utils';
+export * from './type-guards.utils';
+export * from './url-validations.utils';

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

@@ -0,0 +1,5 @@
+export * from './config-validations.utils';
+export * from './event-validations.utils';
+export * from './metadata-validations.utils';
+export * from './type-guards.utils';
+export * from './url-validations.utils';

package/dist/esm/utils/validations/metadata-validations.utils.d.ts

@@ -0,0 +1,22 @@
+import { MetadataType } from '../../types';
+/**
+ * Validates an event name
+ * @param eventName - The event name to validate
+ * @returns Validation result with error message if invalid
+ */
+export declare const isValidEventName: (eventName: string) => {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Validates metadata for events
+ * @param eventName - The event name (for error messages)
+ * @param metadata - The metadata to validate
+ * @param type - Type of metadata (globalMetadata or customEvent)
+ * @returns Validation result with sanitized metadata if valid
+ */
+export declare const isValidMetadata: (eventName: string, metadata: Record<string, unknown>, type?: "globalMetadata" | "customEvent") => {
+    valid: boolean;
+    error?: string;
+    sanitizedMetadata?: Record<string, MetadataType>;
+};

package/dist/esm/utils/validations/metadata-validations.utils.js

@@ -0,0 +1,110 @@
+import { MAX_CUSTOM_EVENT_ARRAY_SIZE, MAX_CUSTOM_EVENT_KEYS, MAX_CUSTOM_EVENT_NAME_LENGTH, MAX_CUSTOM_EVENT_STRING_SIZE, MAX_STRING_LENGTH, } from '../../constants';
+import { sanitizeMetadata } from '../security/sanitize.utils';
+import { isOnlyPrimitiveFields } from './type-guards.utils';
+/**
+ * Validates an event name
+ * @param eventName - The event name to validate
+ * @returns Validation result with error message if invalid
+ */
+export const isValidEventName = (eventName) => {
+    if (typeof eventName !== 'string') {
+        return {
+            valid: false,
+            error: 'Event name must be a string',
+        };
+    }
+    if (eventName.length === 0) {
+        return {
+            valid: false,
+            error: 'Event name cannot be empty',
+        };
+    }
+    if (eventName.length > MAX_CUSTOM_EVENT_NAME_LENGTH) {
+        return {
+            valid: false,
+            error: `Event name is too long (max ${MAX_CUSTOM_EVENT_NAME_LENGTH} characters)`,
+        };
+    }
+    if (eventName.includes('<') || eventName.includes('>') || eventName.includes('&')) {
+        return {
+            valid: false,
+            error: 'Event name contains invalid characters',
+        };
+    }
+    const reservedWords = ['constructor', 'prototype', '__proto__', 'eval', 'function', 'var', 'let', 'const'];
+    if (reservedWords.includes(eventName.toLowerCase())) {
+        return {
+            valid: false,
+            error: 'Event name cannot be a reserved word',
+        };
+    }
+    return { valid: true };
+};
+/**
+ * Validates metadata for events
+ * @param eventName - The event name (for error messages)
+ * @param metadata - The metadata to validate
+ * @param type - Type of metadata (globalMetadata or customEvent)
+ * @returns Validation result with sanitized metadata if valid
+ */
+export const isValidMetadata = (eventName, metadata, type) => {
+    const sanitizedMetadata = sanitizeMetadata(metadata);
+    const intro = type && type === 'customEvent' ? `${type} "${eventName}" metadata error` : `${eventName} metadata error`;
+    if (!isOnlyPrimitiveFields(sanitizedMetadata)) {
+        return {
+            valid: false,
+            error: `${intro}: object has invalid types. Valid types are string, number, boolean or string arrays.`,
+        };
+    }
+    let jsonString;
+    try {
+        jsonString = JSON.stringify(sanitizedMetadata);
+    }
+    catch {
+        return {
+            valid: false,
+            error: `${intro}: object contains circular references or cannot be serialized.`,
+        };
+    }
+    if (jsonString.length > MAX_CUSTOM_EVENT_STRING_SIZE) {
+        return {
+            valid: false,
+            error: `${intro}: object is too large (max ${MAX_CUSTOM_EVENT_STRING_SIZE / 1024} KB).`,
+        };
+    }
+    const keyCount = Object.keys(sanitizedMetadata).length;
+    if (keyCount > MAX_CUSTOM_EVENT_KEYS) {
+        return {
+            valid: false,
+            error: `${intro}: object has too many keys (max ${MAX_CUSTOM_EVENT_KEYS} keys).`,
+        };
+    }
+    for (const [key, value] of Object.entries(sanitizedMetadata)) {
+        if (Array.isArray(value)) {
+            if (value.length > MAX_CUSTOM_EVENT_ARRAY_SIZE) {
+                return {
+                    valid: false,
+                    error: `${intro}: array property "${key}" is too large (max ${MAX_CUSTOM_EVENT_ARRAY_SIZE} items).`,
+                };
+            }
+            for (const item of value) {
+                if (typeof item === 'string' && item.length > 500) {
+                    return {
+                        valid: false,
+                        error: `${intro}: array property "${key}" contains strings that are too long (max 500 characters).`,
+                    };
+                }
+            }
+        }
+        if (typeof value === 'string' && value.length > MAX_STRING_LENGTH) {
+            return {
+                valid: false,
+                error: `${intro}: property "${key}" is too long (max ${MAX_STRING_LENGTH} characters).`,
+            };
+        }
+    }
+    return {
+        valid: true,
+        sanitizedMetadata,
+    };
+};

package/dist/esm/utils/validations/type-guards.utils.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Checks if an object contains only primitive fields (string, number, boolean, or string arrays)
+ * @param object - The object to check
+ * @returns True if the object contains only primitive fields
+ */
+export declare const isOnlyPrimitiveFields: (object: Record<string, unknown>) => boolean;

package/dist/esm/utils/validations/type-guards.utils.js

@@ -0,0 +1,27 @@
+/**
+ * Checks if an object contains only primitive fields (string, number, boolean, or string arrays)
+ * @param object - The object to check
+ * @returns True if the object contains only primitive fields
+ */
+export const isOnlyPrimitiveFields = (object) => {
+    if (typeof object !== 'object' || object === null) {
+        return false;
+    }
+    for (const value of Object.values(object)) {
+        if (value === null || value === undefined) {
+            continue;
+        }
+        const type = typeof value;
+        if (type === 'string' || type === 'number' || type === 'boolean') {
+            continue;
+        }
+        if (Array.isArray(value)) {
+            if (!value.every((item) => typeof item === 'string')) {
+                return false;
+            }
+            continue;
+        }
+        return false;
+    }
+    return true;
+};

package/dist/esm/utils/validations/url-validations.utils.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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
+ */
+export declare const isValidUrl: (url: string, allowHttp?: boolean) => boolean;
+/**
+ * Validates a URL field in configuration
+ * @param url - The URL to validate
+ * @param allowHttp - Whether to allow HTTP URLs
+ * @param fieldName - The name of the field being validated
+ * @param errors - Array to push errors to
+ */
+export declare const validateUrl: (url: unknown, allowHttp: boolean | undefined, fieldName: string, errors: string[]) => void;

package/dist/esm/utils/validations/url-validations.utils.js

@@ -0,0 +1,42 @@
+/**
+ * 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
+ */
+export 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;
+    }
+};
+/**
+ * Validates a URL field in configuration
+ * @param url - The URL to validate
+ * @param allowHttp - Whether to allow HTTP URLs
+ * @param fieldName - The name of the field being validated
+ * @param errors - Array to push errors to
+ */
+export const validateUrl = (url, allowHttp, fieldName, errors) => {
+    if (url !== undefined) {
+        if (typeof url === 'string') {
+            try {
+                const parsed = new URL(url);
+                if (parsed.protocol === 'http:' && !allowHttp) {
+                    errors.push(`${fieldName} using http requires allowHttp=true`);
+                }
+            }
+            catch {
+                errors.push(`${fieldName} must be a valid URL`);
+            }
+        }
+        else {
+            errors.push(`${fieldName} must be a string`);
+        }
+    }
+};