user-analytics-tracker 4.2.0 → 4.4.0

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+# [4.4.0](https://github.com/Switch-org/analytics-tracker/compare/v4.3.0...v4.4.0) (2026-01-30)
+
+
+### Features
+
+* update geo-location , essential data ([5511ff5](https://github.com/Switch-org/analytics-tracker/commit/5511ff545bc7850dea83e50c64270f8c112243e9))
+* update geo-location , essential dataa ([a8f0c67](https://github.com/Switch-org/analytics-tracker/commit/a8f0c6765f6e91e19ab45cedf197d9df4820e3a7))
+* updated key_api flow for customers ([5c58315](https://github.com/Switch-org/analytics-tracker/commit/5c58315f856ab924cc998ebfc84a88e93d5253d3))
+
+# [4.3.0](https://github.com/Switch-org/analytics-tracker/compare/v4.2.0...v4.3.0) (2026-01-30)
+
+
+### Features
+
+* updated api_key flow for consumers ([#35](https://github.com/Switch-org/analytics-tracker/issues/35)) ([b5ce7de](https://github.com/Switch-org/analytics-tracker/commit/b5ce7de0201b69f085faf0c003427a961a4ec471))
+
 # [4.2.0](https://github.com/Switch-org/analytics-tracker/compare/v4.1.2...v4.2.0) (2026-01-21)
 
 

package/README.md

@@ -95,6 +95,14 @@ const analytics = useAnalytics({
     // Metrics configuration
     enableMetrics: false,       // Enable metrics collection (default: false)
     
+    // IP Geolocation - optional. Use apiKey (env var) for higher rate limits; for paid ipwhois.pro add baseUrl + ip when you have it
+    ipGeolocation: {
+      apiKey: import.meta.env.VITE_IPWHOIS_API_KEY,
+      baseUrl: 'https://ipwho.is', // or 'https://ipwhois.pro' for paid (URL: baseUrl/{IP}?key=API_KEY)
+      timeout: 5000,
+      ip: undefined, // set when you have the IP (e.g. server-side: getIPFromRequest(req))
+    },
+    
     // Field storage configuration (optional) - control which fields are stored
     fieldStorage: {
       ipLocation: { mode: 'essential' },    // IP location fields (includes connection data)
@@ -156,13 +164,20 @@ Use environment variables for different environments:
 ```tsx
 // .env.local (development)
 // NEXT_PUBLIC_ANALYTICS_API=https://api-dev.yourcompany.com/analytics
+// NEXT_PUBLIC_IPWHOIS_API_KEY=your-ipwho-is-key  // optional, for higher rate limits
 
 // .env.production
 // NEXT_PUBLIC_ANALYTICS_API=https://api.yourcompany.com/analytics
+// NEXT_PUBLIC_IPWHOIS_API_KEY=your-ipwho-is-key
 
 const analytics = useAnalytics({
   config: {
     apiEndpoint: process.env.NEXT_PUBLIC_ANALYTICS_API || '/api/analytics',
+    // Optional: your own ipwho.is API key (use env var; omit for free tier)
+    ipGeolocation: {
+      apiKey: process.env.NEXT_PUBLIC_IPWHOIS_API_KEY,
+      timeout: 5000,
+    },
   },
 });
 ```
@@ -341,6 +356,13 @@ interface AnalyticsConfig {
   logLevel?: LogLevel;       // 'silent' | 'error' | 'warn' | 'info' | 'debug' (default: 'warn')
   // Metrics options
   enableMetrics?: boolean;   // Enable metrics collection (default: false)
+  // IP Geolocation (ipwho.is) - pass your own API key via env var for higher rate limits
+  ipGeolocation?: {
+    apiKey?: string;   // Use env var. Required for paid; optional for ipwho.is free tier.
+    baseUrl?: string;  // Default: 'https://ipwho.is'. Use 'https://ipwhois.pro' for paid (URL: baseUrl/{IP}?key=API_KEY)
+    timeout?: number;  // Default: 5000
+    ip?: string;       // When provided (paid/server-side), lookup this IP
+  };
   // Existing options
   autoSend?: boolean;
   enableLocation?: boolean;
@@ -728,11 +750,16 @@ import { getIPLocation, getIPFromRequest } from 'user-analytics-tracker';
 
 // In your API route (Next.js example)
 export async function POST(req: Request) {
-  // Extract IP from request headers
   const ip = getIPFromRequest(req);
-  
-  // Get location data from IP
+
+  // Free tier (ipwho.is)
   const location = await getIPLocation(ip);
+
+  // Paid (ipwhois.pro): baseUrl/{IP}?key=API_KEY
+  // const location = await getIPLocation(ip, {
+  //   baseUrl: 'https://ipwhois.pro',
+  //   apiKey: process.env.IPWHOIS_PRO_API_KEY,
+  // });
   // location contains: country, region, city, lat, lon, timezone, isp, etc.
 }
 ```
@@ -981,7 +1008,7 @@ MIT © [Switch Org](https://github.com/switch-org)
 
 ## 🙏 Acknowledgments
 
-- Uses [ipwho.is](https://ipwho.is/) for free IP geolocation and accurate connection data
+- Uses [ipwho.is](https://ipwho.is/) for IP geolocation and connection data (free tier; consumers can pass their own API key via `config.ipGeolocation.apiKey` for higher rate limits)
 - Built with modern web APIs (User-Agent Client Hints, Geolocation API)
 
 <!-- ## 📞 Support

package/dist/index.cjs.js

@@ -625,13 +625,17 @@ function checkAndSetLocationConsent(msisdn) {
  *
  * @example
  * ```typescript
- * // Without API key (free tier)
+ * // Without API key (free tier) - auto-detect requestor IP
  * const location = await getCompleteIPLocation();
  *
- * // With API key (for higher rate limits)
+ * // With API key (higher rate limits)
+ * const location = await getCompleteIPLocation({ apiKey: '<key>', baseUrl: 'https://ipwho.is' });
+ *
+ * // Paid / server-side: provide IP + API key (e.g. ipwhois.pro)
  * const location = await getCompleteIPLocation({
- *   apiKey: '<your-api-key>',
- *   baseUrl: 'https://ipwho.is'
+ *   baseUrl: 'https://ipwhois.pro',
+ *   apiKey: '<key>',
+ *   ip: '203.0.113.42',
  * });
  * ```
  */
@@ -644,17 +648,25 @@ async function getCompleteIPLocation(config) {
     const baseUrl = config?.baseUrl || 'https://ipwho.is';
     const timeout = config?.timeout || 5000;
     const apiKey = config?.apiKey;
+    const configIp = config?.ip?.trim();
     try {
-        // Build URL with optional API key
+        // Build URL: baseUrl/{IP}?key=API_KEY when IP provided (paid/server-side); else baseUrl/ or baseUrl?key=...
         let url = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
-        // Add API key as query parameter if provided
-        if (apiKey) {
-            url += `?key=${encodeURIComponent(apiKey)}`;
+        if (configIp) {
+            // Paid / server-side: lookup specific IP. Format: https://ipwhois.pro/{IP}?key=YOUR_API_KEY
+            url += `/${encodeURIComponent(configIp)}`;
+            if (apiKey) {
+                url += `?key=${encodeURIComponent(apiKey)}`;
+            }
         }
         else {
+            // Auto-detect requestor IP (root path + optional key)
             url += '/';
+            if (apiKey) {
+                url += `?key=${encodeURIComponent(apiKey)}`;
+            }
         }
-        // Call ipwho.is without IP parameter - it auto-detects user's IP and returns everything
+        // Call API: with IP path it returns that IP's location; without path it returns requestor's IP
         // This is the HIGH PRIORITY source - gets IP, location, connection, timezone, flag, etc. in one call
         const response = await fetch(url, {
             method: 'GET',
@@ -734,6 +746,10 @@ async function getCompleteIPLocation(config) {
  * ```
  */
 async function getPublicIP(config) {
+    // When consumer provides IP (paid/server-side), return it without fetching
+    if (config?.ip?.trim()) {
+        return config.ip.trim();
+    }
     // Try to get complete location first (includes IP)
     const completeLocation = await getCompleteIPLocation(config);
     if (completeLocation?.ip) {
@@ -744,7 +760,7 @@ async function getPublicIP(config) {
         const baseUrl = config?.baseUrl || 'https://ipwho.is';
         const timeout = config?.timeout || 5000;
         const apiKey = config?.apiKey;
-        // Build URL with optional API key
+        // Build URL with optional API key (auto-detect requestor IP)
         let url = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
         if (apiKey) {
             url += `?key=${encodeURIComponent(apiKey)}`;
@@ -791,8 +807,12 @@ async function getPublicIP(config) {
  * const location = await getIPLocation('203.0.113.42');
  *
  * // With API key
+ * const location = await getIPLocation('203.0.113.42', { apiKey: '<key>' });
+ *
+ * // Paid ipwhois.pro: same URL format baseUrl/{IP}?key=API_KEY
  * const location = await getIPLocation('203.0.113.42', {
- *   apiKey: '<your-api-key>'
+ *   baseUrl: 'https://ipwhois.pro',
+ *   apiKey: '<key>',
  * });
  * ```
  *
@@ -816,14 +836,13 @@ async function getIPLocation(ip, config) {
         const baseUrl = config?.baseUrl || 'https://ipwho.is';
         const timeout = config?.timeout || 5000;
         const apiKey = config?.apiKey;
-        // Build URL with IP and optional API key
+        // Build URL: baseUrl/{IP}?key=API_KEY (same format as ipwhois.pro paid: https://ipwhois.pro/{IP}?key=YOUR_API_KEY)
         let url = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
-        url += `/${ip}`;
-        // Add API key as query parameter if provided
+        url += `/${encodeURIComponent(ip)}`;
         if (apiKey) {
             url += `?key=${encodeURIComponent(apiKey)}`;
         }
-        // Using ipwho.is API
+        // Using ipwho.is / ipwhois.pro API
         const response = await fetch(url, {
             method: 'GET',
             headers: {
@@ -3443,11 +3462,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
+ *   },
  * });
  * ```
  */
@@ -3468,6 +3493,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)
             });
         }
     }, [
@@ -3482,6 +3508,7 @@ function useAnalytics(options = {}) {
         config?.sessionTimeout,
         config?.fieldStorage,
         config?.ipLocationFields,
+        config?.ipGeolocation,
     ]);
     const [networkInfo, setNetworkInfo] = react.useState(null);
     const [deviceInfo, setDeviceInfo] = react.useState(null);