user-analytics-tracker 1.2.0

package/dist/index.d.ts

@@ -0,0 +1,415 @@
+/**
+ * Core types for the analytics tracker package
+ */
+type NetworkType = 'wifi' | 'hotspot' | 'cellular' | 'ethernet' | 'unknown';
+type DeviceType = 'mobile' | 'tablet' | 'desktop' | 'unknown';
+interface NetworkInfo {
+    type: NetworkType;
+    effectiveType?: string;
+    downlink?: number;
+    rtt?: number;
+    saveData?: boolean;
+    connectionType?: string;
+}
+interface DeviceInfo {
+    type: DeviceType;
+    os: string;
+    osVersion: string;
+    browser: string;
+    browserVersion: string;
+    screenResolution: string;
+    deviceModel: string;
+    deviceBrand: string;
+    language: string;
+    timezone: string;
+    userAgent: string;
+    deviceMemory?: number;
+    hardwareConcurrency?: number;
+    touchSupport: boolean;
+    pixelRatio: number;
+    colorDepth: number;
+    orientation: string;
+    cpuArchitecture: string;
+}
+interface LocationInfo {
+    lat?: number | null;
+    lon?: number | null;
+    accuracy?: number | null;
+    permission?: 'granted' | 'denied' | 'prompt' | 'unsupported';
+    source: 'gps' | 'ip' | 'unknown';
+    ts?: string;
+    ip?: string | null;
+    country?: string;
+    countryCode?: string;
+    city?: string;
+    region?: string;
+    timezone?: string;
+}
+interface AttributionInfo {
+    landingUrl: string;
+    path: string;
+    hostname: string;
+    referrerUrl: string | null;
+    referrerDomain: string | null;
+    navigationType: 'navigate' | 'reload' | 'back_forward' | 'prerender' | 'unknown';
+    isReload: boolean;
+    isBackForward: boolean;
+    sessionStart?: string | null;
+    utm_source?: string | null;
+    utm_medium?: string | null;
+    utm_campaign?: string | null;
+    utm_term?: string | null;
+    utm_content?: string | null;
+    gclid?: string | null;
+    fbclid?: string | null;
+    ttclid?: string | null;
+    msclkid?: string | null;
+    dmclid?: string | null;
+    firstTouch?: Record<string, string | null> | null;
+    lastTouch?: Record<string, string | null> | null;
+}
+interface IPLocation {
+    ip: string;
+    country?: string;
+    countryCode?: string;
+    region?: string;
+    regionName?: string;
+    city?: string;
+    lat?: number;
+    lon?: number;
+    timezone?: string;
+    isp?: string;
+    org?: string;
+    as?: string;
+    query?: string;
+}
+interface AnalyticsConfig {
+    apiEndpoint: string;
+    autoSend?: boolean;
+    enableLocation?: boolean;
+    enableIPGeolocation?: boolean;
+    enableNetworkDetection?: boolean;
+    enableDeviceDetection?: boolean;
+    enableAttribution?: boolean;
+    sessionStoragePrefix?: string;
+    localStoragePrefix?: string;
+}
+interface AnalyticsEvent {
+    sessionId: string;
+    pageUrl: string;
+    timestamp: Date | string;
+    networkInfo?: NetworkInfo;
+    deviceInfo?: DeviceInfo;
+    location?: LocationInfo;
+    attribution?: AttributionInfo;
+    ipLocation?: IPLocation;
+    userId?: string;
+    customData?: Record<string, any>;
+    eventId?: string;
+    eventName?: string;
+    eventParameters?: Record<string, any>;
+}
+interface UseAnalyticsReturn {
+    sessionId: string | null;
+    networkInfo: NetworkInfo | null;
+    deviceInfo: DeviceInfo | null;
+    location: LocationInfo | null;
+    attribution: AttributionInfo | null;
+    pageVisits: number;
+    interactions: number;
+    logEvent: (customData?: Record<string, any>) => Promise<void>;
+    trackEvent: (eventName: string, parameters?: Record<string, any>) => Promise<void>;
+    trackPageView: (pageName?: string, parameters?: Record<string, any>) => Promise<void>;
+    incrementInteraction: () => void;
+    refresh: () => Promise<{
+        net: NetworkInfo;
+        dev: DeviceInfo;
+        attr: AttributionInfo;
+        loc: LocationInfo;
+    }>;
+}
+
+/**
+ * Network Type Detector
+ * Detects WiFi, Mobile Data (Cellular), Hotspot, Ethernet, or Unknown
+ */
+declare class NetworkDetector {
+    static detect(): NetworkInfo;
+}
+
+/**
+ * Device Information Detector
+ * Detects device type, OS, browser, and hardware specs
+ */
+declare class DeviceDetector {
+    private static getRealDeviceInfo;
+    private static detectBrowser;
+    static detect(): Promise<DeviceInfo>;
+    private static detectBrand;
+    private static getDefaultDeviceInfo;
+}
+
+/**
+ * Location Detector
+ * Detects GPS location with consent management, falls back to IP-based location API
+ * IP-based location works automatically without user permission
+ */
+declare class LocationDetector {
+    private static locationFetchingRef;
+    private static lastLocationRef;
+    private static locationConsentLoggedRef;
+    private static ipLocationFetchingRef;
+    private static lastIPLocationRef;
+    /**
+     * Detect location using IP-based API only (no GPS, no permission needed)
+     * Fast and automatic - works immediately without user interaction
+     */
+    static detectIPOnly(): Promise<LocationInfo>;
+    /**
+     * Detect location with automatic consent granted
+     * Tries GPS first (if available), then falls back to IP-based location
+     * Automatically sets location consent to bypass permission checks
+     */
+    static detectWithAutoConsent(): Promise<LocationInfo>;
+    /**
+     * Get browser GPS location
+     * Respects location consent (set via MSISDN entry)
+     * Falls back to IP-based location automatically if GPS fails
+     */
+    static detect(): Promise<LocationInfo>;
+    /**
+     * 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)
+     */
+    private static getIPBasedLocation;
+    /**
+     * Clear location cache (useful when consent is granted)
+     */
+    static clearCache(): void;
+}
+
+/**
+ * Attribution Detector
+ * Detects UTM parameters, referrer, navigation type, and tracks first/last touch
+ */
+declare class AttributionDetector {
+    static detect(): AttributionInfo;
+    private static getDefaultAttribution;
+}
+
+/**
+ * Analytics Service
+ * Sends analytics events to your backend API
+ *
+ * Supports both relative paths (e.g., '/api/analytics') and full URLs (e.g., 'https://your-server.com/api/analytics')
+ */
+declare class AnalyticsService {
+    private static apiEndpoint;
+    /**
+     * Configure the analytics API endpoint
+     *
+     * @param config - Configuration object
+     * @param config.apiEndpoint - Your backend API endpoint URL
+     *   - Relative path: '/api/analytics' (sends to same domain)
+     *   - Full URL: 'https://your-server.com/api/analytics' (sends to your server)
+     *
+     * @example
+     * ```typescript
+     * // Use your own server
+     * AnalyticsService.configure({
+     *   apiEndpoint: 'https://api.yourcompany.com/analytics'
+     * });
+     *
+     * // Or use relative path (same domain)
+     * AnalyticsService.configure({
+     *   apiEndpoint: '/api/analytics'
+     * });
+     * ```
+     */
+    static configure(config: {
+        apiEndpoint: string;
+    }): void;
+    /**
+     * Generate a random event ID
+     */
+    private static generateEventId;
+    /**
+     * Track user journey/analytics event
+     */
+    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, }: {
+        sessionId: string;
+        pageUrl: string;
+        networkInfo?: NetworkInfo;
+        deviceInfo?: DeviceInfo;
+        location?: any;
+        attribution?: AttributionInfo;
+        ipLocation?: any;
+        userId?: string;
+        customData?: Record<string, any>;
+        pageVisits?: number;
+        interactions?: number;
+    }): Promise<void>;
+    /**
+     * Track a custom event (Firebase/GA-style)
+     * Automatically collects device, network, location context if available
+     *
+     * @param eventName - Name of the event (e.g., 'button_click', 'purchase', 'sign_up')
+     * @param parameters - Event-specific parameters (optional)
+     * @param context - Optional context override (auto-collected if not provided)
+     *
+     * @example
+     * ```typescript
+     * // Simple event tracking
+     * AnalyticsService.logEvent('button_click', {
+     *   button_name: 'signup',
+     *   button_location: 'header'
+     * });
+     *
+     * // Purchase event
+     * AnalyticsService.logEvent('purchase', {
+     *   transaction_id: 'T12345',
+     *   value: 29.99,
+     *   currency: 'USD',
+     *   items: [{ id: 'item1', name: 'Product 1', price: 29.99 }]
+     * });
+     * ```
+     */
+    static logEvent(eventName: string, parameters?: Record<string, any>, context?: {
+        sessionId?: string;
+        pageUrl?: string;
+        networkInfo?: NetworkInfo;
+        deviceInfo?: DeviceInfo;
+        location?: any;
+        attribution?: AttributionInfo;
+        userId?: string;
+    }): Promise<void>;
+    /**
+     * Track a page view event (Firebase/GA-style)
+     * Automatically collects device, network, location context
+     *
+     * @param pageName - Optional page name (defaults to current URL pathname)
+     * @param parameters - Optional page view parameters
+     *
+     * @example
+     * ```typescript
+     * // Track current page view
+     * AnalyticsService.trackPageView();
+     *
+     * // Track with custom page name
+     * AnalyticsService.trackPageView('/dashboard', {
+     *   page_title: 'Dashboard',
+     *   user_type: 'premium'
+     * });
+     * ```
+     */
+    static trackPageView(pageName?: string, parameters?: Record<string, any>): Promise<void>;
+}
+
+interface UseAnalyticsOptions {
+    autoSend?: boolean;
+    config?: Partial<AnalyticsConfig>;
+    onReady?: (data: {
+        sessionId: string;
+        networkInfo: NetworkInfo;
+        deviceInfo: DeviceInfo;
+        location: LocationInfo;
+        attribution: AttributionInfo;
+    }) => void;
+}
+/**
+ * React hook for analytics tracking
+ *
+ * @example
+ * ```tsx
+ * const { sessionId, networkInfo, deviceInfo, logEvent } = useAnalytics({
+ *   autoSend: true,
+ *   config: { apiEndpoint: '/api/analytics' }
+ * });
+ * ```
+ */
+declare function useAnalytics(options?: UseAnalyticsOptions): UseAnalyticsReturn;
+
+/**
+ * Storage utilities for analytics tracking
+ */
+declare const loadJSON: <T>(key: string) => T | null;
+declare const saveJSON: (key: string, obj: unknown) => void;
+declare const loadSessionJSON: <T>(key: string) => T | null;
+declare const saveSessionJSON: (key: string, obj: unknown) => void;
+/**
+ * Generate or retrieve a user ID from localStorage
+ */
+declare function getOrCreateUserId(length?: number): string;
+/**
+ * Track page visits with localStorage
+ */
+declare function trackPageVisit(): number;
+
+/**
+ * Location Consent Manager
+ * When user enters MSISDN, they implicitly consent to location tracking
+ * This utility manages the consent state and prevents unnecessary permission prompts
+ */
+/**
+ * Set location consent as granted (when MSISDN is provided)
+ */
+declare function setLocationConsentGranted(): void;
+/**
+ * Check if location consent has been granted
+ */
+declare function hasLocationConsent(): boolean;
+/**
+ * Get location consent timestamp
+ */
+declare function getLocationConsentTimestamp(): string | null;
+/**
+ * Clear location consent (for testing or user revocation)
+ */
+declare function clearLocationConsent(): void;
+/**
+ * Check if MSISDN is provided and set consent accordingly
+ * Call this whenever MSISDN is detected
+ */
+declare function checkAndSetLocationConsent(msisdn?: string | null): boolean;
+
+/**
+ * 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"
+ * ```
+ */
+declare function getPublicIP(): Promise<string | 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)
+ */
+declare function getIPLocation(ip: string): 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;
+
+export { AnalyticsService, AttributionDetector, DeviceDetector, LocationDetector, NetworkDetector, checkAndSetLocationConsent, clearLocationConsent, useAnalytics as default, getIPFromRequest, getIPLocation, getLocationConsentTimestamp, getOrCreateUserId, getPublicIP, hasLocationConsent, loadJSON, loadSessionJSON, saveJSON, saveSessionJSON, setLocationConsentGranted, trackPageVisit, useAnalytics };
+export type { AnalyticsConfig, AnalyticsEvent, AttributionInfo, DeviceInfo, DeviceType, IPLocation, LocationInfo, NetworkInfo, NetworkType, UseAnalyticsOptions, UseAnalyticsReturn };