@tracelog/lib 0.4.1 → 0.5.0

package/dist/esm/types/api.types.d.ts

@@ -1,9 +1,10 @@
 /**
  * Special project IDs for testing and development
  *
- * Both automatically force mode: 'debug' but differ in HTTP behavior:
+ * All automatically force mode: 'debug' but differ in HTTP behavior:
  * - Skip: NO network calls (pure offline testing)
  * - Localhost: Makes network calls to local server (integration testing)
+ * - Fail: Makes network calls that intentionally fail (persistence testing)
  */
 export declare enum SpecialProjectId {
     /**
@@ -20,17 +21,32 @@ export declare enum SpecialProjectId {
      */
     Skip = "skip",
     /**
-     * Value: 'localhost:' (used as prefix)
+     * Value: 'localhost:8080'
      *
-     * Makes HTTP calls to local development server
-     * Must specify full address: 'localhost:PORT' (e.g., 'localhost:3000')
-     * Converts to http://localhost:PORT/config for requests
+     * Makes HTTP calls to local development server on port 8080
+     * Converts to http://localhost:8080/config for requests
      * Requires origin to be in ALLOWED_ORIGINS list, forces debug mode
      * Perfect for local development with running middleware
      *
      * @example
-     * await TraceLog.init({ id: 'localhost:3000' });
-     * // Makes requests to: http://localhost:3000/config
+     * await TraceLog.init({ id: SpecialProjectId.Localhost });
+     * // or
+     * await TraceLog.init({ id: 'localhost:8080' });
+     * // Makes requests to: http://localhost:8080/config
+     */
+    Localhost = "localhost:8080",
+    /**
+     * Value: 'localhost:9999'
+     *
+     * Makes HTTP calls to non-existent server (port 9999)
+     * All HTTP requests will fail naturally, triggering persistence
+     * Forces debug mode, perfect for testing event persistence & recovery
+     *
+     * @example
+     * await TraceLog.init({ id: SpecialProjectId.Fail });
+     * // or
+     * await TraceLog.init({ id: 'localhost:9999' });
+     * // Makes requests to: http://localhost:9999 (will fail)
      */
-    Localhost = "localhost:"
+    Fail = "localhost:9999"
 }

package/dist/esm/types/api.types.js

@@ -1,9 +1,10 @@
 /**
  * Special project IDs for testing and development
  *
- * Both automatically force mode: 'debug' but differ in HTTP behavior:
+ * All automatically force mode: 'debug' but differ in HTTP behavior:
  * - Skip: NO network calls (pure offline testing)
  * - Localhost: Makes network calls to local server (integration testing)
+ * - Fail: Makes network calls that intentionally fail (persistence testing)
  */
 export var SpecialProjectId;
 (function (SpecialProjectId) {
@@ -21,17 +22,32 @@ export var SpecialProjectId;
      */
     SpecialProjectId["Skip"] = "skip";
     /**
-     * Value: 'localhost:' (used as prefix)
+     * Value: 'localhost:8080'
      *
-     * Makes HTTP calls to local development server
-     * Must specify full address: 'localhost:PORT' (e.g., 'localhost:3000')
-     * Converts to http://localhost:PORT/config for requests
+     * Makes HTTP calls to local development server on port 8080
+     * Converts to http://localhost:8080/config for requests
      * Requires origin to be in ALLOWED_ORIGINS list, forces debug mode
      * Perfect for local development with running middleware
      *
      * @example
-     * await TraceLog.init({ id: 'localhost:3000' });
-     * // Makes requests to: http://localhost:3000/config
+     * await TraceLog.init({ id: SpecialProjectId.Localhost });
+     * // or
+     * await TraceLog.init({ id: 'localhost:8080' });
+     * // Makes requests to: http://localhost:8080/config
+     */
+    SpecialProjectId["Localhost"] = "localhost:8080";
+    /**
+     * Value: 'localhost:9999'
+     *
+     * Makes HTTP calls to non-existent server (port 9999)
+     * All HTTP requests will fail naturally, triggering persistence
+     * Forces debug mode, perfect for testing event persistence & recovery
+     *
+     * @example
+     * await TraceLog.init({ id: SpecialProjectId.Fail });
+     * // or
+     * await TraceLog.init({ id: 'localhost:9999' });
+     * // Makes requests to: http://localhost:9999 (will fail)
      */
-    SpecialProjectId["Localhost"] = "localhost:";
+    SpecialProjectId["Fail"] = "localhost:9999";
 })(SpecialProjectId || (SpecialProjectId = {}));

package/dist/esm/types/event.types.d.ts

