user-analytics-tracker 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [2.2.0](https://github.com/switch-org/analytics-tracker/compare/v2.1.0...v2.2.0) (2025-12-30)
+
+
+### Features
+
+* ip-location, connection update with ipwho-is api ([fa1b369](https://github.com/switch-org/analytics-tracker/commit/fa1b36997ecad6f71c758f738c768090529bb2b0))
+
 # [2.1.0](https://github.com/switch-org/analytics-tracker/compare/v2.0.0...v2.1.0) (2025-12-29)
 
 

package/dist/index.cjs.js

@@ -562,25 +562,28 @@ function checkAndSetLocationConsent(msisdn) {
  * This ensures we capture all available data and any new fields added by the API
  */
 /**
- * Get public IP address using ipwho.is 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
  *
- * @returns Promise<string | null> - The public IP address, or null if unavailable
+ * @returns Promise<IPLocation | null> - Complete IP location data, or null if unavailable
  *
  * @example
  * ```typescript
- * const ip = await getPublicIP();
- * console.log('Your IP:', ip); // e.g., "203.0.113.42"
+ * const location = await getCompleteIPLocation();
+ * console.log('IP:', location?.ip);
+ * console.log('Country:', location?.country);
+ * console.log('ISP:', location?.connection?.isp);
  * ```
  */
-async function getPublicIP() {
+async function getCompleteIPLocation() {
     // Skip if we're in an environment without fetch (SSR)
     if (typeof fetch === 'undefined') {
         return null;
     }
     try {
-        // Call ipwho.is without IP parameter - it auto-detects user's IP
-        // Using HTTPS endpoint for better security
+        // 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/', {
             method: 'GET',
             headers: {
@@ -597,22 +600,105 @@ async function getPublicIP() {
         if (data.success === false) {
             return null;
         }
-        return data.ip || null;
+        // Store all keys dynamically from the response
+        // This ensures we capture all fields, including nested objects and any new fields
+        const locationData = {
+            ip: data.ip,
+            // Map all fields from the API response dynamically
+            ...Object.keys(data).reduce((acc, key) => {
+                // Store all keys and their values, preserving nested objects
+                acc[key] = data[key];
+                return acc;
+            }, {}),
+        };
+        // Add backward compatibility mappings for existing code
+        if (data.latitude !== undefined) {
+            locationData.lat = data.latitude;
+        }
+        if (data.longitude !== undefined) {
+            locationData.lon = data.longitude;
+        }
+        if (data.country_code !== undefined) {
+            locationData.countryCode = data.country_code;
+        }
+        if (data.region !== undefined) {
+            locationData.regionName = data.region;
+        }
+        if (data.connection?.isp !== undefined) {
+            locationData.isp = data.connection.isp;
+        }
+        if (data.connection?.org !== undefined) {
+            locationData.org = data.connection.org;
+        }
+        if (data.connection?.asn !== undefined) {
+            locationData.as = `AS${data.connection.asn}`;
+        }
+        if (data.timezone?.id !== undefined) {
+            locationData.timezone = data.timezone.id;
+        }
+        locationData.query = data.ip;
+        return locationData;
     }
     catch (error) {
         // Silently fail - don't break user experience
         if (error.name !== 'AbortError') {
-            console.warn('[IP Geolocation] Error fetching public IP:', error.message);
+            console.warn('[IP Geolocation] Error fetching complete IP location from ipwho.is:', error.message);
         }
         return null;
     }
 }
 /**
- * Get location from IP address using ipwho.is API
+ * Get public IP address using ipwho.is API (FALLBACK - lower priority)
+ * This is kept for backward compatibility and as a fallback
+ * Prefer getCompleteIPLocation() which gets everything in one call
+ *
+ * @returns Promise<string | null> - The public IP address, or null if unavailable
+ *
+ * @example
+ * ```typescript
+ * const ip = await getPublicIP();
+ * console.log('Your IP:', ip); // e.g., "203.0.113.42"
+ * ```
+ */
+async function getPublicIP() {
+    // Try to get complete location first (includes IP)
+    const completeLocation = await getCompleteIPLocation();
+    if (completeLocation?.ip) {
+        return completeLocation.ip;
+    }
+    // Fallback: try direct IP fetch (less efficient, lower priority)
+    try {
+        const response = await fetch('https://ipwho.is/', {
+            method: 'GET',
+            headers: {
+                Accept: 'application/json',
+            },
+            signal: AbortSignal.timeout(5000),
+        });
+        if (!response.ok) {
+            return null;
+        }
+        const data = await response.json();
+        if (data.success === false) {
+            return null;
+        }
+        return data.ip || null;
+    }
+    catch (error) {
+        if (error.name !== 'AbortError') {
+            console.warn('[IP Geolocation] Error fetching public IP (fallback):', error.message);
+        }
+        return null;
+    }
+}
+/**
+ * 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
+ *
+ * Note: If you don't have an IP yet, use getCompleteIPLocation() which gets everything in one call
  */
 async function getIPLocation(ip) {
     // Skip localhost/private IPs (these can't be geolocated)
@@ -1039,15 +1125,21 @@ class LocationDetector {
         }
         this.ipLocationFetchingRef.current = true;
         try {
-            // Get public IP first, then get location
-            const publicIP = await getPublicIP();
-            if (!publicIP) {
-                throw new Error('Could not determine public IP address');
+            // 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();
+            // 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();
+                if (publicIP) {
+                    // Fallback: Get location from IP using ipwho.is API
+                    ipLocation = await getIPLocation(publicIP);
+                }
             }
-            // Get location from IP using ipwho.is API
-            const ipLocation = await getIPLocation(publicIP);
             if (!ipLocation) {
-                throw new Error('Could not fetch location data');
+                throw new Error('Could not fetch location data from ipwho.is');
             }
             // Convert IP location to LocationInfo format
             // Map all available fields from the IP location response
@@ -1062,7 +1154,7 @@ class LocationDetector {
                 permission: 'granted', // IP location doesn't require permission
                 source: 'ip',
                 ts: new Date().toISOString(),
-                ip: ipLocation.ip || publicIP,
+                ip: ipLocation.ip || undefined,
                 country: ipLocation.country || undefined,
                 countryCode: ipLocation.country_code || ipLocation.countryCode || undefined,
                 city: ipLocation.city || undefined,
@@ -1072,7 +1164,7 @@ class LocationDetector {
             // Store the full IP location data in a custom field for access to all keys
             // This preserves all dynamic keys from the API response
             locationResult.ipLocationData = ipLocation;
-            console.log('[Location] IP-based location obtained:', {
+            console.log('[Location] IP-based location obtained from ipwho.is:', {
                 ip: locationResult.ip,
                 lat: locationResult.lat,
                 lon: locationResult.lon,
@@ -1080,6 +1172,8 @@ class LocationDetector {
                 country: locationResult.country,
                 continent: ipLocation.continent,
                 timezone: locationResult.timezone,
+                isp: ipLocation.connection?.isp,
+                connection: ipLocation.connection,
             });
             this.lastIPLocationRef.current = locationResult;
             return locationResult;
@@ -1916,6 +2010,73 @@ class MetricsCollector {
 // Global metrics collector instance
 const metricsCollector = new MetricsCollector();
 
+/**
+ * Transform IP location data from API format (snake_case) to backend-expected format (camelCase)
+ * This ensures compatibility with the analytics backend integration
+ *
+ * @param ipLocation - Raw IP location data from ipwho.is API
+ * @returns Transformed IP location data matching backend schema
+ */
+function transformIPLocationForBackend(ipLocation) {
+    if (!ipLocation) {
+        return null;
+    }
+    // Transform to match backend expected format (camelCase)
+    const transformed = {
+        // Basic fields
+        ip: ipLocation.ip,
+        country: ipLocation.country,
+        countryCode: ipLocation.country_code || ipLocation.countryCode,
+        region: ipLocation.region || ipLocation.regionName,
+        city: ipLocation.city,
+        postal: ipLocation.postal,
+        capital: ipLocation.capital,
+        callingCode: ipLocation.calling_code || ipLocation.callingCode,
+        // Geographic fields
+        continent: ipLocation.continent,
+        continentCode: ipLocation.continent_code || ipLocation.continentCode,
+        lat: ipLocation.latitude ?? ipLocation.lat,
+        lon: ipLocation.longitude ?? ipLocation.lon,
+        borders: ipLocation.borders,
+        // Network fields
+        type: ipLocation.type,
+        isEu: ipLocation.is_eu ?? ipLocation.isEu,
+        // ISP/Connection - preserve connection object and also add top-level isp
+        isp: ipLocation.connection?.isp || ipLocation.isp,
+        connection: ipLocation.connection ? {
+            asn: ipLocation.connection.asn,
+            org: ipLocation.connection.org,
+            isp: ipLocation.connection.isp,
+            domain: ipLocation.connection.domain,
+        } : undefined,
+        // Timezone - store both simple string and full details object
+        timezone: typeof ipLocation.timezone === 'string'
+            ? ipLocation.timezone
+            : ipLocation.timezone?.id,
+        timezoneDetails: ipLocation.timezone && typeof ipLocation.timezone === 'object' ? {
+            id: ipLocation.timezone.id,
+            abbr: ipLocation.timezone.abbr,
+            isDst: ipLocation.timezone.is_dst,
+            offset: ipLocation.timezone.offset,
+            utc: ipLocation.timezone.utc,
+            currentTime: ipLocation.timezone.current_time,
+        } : undefined,
+        // Flag - transform to camelCase
+        flag: ipLocation.flag ? {
+            img: ipLocation.flag.img,
+            emoji: ipLocation.flag.emoji,
+            emojiUnicode: ipLocation.flag.emoji_unicode,
+        } : undefined,
+    };
+    // Remove undefined values to keep the payload clean
+    Object.keys(transformed).forEach(key => {
+        if (transformed[key] === undefined) {
+            delete transformed[key];
+        }
+    });
+    return transformed;
+}
+
 /**
  * Analytics Service
  * Sends analytics events to your backend API
@@ -2179,6 +2340,8 @@ class AnalyticsService {
      * Track user journey with full context
      */
     static async trackUserJourney({ sessionId, pageUrl, networkInfo, deviceInfo, location, attribution, ipLocation, userId, customData, pageVisits = 1, interactions = 0, }) {
+        // Transform IP location data to match backend expected format (camelCase)
+        const transformedIPLocation = transformIPLocationForBackend(ipLocation);
         await this.trackEvent({
             sessionId,
             pageUrl,
@@ -2190,7 +2353,8 @@ class AnalyticsService {
             userId: userId ?? sessionId,
             customData: {
                 ...customData,
-                ...(ipLocation && { ipLocation }),
+                // Store transformed IP location in customData for backend integration
+                ...(transformedIPLocation && { ipLocation: transformedIPLocation }),
             },
             eventName: 'page_view', // Auto-tracked as page view
         });
@@ -2261,6 +2425,13 @@ 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;
+        // Transform IP location data to match backend expected format
+        const transformedIPLocation = transformIPLocationForBackend(ipLocationData);
         await this.trackEvent({
             sessionId: finalSessionId,
             pageUrl: finalPageUrl,
@@ -2271,7 +2442,11 @@ class AnalyticsService {
             userId: context?.userId || finalSessionId,
             eventName,
             eventParameters: parameters || {},
-            customData: parameters || {},
+            customData: {
+                ...(parameters || {}),
+                // Store transformed IP location in customData for backend integration
+                ...(transformedIPLocation && { ipLocation: transformedIPLocation }),
+            },
         });
     }
     /**
@@ -2744,6 +2919,7 @@ exports.checkAndSetLocationConsent = checkAndSetLocationConsent;
 exports.clearLocationConsent = clearLocationConsent;
 exports.clearSession = clearSession;
 exports.default = useAnalytics;
+exports.getCompleteIPLocation = getCompleteIPLocation;
 exports.getIPFromRequest = getIPFromRequest;
 exports.getIPLocation = getIPLocation;
 exports.getLocationConsentTimestamp = getLocationConsentTimestamp;
@@ -2760,6 +2936,7 @@ exports.saveJSON = saveJSON;
 exports.saveSessionJSON = saveSessionJSON;
 exports.setLocationConsentGranted = setLocationConsentGranted;
 exports.trackPageVisit = trackPageVisit;
+exports.transformIPLocationForBackend = transformIPLocationForBackend;
 exports.updateSessionActivity = updateSessionActivity;
 exports.useAnalytics = useAnalytics;
 //# sourceMappingURL=index.cjs.js.map