@tracelog/lib 0.6.0 → 0.6.3

package/dist/cjs/api.d.ts

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

package/dist/cjs/api.js

@@ -4,6 +4,7 @@ exports.__setAppInstance = exports.destroy = exports.isInitialized = exports.off
 const app_1 = require("./app");
 const utils_1 = require("./utils");
 const test_bridge_1 = require("./test-bridge");
+const constants_1 = require("./constants");
 require("./types/window.types");
 // Buffer for listeners registered before init()
 const pendingListeners = [];
@@ -25,7 +26,7 @@ const init = async (config) => {
     }
     isInitializing = true;
     try {
-        const validatedConfig = (0, utils_1.validateAndNormalizeConfig)(config);
+        const validatedConfig = (0, utils_1.validateAndNormalizeConfig)(config ?? {});
         const instance = new app_1.App();
         try {
             // Attach buffered listeners BEFORE init() so they capture initial events
@@ -33,7 +34,14 @@ const init = async (config) => {
                 instance.on(event, callback);
             });
             pendingListeners.length = 0;
-            await instance.init(validatedConfig);
+            // Wrap initialization with timeout using Promise.race
+            const initPromise = instance.init(validatedConfig);
+            const timeoutPromise = new Promise((_, reject) => {
+                setTimeout(() => {
+                    reject(new Error(`[TraceLog] Initialization timeout after ${constants_1.INITIALIZATION_TIMEOUT_MS}ms`));
+                }, constants_1.INITIALIZATION_TIMEOUT_MS);
+            });
+            await Promise.race([initPromise, timeoutPromise]);
             app = instance;
         }
         catch (error) {
@@ -113,8 +121,9 @@ const destroy = async () => {
         app = null;
         isInitializing = false;
         pendingListeners.length = 0;
-        (0, utils_1.log)('error', 'Error during destroy, forced cleanup', { error });
-        throw error;
+        // Log error but don't re-throw - destroy should always complete successfully
+        // Applications should be able to tear down TraceLog even if internal cleanup fails
+        (0, utils_1.log)('warn', 'Error during destroy, forced cleanup completed', { error });
     }
     finally {
         isDestroying = false;

package/dist/cjs/app.d.ts

@@ -29,7 +29,7 @@ export declare class App extends StateManager {
         googleAnalytics?: GoogleAnalyticsIntegration;
     };
     get initialized(): boolean;
-    init(config: Config): Promise<void>;
+    init(config?: Config): Promise<void>;
     sendCustomEvent(name: string, metadata?: Record<string, unknown> | Record<string, unknown>[]): void;
     on<K extends keyof EmitterMap>(event: K, callback: EmitterCallback<EmitterMap[K]>): void;
     off<K extends keyof EmitterMap>(event: K, callback: EmitterCallback<EmitterMap[K]>): void;

package/dist/cjs/app.js

@@ -28,7 +28,7 @@ class App extends state_manager_1.StateManager {
     get initialized() {
         return this.isInitialized;
     }
-    async init(config) {
+    async init(config = {}) {
         if (this.isInitialized) {
             return;
         }
@@ -103,12 +103,12 @@ class App extends state_manager_1.StateManager {
         this.isInitialized = false;
         this.handlers = {};
     }
-    setupState(config) {
+    setupState(config = {}) {
         this.set('config', config);
         const userId = user_manager_1.UserManager.getId(this.managers.storage);
         this.set('userId', userId);
-        const apiUrl = (0, utils_1.getApiUrl)(config);
-        this.set('apiUrl', apiUrl);
+        const collectApiUrl = (0, utils_1.getCollectApiUrl)(config);
+        this.set('collectApiUrl', collectApiUrl);
         const device = (0, utils_1.getDeviceType)();
         this.set('device', device);
         const pageUrl = (0, utils_1.normalizeUrl)(window.location.href, config.sensitiveQueryParams);

package/dist/cjs/constants/config.constants.d.ts

@@ -22,7 +22,10 @@ export declare const MAX_SCROLL_EVENTS_PER_SESSION = 120;
 export declare const DEFAULT_SAMPLING_RATE = 1;
 export declare const MIN_SAMPLING_RATE = 0;
 export declare const MAX_SAMPLING_RATE = 1;
+export declare const RATE_LIMIT_WINDOW_MS = 1000;
+export declare const MAX_EVENTS_PER_SECOND = 200;
 export declare const BATCH_SIZE_THRESHOLD = 50;
+export declare const MAX_PENDING_EVENTS_BUFFER = 100;
 export declare const MIN_SESSION_TIMEOUT_MS = 30000;
 export declare const MAX_SESSION_TIMEOUT_MS = 86400000;
 export declare const MAX_CUSTOM_EVENT_NAME_LENGTH = 120;

package/dist/cjs/constants/config.constants.js

@@ -4,8 +4,8 @@
  * This file centralizes all timing, limits, browser, and initialization constants
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TAB_CLEANUP_DELAY_MS = exports.TAB_ELECTION_TIMEOUT_MS = exports.TAB_HEARTBEAT_INTERVAL_MS = exports.CROSS_TAB_INITIALIZATION_LOCK_TIMEOUT_MS = exports.SESSION_CLEANUP_DELAY_MS = exports.SESSION_MAX_RETRY_ATTEMPTS = exports.SESSION_SYNC_TIMEOUT_MS = exports.INITIALIZATION_TIMEOUT_MS = exports.INITIALIZATION_CONCURRENT_RETRY_DELAY_MS = exports.INITIALIZATION_MAX_CONCURRENT_RETRIES = exports.UTM_PARAMS = exports.INTERACTIVE_SELECTORS = exports.HTML_DATA_ATTR_PREFIX = exports.MAX_FINGERPRINTS_HARD_LIMIT = exports.FINGERPRINT_CLEANUP_MULTIPLIER = exports.MAX_FINGERPRINTS = exports.SYNC_XHR_TIMEOUT_MS = exports.PRECISION_TWO_DECIMALS = exports.MAX_OBJECT_DEPTH = exports.MAX_ARRAY_LENGTH = exports.MAX_STRING_LENGTH = exports.MAX_TEXT_LENGTH = exports.MAX_NESTED_OBJECT_KEYS = exports.MAX_CUSTOM_EVENT_ARRAY_SIZE = exports.MAX_CUSTOM_EVENT_KEYS = exports.MAX_CUSTOM_EVENT_STRING_SIZE = exports.MAX_CUSTOM_EVENT_NAME_LENGTH = exports.MAX_SESSION_TIMEOUT_MS = exports.MIN_SESSION_TIMEOUT_MS = exports.BATCH_SIZE_THRESHOLD = exports.MAX_SAMPLING_RATE = exports.MIN_SAMPLING_RATE = exports.DEFAULT_SAMPLING_RATE = exports.MAX_SCROLL_EVENTS_PER_SESSION = exports.SCROLL_MIN_EVENT_INTERVAL_MS = exports.MIN_SCROLL_DEPTH_CHANGE = exports.SIGNIFICANT_SCROLL_DELTA = exports.DEFAULT_MOTION_THRESHOLD = exports.MAX_METADATA_SIZE = exports.REQUEST_TIMEOUT_MS = exports.RETRY_DELAY_MS = exports.MAX_RETRIES = exports.MAX_EVENTS_QUEUE_LENGTH = exports.EVENT_PERSISTENCE_MAX_AGE_MS = exports.EVENT_EXPIRY_HOURS = exports.DEFAULT_VISIBILITY_TIMEOUT_MS = exports.SCROLL_DEBOUNCE_TIME_MS = exports.EVENT_SENT_INTERVAL_MS = exports.DUPLICATE_EVENT_THRESHOLD_MS = exports.DEFAULT_SESSION_TIMEOUT = void 0;
-exports.XSS_PATTERNS = exports.VALIDATION_MESSAGES = exports.MAX_RETRY_ATTEMPTS = exports.RATE_LIMIT_INTERVAL = exports.RETRY_BACKOFF_MAX = exports.RETRY_BACKOFF_INITIAL = exports.SCROLL_SUPPRESS_MULTIPLIER = exports.MIN_SESSION_RECOVERY_WINDOW_MS = exports.MAX_SESSION_RECOVERY_WINDOW_MS = exports.MAX_SESSION_RECOVERY_ATTEMPTS = exports.SESSION_RECOVERY_WINDOW_MULTIPLIER = void 0;
+exports.CROSS_TAB_INITIALIZATION_LOCK_TIMEOUT_MS = exports.SESSION_CLEANUP_DELAY_MS = exports.SESSION_MAX_RETRY_ATTEMPTS = exports.SESSION_SYNC_TIMEOUT_MS = exports.INITIALIZATION_TIMEOUT_MS = exports.INITIALIZATION_CONCURRENT_RETRY_DELAY_MS = exports.INITIALIZATION_MAX_CONCURRENT_RETRIES = exports.UTM_PARAMS = exports.INTERACTIVE_SELECTORS = exports.HTML_DATA_ATTR_PREFIX = exports.MAX_FINGERPRINTS_HARD_LIMIT = exports.FINGERPRINT_CLEANUP_MULTIPLIER = exports.MAX_FINGERPRINTS = exports.SYNC_XHR_TIMEOUT_MS = exports.PRECISION_TWO_DECIMALS = exports.MAX_OBJECT_DEPTH = exports.MAX_ARRAY_LENGTH = exports.MAX_STRING_LENGTH = exports.MAX_TEXT_LENGTH = exports.MAX_NESTED_OBJECT_KEYS = exports.MAX_CUSTOM_EVENT_ARRAY_SIZE = exports.MAX_CUSTOM_EVENT_KEYS = exports.MAX_CUSTOM_EVENT_STRING_SIZE = exports.MAX_CUSTOM_EVENT_NAME_LENGTH = exports.MAX_SESSION_TIMEOUT_MS = exports.MIN_SESSION_TIMEOUT_MS = exports.MAX_PENDING_EVENTS_BUFFER = exports.BATCH_SIZE_THRESHOLD = exports.MAX_EVENTS_PER_SECOND = exports.RATE_LIMIT_WINDOW_MS = exports.MAX_SAMPLING_RATE = exports.MIN_SAMPLING_RATE = exports.DEFAULT_SAMPLING_RATE = exports.MAX_SCROLL_EVENTS_PER_SESSION = exports.SCROLL_MIN_EVENT_INTERVAL_MS = exports.MIN_SCROLL_DEPTH_CHANGE = exports.SIGNIFICANT_SCROLL_DELTA = exports.DEFAULT_MOTION_THRESHOLD = exports.MAX_METADATA_SIZE = exports.REQUEST_TIMEOUT_MS = exports.RETRY_DELAY_MS = exports.MAX_RETRIES = exports.MAX_EVENTS_QUEUE_LENGTH = exports.EVENT_PERSISTENCE_MAX_AGE_MS = exports.EVENT_EXPIRY_HOURS = exports.DEFAULT_VISIBILITY_TIMEOUT_MS = exports.SCROLL_DEBOUNCE_TIME_MS = exports.EVENT_SENT_INTERVAL_MS = exports.DUPLICATE_EVENT_THRESHOLD_MS = exports.DEFAULT_SESSION_TIMEOUT = void 0;
+exports.XSS_PATTERNS = exports.VALIDATION_MESSAGES = exports.MAX_RETRY_ATTEMPTS = exports.RATE_LIMIT_INTERVAL = exports.RETRY_BACKOFF_MAX = exports.RETRY_BACKOFF_INITIAL = exports.SCROLL_SUPPRESS_MULTIPLIER = exports.MIN_SESSION_RECOVERY_WINDOW_MS = exports.MAX_SESSION_RECOVERY_WINDOW_MS = exports.MAX_SESSION_RECOVERY_ATTEMPTS = exports.SESSION_RECOVERY_WINDOW_MULTIPLIER = exports.TAB_CLEANUP_DELAY_MS = exports.TAB_ELECTION_TIMEOUT_MS = exports.TAB_HEARTBEAT_INTERVAL_MS = void 0;
 // ============================================================================
 // SESSION & TIMING
 // ============================================================================
@@ -36,8 +36,11 @@ exports.MAX_SCROLL_EVENTS_PER_SESSION = 120;
 exports.DEFAULT_SAMPLING_RATE = 1;
 exports.MIN_SAMPLING_RATE = 0;
 exports.MAX_SAMPLING_RATE = 1;
+exports.RATE_LIMIT_WINDOW_MS = 1000; // 1 second window
+exports.MAX_EVENTS_PER_SECOND = 200; // Maximum 200 events per second
 // Queue and batch limits
 exports.BATCH_SIZE_THRESHOLD = 50;
+exports.MAX_PENDING_EVENTS_BUFFER = 100; // Maximum events to buffer before session init
 // Session timeout validation limits
 exports.MIN_SESSION_TIMEOUT_MS = 30000; // 30 seconds minimum
 exports.MAX_SESSION_TIMEOUT_MS = 86400000; // 24 hours maximum

package/dist/cjs/handlers/click.handler.js

@@ -17,9 +17,9 @@ class ClickHandler extends state_manager_1.StateManager {
         this.clickHandler = (event) => {
             const mouseEvent = event;
             const target = mouseEvent.target;
-            const clickedElement = target instanceof HTMLElement
+            const clickedElement = typeof HTMLElement !== 'undefined' && target instanceof HTMLElement
                 ? target
-                : target instanceof Node && target.parentElement instanceof HTMLElement
+                : typeof HTMLElement !== 'undefined' && target instanceof Node && target.parentElement instanceof HTMLElement
                     ? target.parentElement
                     : null;
             if (!clickedElement) {

package/dist/cjs/handlers/scroll.handler.js

@@ -45,7 +45,7 @@ class ScrollHandler extends state_manager_1.StateManager {
     trySetupContainers(selectors, attempt) {
         const elements = selectors
             .map((sel) => this.safeQuerySelector(sel))
-            .filter((element) => element instanceof HTMLElement);
+            .filter((element) => element != null && typeof HTMLElement !== 'undefined' && element instanceof HTMLElement);
         if (elements.length > 0) {
             for (const element of elements) {
                 const isAlreadyTracking = this.containers.some((c) => c.element === element);

package/dist/cjs/handlers/session.handler.js

@@ -21,7 +21,7 @@ class SessionHandler extends state_manager_1.StateManager {
             return;
         }
         const config = this.get('config');
-        const projectId = config?.integrations?.tracelog?.projectId ?? config?.integrations?.custom?.apiUrl ?? 'default';
+        const projectId = config?.integrations?.tracelog?.projectId ?? config?.integrations?.custom?.collectApiUrl ?? 'default';
         if (!projectId) {
             throw new Error('Cannot start session tracking: config not available');
         }

package/dist/cjs/managers/event.manager.d.ts

@@ -12,6 +12,8 @@ export declare class EventManager extends StateManager {
     private lastEventFingerprint;
     private lastEventTime;
     private sendIntervalId;
+    private rateLimitCounter;
+    private rateLimitWindowStart;
     constructor(storeManager: StorageManager, googleAnalytics?: GoogleAnalyticsIntegration | null, emitter?: Emitter | null);
     recoverPersistedEvents(): Promise<void>;
     track({ type, page_url, from_page_url, scroll_data, click_data, custom_event, web_vitals, error_data, session_end_reason, }: Partial<EventData>): void;
@@ -32,6 +34,7 @@ export declare class EventManager extends StateManager {
     private startSendInterval;
     private handleGoogleAnalyticsIntegration;
     private shouldSample;
+    private checkRateLimit;
     private removeProcessedEvents;
     private emitEvent;
     private emitEventsQueue;

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

@@ -14,6 +14,8 @@ class EventManager extends state_manager_1.StateManager {
         this.lastEventFingerprint = null;
         this.lastEventTime = 0;
         this.sendIntervalId = null;
+        this.rateLimitCounter = 0;
+        this.rateLimitWindowStart = 0;
         this.googleAnalytics = googleAnalytics;
         this.dataSender = new sender_manager_1.SenderManager(storeManager);
         this.emitter = emitter;
@@ -36,10 +38,19 @@ class EventManager extends state_manager_1.StateManager {
     }
     track({ type, page_url, from_page_url, scroll_data, click_data, custom_event, web_vitals, error_data, session_end_reason, }) {
         if (!type) {
-            (0, utils_1.log)('warn', 'Event type is required');
+            (0, utils_1.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 >= config_constants_1.MAX_PENDING_EVENTS_BUFFER) {
+                // Drop oldest event (FIFO) to make room for new one
+                this.pendingEventsBuffer.shift();
+                (0, utils_1.log)('warn', 'Pending events buffer full - dropping oldest event', {
+                    data: { maxBufferSize: config_constants_1.MAX_PENDING_EVENTS_BUFFER },
+                });
+            }
             this.pendingEventsBuffer.push({
                 type,
                 page_url,
@@ -53,10 +64,16 @@ class EventManager extends state_manager_1.StateManager {
             });
             return;
         }
+        // Rate limiting check (except for critical events)
+        // Applied AFTER session check to only rate-limit processable events
+        const isCriticalEvent = type === types_1.EventType.SESSION_START || type === types_1.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 === types_1.EventType.SESSION_START;
-        const isSessionEnd = eventType === types_1.EventType.SESSION_END;
-        const isCriticalEvent = isSessionStart || isSessionEnd;
         const currentPageUrl = page_url || this.get('pageUrl');
         const payload = this.buildEventPayload({
             type: eventType,
@@ -75,7 +92,7 @@ class EventManager extends state_manager_1.StateManager {
         if (isSessionStart) {
             const currentSessionId = this.get('sessionId');
             if (!currentSessionId) {
-                (0, utils_1.log)('warn', 'Session start event ignored: missing sessionId');
+                (0, utils_1.log)('error', 'Session start event requires sessionId - event will be ignored');
                 return;
             }
             if (this.get('hasStartSession')) {
@@ -108,6 +125,8 @@ class EventManager extends state_manager_1.StateManager {
         this.pendingEventsBuffer = [];
         this.lastEventFingerprint = null;
         this.lastEventTime = 0;
+        this.rateLimitCounter = 0;
+        this.rateLimitWindowStart = 0;
         this.dataSender.stop();
     }
     async flushImmediately() {
@@ -123,12 +142,19 @@ class EventManager extends state_manager_1.StateManager {
         if (this.pendingEventsBuffer.length === 0) {
             return;
         }
-        if (!this.get('sessionId')) {
-            (0, utils_1.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
+            (0, utils_1.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);
         });
@@ -304,6 +330,21 @@ class EventManager extends state_manager_1.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 > config_constants_1.RATE_LIMIT_WINDOW_MS) {
+            this.rateLimitCounter = 0;
+            this.rateLimitWindowStart = now;
+        }
+        // Check if limit exceeded
+        if (this.rateLimitCounter >= config_constants_1.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/cjs/managers/sender.manager.js

@@ -23,7 +23,7 @@ class SenderManager extends state_manager_1.StateManager {
             return true;
         }
         const config = this.get('config');
-        if (config?.integrations?.custom?.apiUrl === types_1.SpecialApiUrl.Fail) {
+        if (config?.integrations?.custom?.collectApiUrl === types_1.SpecialApiUrl.Fail) {
             (0, utils_1.log)('warn', 'Fail mode: simulating network failure (sync)', {
                 data: { events: body.events.length },
             });
@@ -93,7 +93,7 @@ class SenderManager extends state_manager_1.StateManager {
             return this.simulateSuccessfulSend();
         }
         const config = this.get('config');
-        if (config?.integrations?.custom?.apiUrl === types_1.SpecialApiUrl.Fail) {
+        if (config?.integrations?.custom?.collectApiUrl === types_1.SpecialApiUrl.Fail) {
             (0, utils_1.log)('warn', 'Fail mode: simulating network failure', {
                 data: { events: body.events.length },
             });
@@ -155,7 +155,6 @@ class SenderManager extends state_manager_1.StateManager {
         return false;
     }
     prepareRequest(body) {
-        const url = `${this.get('apiUrl')}/collect`;
         // Enrich payload with metadata for sendBeacon() fallback
         // sendBeacon() doesn't send custom headers, so we include referer in payload
         const enrichedBody = {
@@ -166,7 +165,7 @@ class SenderManager extends state_manager_1.StateManager {
             },
         };
         return {
-            url,
+            url: this.get('collectApiUrl'),
             payload: JSON.stringify(enrichedBody),
         };
     }
@@ -272,7 +271,7 @@ class SenderManager extends state_manager_1.StateManager {
         }, retryDelay);
     }
     shouldSkipSend() {
-        return !this.get('apiUrl');
+        return !this.get('collectApiUrl');
     }
     async simulateSuccessfulSend() {
         const delay = Math.random() * 400 + 100;

package/dist/cjs/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/cjs/managers/storage.manager.js

@@ -40,6 +40,9 @@ 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);
@@ -49,15 +52,37 @@ class StorageManager {
         catch (error) {
             if (error instanceof DOMException && error.name === 'QuotaExceededError') {
                 this.hasQuotaExceededError = true;
-                (0, utils_1.log)('error', 'localStorage quota exceeded - data will not persist after reload', {
-                    error,
+                (0, utils_1.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) {
+                        (0, utils_1.log)('error', 'localStorage quota exceeded even after cleanup - data will not persist', {
+                            error: retryError,
+                            data: { key, valueSize: value.length },
+                        });
+                    }
+                }
+                else {
+                    (0, utils_1.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
@@ -111,6 +136,69 @@ 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) {
+            (0, utils_1.log)('error', 'Failed to cleanup old data', { error });
+            return false;
+        }
+    }
     /**
      * Initialize storage (localStorage or sessionStorage) with feature detection
      */
@@ -148,6 +236,8 @@ 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);
@@ -162,9 +252,8 @@ 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/cjs/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/cjs/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/cjs/test-bridge.js

@@ -77,7 +77,7 @@ class TestBridge extends app_1.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/cjs/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/cjs/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/cjs/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/cjs/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;