user-analytics-tracker 4.5.0 → 4.6.0

package/dist/index.d.cts

@@ -138,6 +138,8 @@ interface AnalyticsConfig {
         baseUrl?: string;
         timeout?: number;
         ip?: string;
+        /** Proxy URL for paid users in browser: client calls this; your backend calls ipwho.is with API key (key never in browser). */
+        proxyUrl?: string;
     };
     fieldStorage?: {
         ipLocation?: FieldStorageConfig$1;
@@ -266,17 +268,28 @@ declare class DeviceDetector {
  * 3) Paid subscription (e.g. ipwhois.pro):
  *    - URL format: https://ipwhois.pro/{IP}?key=YOUR_API_KEY
  *    - Pass baseUrl: 'https://ipwhois.pro', apiKey, and ip when you have the IP.
+ *
+ * 4) Paid users in the browser (recommended): use a proxy so API key and IP are not exposed.
+ *    - Set ipGeolocation.proxyUrl to your backend route (e.g. '/api/ip-geolocation').
+ *    - Browser calls the proxy; proxy calls ipwho.is/ipwhois.pro with API key from env and request IP.
+ *    - See docs for proxy contract and example backend implementation.
  */
 /**
  * IP Geolocation configuration interface
- * Supports ipwho.is (free/paid) and ipwhois.pro (paid: baseUrl/{IP}?key=API_KEY)
+ * Supports ipwho.is (free/paid), ipwhois.pro (paid), and proxy (paid users in browser - no key in client).
  */
 interface IPGeolocationConfig {
     apiKey?: string;
     baseUrl?: string;
     timeout?: number;
-    /** When provided (e.g. server-side or paid flow), lookup this IP. URL becomes baseUrl/{ip}?key=API_KEY */
+    /** When provided (server-side), lookup this IP. Ignored when proxyUrl is set. */
     ip?: string;
+    /**
+     * When set, the client calls this URL instead of ipwho.is. Your backend holds the API key and
+     * calls ipwho.is/ipwhois.pro server-side. Use for paid users in the browser so key and IP are not exposed.
+     * Contract: GET proxyUrl → auto-detect IP; GET proxyUrl?ip=1.2.3.4 → lookup that IP. Response = same JSON as ipwho.is.
+     */
+    proxyUrl?: string;
 }
 /**
  * Get complete IP location data from ipwho.is API (HIGH PRIORITY)
@@ -299,6 +312,9 @@ interface IPGeolocationConfig {
  *   apiKey: '<key>',
  *   ip: '203.0.113.42',
  * });
+ *
+ * // Paid users in browser: use proxy so API key is not exposed (GET proxyUrl → same JSON)
+ * const location = await getCompleteIPLocation({ proxyUrl: '/api/ip-geolocation', timeout: 5000 });
  * ```
  */
 declare function getCompleteIPLocation(config?: IPGeolocationConfig): Promise<IPLocation | null>;

package/dist/index.d.ts

@@ -138,6 +138,8 @@ interface AnalyticsConfig {
         baseUrl?: string;
         timeout?: number;
         ip?: string;
+        /** Proxy URL for paid users in browser: client calls this; your backend calls ipwho.is with API key (key never in browser). */
+        proxyUrl?: string;
     };
     fieldStorage?: {
         ipLocation?: FieldStorageConfig$1;
@@ -266,17 +268,28 @@ declare class DeviceDetector {
  * 3) Paid subscription (e.g. ipwhois.pro):
  *    - URL format: https://ipwhois.pro/{IP}?key=YOUR_API_KEY
  *    - Pass baseUrl: 'https://ipwhois.pro', apiKey, and ip when you have the IP.
+ *
+ * 4) Paid users in the browser (recommended): use a proxy so API key and IP are not exposed.
+ *    - Set ipGeolocation.proxyUrl to your backend route (e.g. '/api/ip-geolocation').
+ *    - Browser calls the proxy; proxy calls ipwho.is/ipwhois.pro with API key from env and request IP.
+ *    - See docs for proxy contract and example backend implementation.
  */
 /**
  * IP Geolocation configuration interface
- * Supports ipwho.is (free/paid) and ipwhois.pro (paid: baseUrl/{IP}?key=API_KEY)
+ * Supports ipwho.is (free/paid), ipwhois.pro (paid), and proxy (paid users in browser - no key in client).
  */
 interface IPGeolocationConfig {
     apiKey?: string;
     baseUrl?: string;
     timeout?: number;
-    /** When provided (e.g. server-side or paid flow), lookup this IP. URL becomes baseUrl/{ip}?key=API_KEY */
+    /** When provided (server-side), lookup this IP. Ignored when proxyUrl is set. */
     ip?: string;
+    /**
+     * When set, the client calls this URL instead of ipwho.is. Your backend holds the API key and
+     * calls ipwho.is/ipwhois.pro server-side. Use for paid users in the browser so key and IP are not exposed.
+     * Contract: GET proxyUrl → auto-detect IP; GET proxyUrl?ip=1.2.3.4 → lookup that IP. Response = same JSON as ipwho.is.
+     */
+    proxyUrl?: string;
 }
 /**
  * Get complete IP location data from ipwho.is API (HIGH PRIORITY)
@@ -299,6 +312,9 @@ interface IPGeolocationConfig {
  *   apiKey: '<key>',
  *   ip: '203.0.113.42',
  * });
+ *
+ * // Paid users in browser: use proxy so API key is not exposed (GET proxyUrl → same JSON)
+ * const location = await getCompleteIPLocation({ proxyUrl: '/api/ip-geolocation', timeout: 5000 });
  * ```
  */
 declare function getCompleteIPLocation(config?: IPGeolocationConfig): Promise<IPLocation | null>;

