@tracelog/lib 0.0.1

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

@@ -0,0 +1,319 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeUrl = exports.sanitizeMetadata = exports.sanitizeApiConfig = exports.sanitizePathString = exports.sanitizeString = void 0;
+const constants_1 = require("../../constants");
+const logging_1 = require("../logging");
+/**
+ * Sanitizes a string value to prevent XSS attacks
+ * @param value - The string to sanitize
+ * @returns The sanitized string
+ */
+const sanitizeString = (value) => {
+    if (!value || typeof value !== 'string' || value.trim().length === 0) {
+        logging_1.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 > constants_1.MAX_STRING_LENGTH) {
+        sanitized = value.slice(0, Math.max(0, constants_1.MAX_STRING_LENGTH));
+        logging_1.debugLog.warn('Sanitize', 'String truncated due to length limit', {
+            originalLength,
+            maxLength: constants_1.MAX_STRING_LENGTH,
+            truncatedLength: sanitized.length,
+        });
+    }
+    // Remove potential XSS patterns
+    let xssPatternMatches = 0;
+    for (const pattern of constants_1.XSS_PATTERNS) {
+        const beforeReplace = sanitized;
+        sanitized = sanitized.replace(pattern, '');
+        if (beforeReplace !== sanitized) {
+            xssPatternMatches++;
+        }
+    }
+    if (xssPatternMatches > 0) {
+        logging_1.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) {
+        logging_1.debugLog.debug('Sanitize', 'String sanitization completed', {
+            originalLength,
+            sanitizedLength: result.length,
+            xssPatternMatches,
+            wasTruncated: originalLength > constants_1.MAX_STRING_LENGTH,
+        });
+    }
+    return result;
+};
+exports.sanitizeString = sanitizeString;
+/**
+ * Sanitizes a path string for route exclusion checks
+ * @param value - The path string to sanitize
+ * @returns The sanitized path string
+ */
+const sanitizePathString = (value) => {
+    if (typeof value !== 'string') {
+        return '';
+    }
+    if (value.length > constants_1.MAX_STRING_LENGTH) {
+        value = value.slice(0, Math.max(0, constants_1.MAX_STRING_LENGTH));
+    }
+    let sanitized = value;
+    for (const pattern of constants_1.XSS_PATTERNS) {
+        sanitized = sanitized.replace(pattern, '');
+    }
+    sanitized = sanitized
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&#x27;');
+    return sanitized.trim();
+};
+exports.sanitizePathString = sanitizePathString;
+/**
+ * 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 > constants_1.MAX_OBJECT_DEPTH) {
+        logging_1.debugLog.warn('Sanitize', 'Maximum object depth exceeded during sanitization', {
+            depth,
+            maxDepth: constants_1.MAX_OBJECT_DEPTH,
+        });
+        return null;
+    }
+    if (value === null || value === undefined) {
+        return null;
+    }
+    if (typeof value === 'string') {
+        return (0, exports.sanitizeString)(value);
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value) || value < -Number.MAX_SAFE_INTEGER || value > Number.MAX_SAFE_INTEGER) {
+            logging_1.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, constants_1.MAX_ARRAY_LENGTH);
+        if (originalLength > constants_1.MAX_ARRAY_LENGTH) {
+            logging_1.debugLog.warn('Sanitize', 'Array truncated due to length limit', {
+                originalLength,
+                maxLength: constants_1.MAX_ARRAY_LENGTH,
+                depth,
+            });
+        }
+        const sanitizedArray = limitedArray.map((item) => sanitizeValue(item, depth + 1)).filter((item) => item !== null);
+        if (originalLength > 0 && sanitizedArray.length === 0) {
+            logging_1.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) {
+            logging_1.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 = (0, exports.sanitizeString)(key);
+            if (sanitizedKey) {
+                const sanitizedValue = sanitizeValue(value_, depth + 1);
+                if (sanitizedValue !== null) {
+                    sanitizedObject[sanitizedKey] = sanitizedValue;
+                }
+                else {
+                    filteredKeysCount++;
+                }
+            }
+            else {
+                filteredKeysCount++;
+            }
+        }
+        if (filteredKeysCount > 0) {
+            logging_1.debugLog.debug('Sanitize', 'Object properties filtered during sanitization', {
+                filteredKeysCount,
+                remainingKeys: Object.keys(sanitizedObject).length,
+                depth,
+            });
+        }
+        return sanitizedObject;
+    }
+    logging_1.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
+ */
+const sanitizeApiConfig = (data) => {
+    logging_1.debugLog.debug('Sanitize', 'Starting API config sanitization');
+    const safeData = {};
+    if (typeof data !== 'object' || data === null) {
+        logging_1.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 (constants_1.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) => (0, exports.sanitizePathString)(String(path))).filter(Boolean);
+                    const filteredPathsCount = originalPathsCount - safeData.excludedUrlPaths.length;
+                    if (filteredPathsCount > 0) {
+                        logging_1.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;
+                        logging_1.debugLog.debug('Sanitize', 'Tags processed', { count: value.length });
+                    }
+                    else {
+                        logging_1.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 {
+                        logging_1.debugLog.warn('Sanitize', 'API config value sanitized to null', { key, originalValue: value });
+                    }
+                }
+                processedKeys++;
+            }
+            else {
+                filteredKeys++;
+                logging_1.debugLog.debug('Sanitize', 'API config key not allowed', { key });
+            }
+        }
+        logging_1.debugLog.info('Sanitize', 'API config sanitization completed', {
+            originalKeys: originalKeys.length,
+            processedKeys,
+            filteredKeys,
+            finalKeys: Object.keys(safeData).length,
+        });
+    }
+    catch (error) {
+        logging_1.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;
+};
+exports.sanitizeApiConfig = sanitizeApiConfig;
+/**
+ * Sanitizes user metadata for custom events
+ * @param metadata - The metadata to sanitize
+ * @returns The sanitized metadata
+ */
+const sanitizeMetadata = (metadata) => {
+    logging_1.debugLog.debug('Sanitize', 'Starting metadata sanitization', { hasMetadata: metadata != null });
+    if (typeof metadata !== 'object' || metadata === null) {
+        logging_1.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;
+        logging_1.debugLog.debug('Sanitize', 'Metadata sanitization completed', {
+            originalKeys,
+            finalKeys,
+            keysFiltered: originalKeys - finalKeys,
+        });
+        return result;
+    }
+    catch (error) {
+        logging_1.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'}`);
+    }
+};
+exports.sanitizeMetadata = sanitizeMetadata;
+/**
+ * Sanitizes URL strings for tracking
+ * @param url - The URL to sanitize
+ * @returns The sanitized URL
+ */
+const sanitizeUrl = (url) => {
+    logging_1.debugLog.debug('Sanitize', 'Starting URL sanitization', { urlLength: typeof url === 'string' ? url.length : 0 });
+    if (typeof url !== 'string') {
+        logging_1.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)) {
+            logging_1.debugLog.warn('Sanitize', 'URL protocol not allowed', {
+                protocol: urlObject.protocol,
+                allowedProtocols: ['http:', 'https:'],
+            });
+            return '';
+        }
+        // Sanitize the URL string
+        const result = (0, exports.sanitizeString)(urlObject.href);
+        logging_1.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
+        logging_1.debugLog.warn('Sanitize', 'URL parsing failed, falling back to string sanitization', {
+            urlPreview: url.slice(0, 100),
+        });
+        return (0, exports.sanitizeString)(url);
+    }
+};
+exports.sanitizeUrl = sanitizeUrl;

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

