user-analytics-tracker 4.1.2 → 4.3.0

package/dist/index.cjs.js

@@ -4,6 +4,7 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 var react = require('react');
 
+/* eslint-disable @typescript-eslint/no-explicit-any */
 /**
  * Core types for the analytics tracker package
  */
@@ -14,16 +15,11 @@ var react = require('react');
 const DEFAULT_ESSENTIAL_IP_FIELDS = [
     // Core identification
     'ip',
-    'country',
     'countryCode',
-    'region',
     'city',
     // Geographic coordinates (stored here, not duplicated in location)
     'lat',
     'lon',
-    // Additional geographic info
-    'continent',
-    'continentCode',
     // Network info
     'type',
     'isEu',
@@ -33,27 +29,14 @@ const DEFAULT_ESSENTIAL_IP_FIELDS = [
     'connection.org',
     'connection.isp',
     'connection.domain',
-    // Timezone (stored here, not duplicated in location)
-    'timezone',
-    'timezoneDetails',
-    'timezoneDetails.id',
-    'timezoneDetails.abbr',
-    'timezoneDetails.utc',
-    // Flag (only emoji in essential mode)
-    'flag.emoji',
 ];
 /**
  * Default essential fields for Device Info storage
+ * In essential mode, only OS and browser are stored
  */
 const DEFAULT_ESSENTIAL_DEVICE_FIELDS = [
-    'type',
     'os',
-    'osVersion',
     'browser',
-    'browserVersion',
-    'deviceModel',
-    'deviceBrand',
-    'userAgent',
 ];
 /**
  * Default essential fields for Network Info storage
@@ -86,17 +69,6 @@ const DEFAULT_ESSENTIAL_LOCATION_FIELDS = [
 const DEFAULT_ESSENTIAL_ATTRIBUTION_FIELDS = [
     'landingUrl',
     'path',
-    'hostname',
-    'referrerUrl',
-    'referrerDomain',
-    'navigationType',
-    'isReload',
-    'isBackForward',
-    'utm_source',
-    'utm_medium',
-    'utm_campaign',
-    'utm_term',
-    'utm_content',
 ];
 
 /**
@@ -149,7 +121,7 @@ class NetworkDetector {
             const downlink = c.downlink || 0;
             const rtt = c.rtt || 0;
             const saveData = c.saveData || false;
-            c.effectiveType?.toLowerCase() || '';
+            // const effectiveType = c.effectiveType?.toLowerCase() || ''; // Reserved for future use
             const isMobileDevice = /Android|iPhone|iPad|iPod/i.test(navigator.userAgent);
             const isDesktop = !isMobileDevice;
             // Data saver mode strongly suggests cellular
@@ -564,6 +536,7 @@ var deviceDetector = /*#__PURE__*/Object.freeze({
     DeviceDetector: DeviceDetector
 });
 
+/* eslint-disable no-console */
 /**
  * Location Consent Manager
  * When user enters MSISDN, they implicitly consent to location tracking
@@ -643,44 +616,53 @@ function checkAndSetLocationConsent(msisdn) {
     return false;
 }
 
-/**
- * IP Geolocation Service
- * Fetches location data (country, region, city) from user's IP address
- * 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 complete IP location data from ipwho.is API (HIGH PRIORITY)
  * This is the primary method - gets IP, location, connection, and all data in one call
- * No API key required
  *
+ * @param config - Optional configuration for API key and base URL
  * @returns Promise<IPLocation | null> - Complete IP location data, or null if unavailable
  *
  * @example
  * ```typescript
+ * // Without API key (free tier)
  * const location = await getCompleteIPLocation();
- * console.log('IP:', location?.ip);
- * console.log('Country:', location?.country);
- * console.log('ISP:', location?.connection?.isp);
+ *
+ * // With API key (for higher rate limits)
+ * const location = await getCompleteIPLocation({
+ *   apiKey: '<your-api-key>',
+ *   baseUrl: 'https://ipwho.is'
+ * });
  * ```
  */
-async function getCompleteIPLocation() {
+async function getCompleteIPLocation(config) {
     // Skip if we're in an environment without fetch (SSR)
     if (typeof fetch === 'undefined') {
         return null;
     }
+    // Use provided config or defaults
+    const baseUrl = config?.baseUrl || 'https://ipwho.is';
+    const timeout = config?.timeout || 5000;
+    const apiKey = config?.apiKey;
     try {
+        // Build URL with optional API key
+        let url = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+        // Add API key as query parameter if provided
+        if (apiKey) {
+            url += `?key=${encodeURIComponent(apiKey)}`;
+        }
+        else {
+            url += '/';
+        }
         // Call ipwho.is without IP parameter - it auto-detects user's IP and returns everything
         // This is the HIGH PRIORITY source - gets IP, location, connection, timezone, flag, etc. in one call
-        const response = await fetch('https://ipwho.is/', {
+        const response = await fetch(url, {
             method: 'GET',
             headers: {
                 Accept: 'application/json',
             },
             // Add timeout to prevent hanging
-            signal: AbortSignal.timeout(5000),
+            signal: AbortSignal.timeout(timeout),
         });
         if (!response.ok) {
             return null;
@@ -742,6 +724,7 @@ async function getCompleteIPLocation() {
  * This is kept for backward compatibility and as a fallback
  * Prefer getCompleteIPLocation() which gets everything in one call
  *
+ * @param config - Optional configuration for API key and base URL
  * @returns Promise<string | null> - The public IP address, or null if unavailable
  *
  * @example
@@ -750,20 +733,31 @@ async function getCompleteIPLocation() {
  * console.log('Your IP:', ip); // e.g., "203.0.113.42"
  * ```
  */
-async function getPublicIP() {
+async function getPublicIP(config) {
     // Try to get complete location first (includes IP)
-    const completeLocation = await getCompleteIPLocation();
+    const completeLocation = await getCompleteIPLocation(config);
     if (completeLocation?.ip) {
         return completeLocation.ip;
     }
     // Fallback: try direct IP fetch (less efficient, lower priority)
     try {
-        const response = await fetch('https://ipwho.is/', {
+        const baseUrl = config?.baseUrl || 'https://ipwho.is';
+        const timeout = config?.timeout || 5000;
+        const apiKey = config?.apiKey;
+        // Build URL with optional API key
+        let url = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+        if (apiKey) {
+            url += `?key=${encodeURIComponent(apiKey)}`;
+        }
+        else {
+            url += '/';
+        }
+        const response = await fetch(url, {
             method: 'GET',
             headers: {
                 Accept: 'application/json',
             },
-            signal: AbortSignal.timeout(5000),
+            signal: AbortSignal.timeout(timeout),
         });
         if (!response.ok) {
             return null;
@@ -783,14 +777,28 @@ async function getPublicIP() {
 }
 /**
  * Get location from IP address using ipwho.is API (HIGH PRIORITY)
- * Free tier: 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
  *
+ * @param ip - IP address to geolocate
+ * @param config - Optional configuration for API key and base URL
+ * @returns Promise<IPLocation | null> - IP location data, or null if unavailable
+ *
+ * @example
+ * ```typescript
+ * // Without API key
+ * const location = await getIPLocation('203.0.113.42');
+ *
+ * // With API key
+ * const location = await getIPLocation('203.0.113.42', {
+ *   apiKey: '<your-api-key>'
+ * });
+ * ```
+ *
  * Note: If you don't have an IP yet, use getCompleteIPLocation() which gets everything in one call
  */
-async function getIPLocation(ip) {
+async function getIPLocation(ip, config) {
     // Skip localhost/private IPs (these can't be geolocated)
     if (!ip ||
         ip === '0.0.0.0' ||
@@ -804,14 +812,25 @@ async function getIPLocation(ip) {
         return null;
     }
     try {
-        // Using ipwho.is API (no API key required)
-        const response = await fetch(`https://ipwho.is/${ip}`, {
+        // Use provided config or defaults
+        const baseUrl = config?.baseUrl || 'https://ipwho.is';
+        const timeout = config?.timeout || 5000;
+        const apiKey = config?.apiKey;
+        // Build URL with IP and optional API key
+        let url = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+        url += `/${ip}`;
+        // Add API key as query parameter if provided
+        if (apiKey) {
+            url += `?key=${encodeURIComponent(apiKey)}`;
+        }
+        // Using ipwho.is API
+        const response = await fetch(url, {
             method: 'GET',
             headers: {
                 Accept: 'application/json',
             },
             // Add timeout to prevent hanging
-            signal: AbortSignal.timeout(5000),
+            signal: AbortSignal.timeout(timeout),
         });
         if (!response.ok) {
             console.warn(`[IP Geolocation] Failed to fetch location for IP ${ip}: ${response.status}`);
@@ -920,6 +939,23 @@ function getIPFromRequest(req) {
  * IP-based location works automatically without user permission
  */
 class LocationDetector {
+    /**
+     * Configure IP geolocation settings (API key, base URL, timeout)
+     *
+     * @param config - IP geolocation configuration
+     *
+     * @example
+     * ```typescript
+     * LocationDetector.configureIPGeolocation({
+     *   apiKey: '<your-ipwho-is-api-key>',
+     *   baseUrl: 'https://ipwho.is',
+     *   timeout: 5000
+     * });
+     * ```
+     */
+    static configureIPGeolocation(config) {
+        this.ipGeolocationConfig = config;
+    }
     /**
      * Detect location using IP-based API only (no GPS, no permission needed)
      * Fast and automatic - works immediately without user interaction
@@ -1218,14 +1254,15 @@ class LocationDetector {
             // HIGH PRIORITY: Get complete IP location data from ipwho.is in one call
             // This gets IP, location, connection, timezone, flag, and all other data at once
             // More efficient than making separate calls
-            let ipLocation = await getCompleteIPLocation();
+            // Use configured API key and settings if available
+            let ipLocation = await getCompleteIPLocation(this.ipGeolocationConfig || undefined);
             // If complete location fetch failed, try fallback: get IP first, then location
             if (!ipLocation) {
                 console.log('[Location] Primary ipwho.is call failed, trying fallback...');
-                const publicIP = await getPublicIP();
+                const publicIP = await getPublicIP(this.ipGeolocationConfig || undefined);
                 if (publicIP) {
                     // Fallback: Get location from IP using ipwho.is API
-                    ipLocation = await getIPLocation(publicIP);
+                    ipLocation = await getIPLocation(publicIP, this.ipGeolocationConfig || undefined);
                 }
             }
             if (!ipLocation) {
@@ -1301,6 +1338,7 @@ LocationDetector.lastLocationRef = { current: null };
 LocationDetector.locationConsentLoggedRef = { current: false };
 LocationDetector.ipLocationFetchingRef = { current: false };
 LocationDetector.lastIPLocationRef = { current: null };
+LocationDetector.ipGeolocationConfig = null;
 
 var locationDetector = /*#__PURE__*/Object.freeze({
     __proto__: null,
@@ -1411,7 +1449,7 @@ function getOrCreateSession(timeout = DEFAULT_SESSION_TIMEOUT) {
         return updated;
     }
     // Create new session
-    const sessionId = `session-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+    const sessionId = `session-${Date.now()}-${getSecureRandomString(16)}`;
     const newSession = {
         sessionId,
         startTime: now,
@@ -1455,6 +1493,25 @@ function clearSession() {
         // Silently fail
     }
 }
+/**
+ * Generate a cryptographically secure random string.
+ * Length is the number of bytes, which are hex-encoded (2 chars per byte).
+ */
+function getSecureRandomString(length) {
+    if (typeof window !== 'undefined' && window.crypto && window.crypto.getRandomValues) {
+        const bytes = new Uint8Array(length);
+        window.crypto.getRandomValues(bytes);
+        let result = '';
+        for (let i = 0; i < bytes.length; i++) {
+            const hex = bytes[i].toString(16).padStart(2, '0');
+            result += hex;
+        }
+        return result;
+    }
+    // Fallback to a less secure method only if crypto is unavailable.
+    // This should be rare in modern browsers.
+    return Math.random().toString(36).substring(2, 2 + length);
+}
 
 var storage = /*#__PURE__*/Object.freeze({
     __proto__: null,
@@ -1616,6 +1673,7 @@ var attributionDetector = /*#__PURE__*/Object.freeze({
     AttributionDetector: AttributionDetector
 });
 
+/* eslint-disable no-console, @typescript-eslint/no-explicit-any */
 /**
  * Logger utility for analytics tracker
  * Provides configurable logging levels for development and production
@@ -1666,6 +1724,7 @@ class Logger {
 }
 const logger = new Logger();
 
+/* eslint-disable @typescript-eslint/no-explicit-any */
 /**
  * Queue Manager for Analytics Events
  * Handles batching, persistence, and offline support
@@ -1831,7 +1890,7 @@ class QueueManager {
                         navigator.sendBeacon(this.getEndpointFromCallback(), blob);
                         this.saveToStorage();
                     }
-                    catch (error) {
+                    catch {
                         // Fallback: put events back in queue
                         this.queue.unshift(...events.map((e) => ({
                             event: e,
@@ -2100,6 +2159,7 @@ class MetricsCollector {
 // Global metrics collector instance
 const metricsCollector = new MetricsCollector();
 
+/* eslint-disable @typescript-eslint/no-explicit-any */
 /**
  * Generic field storage transformer
  * Filters object fields based on storage configuration
@@ -2196,6 +2256,11 @@ function filterFieldsByConfig(data, config, defaultEssentialFields) {
             filtered[key] = data[key];
         }
     });
+    // If no fields were included, return null (not empty object)
+    // This helps distinguish between "no data" and "filtered out all fields"
+    if (Object.keys(filtered).length === 0) {
+        return null;
+    }
     // Handle nested objects - only create if at least one child field is included
     if (data.connection && shouldIncludeParent('connection')) {
         filtered.connection = {};
@@ -2298,6 +2363,12 @@ function transformIPLocationForBackend(ipLocation, config) {
     if (!ipLocation) {
         return null;
     }
+    // If ipLocation is a simple object with just ip, preserve it for validation
+    // Skip transformation and filtering to ensure ip is always preserved
+    if (ipLocation.ip && Object.keys(ipLocation).length === 1) {
+        // Return object with ip directly (ip is essential field, always preserved)
+        return { ip: ipLocation.ip };
+    }
     // Transform to match backend expected format (camelCase)
     // Build complete object first, then filter based on configuration
     const transformed = {
@@ -2358,6 +2429,194 @@ function transformIPLocationForBackend(ipLocation, config) {
     return filterFieldsByConfig(transformed, config, DEFAULT_ESSENTIAL_IP_FIELDS);
 }
 
+/**
+ * Extract required fields from analytics event
+ */
+function extractRequiredFields(event) {
+    // Extract IP from ipLocation or location or customData.ipLocation
+    const ip = event.ipLocation?.ip ||
+        event.location?.ip ||
+        event.customData?.ipLocation?.ip ||
+        null;
+    // Extract lat/lon from location or ipLocation
+    const lat = event.location?.lat || event.ipLocation?.latitude || event.ipLocation?.lat || null;
+    const lon = event.location?.lon || event.ipLocation?.longitude || event.ipLocation?.lon || null;
+    // Extract mobile status
+    const mobile = event.deviceInfo?.type === 'mobile' ? true : event.deviceInfo?.type ? false : null;
+    // Extract location (city - country removed in essential mode)
+    const location = event.ipLocation?.city ||
+        event.location?.city ||
+        event.ipLocation?.country ||
+        event.location?.country ||
+        null;
+    // Extract msisdn from customData
+    const msisdn = event.customData?.msisdn || null;
+    // Session ID
+    const session = event.sessionId || null;
+    // Extract operator/ISP
+    const operators = event.ipLocation?.connection?.isp ||
+        event.ipLocation?.connection?.org ||
+        null;
+    // Extract page name from URL
+    const pageUrl = event.pageUrl || null;
+    let page = null;
+    if (pageUrl) {
+        try {
+            page = new URL(pageUrl).pathname;
+        }
+        catch {
+            // If URL parsing fails, try to extract pathname manually
+            const match = pageUrl.match(/^https?:\/\/[^/]+(\/.*)?$/);
+            page = match ? (match[1] || '/') : null;
+        }
+    }
+    // Event type
+    const eventType = event.eventName || 'page_view';
+    // Company name from customData
+    const companyName = event.customData?.companyName || null;
+    // Event ID
+    const eventId = event.eventId || null;
+    // Timestamp
+    const timestamp = event.timestamp || null;
+    // GPS source check
+    const gps = event.location?.source === 'gps' ? true :
+        (event.location?.source === 'ip' ? false : null);
+    // OS
+    const os = event.deviceInfo?.os || null;
+    // Browser
+    const browser = event.deviceInfo?.browser || null;
+    // Service ID
+    const serviceId = event.customData?.serviceId || null;
+    return {
+        ip,
+        lat,
+        lon,
+        mobile,
+        location,
+        msisdn,
+        session,
+        operators,
+        page,
+        pageUrl,
+        eventType,
+        companyName,
+        eventId,
+        timestamp,
+        gps,
+        os,
+        browser,
+        serviceId,
+    };
+}
+/**
+ * Validate that event has minimum required fields
+ * Returns true if valid, false if should be filtered out
+ */
+function validateRequiredFields(fields) {
+    // Must have at least one of: IP, or (lat AND lon)
+    const hasLocation = fields.ip || (fields.lat !== null && fields.lon !== null);
+    if (!hasLocation) {
+        return false;
+    }
+    // Must have session (non-empty string, not 'unknown')
+    if (!fields.session || fields.session === 'unknown' || fields.session.trim() === '') {
+        return false;
+    }
+    // Must have pageUrl (non-empty string)
+    if (!fields.pageUrl || fields.pageUrl.trim() === '') {
+        return false;
+    }
+    // Must have eventType
+    if (!fields.eventType) {
+        return false;
+    }
+    // Must have eventId
+    if (!fields.eventId) {
+        return false;
+    }
+    // Must have timestamp
+    if (!fields.timestamp) {
+        return false;
+    }
+    // Must have at least one of: mobile, OS, or browser
+    const hasDeviceInfo = fields.mobile !== null || fields.os || fields.browser;
+    if (!hasDeviceInfo) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Check if event has null values for critical fields
+ * Returns true if should be filtered out (too many nulls)
+ */
+function hasTooManyNulls(fields) {
+    // Only count non-critical fields for null percentage
+    // Critical fields (ip, lat, lon, session, pageUrl, eventType, eventId, timestamp) are already validated
+    const nonCriticalFields = ['mobile', 'location', 'msisdn', 'operators', 'page', 'companyName', 'gps', 'os', 'browser', 'serviceId'];
+    const nullCount = nonCriticalFields.filter(key => {
+        const value = fields[key];
+        return value === null || value === undefined;
+    }).length;
+    const totalNonCritical = nonCriticalFields.length;
+    const nullPercentage = totalNonCritical > 0 ? nullCount / totalNonCritical : 0;
+    // Filter out if more than 70% of non-critical fields are null (more lenient)
+    return nullPercentage > 0.7;
+}
+/**
+ * Validate and filter event
+ * Returns null if event should be filtered out, otherwise returns the event
+ */
+function validateEvent(event) {
+    const fields = extractRequiredFields(event);
+    // Check if has too many null values
+    if (hasTooManyNulls(fields)) {
+        logger.debug('Event filtered: too many null values', {
+            fields,
+            sessionId: event.sessionId,
+            pageUrl: event.pageUrl,
+            eventName: event.eventName,
+        });
+        return null;
+    }
+    // Check if has minimum required fields
+    if (!validateRequiredFields(fields)) {
+        logger.debug('Event filtered: missing required fields', {
+            fields,
+            sessionId: event.sessionId,
+            pageUrl: event.pageUrl,
+            eventName: event.eventName,
+            hasIP: !!fields.ip,
+            hasLatLon: fields.lat !== null && fields.lon !== null,
+            hasSession: !!fields.session,
+            hasPageUrl: !!fields.pageUrl,
+            hasEventType: !!fields.eventType,
+            hasEventId: !!fields.eventId,
+            hasTimestamp: !!fields.timestamp,
+            hasDeviceInfo: fields.mobile !== null || !!fields.os || !!fields.browser,
+        });
+        return null;
+    }
+    return event;
+}
+/**
+ * Generate a unique key for deduplication
+ * Based on: sessionId + pageUrl + eventName + timestamp (rounded to nearest second)
+ */
+function generateDeduplicationKey(event) {
+    const timestamp = event.timestamp instanceof Date
+        ? event.timestamp.getTime()
+        : new Date(event.timestamp).getTime();
+    // Round timestamp to nearest second to handle rapid duplicate events
+    const roundedTimestamp = Math.floor(timestamp / 1000) * 1000;
+    const parts = [
+        event.sessionId || '',
+        event.pageUrl || '',
+        event.eventName || 'page_view',
+        roundedTimestamp.toString(),
+    ];
+    return parts.join('|');
+}
+
 /**
  * Analytics Service
  * Sends analytics events to your backend API
@@ -2411,6 +2670,8 @@ class AnalyticsService {
             logLevel: 'warn',
             ...config,
         };
+        // Clear seen event keys when reconfiguring (important for tests)
+        this.seenEventKeys.clear();
         // Set log level
         if (this.config.logLevel) {
             logger.setLevel(this.config.logLevel);
@@ -2425,6 +2686,10 @@ class AnalyticsService {
         if (this.config.enableMetrics) {
             metricsCollector.reset();
         }
+        // Configure IP geolocation if provided
+        if (this.config.ipGeolocation) {
+            LocationDetector.configureIPGeolocation(this.config.ipGeolocation);
+        }
         this.isInitialized = true;
     }
     /**
@@ -2469,10 +2734,56 @@ class AnalyticsService {
     }
     /**
      * Send a batch of events with retry logic
+     * Filters out invalid and duplicate events before sending
      */
     static async sendBatch(events) {
-        if (events.length === 0)
+        // Validate and filter events
+        const validatedEvents = [];
+        const seenInBatch = new Set();
+        for (const event of events) {
+            // Validate event
+            const validated = validateEvent(event);
+            if (!validated) {
+                logger.debug('Event filtered out in batch: missing required fields', {
+                    sessionId: event.sessionId,
+                    pageUrl: event.pageUrl,
+                    hasIPLocation: !!event.ipLocation,
+                    hasIP: !!(event.ipLocation?.ip),
+                });
+                continue;
+            }
+            // Check for duplicates in this batch only
+            // Note: Events are already deduplicated when queued, so we only check within the batch
+            const dedupeKey = generateDeduplicationKey(validated);
+            if (seenInBatch.has(dedupeKey)) {
+                logger.debug('Duplicate event filtered out in batch', { dedupeKey });
+                continue;
+            }
+            // Add to seen events for this batch
+            seenInBatch.add(dedupeKey);
+            // Also add to global seen events cache (for cross-batch deduplication)
+            // But don't filter out if already seen - events from queue are already validated
+            if (!this.seenEventKeys.has(dedupeKey)) {
+                this.seenEventKeys.add(dedupeKey);
+                // Manage cache size
+                if (this.seenEventKeys.size > this.DEDUPE_CACHE_SIZE) {
+                    const firstKey = this.seenEventKeys.values().next().value;
+                    if (firstKey !== undefined) {
+                        this.seenEventKeys.delete(firstKey);
+                    }
+                }
+            }
+            validatedEvents.push(validated);
+        }
+        if (validatedEvents.length === 0) {
+            logger.debug('All events in batch were filtered out');
             return;
+        }
+        // Use validated events
+        if (validatedEvents.length === 0) {
+            return;
+        }
+        events = validatedEvents;
         // Apply plugin transformations
         const transformedEvents = [];
         for (const event of events) {
@@ -2592,6 +2903,7 @@ class AnalyticsService {
     /**
      * Track user journey/analytics event
      * Events are automatically queued and batched
+     * Duplicate events and events with null values are filtered out
      */
     static async trackEvent(event) {
         const payload = {
@@ -2599,9 +2911,39 @@ class AnalyticsService {
             timestamp: new Date(),
             eventId: this.generateEventId(),
         };
+        // Validate event - filter out if missing required fields or too many nulls
+        const validatedEvent = validateEvent(payload);
+        if (!validatedEvent) {
+            logger.debug('Event filtered out: missing required fields or too many null values', {
+                sessionId: payload.sessionId,
+                pageUrl: payload.pageUrl,
+                eventName: payload.eventName,
+            });
+            return;
+        }
+        // Check for duplicates
+        const dedupeKey = generateDeduplicationKey(validatedEvent);
+        if (this.seenEventKeys.has(dedupeKey)) {
+            logger.debug('Duplicate event filtered out', {
+                dedupeKey,
+                sessionId: validatedEvent.sessionId,
+                pageUrl: validatedEvent.pageUrl,
+                eventName: validatedEvent.eventName,
+            });
+            return;
+        }
+        // Add to seen events (with cache size limit)
+        this.seenEventKeys.add(dedupeKey);
+        if (this.seenEventKeys.size > this.DEDUPE_CACHE_SIZE) {
+            // Remove oldest entries (simple FIFO - remove first entry)
+            const firstKey = this.seenEventKeys.values().next().value;
+            if (firstKey !== undefined) {
+                this.seenEventKeys.delete(firstKey);
+            }
+        }
         // If queue is available, use it (browser environment)
         if (this.queueManager && typeof window !== 'undefined') {
-            this.queueManager.enqueue(payload);
+            this.queueManager.enqueue(validatedEvent);
             // Record metrics
             if (this.config.enableMetrics) {
                 metricsCollector.recordQueued();
@@ -2611,7 +2953,7 @@ class AnalyticsService {
         }
         // Fallback: send immediately (SSR or queue not initialized)
         try {
-            await this.sendBatch([payload]);
+            await this.sendBatch([validatedEvent]);
         }
         catch (err) {
             logger.warn('Failed to send event:', err);
@@ -2620,12 +2962,17 @@ class AnalyticsService {
     /**
      * Track user journey with full context
      */
-    static async trackUserJourney({ sessionId, pageUrl, networkInfo, deviceInfo, location, attribution, ipLocation, userId, customData, pageVisits = 1, interactions = 0, }) {
+    static async trackUserJourney({ sessionId, pageUrl, networkInfo, deviceInfo, location, attribution, ipLocation, userId, customData, pageVisits: _pageVisits = 1, interactions: _interactions = 0, }) {
         // Get field storage config (support both new and legacy format)
         const fieldStorage = this.config.fieldStorage || {};
         const ipLocationConfig = fieldStorage.ipLocation || this.config.ipLocationFields;
         // Transform and filter all data types based on configuration
-        const transformedIPLocation = transformIPLocationForBackend(ipLocation, ipLocationConfig);
+        // Use raw ipLocation if transformation returns null (for validation purposes)
+        let transformedIPLocation = transformIPLocationForBackend(ipLocation, ipLocationConfig);
+        // Fallback to original ipLocation if transform returns null (needed for validation)
+        if (!transformedIPLocation && ipLocation) {
+            transformedIPLocation = ipLocation;
+        }
         const filteredDeviceInfo = filterFieldsByConfig(deviceInfo, fieldStorage.deviceInfo, DEFAULT_ESSENTIAL_DEVICE_FIELDS);
         // In essential mode, don't store browser-based networkInfo
         // Connection data from ipwho.is (in customData.ipLocation.connection) is more accurate
@@ -2665,8 +3012,7 @@ class AnalyticsService {
             deviceInfo: filteredDeviceInfo || undefined,
             location: filteredLocation || undefined,
             attribution: filteredAttribution || undefined,
-            // Don't include raw ipLocation - we have the filtered/transformed version in customData
-            ipLocation: undefined,
+            ipLocation: transformedIPLocation || ipLocation || undefined,
             userId: userId ?? sessionId,
             customData: {
                 ...customData,
@@ -2723,7 +3069,7 @@ class AnalyticsService {
                         attribution: AttributionDetector.detect(),
                     };
                 }
-                catch (error) {
+                catch {
                     // If auto-collection fails, use minimal context
                     const { getOrCreateUserId } = await Promise.resolve().then(function () { return storage; });
                     autoContext = {
@@ -2740,19 +3086,116 @@ class AnalyticsService {
                 };
             }
         }
-        const finalSessionId = context?.sessionId || autoContext?.sessionId || 'unknown';
-        const finalPageUrl = context?.pageUrl || autoContext?.pageUrl || '';
-        // Extract IP location from location object if available
-        const locationData = context?.location || autoContext?.location;
-        const ipLocationData = locationData && typeof locationData === 'object'
-            ? locationData?.ipLocationData
-            : undefined;
+        // Ensure sessionId is always a valid non-empty string for validation
+        let finalSessionId = context?.sessionId || autoContext?.sessionId || 'unknown';
+        if (finalSessionId === 'unknown' || finalSessionId.trim() === '') {
+            // Try to get from storage if available
+            if (typeof window !== 'undefined') {
+                try {
+                    const { getOrCreateUserId } = await Promise.resolve().then(function () { return storage; });
+                    finalSessionId = getOrCreateUserId();
+                }
+                catch {
+                    // If storage is not available, generate a temporary session ID
+                    finalSessionId = `temp-${Date.now()}`;
+                }
+            }
+            else {
+                // SSR environment - generate a temporary session ID
+                finalSessionId = `temp-${Date.now()}`;
+            }
+        }
+        // Ensure pageUrl is always a valid non-empty string for validation
+        let finalPageUrl = context?.pageUrl || autoContext?.pageUrl || '';
+        // If pageUrl is empty, try to get it from window.location if available
+        if (!finalPageUrl && typeof window !== 'undefined' && window.location) {
+            finalPageUrl = window.location.href;
+        }
+        // If still empty, use a default value to pass validation
+        if (!finalPageUrl || finalPageUrl.trim() === '') {
+            finalPageUrl = 'https://unknown';
+        }
+        // Extract IP location from context.ipLocation, location object, or auto-collected location
+        const ipLocationData = context?.ipLocation ||
+            (context?.location && typeof context.location === 'object'
+                ? context.location?.ipLocationData
+                : undefined) ||
+            (autoContext?.location && typeof autoContext.location === 'object'
+                ? autoContext.location?.ipLocationData
+                : undefined);
         // Get field storage config (support both new and legacy format)
         const fieldStorage = this.config.fieldStorage || {};
         const ipLocationConfig = fieldStorage.ipLocation || this.config.ipLocationFields;
         // Transform and filter all data types based on configuration
-        const transformedIPLocation = transformIPLocationForBackend(ipLocationData, ipLocationConfig);
-        const filteredDeviceInfo = filterFieldsByConfig(context?.deviceInfo || autoContext?.deviceInfo, fieldStorage.deviceInfo, DEFAULT_ESSENTIAL_DEVICE_FIELDS);
+        // Use raw ipLocationData if transformation returns null (for validation purposes)
+        // Always prioritize context?.ipLocation if it has an IP (most direct and reliable source)
+        const rawIPLocation = (context?.ipLocation && context.ipLocation.ip)
+            ? context.ipLocation
+            : (ipLocationData || undefined);
+        // Preserve ip field for validation - always ensure ip is available
+        const preserveIP = rawIPLocation?.ip;
+        let transformedIPLocation = transformIPLocationForBackend(rawIPLocation, ipLocationConfig);
+        // Critical: Ensure ip field is always preserved for validation
+        // If transformation removed ip or returned null/empty, restore it from rawIPLocation
+        if (preserveIP) {
+            if (!transformedIPLocation) {
+                // Transformation returned null, use rawIPLocation
+                transformedIPLocation = rawIPLocation;
+            }
+            else if (Object.keys(transformedIPLocation).length === 0) {
+                // Transformation returned empty object, use rawIPLocation
+                transformedIPLocation = rawIPLocation;
+            }
+            else if (!transformedIPLocation.ip) {
+                // Transformation returned object but without ip field, restore it
+                transformedIPLocation = { ...transformedIPLocation, ip: preserveIP };
+            }
+        }
+        else if (!transformedIPLocation && rawIPLocation) {
+            // No ip to preserve, but use rawIPLocation if transformation failed
+            transformedIPLocation = rawIPLocation;
+        }
+        const rawDeviceInfo = context?.deviceInfo || autoContext?.deviceInfo;
+        const filteredDeviceInfo = filterFieldsByConfig(rawDeviceInfo, fieldStorage.deviceInfo, DEFAULT_ESSENTIAL_DEVICE_FIELDS);
+        // Ensure deviceInfo has os and browser for validation (critical fields)
+        // If filtering removed them, restore from rawDeviceInfo
+        let finalDeviceInfo = filteredDeviceInfo;
+        if (rawDeviceInfo) {
+            if (!finalDeviceInfo) {
+                // Filtering returned null, create minimal object with essential fields
+                finalDeviceInfo = {};
+                if (rawDeviceInfo.os)
+                    finalDeviceInfo.os = rawDeviceInfo.os;
+                if (rawDeviceInfo.browser)
+                    finalDeviceInfo.browser = rawDeviceInfo.browser;
+            }
+            else {
+                // Ensure os and browser are present for validation
+                if (!finalDeviceInfo.os && rawDeviceInfo.os) {
+                    finalDeviceInfo = { ...finalDeviceInfo, os: rawDeviceInfo.os };
+                }
+                if (!finalDeviceInfo.browser && rawDeviceInfo.browser) {
+                    finalDeviceInfo = { ...finalDeviceInfo, browser: rawDeviceInfo.browser };
+                }
+            }
+            // Only use finalDeviceInfo if it has at least os or browser
+            // But if rawDeviceInfo has os or browser, ensure finalDeviceInfo has them
+            if (rawDeviceInfo.os || rawDeviceInfo.browser) {
+                if (!finalDeviceInfo) {
+                    finalDeviceInfo = {};
+                }
+                if (rawDeviceInfo.os && !finalDeviceInfo.os) {
+                    finalDeviceInfo.os = rawDeviceInfo.os;
+                }
+                if (rawDeviceInfo.browser && !finalDeviceInfo.browser) {
+                    finalDeviceInfo.browser = rawDeviceInfo.browser;
+                }
+            }
+            else if (!finalDeviceInfo || (!finalDeviceInfo.os && !finalDeviceInfo.browser)) {
+                // No os or browser in rawDeviceInfo, and finalDeviceInfo doesn't have them either
+                finalDeviceInfo = null;
+            }
+        }
         // In essential mode, don't store browser-based networkInfo
         // Connection data from ipwho.is (in customData.ipLocation.connection) is more accurate
         const networkInfoConfig = fieldStorage.networkInfo;
@@ -2782,20 +3225,65 @@ class AnalyticsService {
             };
         }
         const filteredAttribution = filterFieldsByConfig(context?.attribution || autoContext?.attribution, fieldStorage.attribution, DEFAULT_ESSENTIAL_ATTRIBUTION_FIELDS);
+        // Ensure ipLocation is available for validation
+        // Always preserve ip field - critical for validation
+        // Use transformedIPLocation if it has ip, otherwise fall back to rawIPLocation
+        let finalIPLocation = undefined;
+        // Priority 1: If we have rawIPLocation with IP, always use it (most reliable source)
+        if (rawIPLocation && rawIPLocation.ip) {
+            if (transformedIPLocation && transformedIPLocation.ip) {
+                // Both have IP, prefer transformed (has filtering applied)
+                finalIPLocation = transformedIPLocation;
+            }
+            else if (transformedIPLocation) {
+                // Transformed exists but no IP, merge with rawIPLocation to preserve IP
+                finalIPLocation = { ...transformedIPLocation, ip: rawIPLocation.ip };
+            }
+            else {
+                // No transformation, use rawIPLocation directly
+                finalIPLocation = rawIPLocation;
+            }
+        }
+        else if (transformedIPLocation) {
+            // No raw IP, but transformation succeeded
+            finalIPLocation = transformedIPLocation;
+        }
+        else if (context?.ipLocation && context.ipLocation.ip) {
+            // Fallback to context.ipLocation if available
+            finalIPLocation = context.ipLocation;
+        }
+        // Final safety check: ensure IP is always present if we have it from any source
+        if (!finalIPLocation || !finalIPLocation.ip) {
+            if (rawIPLocation && rawIPLocation.ip) {
+                finalIPLocation = rawIPLocation;
+            }
+            else if (context?.ipLocation && context.ipLocation.ip) {
+                finalIPLocation = context.ipLocation;
+            }
+        }
+        // Ultimate safeguard: if context.ipLocation has IP, always use it for validation
+        // This ensures validation never fails due to missing IP when it's provided in context
+        if (context?.ipLocation && context.ipLocation.ip) {
+            if (!finalIPLocation || !finalIPLocation.ip) {
+                finalIPLocation = context.ipLocation;
+            }
+        }
         await this.trackEvent({
             sessionId: finalSessionId,
             pageUrl: finalPageUrl,
             networkInfo: filteredNetworkInfo || undefined,
-            deviceInfo: filteredDeviceInfo || undefined,
+            deviceInfo: (finalDeviceInfo && (finalDeviceInfo.os || finalDeviceInfo.browser)) ? finalDeviceInfo : undefined,
             location: filteredLocation || undefined,
             attribution: filteredAttribution || undefined,
+            ipLocation: finalIPLocation,
             userId: context?.userId || finalSessionId,
             eventName,
             eventParameters: parameters || {},
             customData: {
                 ...(parameters || {}),
                 // Store transformed IP location in customData for backend integration
-                ...(transformedIPLocation && { ipLocation: transformedIPLocation }),
+                // Use transformed if available, otherwise use raw (for validation)
+                ...(finalIPLocation && { ipLocation: transformedIPLocation || finalIPLocation }),
             },
         });
     }
@@ -2818,13 +3306,13 @@ class AnalyticsService {
      * });
      * ```
      */
-    static async trackPageView(pageName, parameters) {
+    static async trackPageView(pageName, parameters, context) {
         const page = pageName || (typeof window !== 'undefined' ? window.location.pathname : '');
         await this.logEvent('page_view', {
             page_name: page,
             page_title: typeof document !== 'undefined' ? document.title : undefined,
             ...parameters,
-        });
+        }, context);
     }
     /**
      * Manually flush the event queue
@@ -2865,7 +3353,10 @@ AnalyticsService.apiEndpoint = '/api/analytics';
 AnalyticsService.queueManager = null;
 AnalyticsService.config = {};
 AnalyticsService.isInitialized = false;
+AnalyticsService.seenEventKeys = new Set();
+AnalyticsService.DEDUPE_CACHE_SIZE = 1000; // Keep last 1000 event keys
 
+/* eslint-disable @typescript-eslint/no-explicit-any */
 /**
  * Debug utilities for analytics tracker
  * Provides debugging tools in development mode
@@ -2944,6 +3435,7 @@ function initDebug() {
     logger.info('Available methods: getQueue(), getQueueSize(), flushQueue(), clearQueue(), getStats(), setLogLevel()');
 }
 
+/* eslint-disable @typescript-eslint/no-explicit-any */
 /**
  * React Hook for Analytics Tracking
  * Provides device, network, location, and attribution data
@@ -2951,11 +3443,17 @@ function initDebug() {
 /**
  * React hook for analytics tracking
  *
+ * To use your own ipwho.is API key (higher rate limits), pass ipGeolocation in config.
+ * Use an env var so the key is not committed (e.g. VITE_IPWHOIS_API_KEY, REACT_APP_IPWHOIS_API_KEY).
+ *
  * @example
  * ```tsx
  * const { sessionId, networkInfo, deviceInfo, logEvent } = useAnalytics({
  *   autoSend: true,
- *   config: { apiEndpoint: '/api/analytics' }
+ *   config: {
+ *     apiEndpoint: '/api/analytics',
+ *     ipGeolocation: { apiKey: import.meta.env.VITE_IPWHOIS_API_KEY }, // optional; omit for free tier
+ *   },
  * });
  * ```
  */
@@ -2976,6 +3474,7 @@ function useAnalytics(options = {}) {
                 sessionTimeout: config.sessionTimeout,
                 fieldStorage: config.fieldStorage,
                 ipLocationFields: config.ipLocationFields, // Legacy support
+                ipGeolocation: config.ipGeolocation, // ipwho.is API key (use env var, e.g. VITE_IPWHOIS_API_KEY)
             });
         }
     }, [
@@ -2988,6 +3487,9 @@ function useAnalytics(options = {}) {
         config?.logLevel,
         config?.enableMetrics,
         config?.sessionTimeout,
+        config?.fieldStorage,
+        config?.ipLocationFields,
+        config?.ipGeolocation,
     ]);
     const [networkInfo, setNetworkInfo] = react.useState(null);
     const [deviceInfo, setDeviceInfo] = react.useState(null);
@@ -3279,7 +3781,9 @@ exports.checkAndSetLocationConsent = checkAndSetLocationConsent;
 exports.clearLocationConsent = clearLocationConsent;
 exports.clearSession = clearSession;
 exports.default = useAnalytics;
+exports.extractRequiredFields = extractRequiredFields;
 exports.filterFieldsByConfig = filterFieldsByConfig;
+exports.generateDeduplicationKey = generateDeduplicationKey;
 exports.getCompleteIPLocation = getCompleteIPLocation;
 exports.getIPFromRequest = getIPFromRequest;
 exports.getIPLocation = getIPLocation;
@@ -3300,4 +3804,6 @@ exports.trackPageVisit = trackPageVisit;
 exports.transformIPLocationForBackend = transformIPLocationForBackend;
 exports.updateSessionActivity = updateSessionActivity;
 exports.useAnalytics = useAnalytics;
+exports.validateEvent = validateEvent;
+exports.validateRequiredFields = validateRequiredFields;
 //# sourceMappingURL=index.cjs.js.map