user-analytics-tracker 1.7.0 → 2.1.0

package/dist/index.d.ts

@@ -68,21 +68,53 @@ interface AttributionInfo {
     firstTouch?: Record<string, string | null> | null;
     lastTouch?: Record<string, string | null> | null;
 }
-interface IPLocation {
+interface IPLocation extends Record<string, any> {
     ip: string;
+    success?: boolean;
+    type?: string;
+    continent?: string;
+    continent_code?: string;
     country?: string;
-    countryCode?: string;
+    country_code?: string;
     region?: string;
-    regionName?: string;
+    region_code?: string;
     city?: string;
+    latitude?: number;
+    longitude?: number;
+    is_eu?: boolean;
+    postal?: string;
+    calling_code?: string;
+    capital?: string;
+    borders?: string;
+    flag?: {
+        img?: string;
+        emoji?: string;
+        emoji_unicode?: string;
+    };
+    connection?: {
+        asn?: number;
+        org?: string;
+        isp?: string;
+        domain?: string;
+    };
+    timezone?: {
+        id?: string;
+        abbr?: string;
+        is_dst?: boolean;
+        offset?: number;
+        utc?: string;
+        current_time?: string;
+    };
+    countryCode?: string;
+    regionName?: string;
     lat?: number;
     lon?: number;
-    timezone?: string;
     isp?: string;
     org?: string;
     as?: string;
     query?: string;
 }
+type LogLevel$1 = 'silent' | 'error' | 'warn' | 'info' | 'debug';
 interface AnalyticsConfig {
     apiEndpoint: string;
     autoSend?: boolean;
@@ -93,6 +125,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;
@@ -180,7 +220,8 @@ declare class LocationDetector {
     /**
      * Get location from IP-based public API (client-side)
      * Works without user permission, good fallback when GPS is unavailable
-     * Uses ip-api.com free tier (no API key required, 45 requests/minute)
+     * Uses ipwho.is API (no API key required)
+     * Stores all keys dynamically from the API response
      */
     private static getIPBasedLocation;
     /**
@@ -198,44 +239,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 +480,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 +538,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
@@ -380,11 +599,14 @@ declare function checkAndSetLocationConsent(msisdn?: string | null): boolean;
 /**
  * IP Geolocation Service
  * Fetches location data (country, region, city) from user's IP address
- * Uses free tier of ip-api.com (no API key required, 45 requests/minute)
+ * Uses ipwho.is API (no API key required)
+ *
+ * Stores all keys dynamically from the API response, including nested objects
+ * This ensures we capture all available data and any new fields added by the API
  */
 /**
- * Get public IP address using ip-api.com
- * Free tier: 45 requests/minute, no API key required
+ * Get public IP address using ipwho.is API
+ * No API key required
  *
  * @returns Promise<string | null> - The public IP address, or null if unavailable
  *
@@ -396,13 +618,11 @@ declare function checkAndSetLocationConsent(msisdn?: string | null): boolean;
  */
 declare function getPublicIP(): Promise<string | null>;
 /**
- * Get location from IP address using ip-api.com
- * Free tier: 45 requests/minute, no API key required
+ * Get location from IP address using ipwho.is API
+ * Free tier: No API key required
  *
- * Alternative services:
- * - ipapi.co (requires API key for production)
- * - ipgeolocation.io (requires API key)
- * - ip-api.com (free tier available)
+ * Stores all keys dynamically from the API response, including nested objects
+ * This ensures we capture all available data and any new fields added by the API
  */
 declare function getIPLocation(ip: string): Promise<IPLocation | null>;
 /**
@@ -411,5 +631,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 };