@@ -0,0 +1,297 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidConfigApiResponse = exports.validateFinalConfig = exports.validateConfig = exports.validateAndNormalizeConfig = exports.validateAppConfig = void 0;
+const constants_1 = require("../../constants");
+const types_1 = require("../../types");
+const validation_error_types_1 = require("../../types/validation-error.types");
+const logging_1 = require("../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
+ */
+const validateAppConfig = (config) => {
+    // Validate config exists and has id property
+    if (!config || typeof config !== 'object') {
+        logging_1.debugLog.clientError('ConfigValidation', 'Configuration must be an object', { config });
+        throw new validation_error_types_1.AppConfigValidationError('Configuration must be an object', 'config');
+    }
+    // Check if id property exists (allow falsy values to be handled by normalization)
+    if (!('id' in config)) {
+        logging_1.debugLog.clientError('ConfigValidation', 'Project ID is missing from configuration');
+        throw new validation_error_types_1.ProjectIdValidationError(constants_1.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') {
+        logging_1.debugLog.clientError('ConfigValidation', 'Project ID must be a non-empty string', {
+            providedId: config.id,
+            type: typeof config.id,
+        });
+        throw new validation_error_types_1.ProjectIdValidationError(constants_1.VALIDATION_MESSAGES.MISSING_PROJECT_ID, 'config');
+    }
+    if (config.sessionTimeout !== undefined) {
+        if (typeof config.sessionTimeout !== 'number' ||
+            config.sessionTimeout < constants_1.MIN_SESSION_TIMEOUT_MS ||
+            config.sessionTimeout > constants_1.MAX_SESSION_TIMEOUT_MS) {
+            logging_1.debugLog.clientError('ConfigValidation', 'Invalid session timeout', {
+                provided: config.sessionTimeout,
+                min: constants_1.MIN_SESSION_TIMEOUT_MS,
+                max: constants_1.MAX_SESSION_TIMEOUT_MS,
+            });
+            throw new validation_error_types_1.SessionTimeoutValidationError(constants_1.VALIDATION_MESSAGES.INVALID_SESSION_TIMEOUT, 'config');
+        }
+    }
+    if (config.globalMetadata !== undefined) {
+        if (typeof config.globalMetadata !== 'object' || config.globalMetadata === null) {
+            logging_1.debugLog.clientError('ConfigValidation', 'Global metadata must be an object', {
+                provided: config.globalMetadata,
+                type: typeof config.globalMetadata,
+            });
+            throw new validation_error_types_1.AppConfigValidationError(constants_1.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)) {
+            logging_1.debugLog.clientError('ConfigValidation', 'Sensitive query params must be an array', {
+                provided: config.sensitiveQueryParams,
+                type: typeof config.sensitiveQueryParams,
+            });
+            throw new validation_error_types_1.AppConfigValidationError(constants_1.VALIDATION_MESSAGES.INVALID_SENSITIVE_QUERY_PARAMS, 'config');
+        }
+        for (const param of config.sensitiveQueryParams) {
+            if (typeof param !== 'string') {
+                logging_1.debugLog.clientError('ConfigValidation', 'All sensitive query params must be strings', {
+                    param,
+                    type: typeof param,
+                });
+                throw new validation_error_types_1.AppConfigValidationError('All sensitive query params must be strings', 'config');
+            }
+        }
+    }
+    if (config.errorSampling !== undefined) {
+        if (typeof config.errorSampling !== 'number' || config.errorSampling < 0 || config.errorSampling > 1) {
+            logging_1.debugLog.clientError('ConfigValidation', 'Invalid error sampling rate', {
+                provided: config.errorSampling,
+                expected: '0-1',
+            });
+            throw new validation_error_types_1.SamplingRateValidationError(constants_1.VALIDATION_MESSAGES.INVALID_ERROR_SAMPLING_RATE, 'config');
+        }
+    }
+};
+exports.validateAppConfig = validateAppConfig;
+/**
+ * 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() === '') {
+            logging_1.debugLog.clientError('ConfigValidation', 'Invalid scroll container selector', {
+                selector,
+                type: typeof selector,
+                isEmpty: selector === '' || (typeof selector === 'string' && selector.trim() === ''),
+            });
+            throw new validation_error_types_1.AppConfigValidationError(constants_1.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
+                logging_1.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() === '') {
+            logging_1.debugLog.clientError('ConfigValidation', 'Invalid Google Analytics measurement ID', {
+                provided: integrations.googleAnalytics.measurementId,
+                type: typeof integrations.googleAnalytics.measurementId,
+            });
+            throw new validation_error_types_1.IntegrationValidationError(constants_1.VALIDATION_MESSAGES.INVALID_GOOGLE_ANALYTICS_ID, 'config');
+        }
+        const measurementId = integrations.googleAnalytics.measurementId.trim();
+        if (!measurementId.match(/^(G-|UA-)/)) {
+            logging_1.debugLog.clientError('ConfigValidation', 'Google Analytics measurement ID must start with "G-" or "UA-"', {
+                provided: measurementId,
+            });
+            throw new validation_error_types_1.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
+ */
+const validateAndNormalizeConfig = (config) => {
+    // First validate the structure and basic types
+    (0, exports.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) {
+        logging_1.debugLog.clientError('ConfigValidation', 'Project ID is empty after trimming whitespace', {
+            originalId: config.id,
+            normalizedId: normalizedConfig.id,
+        });
+        throw new validation_error_types_1.ProjectIdValidationError(constants_1.VALIDATION_MESSAGES.PROJECT_ID_EMPTY_AFTER_TRIM, 'config');
+    }
+    return normalizedConfig;
+};
+exports.validateAndNormalizeConfig = validateAndNormalizeConfig;
+/**
+ * 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
+ */
+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 < constants_1.MIN_SESSION_TIMEOUT_MS) {
+            errors.push('sessionTimeout must be at least 30 seconds (30000ms)');
+        }
+        else if (config.sessionTimeout > constants_1.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 };
+};
+exports.validateConfig = validateConfig;
+/**
+ * Validates the final configuration
+ * @param config - The configuration to validate
+ * @returns Validation result with errors and warnings
+ */
+const validateFinalConfig = (config) => {
+    const errors = [];
+    const warnings = [];
+    validateSamplingRate(config.samplingRate, errors);
+    validateExcludedUrlPaths(config.excludedUrlPaths, errors);
+    // No custom API endpoints supported
+    return { errors, warnings };
+};
+exports.validateFinalConfig = validateFinalConfig;
+/**
+ * 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
+ */
+const isValidConfigApiResponse = (json) => {
+    try {
+        if (typeof json !== 'object' || !json) {
+            return false;
+        }
+        const response = json;
+        const result = {
+            mode: response['mode'] === undefined || [types_1.Mode.QA, types_1.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;
+    }
+};
+exports.isValidConfigApiResponse = isValidConfigApiResponse;

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