user-analytics-tracker 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -1,3 +1,34 @@
+# [2.1.0](https://github.com/switch-org/analytics-tracker/compare/v2.0.0...v2.1.0) (2025-12-29)
+
+
+### Features
+
+* migrate IP geolocation to ipwho.is API with dynamic key storage ([0605f72](https://github.com/switch-org/analytics-tracker/commit/0605f7207baa590b776a3b52cbc055e98a8a22e4))
+
+# [2.1.0](https://github.com/switch-org/analytics-tracker/compare/v2.0.0...v2.1.0) (TBD)
+
+### Features
+
+* **IP Geolocation API Migration**: Migrated from ip-api.com to ipwho.is API for IP-based location tracking
+  - More comprehensive location data including continent, flag, connection details, and timezone information
+  - Dynamic key storage: All API response keys are automatically stored, including nested objects
+  - Future-proof: New fields added by the API are automatically captured without code changes
+  - No API key required: Free tier with no authentication needed
+* **Enhanced IP Location Data**: The `IPLocation` interface now includes all fields from the ipwho.is API response
+  - New fields: `continent`, `continent_code`, `flag`, `connection`, `timezone` (with full details), `is_eu`, `postal`, `calling_code`, `capital`, `borders`
+  - Full backward compatibility: All existing fields (`lat`, `lon`, `countryCode`, etc.) remain available
+  - Access to full IP location data in analytics events via `ipLocationData` field
+
+### Improvements
+
+* Better IP location data coverage with additional metadata
+* Automatic storage of all API response keys, including future additions
+* Improved type definitions for IP location data
+
+### Migration Notes
+
+This upgrade is **fully backward compatible**. No code changes are required. See the [Upgrade Guide](./docs/upgrade-guide.md) for details on accessing new fields.
+
 # [2.0.0](https://github.com/switch-org/analytics-tracker/compare/v1.7.0...v2.0.0) (2025-12-01)
 
 

package/README.md

@@ -15,7 +15,8 @@ A comprehensive, lightweight analytics tracking library for React applications.
 - 📍 **Location Tracking**: 
   - **IP-based location** - Requires user consent (privacy-compliant)
   - **GPS location** - Requires explicit user consent and browser permission
-  - Includes public IP address, country, city, region, timezone
+  - Includes public IP address, country, city, region, timezone, continent, flag, connection details
+  - Dynamic key storage: All IP location API fields are automatically captured
   - Automatic fallback from GPS to IP when GPS unavailable
   - Consent management utilities included
 - 🎯 **Attribution Tracking**: UTM parameters, referrer tracking, first/last touch attribution
@@ -855,6 +856,14 @@ export async function POST(req: NextRequest) {
 
 Comprehensive documentation is available in the [`docs/`](./docs) directory:
 
+- **[Upgrade Guide](./docs/upgrade-guide.md)** - Step-by-step migration instructions for upgrading between versions
+
+- **[Upgrade Guide](./docs/upgrade-guide.md)** - Step-by-step migration instructions for upgrading between versions
+  - Breaking changes and compatibility notes
+  - New features and improvements
+  - Migration examples
+  - Troubleshooting upgrade issues
+
 - **[Usage Guide](./docs/usage-guide.md)** - Complete guide on how to use the package in your applications
   - Installation instructions
   - Basic and advanced usage examples
@@ -964,7 +973,7 @@ MIT © [Switch Org](https://github.com/switch-org)
 
 ## 🙏 Acknowledgments
 
-- Uses [ip-api.com](http://ip-api.com) for free IP geolocation
+- Uses [ipwho.is](https://ipwho.is/) for free IP geolocation
 - Built with modern web APIs (User-Agent Client Hints, Network Information API, Geolocation API)
 
 <!-- ## 📞 Support

package/dist/index.cjs.js

@@ -553,6 +553,191 @@ 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 public IP address using ipwho.is API
+ * No API key required
+ *
+ * @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() {
+    // 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
+        const response = await fetch('https://ipwho.is/', {
+            method: 'GET',
+            headers: {
+                Accept: 'application/json',
+            },
+            // Add timeout to prevent hanging
+            signal: AbortSignal.timeout(5000),
+        });
+        if (!response.ok) {
+            return null;
+        }
+        const data = await response.json();
+        // ipwho.is returns success field
+        if (data.success === false) {
+            return null;
+        }
+        return data.ip || null;
+    }
+    catch (error) {
+        // Silently fail - don't break user experience
+        if (error.name !== 'AbortError') {
+            console.warn('[IP Geolocation] Error fetching public IP:', error.message);
+        }
+        return null;
+    }
+}
+/**
+ * Get location from IP address using ipwho.is API
+ * 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
+ */
+async function getIPLocation(ip) {
+    // Skip localhost/private IPs (these can't be geolocated)
+    if (!ip ||
+        ip === '0.0.0.0' ||
+        ip === '::1' ||
+        ip.startsWith('127.') ||
+        ip.startsWith('192.168.') ||
+        ip.startsWith('10.') ||
+        ip.startsWith('172.') ||
+        ip.startsWith('::ffff:127.')) {
+        console.log(`[IP Geolocation] Skipping localhost/private IP: ${ip} (geolocation not available for local IPs)`);
+        return null;
+    }
+    try {
+        // Using ipwho.is API (no API key required)
+        const response = await fetch(`https://ipwho.is/${ip}`, {
+            method: 'GET',
+            headers: {
+                Accept: 'application/json',
+            },
+            // Add timeout to prevent hanging
+            signal: AbortSignal.timeout(5000),
+        });
+        if (!response.ok) {
+            console.warn(`[IP Geolocation] Failed to fetch location for IP ${ip}: ${response.status}`);
+            return null;
+        }
+        const data = await response.json();
+        // ipwho.is returns success field
+        if (data.success === false) {
+            console.warn(`[IP Geolocation] API error for IP ${ip}: ${data.message || 'Unknown error'}`);
+            return 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 || 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 || ip;
+        return locationData;
+    }
+    catch (error) {
+        // Silently fail - don't break user experience
+        if (error.name !== 'AbortError') {
+            console.warn(`[IP Geolocation] Error fetching location for IP ${ip}:`, error.message);
+        }
+        return null;
+    }
+}
+/**
+ * Get IP address from request headers
+ * Handles various proxy headers (x-forwarded-for, x-real-ip, etc.)
+ */
+function getIPFromRequest(req) {
+    // Try various headers that proxies/load balancers use
+    const forwardedFor = req.headers?.get?.('x-forwarded-for') ||
+        req.headers?.['x-forwarded-for'] ||
+        req.headers?.['X-Forwarded-For'];
+    if (forwardedFor) {
+        // x-forwarded-for can contain multiple IPs, take the first one
+        const ips = forwardedFor.split(',').map((ip) => ip.trim());
+        const ip = ips[0];
+        if (ip && ip !== '0.0.0.0') {
+            return ip;
+        }
+    }
+    const realIP = req.headers?.get?.('x-real-ip') ||
+        req.headers?.['x-real-ip'] ||
+        req.headers?.['X-Real-IP'];
+    if (realIP && realIP !== '0.0.0.0') {
+        return realIP.trim();
+    }
+    // Try req.ip (from Express/Next.js)
+    if (req.ip && req.ip !== '0.0.0.0') {
+        return req.ip;
+    }
+    // For localhost, detect if we're running locally
+    if (typeof window === 'undefined') {
+        const hostname = req.headers?.get?.('host') || req.headers?.['host'];
+        if (hostname &&
+            (hostname.includes('localhost') ||
+                hostname.includes('127.0.0.1') ||
+                hostname.startsWith('192.168.'))) {
+            return '127.0.0.1'; // Localhost IP
+        }
+    }
+    // If no IP found and we're in development, return localhost
+    if (typeof process !== 'undefined' && process.env?.NODE_ENV === 'development') {
+        return '127.0.0.1'; // Localhost for development
+    }
+    return '0.0.0.0';
+}
+
 /**
  * Location Detector
  * Detects GPS location with consent management, falls back to IP-based location API
@@ -817,7 +1002,8 @@ 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
      */
     static async getIPBasedLocation() {
         // Return cached IP location if available
@@ -853,51 +1039,47 @@ class LocationDetector {
         }
         this.ipLocationFetchingRef.current = true;
         try {
-            // Call ip-api.com without IP parameter - it auto-detects user's IP
-            // Using HTTPS endpoint for better security
-            const response = await fetch('https://ip-api.com/json/?fields=status,message,country,countryCode,region,regionName,city,lat,lon,timezone,query', {
-                method: 'GET',
-                headers: {
-                    Accept: 'application/json',
-                },
-                // Add timeout to prevent hanging
-                signal: AbortSignal.timeout(5000),
-            });
-            if (!response.ok) {
-                throw new Error(`HTTP ${response.status}`);
+            // Get public IP first, then get location
+            const publicIP = await getPublicIP();
+            if (!publicIP) {
+                throw new Error('Could not determine public IP address');
             }
-            const data = await response.json();
-            // ip-api.com returns status field
-            if (data.status === 'fail') {
-                console.warn(`[Location] IP API error: ${data.message}`);
-                const fallback = {
-                    source: 'unknown',
-                    permission: 'granted',
-                };
-                this.lastIPLocationRef.current = fallback;
-                return fallback;
+            // Get location from IP using ipwho.is API
+            const ipLocation = await getIPLocation(publicIP);
+            if (!ipLocation) {
+                throw new Error('Could not fetch location data');
             }
             // Convert IP location to LocationInfo format
+            // Map all available fields from the IP location response
+            // Handle timezone which can be either a string or an object
+            const timezoneValue = typeof ipLocation.timezone === 'string'
+                ? ipLocation.timezone
+                : ipLocation.timezone?.id || undefined;
             const locationResult = {
-                lat: data.lat || null,
-                lon: data.lon || null,
+                lat: ipLocation.latitude ?? ipLocation.lat ?? null,
+                lon: ipLocation.longitude ?? ipLocation.lon ?? null,
                 accuracy: null, // IP-based location has no accuracy metric
                 permission: 'granted', // IP location doesn't require permission
                 source: 'ip',
                 ts: new Date().toISOString(),
-                ip: data.query || null, // Public IP address
-                country: data.country || undefined,
-                countryCode: data.countryCode || undefined,
-                city: data.city || undefined,
-                region: data.regionName || data.region || undefined,
-                timezone: data.timezone || undefined,
+                ip: ipLocation.ip || publicIP,
+                country: ipLocation.country || undefined,
+                countryCode: ipLocation.country_code || ipLocation.countryCode || undefined,
+                city: ipLocation.city || undefined,
+                region: ipLocation.region || ipLocation.regionName || undefined,
+                timezone: timezoneValue,
             };
+            // 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:', {
                 ip: locationResult.ip,
                 lat: locationResult.lat,
                 lon: locationResult.lon,
                 city: locationResult.city,
                 country: locationResult.country,
+                continent: ipLocation.continent,
+                timezone: locationResult.timezone,
             });
             this.lastIPLocationRef.current = locationResult;
             return locationResult;
@@ -2380,6 +2562,8 @@ function useAnalytics(options = {}) {
             if (autoSend) {
                 // Send after idle to not block paint
                 const send = async () => {
+                    // Extract IP location data if available (stored in ipLocationData field)
+                    const ipLocationData = loc?.ipLocationData;
                     await AnalyticsService.trackUserJourney({
                         sessionId: getOrCreateUserId(),
                         pageUrl: typeof window !== 'undefined' ? window.location.href : '',
@@ -2387,6 +2571,7 @@ function useAnalytics(options = {}) {
                         deviceInfo: dev,
                         location: loc,
                         attribution: attr,
+                        ipLocation: ipLocationData,
                         customData: config?.enableLocation ? { locationEnabled: true } : undefined,
                     });
                 };
@@ -2402,6 +2587,8 @@ function useAnalytics(options = {}) {
     const logEvent = react.useCallback(async (customData) => {
         if (!sessionId || !networkInfo || !deviceInfo)
             return;
+        // Extract IP location data if available (stored in ipLocationData field)
+        const ipLocationData = location ? location?.ipLocationData : undefined;
         await AnalyticsService.trackUserJourney({
             sessionId,
             pageUrl: typeof window !== 'undefined' ? window.location.href : '',
@@ -2409,6 +2596,7 @@ function useAnalytics(options = {}) {
             deviceInfo,
             location: location ?? undefined,
             attribution: attribution ?? undefined,
+            ipLocation: ipLocationData,
             userId: sessionId,
             customData,
         });
@@ -2546,167 +2734,6 @@ function useAnalytics(options = {}) {
     ]);
 }
 
-/**
- * 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)
- */
-/**
- * Get public IP address using ip-api.com
- * Free tier: 45 requests/minute, no API key required
- *
- * @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() {
-    // Skip if we're in an environment without fetch (SSR)
-    if (typeof fetch === 'undefined') {
-        return null;
-    }
-    try {
-        // Call ip-api.com without IP parameter - it auto-detects user's IP
-        // Using HTTPS endpoint for better security
-        const response = await fetch('https://ip-api.com/json/?fields=status,message,query', {
-            method: 'GET',
-            headers: {
-                Accept: 'application/json',
-            },
-            // Add timeout to prevent hanging
-            signal: AbortSignal.timeout(5000),
-        });
-        if (!response.ok) {
-            return null;
-        }
-        const data = await response.json();
-        // ip-api.com returns status field
-        if (data.status === 'fail') {
-            return null;
-        }
-        return data.query || null;
-    }
-    catch (error) {
-        // Silently fail - don't break user experience
-        if (error.name !== 'AbortError') {
-            console.warn('[IP Geolocation] Error fetching public IP:', error.message);
-        }
-        return null;
-    }
-}
-/**
- * Get location from IP address using ip-api.com
- * Free tier: 45 requests/minute, no API key required
- *
- * Alternative services:
- * - ipapi.co (requires API key for production)
- * - ipgeolocation.io (requires API key)
- * - ip-api.com (free tier available)
- */
-async function getIPLocation(ip) {
-    // Skip localhost/private IPs (these can't be geolocated)
-    if (!ip ||
-        ip === '0.0.0.0' ||
-        ip === '::1' ||
-        ip.startsWith('127.') ||
-        ip.startsWith('192.168.') ||
-        ip.startsWith('10.') ||
-        ip.startsWith('172.') ||
-        ip.startsWith('::ffff:127.')) {
-        console.log(`[IP Geolocation] Skipping localhost/private IP: ${ip} (geolocation not available for local IPs)`);
-        return null;
-    }
-    try {
-        // Using ip-api.com free tier (JSON format)
-        const response = await fetch(`http://ip-api.com/json/${ip}?fields=status,message,country,countryCode,region,regionName,city,lat,lon,timezone,isp,org,as,query`, {
-            method: 'GET',
-            headers: {
-                Accept: 'application/json',
-            },
-            // Add timeout to prevent hanging
-            signal: AbortSignal.timeout(3000),
-        });
-        if (!response.ok) {
-            console.warn(`[IP Geolocation] Failed to fetch location for IP ${ip}: ${response.status}`);
-            return null;
-        }
-        const data = await response.json();
-        // ip-api.com returns status field
-        if (data.status === 'fail') {
-            console.warn(`[IP Geolocation] API error for IP ${ip}: ${data.message}`);
-            return null;
-        }
-        return {
-            ip: data.query || ip,
-            country: data.country || undefined,
-            countryCode: data.countryCode || undefined,
-            region: data.region || undefined,
-            regionName: data.regionName || undefined,
-            city: data.city || undefined,
-            lat: data.lat || undefined,
-            lon: data.lon || undefined,
-            timezone: data.timezone || undefined,
-            isp: data.isp || undefined,
-            org: data.org || undefined,
-            as: data.as || undefined,
-            query: data.query || ip,
-        };
-    }
-    catch (error) {
-        // Silently fail - don't break user experience
-        if (error.name !== 'AbortError') {
-            console.warn(`[IP Geolocation] Error fetching location for IP ${ip}:`, error.message);
-        }
-        return null;
-    }
-}
-/**
- * Get IP address from request headers
- * Handles various proxy headers (x-forwarded-for, x-real-ip, etc.)
- */
-function getIPFromRequest(req) {
-    // Try various headers that proxies/load balancers use
-    const forwardedFor = req.headers?.get?.('x-forwarded-for') ||
-        req.headers?.['x-forwarded-for'] ||
-        req.headers?.['X-Forwarded-For'];
-    if (forwardedFor) {
-        // x-forwarded-for can contain multiple IPs, take the first one
-        const ips = forwardedFor.split(',').map((ip) => ip.trim());
-        const ip = ips[0];
-        if (ip && ip !== '0.0.0.0') {
-            return ip;
-        }
-    }
-    const realIP = req.headers?.get?.('x-real-ip') ||
-        req.headers?.['x-real-ip'] ||
-        req.headers?.['X-Real-IP'];
-    if (realIP && realIP !== '0.0.0.0') {
-        return realIP.trim();
-    }
-    // Try req.ip (from Express/Next.js)
-    if (req.ip && req.ip !== '0.0.0.0') {
-        return req.ip;
-    }
-    // For localhost, detect if we're running locally
-    if (typeof window === 'undefined') {
-        const hostname = req.headers?.get?.('host') || req.headers?.['host'];
-        if (hostname &&
-            (hostname.includes('localhost') ||
-                hostname.includes('127.0.0.1') ||
-                hostname.startsWith('192.168.'))) {
-            return '127.0.0.1'; // Localhost IP
-        }
-    }
-    // If no IP found and we're in development, return localhost
-    if (typeof process !== 'undefined' && process.env?.NODE_ENV === 'development') {
-        return '127.0.0.1'; // Localhost for development
-    }
-    return '0.0.0.0';
-}
-
 exports.AnalyticsService = AnalyticsService;
 exports.AttributionDetector = AttributionDetector;
 exports.DeviceDetector = DeviceDetector;