user-analytics-tracker 1.7.0 → 2.0.0

package/dist/index.d.ts

@@ -83,6 +83,7 @@ interface IPLocation {
     as?: string;
     query?: string;
 }
+type LogLevel$1 = 'silent' | 'error' | 'warn' | 'info' | 'debug';
 interface AnalyticsConfig {
     apiEndpoint: string;
     autoSend?: boolean;
@@ -93,6 +94,14 @@ interface AnalyticsConfig {
     enableAttribution?: boolean;
     sessionStoragePrefix?: string;
     localStoragePrefix?: string;
+    batchSize?: number;
+    batchInterval?: number;
+    maxQueueSize?: number;
+    maxRetries?: number;
+    retryDelay?: number;
+    sessionTimeout?: number;
+    logLevel?: LogLevel$1;
+    enableMetrics?: boolean;
 }
 interface AnalyticsEvent {
     sessionId: string;
@@ -198,44 +207,175 @@ declare class AttributionDetector {
     private static getDefaultAttribution;
 }
 
+/**
+ * Metrics collection for analytics tracker
+ * Tracks performance and usage statistics
+ */
+interface AnalyticsMetrics {
+    eventsSent: number;
+    eventsQueued: number;
+    eventsFailed: number;
+    eventsFiltered: number;
+    averageSendTime: number;
+    retryCount: number;
+    queueSize: number;
+    lastFlushTime: number | null;
+    errors: Array<{
+        timestamp: number;
+        error: string;
+    }>;
+}
+
+/**
+ * Queue Manager for Analytics Events
+ * Handles batching, persistence, and offline support
+ */
+
+interface QueuedEvent {
+    event: AnalyticsEvent;
+    retries: number;
+    timestamp: number;
+    id: string;
+}
+interface QueueConfig {
+    batchSize: number;
+    batchInterval: number;
+    maxQueueSize: number;
+    storageKey: string;
+}
+declare class QueueManager {
+    private queue;
+    private flushTimer;
+    private isFlushing;
+    private config;
+    private flushCallback;
+    constructor(config: QueueConfig);
+    /**
+     * Set the callback function to flush events
+     */
+    setFlushCallback(callback: (events: AnalyticsEvent[]) => Promise<void>): void;
+    /**
+     * Add an event to the queue
+     */
+    enqueue(event: AnalyticsEvent): boolean;
+    /**
+     * Flush events from the queue
+     */
+    flush(): Promise<void>;
+    /**
+     * Get current queue size
+     */
+    getQueueSize(): number;
+    /**
+     * Get all queued events (for debugging)
+     */
+    getQueue(): QueuedEvent[];
+    /**
+     * Clear the queue
+     */
+    clear(): void;
+    /**
+     * Load queue from localStorage
+     */
+    private loadFromStorage;
+    /**
+     * Save queue to localStorage
+     */
+    private saveToStorage;
+    /**
+     * Start auto-flush timer
+     */
+    private startAutoFlush;
+    /**
+     * Setup page unload handler to flush events
+     */
+    private setupPageUnloadHandler;
+    /**
+     * Get endpoint for sendBeacon
+     */
+    private getEndpointFromCallback;
+    /**
+     * Update storage key (for configuration changes)
+     */
+    updateConfig(config: Partial<QueueConfig>): void;
+    /**
+     * Cleanup resources
+     */
+    destroy(): void;
+}
+
 /**
  * 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
  */
 declare class AnalyticsService {
     private static apiEndpoint;
+    private static queueManager;
+    private static config;
+    private static isInitialized;
     /**
-     * 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: {
+    static configure(config: Partial<AnalyticsConfig> & {
         apiEndpoint: string;
     }): void;
+    /**
+     * Initialize the queue manager
+     */
+    private static initializeQueue;
+    /**
+     * Get queue manager instance
+     */
+    static getQueueManager(): QueueManager | null;
     /**
      * Generate a random event ID
      */
     private static generateEventId;
+    /**
+     * Send a batch of events with retry logic
+     */
+    private static sendBatch;
+    /**
+     * Sleep utility for retry delays
+     */
+    private static sleep;
     /**
      * Track user journey/analytics event
+     * Events are automatically queued and batched
      */
     static trackEvent(event: Omit<AnalyticsEvent, 'eventId' | 'timestamp'>): Promise<void>;
     /**
@@ -308,6 +448,23 @@ declare class AnalyticsService {
      * ```
      */
     static trackPageView(pageName?: string, parameters?: Record<string, any>): Promise<void>;
+    /**
+     * Manually flush the event queue
+     * Useful for ensuring events are sent before page unload
+     */
+    static flushQueue(): Promise<void>;
+    /**
+     * Get current queue size
+     */
+    static getQueueSize(): number;
+    /**
+     * Clear the event queue
+     */
+    static clearQueue(): void;
+    /**
+     * Get metrics (if enabled)
+     */
+    static getMetrics(): AnalyticsMetrics | null;
 }
 
 interface UseAnalyticsOptions {
@@ -349,6 +506,36 @@ declare function getOrCreateUserId(length?: number): string;
  * Track page visits with localStorage
  */
 declare function trackPageVisit(): number;
+/**
+ * Session management utilities
+ */
+interface SessionInfo {
+    sessionId: string;
+    startTime: number;
+    lastActivity: number;
+    pageViews: number;
+}
+/**
+ * Get or create a session
+ */
+declare function getOrCreateSession(timeout?: number): SessionInfo;
+/**
+ * Update session activity
+ */
+declare function updateSessionActivity(): void;
+/**
+ * Get current session info
+ */
+declare function getSession(): SessionInfo | null;
+/**
+ * Clear session
+ */
+declare function clearSession(): void;
+
+/**
+ * Initialize debug utilities (only in development)
+ */
+declare function initDebug(): void;
 
 /**
  * Location Consent Manager
@@ -411,5 +598,24 @@ declare function getIPLocation(ip: string): Promise<IPLocation | null>;
  */
 declare function getIPFromRequest(req: Request | any): string;
 
-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 type { AnalyticsConfig, AnalyticsEvent, AttributionInfo, DeviceInfo, DeviceType, IPLocation, LocationInfo, NetworkInfo, NetworkType, UseAnalyticsOptions, UseAnalyticsReturn };
+/**
+ * Logger utility for analytics tracker
+ * Provides configurable logging levels for development and production
+ */
+type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+declare class Logger {
+    private level;
+    private isDevelopment;
+    constructor();
+    setLevel(level: LogLevel): void;
+    getLevel(): LogLevel;
+    private shouldLog;
+    error(message: string, ...args: any[]): void;
+    warn(message: string, ...args: any[]): void;
+    info(message: string, ...args: any[]): void;
+    debug(message: string, ...args: any[]): void;
+}
+declare const logger: Logger;
+
+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 };
+export type { AnalyticsConfig, AnalyticsEvent, AttributionInfo, DeviceInfo, DeviceType, IPLocation, LocationInfo, LogLevel$1 as LogLevel, NetworkInfo, NetworkType, QueueConfig, QueuedEvent, SessionInfo, UseAnalyticsOptions, UseAnalyticsReturn };