@@ -17,8 +17,7 @@ export declare enum ScrollDirection {
 }
 export declare enum ErrorType {
     JS_ERROR = "js_error",
-    PROMISE_REJECTION = "promise_rejection",
-    NETWORK_ERROR = "network_error"
+    PROMISE_REJECTION = "promise_rejection"
 }
 export interface ScrollData {
     depth: number;
@@ -48,7 +47,7 @@ export interface ClickTrackingElementData {
 }
 export interface CustomEventData {
     name: string;
-    metadata?: Record<string, MetadataType>;
+    metadata?: Record<string, MetadataType> | Record<string, MetadataType>[];
 }
 export interface WebVitalsData {
     type: WebVitalType;

package/dist/esm/types/event.types.js

@@ -18,5 +18,4 @@ export var ErrorType;
 (function (ErrorType) {
     ErrorType["JS_ERROR"] = "js_error";
     ErrorType["PROMISE_REJECTION"] = "promise_rejection";
-    ErrorType["NETWORK_ERROR"] = "network_error";
 })(ErrorType || (ErrorType = {}));

package/dist/esm/types/test-bridge.types.d.ts

@@ -18,13 +18,14 @@ export interface TraceLogTestBridge {
     init(config: AppConfig): Promise<void>;
     destroy(): Promise<void>;
     isInitializing(): boolean;
-    sendCustomEvent(name: string, data?: Record<string, unknown>): void;
+    sendCustomEvent(name: string, data?: Record<string, unknown> | Record<string, unknown>[]): void;
     on(event: string, callback: (data: any) => void): void;
     off(event: string, callback: (data: any) => void): void;
     getSessionData(): Record<string, unknown> | null;
     setSessionTimeout(timeout: number): void;
     getQueueLength(): number;
     forceInitLock(enabled?: boolean): void;
+    simulatePersistedEvents(events: any[]): void;
     get<T extends keyof State>(key: T): State[T];
     getStorageManager(): TraceLogStorageManager | null;
     getEventManager(): EventManager | null;

package/dist/esm/utils/logging/debug-logger.utils.d.ts

@@ -1,5 +1,4 @@
-import { StateManager } from '../../managers/state.manager';
-declare class DebugLogger extends StateManager {
+declare class DebugLogger {
     clientError: (ns: string, msg: string, data?: unknown) => void;
     clientWarn: (ns: string, msg: string, data?: unknown) => void;
     info: (ns: string, msg: string, data?: unknown) => void;

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

@@ -1,7 +1,6 @@
-import { StateManager } from '../../managers/state.manager';
-class DebugLogger extends StateManager {
+import { getGlobalState } from '../../managers/state.manager';
+class DebugLogger {
     constructor() {
-        super(...arguments);
         this.clientError = (ns, msg, data) => this.log('CLIENT_ERROR', ns, msg, data);
         this.clientWarn = (ns, msg, data) => this.log('CLIENT_WARN', ns, msg, data);
         this.info = (ns, msg, data) => this.log('INFO', ns, msg, data);
@@ -11,7 +10,7 @@ class DebugLogger extends StateManager {
         this.verbose = (ns, msg, data) => this.log('VERBOSE', ns, msg, data);
     }
     log(level, ns, msg, data) {
-        const mode = this.get('config')?.mode;
+        const mode = getGlobalState()?.config?.mode;
         if (!this.shouldShow(level, mode))
             return;
         const formattedMsg = `[TraceLog:${ns}] ${msg}`;

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

@@ -1,4 +1,4 @@
-import { AppConfig, Config, ApiConfig } from '../../types';
+import { AppConfig, ApiConfig } from '../../types';
 /**
  * Validates the app configuration object (before normalization)
  * This validates the structure and basic types but allows for normalization afterward
@@ -16,31 +16,6 @@ export declare const validateAppConfig: (config: AppConfig) => void;
  * @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[];
-    samplingRate: number;
-};
-export declare const normalizeConfig: (config: Config) => {
-    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[];
-    samplingRate: number;
-};
 /**
  * Type guard to check if a JSON response is a valid API config
  * @param json - The JSON to validate

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

@@ -1,4 +1,4 @@
-import { DEFAULT_SAMPLING_RATE, MAX_SESSION_TIMEOUT_MS, MIN_SESSION_TIMEOUT_MS, VALIDATION_MESSAGES, } from '../../constants';
+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';
@@ -204,118 +204,6 @@ export const validateAndNormalizeConfig = (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) {
-        return undefined;
-    }
-    if (typeof samplingRate !== 'number') {
-        errors.push('samplingRate must be a number');
-        return DEFAULT_SAMPLING_RATE;
-    }
-    if (Number.isNaN(samplingRate) || samplingRate <= 0 || samplingRate > 1) {
-        errors.push(VALIDATION_MESSAGES.INVALID_SAMPLING_RATE);
-        return DEFAULT_SAMPLING_RATE;
-    }
-    return samplingRate;
-};
-/**
- * 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
-    const validatedSamplingRate = validateSamplingRate(config.samplingRate, errors) ?? DEFAULT_SAMPLING_RATE;
-    if (config.tags !== undefined && !Array.isArray(config.tags)) {
-        errors.push('tags must be an array');
-    }
-    validateExcludedUrlPaths(config.excludedUrlPaths, errors);
-    return { errors, warnings, samplingRate: validatedSamplingRate };
-};
-export const normalizeConfig = (config) => {
-    const { errors, warnings, samplingRate } = validateConfig(config);
-    return {
-        config: {
-            ...config,
-            samplingRate,
-        },
-        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 = [];
-    const validatedSamplingRate = validateSamplingRate(config.samplingRate, errors) ?? DEFAULT_SAMPLING_RATE;
-    validateExcludedUrlPaths(config.excludedUrlPaths, errors);
-    // No custom API endpoints supported
-    return { errors, warnings, samplingRate: validatedSamplingRate };
-};
 /**
  * Type guard to check if a JSON response is a valid API config
  * @param json - The JSON to validate
@@ -329,8 +217,11 @@ export const isValidConfigApiResponse = (json) => {
         const response = json;
         const result = {
             mode: response['mode'] === undefined || [Mode.QA, Mode.DEBUG].includes(response['mode']),
+            // Zero is valid for samplingRate (means "sample nothing")
             samplingRate: response['samplingRate'] === undefined ||
-                (typeof response['samplingRate'] === 'number' && response['samplingRate'] > 0 && response['samplingRate'] <= 1),
+                (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',

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

@@ -5,8 +5,8 @@ import { MetadataType } from '../../types';
  * @param metadata - Optional metadata to validate
  * @returns Validation result with sanitized metadata if valid
  */
-export declare const isEventValid: (eventName: string, metadata?: Record<string, unknown>) => {
+export declare const isEventValid: (eventName: string, metadata?: Record<string, unknown> | Record<string, unknown>[]) => {
     valid: boolean;
     error?: string;
-    sanitizedMetadata?: Record<string, MetadataType>;
+    sanitizedMetadata?: Record<string, MetadataType> | Record<string, MetadataType>[];
 };

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

@@ -9,14 +9,14 @@ export declare const isValidEventName: (eventName: string) => {
     error?: string;
 };
 /**
- * Validates metadata for events
+ * Validates metadata for events (supports both objects and arrays of objects)
  * @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") => {
+export declare const isValidMetadata: (eventName: string, metadata: Record<string, unknown> | Record<string, unknown>[], type?: "globalMetadata" | "customEvent") => {
     valid: boolean;
     error?: string;
-    sanitizedMetadata?: Record<string, MetadataType>;
+    sanitizedMetadata?: Record<string, MetadataType> | Record<string, MetadataType>[];
 };

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

@@ -41,13 +41,13 @@ export const isValidEventName = (eventName) => {
     return { valid: true };
 };
 /**
- * Validates metadata for events
+ * Validates a single metadata object
  * @param eventName - The event name (for error messages)
- * @param metadata - The metadata to validate
+ * @param metadata - The metadata object 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 validateSingleMetadata = (eventName, metadata, type) => {
     const sanitizedMetadata = sanitizeMetadata(metadata);
     const intro = type && type === 'customEvent' ? `${type} "${eventName}" metadata error` : `${eventName} metadata error`;
     if (!isOnlyPrimitiveFields(sanitizedMetadata)) {
@@ -108,3 +108,41 @@ export const isValidMetadata = (eventName, metadata, type) => {
         sanitizedMetadata,
     };
 };
+/**
+ * Validates metadata for events (supports both objects and arrays of objects)
+ * @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) => {
+    if (Array.isArray(metadata)) {
+        const sanitizedArray = [];
+        const intro = type && type === 'customEvent' ? `${type} "${eventName}" metadata error` : `${eventName} metadata error`;
+        for (let i = 0; i < metadata.length; i++) {
+            const item = metadata[i];
+            if (typeof item !== 'object' || item === null || Array.isArray(item)) {
+                return {
+                    valid: false,
+                    error: `${intro}: array item at index ${i} must be an object.`,
+                };
+            }
+            const itemValidation = validateSingleMetadata(eventName, item, type);
+            if (!itemValidation.valid) {
+                return {
+                    valid: false,
+                    error: `${intro}: array item at index ${i} is invalid: ${itemValidation.error}`,
+                };
+            }
+            if (itemValidation.sanitizedMetadata) {
+                sanitizedArray.push(itemValidation.sanitizedMetadata);
+            }
+        }
+        // Allow empty arrays after sanitization
+        return {
+            valid: true,
+            sanitizedMetadata: sanitizedArray,
+        };
+    }
+    return validateSingleMetadata(eventName, metadata, type);
+};

package/package.json

@@ -2,7 +2,7 @@
   "name": "@tracelog/lib",
   "description": "JavaScript library for web analytics and real-time event tracking",
   "license": "MIT",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "main": "./dist/cjs/public-api.js",
   "module": "./dist/esm/public-api.js",
   "types": "./dist/esm/public-api.d.ts",