user-analytics-tracker 4.3.0 → 4.5.0

package/dist/index.d.cts

@@ -137,6 +137,7 @@ interface AnalyticsConfig {
         apiKey?: string;
         baseUrl?: string;
         timeout?: number;
+        ip?: string;
     };
     fieldStorage?: {
         ipLocation?: FieldStorageConfig$1;
@@ -254,22 +255,28 @@ declare class DeviceDetector {
  *
  * 1) Browser / client-side:
  *    - Do NOT pass an IP. Call getCompleteIPLocation(config) with no IP.
- *    - The request goes: user's browser → ipwho.is; ipwho.is sees the visitor's
- *      public IP and returns it. The IP is never stored or sent by your code.
- *    - For config.apiKey: avoid hardcoding. Use a build-time env var or omit (free tier).
+ *    - The request goes: user's browser → API; the API sees the visitor's IP and returns it.
+ *    - For config.apiKey: use env var or omit (free tier).
  *
  * 2) Server-side (Node/Express/Next etc.):
- *    - Get the visitor's IP from the incoming request with getIPFromRequest(req).
- *    - Then call getIPLocation(userIp, config) to geolocate that IP.
- *    - Keep apiKey in process.env (e.g. IPWHOIS_API_KEY); never commit it.
+ *    - Get the visitor's IP with getIPFromRequest(req), then call getIPLocation(userIp, config).
+ *    - Or pass ip + apiKey in config: getCompleteIPLocation({ baseUrl, apiKey, ip: userIp }).
+ *    - Keep apiKey in process.env; never commit it.
+ *
+ * 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.
  */
 /**
  * IP Geolocation configuration interface
+ * Supports ipwho.is (free/paid) and ipwhois.pro (paid: baseUrl/{IP}?key=API_KEY)
  */
 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 */
+    ip?: string;
 }
 /**
  * Get complete IP location data from ipwho.is API (HIGH PRIORITY)
@@ -280,13 +287,17 @@ interface IPGeolocationConfig {
  *
  * @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',
  * });
  * ```
  */
@@ -322,8 +333,12 @@ declare function getPublicIP(config?: IPGeolocationConfig): Promise<string | nul
  * 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>',
  * });
  * ```
  *

package/dist/index.d.ts

@@ -137,6 +137,7 @@ interface AnalyticsConfig {
         apiKey?: string;
         baseUrl?: string;
         timeout?: number;
+        ip?: string;
     };
     fieldStorage?: {
         ipLocation?: FieldStorageConfig$1;
@@ -254,22 +255,28 @@ declare class DeviceDetector {
  *
  * 1) Browser / client-side:
  *    - Do NOT pass an IP. Call getCompleteIPLocation(config) with no IP.
- *    - The request goes: user's browser → ipwho.is; ipwho.is sees the visitor's
- *      public IP and returns it. The IP is never stored or sent by your code.
- *    - For config.apiKey: avoid hardcoding. Use a build-time env var or omit (free tier).
+ *    - The request goes: user's browser → API; the API sees the visitor's IP and returns it.
+ *    - For config.apiKey: use env var or omit (free tier).
  *
  * 2) Server-side (Node/Express/Next etc.):
- *    - Get the visitor's IP from the incoming request with getIPFromRequest(req).
- *    - Then call getIPLocation(userIp, config) to geolocate that IP.
- *    - Keep apiKey in process.env (e.g. IPWHOIS_API_KEY); never commit it.
+ *    - Get the visitor's IP with getIPFromRequest(req), then call getIPLocation(userIp, config).
+ *    - Or pass ip + apiKey in config: getCompleteIPLocation({ baseUrl, apiKey, ip: userIp }).
+ *    - Keep apiKey in process.env; never commit it.
+ *
+ * 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.
  */
 /**
  * IP Geolocation configuration interface
+ * Supports ipwho.is (free/paid) and ipwhois.pro (paid: baseUrl/{IP}?key=API_KEY)
  */
 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 */
+    ip?: string;
 }
 /**
  * Get complete IP location data from ipwho.is API (HIGH PRIORITY)
@@ -280,13 +287,17 @@ interface IPGeolocationConfig {
  *
  * @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',
  * });
  * ```
  */
@@ -322,8 +333,12 @@ declare function getPublicIP(config?: IPGeolocationConfig): Promise<string | nul
  * 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>',
  * });
  * ```
  *

package/dist/index.esm.js

@@ -621,13 +621,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',
  * });
  * ```
  */
@@ -640,17 +644,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',
@@ -730,6 +742,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) {
@@ -740,7 +756,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)}`;
@@ -787,8 +803,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>',
  * });
  * ```
  *
@@ -812,14 +832,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: {