user-analytics-tracker 1.7.0 → 2.0.0

package/dist/index.esm.js

@@ -1013,15 +1013,91 @@ function trackPageVisit() {
     localStorage.setItem('analytics:pageVisits', newCount.toString());
     return newCount;
 }
+const SESSION_STORAGE_KEY = 'analytics:session';
+const DEFAULT_SESSION_TIMEOUT = 30 * 60 * 1000; // 30 minutes
+/**
+ * Get or create a session
+ */
+function getOrCreateSession(timeout = DEFAULT_SESSION_TIMEOUT) {
+    if (typeof window === 'undefined') {
+        return {
+            sessionId: `server-${Date.now()}`,
+            startTime: Date.now(),
+            lastActivity: Date.now(),
+            pageViews: 1,
+        };
+    }
+    const stored = loadJSON(SESSION_STORAGE_KEY);
+    const now = Date.now();
+    // Check if session expired
+    if (stored && now - stored.lastActivity < timeout) {
+        // Update last activity
+        const updated = {
+            ...stored,
+            lastActivity: now,
+            pageViews: stored.pageViews + 1,
+        };
+        saveJSON(SESSION_STORAGE_KEY, updated);
+        return updated;
+    }
+    // Create new session
+    const sessionId = `session-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+    const newSession = {
+        sessionId,
+        startTime: now,
+        lastActivity: now,
+        pageViews: 1,
+    };
+    saveJSON(SESSION_STORAGE_KEY, newSession);
+    return newSession;
+}
+/**
+ * Update session activity
+ */
+function updateSessionActivity() {
+    if (typeof window === 'undefined')
+        return;
+    const stored = loadJSON(SESSION_STORAGE_KEY);
+    if (stored) {
+        const updated = {
+            ...stored,
+            lastActivity: Date.now(),
+        };
+        saveJSON(SESSION_STORAGE_KEY, updated);
+    }
+}
+/**
+ * Get current session info
+ */
+function getSession() {
+    return loadJSON(SESSION_STORAGE_KEY);
+}
+/**
+ * Clear session
+ */
+function clearSession() {
+    if (typeof window === 'undefined')
+        return;
+    try {
+        localStorage.removeItem(SESSION_STORAGE_KEY);
+    }
+    catch {
+        // Silently fail
+    }
+}
 
 var storage = /*#__PURE__*/Object.freeze({
     __proto__: null,
+    clearSession: clearSession,
+    getOrCreateSession: getOrCreateSession,
     getOrCreateUserId: getOrCreateUserId,
+    getSession: getSession,
     loadJSON: loadJSON,
     loadSessionJSON: loadSessionJSON,
     saveJSON: saveJSON,
     saveSessionJSON: saveSessionJSON,
-    trackPageVisit: trackPageVisit
+    trackPageVisit: trackPageVisit,
+    updateSessionActivity: updateSessionActivity
 });
 
 const UTM_KEYS = [
@@ -1170,36 +1246,584 @@ var attributionDetector = /*#__PURE__*/Object.freeze({
     AttributionDetector: AttributionDetector
 });
 
+/**
+ * Logger utility for analytics tracker
+ * Provides configurable logging levels for development and production
+ */
+class Logger {
+    constructor() {
+        this.level = 'warn';
+        this.isDevelopment =
+            typeof process !== 'undefined' &&
+                process.env?.NODE_ENV === 'development';
+        // Default to 'info' in development, 'warn' in production
+        if (this.isDevelopment && this.level === 'warn') {
+            this.level = 'info';
+        }
+    }
+    setLevel(level) {
+        this.level = level;
+    }
+    getLevel() {
+        return this.level;
+    }
+    shouldLog(level) {
+        const levels = ['silent', 'error', 'warn', 'info', 'debug'];
+        const currentIndex = levels.indexOf(this.level);
+        const messageIndex = levels.indexOf(level);
+        return messageIndex >= 0 && messageIndex <= currentIndex;
+    }
+    error(message, ...args) {
+        if (this.shouldLog('error')) {
+            console.error(`[Analytics] ${message}`, ...args);
+        }
+    }
+    warn(message, ...args) {
+        if (this.shouldLog('warn')) {
+            console.warn(`[Analytics] ${message}`, ...args);
+        }
+    }
+    info(message, ...args) {
+        if (this.shouldLog('info')) {
+            console.log(`[Analytics] ${message}`, ...args);
+        }
+    }
+    debug(message, ...args) {
+        if (this.shouldLog('debug')) {
+            console.log(`[Analytics] [DEBUG] ${message}`, ...args);
+        }
+    }
+}
+const logger = new Logger();
+
+/**
+ * Queue Manager for Analytics Events
+ * Handles batching, persistence, and offline support
+ */
+class QueueManager {
+    constructor(config) {
+        this.queue = [];
+        this.flushTimer = null;
+        this.isFlushing = false;
+        this.flushCallback = null;
+        this.config = config;
+        this.loadFromStorage();
+        this.startAutoFlush();
+        this.setupPageUnloadHandler();
+    }
+    /**
+     * Set the callback function to flush events
+     */
+    setFlushCallback(callback) {
+        this.flushCallback = callback;
+    }
+    /**
+     * Add an event to the queue
+     */
+    enqueue(event) {
+        if (this.queue.length >= this.config.maxQueueSize) {
+            logger.warn(`Queue full (${this.config.maxQueueSize} events). Dropping oldest event.`);
+            this.queue.shift(); // Remove oldest event
+        }
+        const queuedEvent = {
+            event,
+            retries: 0,
+            timestamp: Date.now(),
+            id: `${Date.now()}-${Math.random().toString(36).substring(7)}`,
+        };
+        this.queue.push(queuedEvent);
+        this.saveToStorage();
+        logger.debug(`Event queued. Queue size: ${this.queue.length}`);
+        // Auto-flush if batch size reached
+        if (this.queue.length >= this.config.batchSize) {
+            this.flush();
+        }
+        return true;
+    }
+    /**
+     * Flush events from the queue
+     */
+    async flush() {
+        if (this.isFlushing || this.queue.length === 0 || !this.flushCallback) {
+            return;
+        }
+        this.isFlushing = true;
+        const eventsToFlush = this.queue.splice(0, this.config.batchSize);
+        if (eventsToFlush.length === 0) {
+            this.isFlushing = false;
+            return;
+        }
+        try {
+            const events = eventsToFlush.map((q) => q.event);
+            await this.flushCallback(events);
+            // Remove successfully flushed events from storage
+            this.saveToStorage();
+            logger.debug(`Flushed ${events.length} events. Queue size: ${this.queue.length}`);
+        }
+        catch (error) {
+            // On failure, put events back in queue (they'll be retried)
+            this.queue.unshift(...eventsToFlush);
+            this.saveToStorage();
+            logger.warn(`Failed to flush events. Re-queued ${eventsToFlush.length} events.`, error);
+            throw error;
+        }
+        finally {
+            this.isFlushing = false;
+        }
+    }
+    /**
+     * Get current queue size
+     */
+    getQueueSize() {
+        return this.queue.length;
+    }
+    /**
+     * Get all queued events (for debugging)
+     */
+    getQueue() {
+        return [...this.queue];
+    }
+    /**
+     * Clear the queue
+     */
+    clear() {
+        this.queue = [];
+        this.saveToStorage();
+        logger.debug('Queue cleared');
+    }
+    /**
+     * Load queue from localStorage
+     */
+    loadFromStorage() {
+        if (typeof window === 'undefined')
+            return;
+        try {
+            const stored = loadJSON(this.config.storageKey);
+            if (stored && Array.isArray(stored)) {
+                // Only load events from last 24 hours to prevent stale data
+                const oneDayAgo = Date.now() - 24 * 60 * 60 * 1000;
+                this.queue = stored.filter((q) => q.timestamp > oneDayAgo);
+                if (this.queue.length > 0) {
+                    logger.debug(`Loaded ${this.queue.length} events from storage`);
+                }
+            }
+        }
+        catch (error) {
+            logger.warn('Failed to load queue from storage', error);
+        }
+    }
+    /**
+     * Save queue to localStorage
+     */
+    saveToStorage() {
+        if (typeof window === 'undefined')
+            return;
+        try {
+            saveJSON(this.config.storageKey, this.queue);
+        }
+        catch (error) {
+            logger.warn('Failed to save queue to storage', error);
+        }
+    }
+    /**
+     * Start auto-flush timer
+     */
+    startAutoFlush() {
+        if (typeof window === 'undefined')
+            return;
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+        }
+        this.flushTimer = setInterval(() => {
+            if (this.queue.length > 0) {
+                this.flush().catch((error) => {
+                    logger.warn('Auto-flush failed', error);
+                });
+            }
+        }, this.config.batchInterval);
+    }
+    /**
+     * Setup page unload handler to flush events
+     */
+    setupPageUnloadHandler() {
+        if (typeof window === 'undefined')
+            return;
+        // Use sendBeacon for reliable delivery on page unload
+        window.addEventListener('beforeunload', () => {
+            if (this.queue.length > 0 && this.flushCallback) {
+                const events = this.queue.splice(0, this.config.batchSize).map((q) => q.event);
+                // Try to send via sendBeacon (more reliable on unload)
+                if (navigator.sendBeacon) {
+                    try {
+                        const blob = new Blob([JSON.stringify(events)], {
+                            type: 'application/json',
+                        });
+                        navigator.sendBeacon(this.getEndpointFromCallback(), blob);
+                        this.saveToStorage();
+                    }
+                    catch (error) {
+                        // Fallback: put events back in queue
+                        this.queue.unshift(...events.map((e) => ({
+                            event: e,
+                            retries: 0,
+                            timestamp: Date.now(),
+                            id: `${Date.now()}-${Math.random().toString(36).substring(7)}`,
+                        })));
+                    }
+                }
+            }
+        });
+        // Also use visibilitychange for better mobile support
+        document.addEventListener('visibilitychange', () => {
+            if (document.visibilityState === 'hidden' && this.queue.length > 0) {
+                this.flush().catch(() => {
+                    // Silently fail on visibility change
+                });
+            }
+        });
+    }
+    /**
+     * Get endpoint for sendBeacon
+     */
+    getEndpointFromCallback() {
+        // Try to get from window or return default
+        if (typeof window !== 'undefined' && window.__analyticsEndpoint) {
+            return window.__analyticsEndpoint;
+        }
+        return '/api/analytics';
+    }
+    /**
+     * Update storage key (for configuration changes)
+     */
+    updateConfig(config) {
+        this.config = { ...this.config, ...config };
+        if (config.batchInterval) {
+            this.startAutoFlush();
+        }
+    }
+    /**
+     * Cleanup resources
+     */
+    destroy() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+    }
+}
+
+/**
+ * Plugin Manager for Analytics Tracker
+ * Manages plugin registration and execution
+ */
+class PluginManager {
+    constructor() {
+        this.plugins = [];
+    }
+    /**
+     * Register a plugin
+     */
+    register(plugin) {
+        if (!plugin.name) {
+            throw new Error('Plugin must have a name');
+        }
+        this.plugins.push(plugin);
+        logger.debug(`Plugin registered: ${plugin.name}`);
+    }
+    /**
+     * Unregister a plugin
+     */
+    unregister(pluginName) {
+        const index = this.plugins.findIndex((p) => p.name === pluginName);
+        if (index !== -1) {
+            this.plugins.splice(index, 1);
+            logger.debug(`Plugin unregistered: ${pluginName}`);
+        }
+    }
+    /**
+     * Get all registered plugins
+     */
+    getPlugins() {
+        return [...this.plugins];
+    }
+    /**
+     * Execute beforeSend hooks for all plugins
+     * Returns the transformed event, or null if filtered out
+     */
+    async executeBeforeSend(event) {
+        let transformedEvent = event;
+        for (const plugin of this.plugins) {
+            if (!plugin.beforeSend)
+                continue;
+            try {
+                const result = await plugin.beforeSend(transformedEvent);
+                // If plugin returns null/undefined, filter out the event
+                if (result === null || result === undefined) {
+                    logger.debug(`Event filtered out by plugin: ${plugin.name}`);
+                    return null;
+                }
+                transformedEvent = result;
+            }
+            catch (error) {
+                logger.warn(`Plugin ${plugin.name} beforeSend hook failed:`, error);
+                // Continue with other plugins even if one fails
+            }
+        }
+        return transformedEvent;
+    }
+    /**
+     * Execute afterSend hooks for all plugins
+     */
+    async executeAfterSend(event) {
+        for (const plugin of this.plugins) {
+            if (!plugin.afterSend)
+                continue;
+            try {
+                await plugin.afterSend(event);
+            }
+            catch (error) {
+                logger.warn(`Plugin ${plugin.name} afterSend hook failed:`, error);
+            }
+        }
+    }
+    /**
+     * Execute onError hooks for all plugins
+     */
+    async executeOnError(event, error) {
+        for (const plugin of this.plugins) {
+            if (!plugin.onError)
+                continue;
+            try {
+                await plugin.onError(event, error);
+            }
+            catch (err) {
+                logger.warn(`Plugin ${plugin.name} onError hook failed:`, err);
+            }
+        }
+    }
+    /**
+     * Clear all plugins
+     */
+    clear() {
+        this.plugins = [];
+        logger.debug('All plugins cleared');
+    }
+}
+// Global plugin manager instance
+const pluginManager = new PluginManager();
+
+/**
+ * Metrics collection for analytics tracker
+ * Tracks performance and usage statistics
+ */
+class MetricsCollector {
+    constructor() {
+        this.metrics = {
+            eventsSent: 0,
+            eventsQueued: 0,
+            eventsFailed: 0,
+            eventsFiltered: 0,
+            averageSendTime: 0,
+            retryCount: 0,
+            queueSize: 0,
+            lastFlushTime: null,
+            errors: [],
+        };
+        this.sendTimes = [];
+        this.maxErrors = 100; // Keep last 100 errors
+    }
+    /**
+     * Record an event being queued
+     */
+    recordQueued() {
+        this.metrics.eventsQueued++;
+    }
+    /**
+     * Record an event being sent
+     */
+    recordSent(sendTime) {
+        this.metrics.eventsSent++;
+        this.sendTimes.push(sendTime);
+        // Keep only last 100 send times for average calculation
+        if (this.sendTimes.length > 100) {
+            this.sendTimes.shift();
+        }
+        // Calculate average
+        const sum = this.sendTimes.reduce((a, b) => a + b, 0);
+        this.metrics.averageSendTime = sum / this.sendTimes.length;
+    }
+    /**
+     * Record a failed event
+     */
+    recordFailed(error) {
+        this.metrics.eventsFailed++;
+        if (error) {
+            this.metrics.errors.push({
+                timestamp: Date.now(),
+                error: error.message || String(error),
+            });
+            // Keep only last N errors
+            if (this.metrics.errors.length > this.maxErrors) {
+                this.metrics.errors.shift();
+            }
+        }
+    }
+    /**
+     * Record a filtered event
+     */
+    recordFiltered() {
+        this.metrics.eventsFiltered++;
+    }
+    /**
+     * Record a retry
+     */
+    recordRetry() {
+        this.metrics.retryCount++;
+    }
+    /**
+     * Update queue size
+     */
+    updateQueueSize(size) {
+        this.metrics.queueSize = size;
+    }
+    /**
+     * Record flush time
+     */
+    recordFlush() {
+        this.metrics.lastFlushTime = Date.now();
+    }
+    /**
+     * Get current metrics
+     */
+    getMetrics() {
+        return {
+            ...this.metrics,
+            errors: [...this.metrics.errors], // Return copy
+        };
+    }
+    /**
+     * Reset metrics
+     */
+    reset() {
+        this.metrics = {
+            eventsSent: 0,
+            eventsQueued: 0,
+            eventsFailed: 0,
+            eventsFiltered: 0,
+            averageSendTime: 0,
+            retryCount: 0,
+            queueSize: 0,
+            lastFlushTime: null,
+            errors: [],
+        };
+        this.sendTimes = [];
+        logger.debug('Metrics reset');
+    }
+    /**
+     * Get metrics summary (for logging)
+     */
+    getSummary() {
+        const m = this.metrics;
+        return `Metrics: ${m.eventsSent} sent, ${m.eventsQueued} queued, ${m.eventsFailed} failed, ${m.eventsFiltered} filtered, ${m.retryCount} retries, avg send time: ${m.averageSendTime.toFixed(2)}ms`;
+    }
+}
+// Global metrics collector instance
+const metricsCollector = new MetricsCollector();
+
 /**
  * Analytics Service
  * Sends analytics events to your backend API
  *
  * Supports both relative paths (e.g., '/api/analytics') and full URLs (e.g., 'https://your-server.com/api/analytics')
+ *
+ * Features:
+ * - Event batching and queueing
+ * - Automatic retry with exponential backoff
+ * - Offline support with localStorage persistence
+ * - Configurable logging levels
  */
 class AnalyticsService {
     /**
-     * Configure the analytics API endpoint
+     * Configure the analytics service
      *
      * @param config - Configuration object
      * @param config.apiEndpoint - Your backend API endpoint URL
-     *   - Relative path: '/api/analytics' (sends to same domain)
-     *   - Full URL: 'https://your-server.com/api/analytics' (sends to your server)
+     * @param config.batchSize - Events per batch (default: 10)
+     * @param config.batchInterval - Flush interval in ms (default: 5000)
+     * @param config.maxQueueSize - Max queued events (default: 100)
+     * @param config.maxRetries - Max retry attempts (default: 3)
+     * @param config.retryDelay - Initial retry delay in ms (default: 1000)
+     * @param config.logLevel - Logging verbosity (default: 'warn')
      *
      * @example
      * ```typescript
-     * // Use your own server
+     * // Basic configuration
      * AnalyticsService.configure({
      *   apiEndpoint: 'https://api.yourcompany.com/analytics'
      * });
      *
-     * // Or use relative path (same domain)
+     * // Advanced configuration
      * AnalyticsService.configure({
-     *   apiEndpoint: '/api/analytics'
+     *   apiEndpoint: '/api/analytics',
+     *   batchSize: 20,
+     *   batchInterval: 10000,
+     *   maxRetries: 5,
+     *   logLevel: 'info'
      * });
      * ```
      */
     static configure(config) {
         this.apiEndpoint = config.apiEndpoint;
+        this.config = {
+            batchSize: 10,
+            batchInterval: 5000,
+            maxQueueSize: 100,
+            maxRetries: 3,
+            retryDelay: 1000,
+            logLevel: 'warn',
+            ...config,
+        };
+        // Set log level
+        if (this.config.logLevel) {
+            logger.setLevel(this.config.logLevel);
+        }
+        // Initialize queue manager
+        this.initializeQueue();
+        // Store endpoint for sendBeacon
+        if (typeof window !== 'undefined') {
+            window.__analyticsEndpoint = this.apiEndpoint;
+        }
+        // Reset metrics if enabled
+        if (this.config.enableMetrics) {
+            metricsCollector.reset();
+        }
+        this.isInitialized = true;
+    }
+    /**
+     * Initialize the queue manager
+     */
+    static initializeQueue() {
+        if (typeof window === 'undefined')
+            return;
+        const batchSize = this.config.batchSize ?? 10;
+        const batchInterval = this.config.batchInterval ?? 5000;
+        const maxQueueSize = this.config.maxQueueSize ?? 100;
+        this.queueManager = new QueueManager({
+            batchSize,
+            batchInterval,
+            maxQueueSize,
+            storageKey: 'analytics:eventQueue',
+        });
+        // Set flush callback
+        this.queueManager.setFlushCallback(async (events) => {
+            await this.sendBatch(events);
+        });
+    }
+    /**
+     * Get queue manager instance
+     */
+    static getQueueManager() {
+        return this.queueManager;
     }
     /**
      * Generate a random event ID
@@ -1215,8 +1839,131 @@ class AnalyticsService {
         // Fallback for environments without crypto
         return Math.random().toString(36).substring(2) + Date.now().toString(36);
     }
+    /**
+     * Send a batch of events with retry logic
+     */
+    static async sendBatch(events) {
+        if (events.length === 0)
+            return;
+        // Apply plugin transformations
+        const transformedEvents = [];
+        for (const event of events) {
+            const transformed = await pluginManager.executeBeforeSend(event);
+            if (transformed) {
+                transformedEvents.push(transformed);
+            }
+            else {
+                if (this.config.enableMetrics) {
+                    metricsCollector.recordFiltered();
+                }
+            }
+        }
+        if (transformedEvents.length === 0) {
+            logger.debug('All events filtered out by plugins');
+            return;
+        }
+        const maxRetries = this.config.maxRetries ?? 3;
+        const retryDelay = this.config.retryDelay ?? 1000;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                const res = await fetch(this.apiEndpoint, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    keepalive: true,
+                    body: JSON.stringify(transformedEvents),
+                });
+                if (res.ok) {
+                    const sendTime = Date.now(); // Approximate send time
+                    logger.debug(`Successfully sent batch of ${transformedEvents.length} events`);
+                    // Record metrics
+                    if (this.config.enableMetrics) {
+                        for (let i = 0; i < transformedEvents.length; i++) {
+                            metricsCollector.recordSent(sendTime);
+                        }
+                        metricsCollector.recordFlush();
+                    }
+                    // Execute afterSend hooks
+                    for (const event of transformedEvents) {
+                        await pluginManager.executeAfterSend(event);
+                    }
+                    return;
+                }
+                // Don't retry on client errors (4xx)
+                if (res.status >= 400 && res.status < 500) {
+                    const errorText = await res.text().catch(() => 'Unknown error');
+                    logger.warn(`Client error (${res.status}): ${errorText}`);
+                    // Record metrics
+                    if (this.config.enableMetrics) {
+                        const error = new Error(`Client error: ${errorText}`);
+                        for (let i = 0; i < transformedEvents.length; i++) {
+                            metricsCollector.recordFailed(error);
+                        }
+                    }
+                    return;
+                }
+                // Retry on server errors (5xx) or network errors
+                if (attempt < maxRetries) {
+                    const delay = retryDelay * Math.pow(2, attempt); // Exponential backoff
+                    logger.debug(`Retry ${attempt + 1}/${maxRetries} after ${delay}ms`);
+                    if (this.config.enableMetrics) {
+                        metricsCollector.recordRetry();
+                    }
+                    await this.sleep(delay);
+                }
+                else {
+                    const errorText = await res.text().catch(() => 'Unknown error');
+                    const error = new Error(`Failed after ${maxRetries} retries: ${errorText}`);
+                    // Record metrics
+                    if (this.config.enableMetrics) {
+                        for (let i = 0; i < transformedEvents.length; i++) {
+                            metricsCollector.recordFailed(error);
+                        }
+                    }
+                    // Execute onError hooks
+                    for (const event of transformedEvents) {
+                        await pluginManager.executeOnError(event, error);
+                    }
+                    throw error;
+                }
+            }
+            catch (err) {
+                // Network error - retry if attempts remaining
+                if (attempt < maxRetries) {
+                    const delay = retryDelay * Math.pow(2, attempt);
+                    logger.debug(`Network error, retry ${attempt + 1}/${maxRetries} after ${delay}ms`);
+                    if (this.config.enableMetrics) {
+                        metricsCollector.recordRetry();
+                    }
+                    await this.sleep(delay);
+                }
+                else {
+                    logger.error(`Failed to send batch after ${maxRetries} retries:`, err);
+                    // Record metrics
+                    if (this.config.enableMetrics) {
+                        const error = err instanceof Error ? err : new Error(String(err));
+                        for (let i = 0; i < transformedEvents.length; i++) {
+                            metricsCollector.recordFailed(error);
+                        }
+                    }
+                    // Execute onError hooks
+                    const error = err instanceof Error ? err : new Error(String(err));
+                    for (const event of transformedEvents) {
+                        await pluginManager.executeOnError(event, error);
+                    }
+                    throw err;
+                }
+            }
+        }
+    }
+    /**
+     * Sleep utility for retry delays
+     */
+    static sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
     /**
      * Track user journey/analytics event
+     * Events are automatically queued and batched
      */
     static async trackEvent(event) {
         const payload = {
@@ -1224,23 +1971,22 @@ class AnalyticsService {
             timestamp: new Date(),
             eventId: this.generateEventId(),
         };
-        try {
-            const res = await fetch(this.apiEndpoint, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                keepalive: true, // Allows sending during unload on some browsers
-                body: JSON.stringify(payload),
-            });
-            if (!res.ok) {
-                console.warn('[Analytics] Send failed:', await res.text());
-            }
-            else if (typeof process !== 'undefined' && process.env?.NODE_ENV === 'development') {
-                console.log('[Analytics] Event sent successfully');
+        // If queue is available, use it (browser environment)
+        if (this.queueManager && typeof window !== 'undefined') {
+            this.queueManager.enqueue(payload);
+            // Record metrics
+            if (this.config.enableMetrics) {
+                metricsCollector.recordQueued();
+                metricsCollector.updateQueueSize(this.queueManager.getQueueSize());
             }
+            return;
+        }
+        // Fallback: send immediately (SSR or queue not initialized)
+        try {
+            await this.sendBatch([payload]);
         }
         catch (err) {
-            // Don't break user experience - silently fail
-            console.warn('[Analytics] Failed to send event:', err);
+            logger.warn('Failed to send event:', err);
         }
     }
     /**
@@ -1369,8 +2115,123 @@ class AnalyticsService {
             ...parameters,
         });
     }
+    /**
+     * Manually flush the event queue
+     * Useful for ensuring events are sent before page unload
+     */
+    static async flushQueue() {
+        if (this.queueManager) {
+            await this.queueManager.flush();
+        }
+    }
+    /**
+     * Get current queue size
+     */
+    static getQueueSize() {
+        return this.queueManager?.getQueueSize() ?? 0;
+    }
+    /**
+     * Clear the event queue
+     */
+    static clearQueue() {
+        this.queueManager?.clear();
+        if (this.config.enableMetrics) {
+            metricsCollector.updateQueueSize(0);
+        }
+    }
+    /**
+     * Get metrics (if enabled)
+     */
+    static getMetrics() {
+        if (!this.config.enableMetrics) {
+            logger.warn('Metrics collection is not enabled. Set enableMetrics: true in config.');
+            return null;
+        }
+        return metricsCollector.getMetrics();
+    }
 }
 AnalyticsService.apiEndpoint = '/api/analytics';
+AnalyticsService.queueManager = null;
+AnalyticsService.config = {};
+AnalyticsService.isInitialized = false;
+
+/**
+ * Debug utilities for analytics tracker
+ * Provides debugging tools in development mode
+ */
+/**
+ * Initialize debug utilities (only in development)
+ */
+function initDebug() {
+    if (typeof window === 'undefined')
+        return;
+    const isDevelopment = typeof process !== 'undefined' &&
+        process.env?.NODE_ENV === 'development';
+    if (!isDevelopment) {
+        return;
+    }
+    const debug = {
+        /**
+         * Get current queue state
+         */
+        getQueue: () => {
+            const queueManager = AnalyticsService.getQueueManager();
+            if (!queueManager) {
+                logger.warn('Queue manager not initialized');
+                return [];
+            }
+            return queueManager.getQueue();
+        },
+        /**
+         * Get queue size
+         */
+        getQueueSize: () => {
+            return AnalyticsService.getQueueSize();
+        },
+        /**
+         * Manually flush the queue
+         */
+        flushQueue: async () => {
+            logger.info('Manually flushing queue...');
+            await AnalyticsService.flushQueue();
+            logger.info('Queue flushed');
+        },
+        /**
+         * Clear the queue
+         */
+        clearQueue: () => {
+            logger.info('Clearing queue...');
+            AnalyticsService.clearQueue();
+            logger.info('Queue cleared');
+        },
+        /**
+         * Get debug statistics
+         */
+        getStats: () => {
+            const queueManager = AnalyticsService.getQueueManager();
+            const metrics = AnalyticsService.getMetrics();
+            return {
+                queueSize: AnalyticsService.getQueueSize(),
+                queue: queueManager?.getQueue() ?? [],
+                config: {
+                    metrics: metrics,
+                    metricsSummary: metrics ? metricsCollector.getSummary() : 'Metrics disabled',
+                },
+            };
+        },
+        /**
+         * Set log level
+         */
+        setLogLevel: (level) => {
+            logger.setLevel(level);
+            logger.info(`Log level set to: ${level}`);
+        },
+    };
+    // Expose to window for console access
+    window.__analyticsDebug = debug;
+    logger.info('Analytics debug tools available at window.__analyticsDebug');
+    logger.info('Available methods: getQueue(), getQueueSize(), flushQueue(), clearQueue(), getStats(), setLogLevel()');
+}
 
 /**
  * React Hook for Analytics Tracking
@@ -1392,9 +2253,29 @@ function useAnalytics(options = {}) {
     // Configure analytics service if endpoint provided
     useEffect(() => {
         if (config?.apiEndpoint) {
-            AnalyticsService.configure({ apiEndpoint: config.apiEndpoint });
+            AnalyticsService.configure({
+                apiEndpoint: config.apiEndpoint,
+                batchSize: config.batchSize,
+                batchInterval: config.batchInterval,
+                maxQueueSize: config.maxQueueSize,
+                maxRetries: config.maxRetries,
+                retryDelay: config.retryDelay,
+                logLevel: config.logLevel,
+                enableMetrics: config.enableMetrics,
+                sessionTimeout: config.sessionTimeout,
+            });
         }
-    }, [config?.apiEndpoint]);
+    }, [
+        config?.apiEndpoint,
+        config?.batchSize,
+        config?.batchInterval,
+        config?.maxQueueSize,
+        config?.maxRetries,
+        config?.retryDelay,
+        config?.logLevel,
+        config?.enableMetrics,
+        config?.sessionTimeout,
+    ]);
     const [networkInfo, setNetworkInfo] = useState(null);
     const [deviceInfo, setDeviceInfo] = useState(null);
     const [attribution, setAttribution] = useState(null);
@@ -1419,6 +2300,10 @@ function useAnalytics(options = {}) {
             };
         }
     }, []);
+    // Initialize debug tools in development
+    useEffect(() => {
+        initDebug();
+    }, []);
     const refresh = useCallback(async () => {
         const net = NetworkDetector.detect();
         const dev = await DeviceDetector.detect();
@@ -1617,6 +2502,17 @@ function useAnalytics(options = {}) {
     const incrementInteraction = useCallback(() => {
         setInteractions((n) => n + 1);
     }, []);
+    // Session management
+    useEffect(() => {
+        if (config?.sessionTimeout) {
+            getOrCreateSession(config.sessionTimeout);
+            // Update session activity on user interactions
+            const activityInterval = setInterval(() => {
+                updateSessionActivity();
+            }, 60000); // Update every minute
+            return () => clearInterval(activityInterval);
+        }
+    }, [config?.sessionTimeout]);
     return useMemo(() => ({
         sessionId,
         networkInfo,
@@ -1807,5 +2703,5 @@ function getIPFromRequest(req) {
     return '0.0.0.0';
 }
 
-export { AnalyticsService, AttributionDetector, DeviceDetector, LocationDetector, NetworkDetector, checkAndSetLocationConsent, clearLocationConsent, useAnalytics as default, getIPFromRequest, getIPLocation, getLocationConsentTimestamp, getOrCreateUserId, getPublicIP, hasLocationConsent, loadJSON, loadSessionJSON, saveJSON, saveSessionJSON, setLocationConsentGranted, trackPageVisit, useAnalytics };
+export { AnalyticsService, AttributionDetector, DeviceDetector, LocationDetector, NetworkDetector, QueueManager, checkAndSetLocationConsent, clearLocationConsent, clearSession, useAnalytics as default, getIPFromRequest, getIPLocation, getLocationConsentTimestamp, getOrCreateSession, getOrCreateUserId, getPublicIP, getSession, hasLocationConsent, initDebug, loadJSON, loadSessionJSON, logger, saveJSON, saveSessionJSON, setLocationConsentGranted, trackPageVisit, updateSessionActivity, useAnalytics };
 //# sourceMappingURL=index.esm.js.map