package/dist/index.esm.js

@@ -633,6 +633,9 @@ function checkAndSetLocationConsent(msisdn) {
  *   apiKey: '<key>',
  *   ip: '203.0.113.42',
  * });
+ *
+ * // Paid users in browser: use proxy so API key is not exposed (GET proxyUrl → same JSON)
+ * const location = await getCompleteIPLocation({ proxyUrl: '/api/ip-geolocation', timeout: 5000 });
  * ```
  */
 async function getCompleteIPLocation(config) {
@@ -640,30 +643,33 @@ async function getCompleteIPLocation(config) {
     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;
-    const configIp = config?.ip?.trim();
+    const timeout = config?.timeout ?? 5000;
     try {
-        // 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;
-        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)}`;
-            }
+        let url;
+        if (config?.proxyUrl?.trim()) {
+            // Paid users in browser: call proxy; proxy holds API key and calls ipwho.is server-side (no key/IP exposed)
+            url = config.proxyUrl.trim();
         }
         else {
-            // Auto-detect requestor IP (root path + optional key)
-            url += '/';
-            if (apiKey) {
-                url += `?key=${encodeURIComponent(apiKey)}`;
+            // Direct call to ipwho.is / ipwhois.pro
+            const baseUrl = config?.baseUrl || 'https://ipwho.is';
+            const apiKey = config?.apiKey;
+            const configIp = config?.ip?.trim();
+            url = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+            if (configIp) {
+                url += `/${encodeURIComponent(configIp)}`;
+                if (apiKey) {
+                    url += `?key=${encodeURIComponent(apiKey)}`;
+                }
+            }
+            else {
+                url += '/';
+                if (apiKey) {
+                    url += `?key=${encodeURIComponent(apiKey)}`;
+                }
             }
         }
-        // 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
+        // Call API or proxy: same response shape (ipwho.is JSON)
         const response = await fetch(url, {
             method: 'GET',
             headers: {
@@ -751,12 +757,14 @@ async function getPublicIP(config) {
     if (completeLocation?.ip) {
         return completeLocation.ip;
     }
-    // Fallback: try direct IP fetch (less efficient, lower priority)
+    // Fallback: try direct IP fetch (only when not using proxy)
+    if (config?.proxyUrl?.trim()) {
+        return null;
+    }
     try {
         const baseUrl = config?.baseUrl || 'https://ipwho.is';
         const timeout = config?.timeout || 5000;
         const apiKey = config?.apiKey;
-        // 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)}`;
@@ -828,23 +836,27 @@ async function getIPLocation(ip, config) {
         return null;
     }
     try {
-        // Use provided config or defaults
-        const baseUrl = config?.baseUrl || 'https://ipwho.is';
-        const timeout = config?.timeout || 5000;
-        const apiKey = config?.apiKey;
-        // 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 += `/${encodeURIComponent(ip)}`;
-        if (apiKey) {
-            url += `?key=${encodeURIComponent(apiKey)}`;
+        const timeout = config?.timeout ?? 5000;
+        let url;
+        if (config?.proxyUrl?.trim()) {
+            const proxy = config.proxyUrl.trim();
+            const sep = proxy.includes('?') ? '&' : '?';
+            url = `${proxy}${sep}ip=${encodeURIComponent(ip)}`;
+        }
+        else {
+            const baseUrl = config?.baseUrl || 'https://ipwho.is';
+            const apiKey = config?.apiKey;
+            url = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+            url += `/${encodeURIComponent(ip)}`;
+            if (apiKey) {
+                url += `?key=${encodeURIComponent(apiKey)}`;
+            }
         }
-        // Using ipwho.is / ipwhois.pro API
         const response = await fetch(url, {
             method: 'GET',
             headers: {
                 Accept: 'application/json',
             },
-            // Add timeout to prevent hanging
             signal: AbortSignal.timeout(timeout),
         });
         if (!response.ok) {