user-analytics-tracker 4.1.2 → 4.3.0

package/dist/index.d.cts

@@ -133,6 +133,11 @@ interface AnalyticsConfig {
     sessionTimeout?: number;
     logLevel?: LogLevel$1;
     enableMetrics?: boolean;
+    ipGeolocation?: {
+        apiKey?: string;
+        baseUrl?: string;
+        timeout?: number;
+    };
     fieldStorage?: {
         ipLocation?: FieldStorageConfig$1;
         deviceInfo?: FieldStorageConfig$1;
@@ -160,11 +165,12 @@ type IPLocationFieldConfig = FieldStorageConfig$1;
  * Default essential fields for IP location storage
  * These fields are stored when mode is 'essential' (default)
  */
-declare const DEFAULT_ESSENTIAL_IP_FIELDS: readonly ["ip", "country", "countryCode", "region", "city", "lat", "lon", "continent", "continentCode", "type", "isEu", "isp", "connection", "connection.asn", "connection.org", "connection.isp", "connection.domain", "timezone", "timezoneDetails", "timezoneDetails.id", "timezoneDetails.abbr", "timezoneDetails.utc", "flag.emoji"];
+declare const DEFAULT_ESSENTIAL_IP_FIELDS: readonly ["ip", "countryCode", "city", "lat", "lon", "type", "isEu", "isp", "connection", "connection.asn", "connection.org", "connection.isp", "connection.domain"];
 /**
  * Default essential fields for Device Info storage
+ * In essential mode, only OS and browser are stored
  */
-declare const DEFAULT_ESSENTIAL_DEVICE_FIELDS: readonly ["type", "os", "osVersion", "browser", "browserVersion", "deviceModel", "deviceBrand", "userAgent"];
+declare const DEFAULT_ESSENTIAL_DEVICE_FIELDS: readonly ["os", "browser"];
 /**
  * Default essential fields for Network Info storage
  *
@@ -180,7 +186,7 @@ declare const DEFAULT_ESSENTIAL_LOCATION_FIELDS: readonly ["lat", "lon", "source
 /**
  * Default essential fields for Attribution Info storage
  */
-declare const DEFAULT_ESSENTIAL_ATTRIBUTION_FIELDS: readonly ["landingUrl", "path", "hostname", "referrerUrl", "referrerDomain", "navigationType", "isReload", "isBackForward", "utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content"];
+declare const DEFAULT_ESSENTIAL_ATTRIBUTION_FIELDS: readonly ["landingUrl", "path"];
 interface AnalyticsEvent {
     sessionId: string;
     pageUrl: string;
@@ -236,6 +242,100 @@ declare class DeviceDetector {
     private static getDefaultDeviceInfo;
 }
 
+/**
+ * IP Geolocation Service
+ * Fetches location data (country, region, city) from user's IP address
+ * Uses ipwho.is API (supports optional API key for higher rate limits)
+ *
+ * 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
+ *
+ * --- Where does the IP come from? (secure usage) ---
+ *
+ * 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).
+ *
+ * 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.
+ */
+/**
+ * IP Geolocation configuration interface
+ */
+interface IPGeolocationConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    timeout?: number;
+}
+/**
+ * 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
+ *
+ * @param config - Optional configuration for API key and base URL
+ * @returns Promise<IPLocation | null> - Complete IP location data, or null if unavailable
+ *
+ * @example
+ * ```typescript
+ * // Without API key (free tier)
+ * const location = await getCompleteIPLocation();
+ *
+ * // With API key (for higher rate limits)
+ * const location = await getCompleteIPLocation({
+ *   apiKey: '<your-api-key>',
+ *   baseUrl: 'https://ipwho.is'
+ * });
+ * ```
+ */
+declare function getCompleteIPLocation(config?: IPGeolocationConfig): Promise<IPLocation | null>;
+/**
+ * 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
+ *
+ * @param config - Optional configuration for API key and base URL
+ * @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"
+ * ```
+ */
+declare function getPublicIP(config?: IPGeolocationConfig): Promise<string | null>;
+/**
+ * Get location from IP address using ipwho.is API (HIGH PRIORITY)
+ *
+ * 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
+ *
+ * @param ip - IP address to geolocate
+ * @param config - Optional configuration for API key and base URL
+ * @returns Promise<IPLocation | null> - IP location data, or null if unavailable
+ *
+ * @example
+ * ```typescript
+ * // Without API key
+ * const location = await getIPLocation('203.0.113.42');
+ *
+ * // With API key
+ * const location = await getIPLocation('203.0.113.42', {
+ *   apiKey: '<your-api-key>'
+ * });
+ * ```
+ *
+ * Note: If you don't have an IP yet, use getCompleteIPLocation() which gets everything in one call
+ */
+declare function getIPLocation(ip: string, config?: IPGeolocationConfig): Promise<IPLocation | null>;
+/**
+ * Get IP address from request headers
+ * Handles various proxy headers (x-forwarded-for, x-real-ip, etc.)
+ */
+declare function getIPFromRequest(req: Request | any): string;
+
 /**
  * Location Detector
  * Detects GPS location with consent management, falls back to IP-based location API
@@ -247,6 +347,22 @@ declare class LocationDetector {
     private static locationConsentLoggedRef;
     private static ipLocationFetchingRef;
     private static lastIPLocationRef;
+    private static ipGeolocationConfig;
+    /**
+     * Configure IP geolocation settings (API key, base URL, timeout)
+     *
+     * @param config - IP geolocation configuration
+     *
+     * @example
+     * ```typescript
+     * LocationDetector.configureIPGeolocation({
+     *   apiKey: '<your-ipwho-is-api-key>',
+     *   baseUrl: 'https://ipwho.is',
+     *   timeout: 5000
+     * });
+     * ```
+     */
+    static configureIPGeolocation(config: IPGeolocationConfig | null): void;
     /**
      * Detect location using IP-based API only (no GPS, no permission needed)
      * Fast and automatic - works immediately without user interaction
@@ -400,6 +516,8 @@ declare class AnalyticsService {
     private static queueManager;
     private static config;
     private static isInitialized;
+    private static seenEventKeys;
+    private static readonly DEDUPE_CACHE_SIZE;
     /**
      * Configure the analytics service
      *
@@ -446,6 +564,7 @@ declare class AnalyticsService {
     private static generateEventId;
     /**
      * Send a batch of events with retry logic
+     * Filters out invalid and duplicate events before sending
      */
     private static sendBatch;
     /**
@@ -455,12 +574,13 @@ declare class AnalyticsService {
     /**
      * Track user journey/analytics event
      * Events are automatically queued and batched
+     * Duplicate events and events with null values are filtered out
      */
     static trackEvent(event: Omit<AnalyticsEvent, 'eventId' | 'timestamp'>): Promise<void>;
     /**
      * Track user journey with full context
      */
-    static trackUserJourney({ sessionId, pageUrl, networkInfo, deviceInfo, location, attribution, ipLocation, userId, customData, pageVisits, interactions, }: {
+    static trackUserJourney({ sessionId, pageUrl, networkInfo, deviceInfo, location, attribution, ipLocation, userId, customData, pageVisits: _pageVisits, interactions: _interactions, }: {
         sessionId: string;
         pageUrl: string;
         networkInfo?: NetworkInfo;
@@ -506,6 +626,7 @@ declare class AnalyticsService {
         location?: any;
         attribution?: AttributionInfo;
         userId?: string;
+        ipLocation?: any;
     }): Promise<void>;
     /**
      * Track a page view event (Firebase/GA-style)
@@ -526,7 +647,16 @@ declare class AnalyticsService {
      * });
      * ```
      */
-    static trackPageView(pageName?: string, parameters?: Record<string, any>): Promise<void>;
+    static trackPageView(pageName?: string, parameters?: Record<string, any>, context?: {
+        sessionId?: string;
+        pageUrl?: string;
+        networkInfo?: NetworkInfo;
+        deviceInfo?: DeviceInfo;
+        location?: any;
+        attribution?: AttributionInfo;
+        userId?: string;
+        ipLocation?: any;
+    }): Promise<void>;
     /**
      * Manually flush the event queue
      * Useful for ensuring events are sent before page unload
@@ -560,11 +690,17 @@ interface UseAnalyticsOptions {
 /**
  * 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
+ *   },
  * });
  * ```
  */
@@ -644,68 +780,58 @@ declare function clearLocationConsent(): void;
 declare function checkAndSetLocationConsent(msisdn?: string | null): boolean;
 
 /**
- * IP Geolocation Service
- * Fetches location data (country, region, city) from user's IP address
- * Uses ipwho.is API (no API key required)
+ * Transform IP location data from API format (snake_case) to backend-expected format (camelCase)
+ * Supports configurable field storage to optimize storage capacity
  *
- * 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
+ * @param ipLocation - Raw IP location data from ipwho.is API
+ * @param config - Optional configuration for which fields to store
+ * @returns Transformed IP location data matching backend schema (only includes configured fields)
  */
+declare function transformIPLocationForBackend(ipLocation: IPLocation | null | any, config?: FieldStorageConfig$1): Record<string, any> | null;
+
 /**
- * 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<IPLocation | null> - Complete IP location data, or null if unavailable
- *
- * @example
- * ```typescript
- * const location = await getCompleteIPLocation();
- * console.log('IP:', location?.ip);
- * console.log('Country:', location?.country);
- * console.log('ISP:', location?.connection?.isp);
- * ```
+ * Required fields for analytics events
+ * Events missing these fields will be filtered out
  */
-declare function getCompleteIPLocation(): Promise<IPLocation | null>;
+interface RequiredEventFields {
+    ip?: string | null;
+    lat?: number | null;
+    lon?: number | null;
+    mobile?: boolean | null;
+    location?: string | null;
+    msisdn?: string | null;
+    session?: string | null;
+    operators?: string | null;
+    page?: string | null;
+    pageUrl?: string | null;
+    eventType?: string | null;
+    companyName?: string | null;
+    eventId?: string | null;
+    timestamp?: Date | string | null;
+    gps?: boolean | null;
+    os?: string | null;
+    browser?: string | null;
+    serviceId?: string | null;
+}
 /**
- * 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"
- * ```
+ * Extract required fields from analytics event
  */
-declare function getPublicIP(): Promise<string | null>;
+declare function extractRequiredFields(event: AnalyticsEvent): RequiredEventFields;
 /**
- * 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
+ * Validate that event has minimum required fields
+ * Returns true if valid, false if should be filtered out
  */
-declare function getIPLocation(ip: string): Promise<IPLocation | null>;
+declare function validateRequiredFields(fields: RequiredEventFields): boolean;
 /**
- * Get IP address from request headers
- * Handles various proxy headers (x-forwarded-for, x-real-ip, etc.)
+ * Validate and filter event
+ * Returns null if event should be filtered out, otherwise returns the event
  */
-declare function getIPFromRequest(req: Request | any): string;
-
+declare function validateEvent(event: AnalyticsEvent): AnalyticsEvent | null;
 /**
- * Transform IP location data from API format (snake_case) to backend-expected format (camelCase)
- * Supports configurable field storage to optimize storage capacity
- *
- * @param ipLocation - Raw IP location data from ipwho.is API
- * @param config - Optional configuration for which fields to store
- * @returns Transformed IP location data matching backend schema (only includes configured fields)
+ * Generate a unique key for deduplication
+ * Based on: sessionId + pageUrl + eventName + timestamp (rounded to nearest second)
  */
-declare function transformIPLocationForBackend(ipLocation: IPLocation | null, config?: FieldStorageConfig$1): Record<string, any> | null;
+declare function generateDeduplicationKey(event: AnalyticsEvent): string;
 
 /**
  * Generic field storage transformer
@@ -745,5 +871,5 @@ declare class Logger {
 }
 declare const logger: Logger;
 
-export { AnalyticsService, AttributionDetector, DEFAULT_ESSENTIAL_ATTRIBUTION_FIELDS, DEFAULT_ESSENTIAL_DEVICE_FIELDS, DEFAULT_ESSENTIAL_IP_FIELDS, DEFAULT_ESSENTIAL_LOCATION_FIELDS, DEFAULT_ESSENTIAL_NETWORK_FIELDS, DeviceDetector, LocationDetector, NetworkDetector, QueueManager, checkAndSetLocationConsent, clearLocationConsent, clearSession, useAnalytics as default, filterFieldsByConfig, getCompleteIPLocation, getIPFromRequest, getIPLocation, getLocationConsentTimestamp, getOrCreateSession, getOrCreateUserId, getPublicIP, getSession, hasLocationConsent, initDebug, loadJSON, loadSessionJSON, logger, saveJSON, saveSessionJSON, setLocationConsentGranted, trackPageVisit, transformIPLocationForBackend, updateSessionActivity, useAnalytics };
-export type { AnalyticsConfig, AnalyticsEvent, AttributionInfo, DeviceInfo, DeviceType, FieldStorageConfig$1 as FieldStorageConfig, FieldStorageConfig as FieldStorageConfigType, IPLocation, IPLocationFieldConfig, LocationInfo, LogLevel$1 as LogLevel, NetworkInfo, NetworkType, QueueConfig, QueuedEvent, SessionInfo, UseAnalyticsOptions, UseAnalyticsReturn };
+export { AnalyticsService, AttributionDetector, DEFAULT_ESSENTIAL_ATTRIBUTION_FIELDS, DEFAULT_ESSENTIAL_DEVICE_FIELDS, DEFAULT_ESSENTIAL_IP_FIELDS, DEFAULT_ESSENTIAL_LOCATION_FIELDS, DEFAULT_ESSENTIAL_NETWORK_FIELDS, DeviceDetector, LocationDetector, NetworkDetector, QueueManager, checkAndSetLocationConsent, clearLocationConsent, clearSession, useAnalytics as default, extractRequiredFields, filterFieldsByConfig, generateDeduplicationKey, getCompleteIPLocation, getIPFromRequest, getIPLocation, getLocationConsentTimestamp, getOrCreateSession, getOrCreateUserId, getPublicIP, getSession, hasLocationConsent, initDebug, loadJSON, loadSessionJSON, logger, saveJSON, saveSessionJSON, setLocationConsentGranted, trackPageVisit, transformIPLocationForBackend, updateSessionActivity, useAnalytics, validateEvent, validateRequiredFields };
+export type { AnalyticsConfig, AnalyticsEvent, AttributionInfo, DeviceInfo, DeviceType, FieldStorageConfig$1 as FieldStorageConfig, FieldStorageConfig as FieldStorageConfigType, IPGeolocationConfig, IPLocation, IPLocationFieldConfig, LocationInfo, LogLevel$1 as LogLevel, NetworkInfo, NetworkType, QueueConfig, QueuedEvent, RequiredEventFields, SessionInfo, UseAnalyticsOptions, UseAnalyticsReturn };