@tracelog/lib 0.6.0 → 0.6.3

package/dist/esm/managers/storage.manager.js

@@ -37,6 +37,9 @@ export class StorageManager {
      * Stores an item in storage
      */
     setItem(key, value) {
+        // Always update fallback FIRST for consistency
+        // This ensures fallback is in sync and can serve as backup if storage fails
+        this.fallbackStorage.set(key, value);
         try {
             if (this.storage) {
                 this.storage.setItem(key, value);
@@ -46,15 +49,37 @@ export class StorageManager {
         catch (error) {
             if (error instanceof DOMException && error.name === 'QuotaExceededError') {
                 this.hasQuotaExceededError = true;
-                log('error', 'localStorage quota exceeded - data will not persist after reload', {
-                    error,
+                log('warn', 'localStorage quota exceeded, attempting cleanup', {
                     data: { key, valueSize: value.length },
                 });
+                // Attempt to free up space by removing old TraceLog data
+                const cleanedUp = this.cleanupOldData();
+                if (cleanedUp) {
+                    // Retry after cleanup
+                    try {
+                        if (this.storage) {
+                            this.storage.setItem(key, value);
+                            // Successfully stored after cleanup
+                            return;
+                        }
+                    }
+                    catch (retryError) {
+                        log('error', 'localStorage quota exceeded even after cleanup - data will not persist', {
+                            error: retryError,
+                            data: { key, valueSize: value.length },
+                        });
+                    }
+                }
+                else {
+                    log('error', 'localStorage quota exceeded and no data to cleanup - data will not persist', {
+                        error,
+                        data: { key, valueSize: value.length },
+                    });
+                }
             }
             // Else: Silent fallback - user already warned in constructor
+            // Data is already in fallbackStorage (set at beginning)
         }
-        // Always update fallback for consistency
-        this.fallbackStorage.set(key, value);
     }
     /**
      * Removes an item from storage
@@ -108,6 +133,69 @@ export class StorageManager {
     hasQuotaError() {
         return this.hasQuotaExceededError;
     }
+    /**
+     * Attempts to cleanup old TraceLog data from storage to free up space
+     * Returns true if any data was removed, false otherwise
+     */
+    cleanupOldData() {
+        if (!this.storage) {
+            return false;
+        }
+        try {
+            const tracelogKeys = [];
+            const persistedEventsKeys = [];
+            // Collect all TraceLog keys
+            for (let i = 0; i < this.storage.length; i++) {
+                const key = this.storage.key(i);
+                if (key?.startsWith('tracelog_')) {
+                    tracelogKeys.push(key);
+                    // Prioritize removing old persisted events
+                    if (key.startsWith('tracelog_persisted_events_')) {
+                        persistedEventsKeys.push(key);
+                    }
+                }
+            }
+            // First, try to remove old persisted events (usually the largest data)
+            if (persistedEventsKeys.length > 0) {
+                persistedEventsKeys.forEach((key) => {
+                    try {
+                        this.storage.removeItem(key);
+                    }
+                    catch {
+                        // Ignore errors during cleanup
+                    }
+                });
+                // Successfully cleaned up - no need to log in production
+                return true;
+            }
+            // If no persisted events, remove non-critical keys
+            // Define critical key prefixes that should be preserved
+            const criticalPrefixes = ['tracelog_session_', 'tracelog_user_id', 'tracelog_device_id', 'tracelog_config'];
+            const nonCriticalKeys = tracelogKeys.filter((key) => {
+                // Keep keys that start with any critical prefix
+                return !criticalPrefixes.some((prefix) => key.startsWith(prefix));
+            });
+            if (nonCriticalKeys.length > 0) {
+                // Remove up to 5 non-critical keys
+                const keysToRemove = nonCriticalKeys.slice(0, 5);
+                keysToRemove.forEach((key) => {
+                    try {
+                        this.storage.removeItem(key);
+                    }
+                    catch {
+                        // Ignore errors during cleanup
+                    }
+                });
+                // Successfully cleaned up - no need to log in production
+                return true;
+            }
+            return false;
+        }
+        catch (error) {
+            log('error', 'Failed to cleanup old data', { error });
+            return false;
+        }
+    }
     /**
      * Initialize storage (localStorage or sessionStorage) with feature detection
      */
@@ -145,6 +233,8 @@ export class StorageManager {
      * Stores an item in sessionStorage
      */
     setSessionItem(key, value) {
+        // Always update fallback FIRST for consistency
+        this.fallbackSessionStorage.set(key, value);
         try {
             if (this.sessionStorageRef) {
                 this.sessionStorageRef.setItem(key, value);
@@ -159,9 +249,8 @@ export class StorageManager {
                 });
             }
             // Else: Silent fallback - user already warned in constructor
+            // Data is already in fallbackSessionStorage (set at beginning)
         }
-        // Always update fallback for consistency
-        this.fallbackSessionStorage.set(key, value);
     }
     /**
      * Removes an item from sessionStorage

package/dist/esm/public-api.d.ts

@@ -1,7 +1,7 @@
 export * from './app.constants';
 export * from './types';
 export declare const tracelog: {
-    init: (config: import("./types").Config) => Promise<void>;
+    init: (config?: import("./types").Config) => Promise<void>;
     event: (name: string, metadata?: Record<string, import("./types").MetadataType> | Record<string, import("./types").MetadataType>[]) => void;
     on: <K extends keyof import("./types").EmitterMap>(event: K, callback: import("./types").EmitterCallback<import("./types").EmitterMap[K]>) => void;
     off: <K extends keyof import("./types").EmitterMap>(event: K, callback: import("./types").EmitterCallback<import("./types").EmitterMap[K]>) => void;

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

@@ -16,7 +16,7 @@ export declare class TestBridge extends App implements TraceLogTestBridge {
     private _isInitializing;
     private _isDestroying;
     constructor(isInitializing: boolean, isDestroying: boolean);
-    init(config: any): Promise<void>;
+    init(config?: any): Promise<void>;
     isInitializing(): boolean;
     sendCustomEvent(name: string, data?: Record<string, unknown> | Record<string, unknown>[]): void;
     getSessionData(): Record<string, unknown> | null;

package/dist/esm/test-bridge.js

@@ -74,7 +74,7 @@ export class TestBridge extends App {
             throw new Error('Storage manager not available');
         }
         const config = this.get('config');
-        const projectId = config?.integrations?.tracelog?.projectId ?? config?.integrations?.custom?.apiUrl ?? 'test';
+        const projectId = config?.integrations?.tracelog?.projectId ?? config?.integrations?.custom?.collectApiUrl ?? 'test';
         const userId = this.get('userId');
         const sessionId = this.get('sessionId');
         if (!projectId || !userId) {

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

@@ -6,8 +6,6 @@ export interface Config {
     globalMetadata?: Record<string, MetadataType>;
     /** Selectors defining custom scroll containers to monitor. */
     scrollContainerSelectors?: string | string[];
-    /** Enables HTTP requests for testing and development flows. */
-    allowHttp?: boolean;
     /** Query parameters to remove before tracking URLs. */
     sensitiveQueryParams?: string[];
     /** Error event sampling rate between 0 and 1. */
@@ -23,8 +21,10 @@ export interface Config {
         };
         /** Custom integration options. */
         custom?: {
-            /** Required API URL for custom integration. */
-            apiUrl: string;
+            /** Endpoint for collecting events. */
+            collectApiUrl: string;
+            /** Allow HTTP URLs (not recommended for production). @default false */
+            allowHttp?: boolean;
         };
         /** Google Analytics integration options. */
         googleAnalytics?: {

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

@@ -3,7 +3,7 @@ import { DeviceType } from './device.types';
 import { Mode } from './mode.types';
 export interface State {
     mode?: Mode;
-    apiUrl: string;
+    collectApiUrl: string;
     config: Config;
     sessionId: string | null;
     userId: string;

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

@@ -15,7 +15,7 @@ import { State } from './state.types';
  */
 export interface TraceLogTestBridge {
     readonly initialized: boolean;
-    init(config: Config): Promise<void>;
+    init(config?: Config): Promise<void>;
     destroy(): Promise<void>;
     isInitializing(): boolean;
     sendCustomEvent(name: string, data?: Record<string, unknown> | Record<string, unknown>[]): void;

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

@@ -1,5 +1,20 @@
 export declare const formatLogMsg: (msg: string, error?: unknown) => string;
-export declare const log: (type: "info" | "warn" | "error", msg: string, extra?: {
+/**
+ * Safe logging utility that respects production environment
+ *
+ * @param type - Log level (info, warn, error, debug)
+ * @param msg - Message to log
+ * @param extra - Optional extra data
+ *
+ * Production behavior:
+ * - debug: Never logged in production
+ * - info: Only logged if showToClient=true
+ * - warn: Always logged (important for debugging production issues)
+ * - error: Always logged
+ * - Stack traces are sanitized
+ * - Data objects are sanitized
+ */
+export declare const log: (type: "info" | "warn" | "error" | "debug", msg: string, extra?: {
     error?: unknown;
     data?: Record<string, unknown>;
     showToClient?: boolean;

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

@@ -1,20 +1,81 @@
 export const formatLogMsg = (msg, error) => {
     if (error) {
+        // In production, sanitize error messages to avoid exposing sensitive paths
+        if (process.env.NODE_ENV !== 'dev' && error instanceof Error) {
+            // Remove file paths and line numbers from error messages
+            const sanitizedMessage = error.message.replace(/\s+at\s+.*$/gm, '').replace(/\(.*?:\d+:\d+\)/g, '');
+            return `[TraceLog] ${msg}: ${sanitizedMessage}`;
+        }
         return `[TraceLog] ${msg}: ${error instanceof Error ? error.message : 'Unknown error'}`;
     }
     return `[TraceLog] ${msg}`;
 };
+/**
+ * Safe logging utility that respects production environment
+ *
+ * @param type - Log level (info, warn, error, debug)
+ * @param msg - Message to log
+ * @param extra - Optional extra data
+ *
+ * Production behavior:
+ * - debug: Never logged in production
+ * - info: Only logged if showToClient=true
+ * - warn: Always logged (important for debugging production issues)
+ * - error: Always logged
+ * - Stack traces are sanitized
+ * - Data objects are sanitized
+ */
 export const log = (type, msg, extra) => {
-    const { error, data, showToClient } = extra ?? {};
+    const { error, data, showToClient = false } = extra ?? {};
     const formattedMsg = error ? formatLogMsg(msg, error) : `[TraceLog] ${msg}`;
     const method = type === 'error' ? 'error' : type === 'warn' ? 'warn' : 'log';
-    if (process.env.NODE_ENV !== 'dev' && !showToClient) {
-        return;
+    // Production logging strategy:
+    // - Development: Log everything
+    // - Production:
+    //   - debug: never logged
+    //   - info: only if showToClient=true
+    //   - warn: always logged (critical for debugging)
+    //   - error: always logged
+    const isProduction = process.env.NODE_ENV !== 'dev';
+    if (isProduction) {
+        // Never log debug in production
+        if (type === 'debug') {
+            return;
+        }
+        // Log info only if explicitly flagged
+        if (type === 'info' && !showToClient) {
+            return;
+        }
+        // warn and error always logged in production
     }
-    if (data !== undefined) {
+    // In production, sanitize data to avoid exposing sensitive information
+    if (isProduction && data !== undefined) {
+        const sanitizedData = sanitizeLogData(data);
+        console[method](formattedMsg, sanitizedData);
+    }
+    else if (data !== undefined) {
         console[method](formattedMsg, data);
     }
     else {
         console[method](formattedMsg);
     }
 };
+/**
+ * Sanitizes log data in production to prevent sensitive information leakage
+ * Simple approach: redact sensitive keys only
+ */
+const sanitizeLogData = (data) => {
+    const sanitized = {};
+    const sensitiveKeys = ['token', 'password', 'secret', 'key', 'apikey', 'api_key', 'sessionid', 'session_id'];
+    for (const [key, value] of Object.entries(data)) {
+        const lowerKey = key.toLowerCase();
+        // Redact sensitive keys
+        if (sensitiveKeys.some((sensitiveKey) => lowerKey.includes(sensitiveKey))) {
+            sanitized[key] = '[REDACTED]';
+        }
+        else {
+            sanitized[key] = value;
+        }
+    }
+    return sanitized;
+};

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

@@ -4,7 +4,7 @@ import { Config } from '@/types';
  * @param id - The project ID
  * @returns The generated API URL
  */
-export declare const getApiUrl: (config: Config) => string;
+export declare const getCollectApiUrl: (config: Config) => string;
 /**
  * Normalizes a URL by removing sensitive query parameters
  * @param url - The URL to normalize

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

@@ -21,8 +21,7 @@ const isValidUrl = (url, allowHttp = false) => {
  * @param id - The project ID
  * @returns The generated API URL
  */
-export const getApiUrl = (config) => {
-    const allowHttp = config.allowHttp ?? false;
+export const getCollectApiUrl = (config) => {
     if (config.integrations?.tracelog?.projectId) {
         const url = new URL(window.location.href);
         const host = url.hostname;
@@ -32,21 +31,21 @@ export const getApiUrl = (config) => {
         }
         const projectId = config.integrations.tracelog.projectId;
         const cleanDomain = parts.slice(-2).join('.');
-        const protocol = allowHttp && url.protocol === 'http:' ? 'http' : 'https';
-        const apiUrl = `${protocol}://${projectId}.${cleanDomain}`;
-        const isValid = isValidUrl(apiUrl, allowHttp);
+        const collectApiUrl = `https://${projectId}.${cleanDomain}/collect`;
+        const isValid = isValidUrl(collectApiUrl);
         if (!isValid) {
             throw new Error('Invalid URL');
         }
-        return apiUrl;
+        return collectApiUrl;
     }
-    if (config.integrations?.custom?.apiUrl) {
-        const apiUrl = config.integrations.custom.apiUrl;
-        const isValid = isValidUrl(apiUrl, allowHttp);
+    const collectApiUrl = config.integrations?.custom?.collectApiUrl;
+    if (collectApiUrl) {
+        const allowHttp = config.integrations?.custom?.allowHttp ?? false;
+        const isValid = isValidUrl(collectApiUrl, allowHttp);
         if (!isValid) {
             throw new Error('Invalid URL');
         }
-        return apiUrl;
+        return collectApiUrl;
     }
     return '';
 };

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

@@ -6,7 +6,7 @@ import { Config } from '../../types';
  * @throws {ProjectIdValidationError} If project ID validation fails
  * @throws {AppConfigValidationError} If other configuration validation fails
  */
-export declare const validateAppConfig: (config: Config) => void;
+export declare const validateAppConfig: (config?: Config) => void;
 /**
  * Validates and normalizes the app configuration
  * This is the primary validation entry point that ensures consistent behavior
@@ -15,4 +15,4 @@ export declare const validateAppConfig: (config: Config) => void;
  * @throws {ProjectIdValidationError} If project ID validation fails after normalization
  * @throws {AppConfigValidationError} If other configuration validation fails
  */
-export declare const validateAndNormalizeConfig: (config: Config) => Config;
+export declare const validateAndNormalizeConfig: (config?: Config) => Config;

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

@@ -9,9 +9,12 @@ import { log } from '../logging.utils';
  * @throws {AppConfigValidationError} If other configuration validation fails
  */
 export const validateAppConfig = (config) => {
-    if (!config || typeof config !== 'object') {
+    if (config !== undefined && (config === null || typeof config !== 'object')) {
         throw new AppConfigValidationError('Configuration must be an object', 'config');
     }
+    if (!config) {
+        return;
+    }
     if (config.sessionTimeout !== undefined) {
         if (typeof config.sessionTimeout !== 'number' ||
             config.sessionTimeout < MIN_SESSION_TIMEOUT_MS ||
@@ -50,11 +53,6 @@ export const validateAppConfig = (config) => {
             throw new SamplingRateValidationError(VALIDATION_MESSAGES.INVALID_SAMPLING_RATE, 'config');
         }
     }
-    if (config.allowHttp !== undefined) {
-        if (typeof config.allowHttp !== 'boolean') {
-            throw new AppConfigValidationError('allowHttp must be a boolean', 'config');
-        }
-    }
 };
 /**
  * Validates CSS selector syntax without executing querySelector (XSS prevention)
@@ -145,13 +143,21 @@ const validateIntegrations = (integrations) => {
         }
     }
     if (integrations.custom) {
-        if (!integrations.custom.apiUrl ||
-            typeof integrations.custom.apiUrl !== 'string' ||
-            integrations.custom.apiUrl.trim() === '') {
+        if (!integrations.custom.collectApiUrl ||
+            typeof integrations.custom.collectApiUrl !== 'string' ||
+            integrations.custom.collectApiUrl.trim() === '') {
             throw new IntegrationValidationError(VALIDATION_MESSAGES.INVALID_CUSTOM_API_URL, 'config');
         }
-        if (!integrations.custom.apiUrl.startsWith('http')) {
-            throw new IntegrationValidationError('Custom API URL must start with "http"', 'config');
+        if (integrations.custom.allowHttp !== undefined && typeof integrations.custom.allowHttp !== 'boolean') {
+            throw new IntegrationValidationError('allowHttp must be a boolean', 'config');
+        }
+        const collectApiUrl = integrations.custom.collectApiUrl.trim();
+        if (!collectApiUrl.startsWith('http://') && !collectApiUrl.startsWith('https://')) {
+            throw new IntegrationValidationError('Custom API URL must start with "http://" or "https://"', 'config');
+        }
+        const allowHttp = integrations.custom.allowHttp ?? false;
+        if (!allowHttp && collectApiUrl.startsWith('http://')) {
+            throw new IntegrationValidationError('Custom API URL must use HTTPS in production. Set allowHttp: true in integration config to allow HTTP (not recommended)', 'config');
         }
     }
     if (integrations.googleAnalytics) {
@@ -177,13 +183,19 @@ const validateIntegrations = (integrations) => {
 export const validateAndNormalizeConfig = (config) => {
     validateAppConfig(config);
     const normalizedConfig = {
-        ...config,
-        sessionTimeout: config.sessionTimeout ?? DEFAULT_SESSION_TIMEOUT,
-        globalMetadata: config.globalMetadata ?? {},
-        sensitiveQueryParams: config.sensitiveQueryParams ?? [],
-        errorSampling: config.errorSampling ?? 1,
-        samplingRate: config.samplingRate ?? 1,
-        allowHttp: config.allowHttp ?? false,
+        ...(config ?? {}),
+        sessionTimeout: config?.sessionTimeout ?? DEFAULT_SESSION_TIMEOUT,
+        globalMetadata: config?.globalMetadata ?? {},
+        sensitiveQueryParams: config?.sensitiveQueryParams ?? [],
+        errorSampling: config?.errorSampling ?? 1,
+        samplingRate: config?.samplingRate ?? 1,
     };
+    // Normalize integrations
+    if (normalizedConfig.integrations?.custom) {
+        normalizedConfig.integrations.custom = {
+            ...normalizedConfig.integrations.custom,
+            allowHttp: normalizedConfig.integrations.custom.allowHttp ?? false,
+        };
+    }
     return normalizedConfig;
 };

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.6.0",
+  "version": "0.6.3",
   "main": "./dist/cjs/public-api.js",
   "module": "./dist/esm/public-api.js",
   "types": "./dist/esm/public-api.d.ts",
@@ -40,10 +40,11 @@
     "test:unit:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "test:integration": "vitest run --config vitest.integration.config.mjs",
-    "serve": "http-server playground -p 3000 --cors",
-    "playground:setup": "npm run build:browser:dev && cp dist/browser/tracelog.esm.js playground/tracelog.js",
-    "playground:dev": "npm run playground:setup && npm run serve",
-    "test:e2e": "npm run build:browser:dev && cp dist/browser/tracelog.esm.js playground/tracelog.js && NODE_ENV=dev playwright test",
+    "serve": "http-server docs -p 3000 --cors",
+    "docs:setup": "npm run build:browser:dev && cp dist/browser/tracelog.esm.js docs/tracelog.js",
+    "docs:dev": "npm run docs:setup && npm run serve",
+    "docs:gh-pages": "npm run build:browser && cp dist/browser/tracelog.esm.js docs/tracelog.js",
+    "test:e2e": "npm run docs:setup && NODE_ENV=dev playwright test",
     "ci:build": "npm run build:all",
     "prepare": "husky",
     "release": "node scripts/release.js",
@@ -55,7 +56,7 @@
     "changelog:preview": "node scripts/generate-changelog.js --dry-run"
   },
   "dependencies": {
-    "web-vitals": "^4.2.4"
+    "web-vitals": "4.2.4"
   },
   "devDependencies": {
     "@commitlint/config-conventional": "^19.8.1",