@tracelog/lib 0.6.0 → 0.6.1

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

@@ -1,4 +1,4 @@
-import { EVENT_SENT_INTERVAL_MS, MAX_EVENTS_QUEUE_LENGTH, DUPLICATE_EVENT_THRESHOLD_MS, } from '../constants/config.constants';
+import { EVENT_SENT_INTERVAL_MS, MAX_EVENTS_QUEUE_LENGTH, DUPLICATE_EVENT_THRESHOLD_MS, RATE_LIMIT_WINDOW_MS, MAX_EVENTS_PER_SECOND, MAX_PENDING_EVENTS_BUFFER, } from '../constants/config.constants';
 import { EmitterEvent, EventType, Mode } from '../types';
 import { getUTMParameters, log, generateEventId } from '../utils';
 import { SenderManager } from './sender.manager';
@@ -11,6 +11,8 @@ export class EventManager extends StateManager {
         this.lastEventFingerprint = null;
         this.lastEventTime = 0;
         this.sendIntervalId = null;
+        this.rateLimitCounter = 0;
+        this.rateLimitWindowStart = 0;
         this.googleAnalytics = googleAnalytics;
         this.dataSender = new SenderManager(storeManager);
         this.emitter = emitter;
@@ -33,10 +35,19 @@ export class EventManager extends StateManager {
     }
     track({ type, page_url, from_page_url, scroll_data, click_data, custom_event, web_vitals, error_data, session_end_reason, }) {
         if (!type) {
-            log('warn', 'Event type is required');
+            log('error', 'Event type is required - event will be ignored');
             return;
         }
+        // Check session BEFORE rate limiting to avoid consuming quota for buffered events
         if (!this.get('sessionId')) {
+            // Protect against unbounded buffer growth during initialization delays
+            if (this.pendingEventsBuffer.length >= MAX_PENDING_EVENTS_BUFFER) {
+                // Drop oldest event (FIFO) to make room for new one
+                this.pendingEventsBuffer.shift();
+                log('warn', 'Pending events buffer full - dropping oldest event', {
+                    data: { maxBufferSize: MAX_PENDING_EVENTS_BUFFER },
+                });
+            }
             this.pendingEventsBuffer.push({
                 type,
                 page_url,
@@ -50,10 +61,16 @@ export class EventManager extends StateManager {
             });
             return;
         }
+        // Rate limiting check (except for critical events)
+        // Applied AFTER session check to only rate-limit processable events
+        const isCriticalEvent = type === EventType.SESSION_START || type === EventType.SESSION_END;
+        if (!isCriticalEvent && !this.checkRateLimit()) {
+            // Rate limit exceeded - drop event silently
+            // Logging would itself cause performance issues
+            return;
+        }
         const eventType = type;
         const isSessionStart = eventType === EventType.SESSION_START;
-        const isSessionEnd = eventType === EventType.SESSION_END;
-        const isCriticalEvent = isSessionStart || isSessionEnd;
         const currentPageUrl = page_url || this.get('pageUrl');
         const payload = this.buildEventPayload({
             type: eventType,
@@ -72,7 +89,7 @@ export class EventManager extends StateManager {
         if (isSessionStart) {
             const currentSessionId = this.get('sessionId');
             if (!currentSessionId) {
-                log('warn', 'Session start event ignored: missing sessionId');
+                log('error', 'Session start event requires sessionId - event will be ignored');
                 return;
             }
             if (this.get('hasStartSession')) {
@@ -105,6 +122,8 @@ export class EventManager extends StateManager {
         this.pendingEventsBuffer = [];
         this.lastEventFingerprint = null;
         this.lastEventTime = 0;
+        this.rateLimitCounter = 0;
+        this.rateLimitWindowStart = 0;
         this.dataSender.stop();
     }
     async flushImmediately() {
@@ -120,12 +139,19 @@ export class EventManager extends StateManager {
         if (this.pendingEventsBuffer.length === 0) {
             return;
         }
-        if (!this.get('sessionId')) {
-            log('warn', 'Cannot flush pending events: session not initialized');
+        const currentSessionId = this.get('sessionId');
+        if (!currentSessionId) {
+            // Keep events in buffer for future retry - do NOT discard
+            // This prevents data loss during legitimate race conditions
+            log('warn', 'Cannot flush pending events: session not initialized - keeping in buffer', {
+                data: { bufferedEventCount: this.pendingEventsBuffer.length },
+            });
             return;
         }
+        // Create copy before clearing to avoid infinite recursion
         const bufferedEvents = [...this.pendingEventsBuffer];
         this.pendingEventsBuffer = [];
+        // Process all buffered events now that session exists
         bufferedEvents.forEach((event) => {
             this.track(event);
         });
@@ -301,6 +327,21 @@ export class EventManager extends StateManager {
         const samplingRate = this.get('config')?.samplingRate ?? 1;
         return Math.random() < samplingRate;
     }
+    checkRateLimit() {
+        const now = Date.now();
+        // Reset counter if window has expired
+        if (now - this.rateLimitWindowStart > RATE_LIMIT_WINDOW_MS) {
+            this.rateLimitCounter = 0;
+            this.rateLimitWindowStart = now;
+        }
+        // Check if limit exceeded
+        if (this.rateLimitCounter >= MAX_EVENTS_PER_SECOND) {
+            return false;
+        }
+        // Increment counter
+        this.rateLimitCounter++;
+        return true;
+    }
     removeProcessedEvents(eventIds) {
         const eventIdSet = new Set(eventIds);
         this.eventsQueue = this.eventsQueue.filter((event) => {

package/dist/esm/managers/storage.manager.d.ts

@@ -35,6 +35,11 @@ export declare class StorageManager {
      * This indicates localStorage is full and data may not persist
      */
     hasQuotaError(): boolean;
+    /**
+     * Attempts to cleanup old TraceLog data from storage to free up space
+     * Returns true if any data was removed, false otherwise
+     */
+    private cleanupOldData;
     /**
      * Initialize storage (localStorage or sessionStorage) with feature detection
      */

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/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. */
@@ -25,6 +23,8 @@ export interface Config {
         custom?: {
             /** Required API URL for custom integration. */
             apiUrl: string;
+            /** Allow HTTP URLs (not recommended for production). @default false */
+            allowHttp?: boolean;
         };
         /** Google Analytics integration options. */
         googleAnalytics?: {

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.js

@@ -22,7 +22,6 @@ const isValidUrl = (url, allowHttp = false) => {
  * @returns The generated API URL
  */
 export const getApiUrl = (config) => {
-    const allowHttp = config.allowHttp ?? false;
     if (config.integrations?.tracelog?.projectId) {
         const url = new URL(window.location.href);
         const host = url.hostname;
@@ -32,9 +31,8 @@ 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 apiUrl = `https://${projectId}.${cleanDomain}`;
+        const isValid = isValidUrl(apiUrl);
         if (!isValid) {
             throw new Error('Invalid URL');
         }
@@ -42,6 +40,7 @@ export const getApiUrl = (config) => {
     }
     if (config.integrations?.custom?.apiUrl) {
         const apiUrl = config.integrations.custom.apiUrl;
+        const allowHttp = config.integrations?.custom?.allowHttp ?? false;
         const isValid = isValidUrl(apiUrl, allowHttp);
         if (!isValid) {
             throw new Error('Invalid URL');

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

@@ -50,11 +50,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)
@@ -150,8 +145,16 @@ const validateIntegrations = (integrations) => {
             integrations.custom.apiUrl.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 apiUrl = integrations.custom.apiUrl.trim();
+        if (!apiUrl.startsWith('http://') && !apiUrl.startsWith('https://')) {
+            throw new IntegrationValidationError('Custom API URL must start with "http://" or "https://"', 'config');
+        }
+        const allowHttp = integrations.custom.allowHttp ?? false;
+        if (!allowHttp && apiUrl.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) {
@@ -183,7 +186,13 @@ export const validateAndNormalizeConfig = (config) => {
         sensitiveQueryParams: config.sensitiveQueryParams ?? [],
         errorSampling: config.errorSampling ?? 1,
         samplingRate: config.samplingRate ?? 1,
-        allowHttp: config.allowHttp ?? false,
     };
+    // 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.1",
   "main": "./dist/cjs/public-api.js",
   "module": "./dist/esm/public-api.js",
   "types": "./dist/esm/public-api.d.ts",
@@ -43,6 +43,7 @@
     "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",
+    "playground:gh-pages": "npm run build:browser && cp dist/browser/tracelog.esm.js playground/tracelog.js",
     "test:e2e": "npm run build:browser:dev && cp dist/browser/tracelog.esm.js playground/tracelog.js && NODE_ENV=dev playwright test",
     "ci:build": "npm run build:all",
     "prepare": "husky",
@@ -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",