@datalyr/react-native 1.3.0 → 1.3.1

package/src/network-status.ts

@@ -0,0 +1,312 @@
+import { debugLog, errorLog } from './utils';
+
+export type NetworkState = {
+  isConnected: boolean;
+  isInternetReachable: boolean | null;
+  type: 'wifi' | 'cellular' | 'ethernet' | 'bluetooth' | 'vpn' | 'none' | 'unknown';
+};
+
+export type NetworkStateListener = (state: NetworkState) => void;
+
+/**
+ * Network status manager that detects online/offline status
+ * Uses @react-native-community/netinfo for React Native or expo-network for Expo
+ */
+class NetworkStatusManager {
+  private state: NetworkState = {
+    isConnected: true, // Default to true until we know otherwise
+    isInternetReachable: null,
+    type: 'unknown',
+  };
+
+  private listeners: Set<NetworkStateListener> = new Set();
+  private unsubscribe: (() => void) | null = null;
+  private initialized = false;
+  private netInfoModule: any = null;
+  private expoNetworkModule: any = null;
+
+  /**
+   * Initialize network status monitoring
+   * Call this during SDK initialization
+   */
+  async initialize(): Promise<void> {
+    if (this.initialized) {
+      return;
+    }
+
+    // Try @react-native-community/netinfo first (most common in RN apps)
+    try {
+      this.netInfoModule = require('@react-native-community/netinfo').default;
+      await this.initializeWithNetInfo();
+      this.initialized = true;
+      debugLog('Network status initialized with @react-native-community/netinfo');
+      return;
+    } catch {
+      // Module not available, try expo-network
+    }
+
+    // Try expo-network (for Expo apps)
+    try {
+      this.expoNetworkModule = require('expo-network');
+      await this.initializeWithExpoNetwork();
+      this.initialized = true;
+      debugLog('Network status initialized with expo-network');
+      return;
+    } catch {
+      // Module not available
+    }
+
+    // Fallback: assume online (no network monitoring available)
+    debugLog('No network status module available, defaulting to online');
+    this.state = {
+      isConnected: true,
+      isInternetReachable: true,
+      type: 'unknown',
+    };
+    this.initialized = true;
+  }
+
+  /**
+   * Initialize with @react-native-community/netinfo
+   */
+  private async initializeWithNetInfo(): Promise<void> {
+    const NetInfo = this.netInfoModule;
+
+    // Get initial state
+    try {
+      const netState = await NetInfo.fetch();
+      this.updateStateFromNetInfo(netState);
+    } catch (error) {
+      errorLog('Failed to fetch initial network state:', error as Error);
+    }
+
+    // Subscribe to changes
+    this.unsubscribe = NetInfo.addEventListener((netState: any) => {
+      this.updateStateFromNetInfo(netState);
+    });
+  }
+
+  /**
+   * Update state from NetInfo response
+   */
+  private updateStateFromNetInfo(netState: any): void {
+    const previouslyConnected = this.state.isConnected;
+
+    this.state = {
+      isConnected: netState.isConnected ?? true,
+      isInternetReachable: netState.isInternetReachable,
+      type: this.mapNetInfoType(netState.type),
+    };
+
+    // Notify listeners if connection status changed
+    if (previouslyConnected !== this.state.isConnected) {
+      debugLog(`Network status changed: ${this.state.isConnected ? 'online' : 'offline'} (${this.state.type})`);
+      this.notifyListeners();
+    }
+  }
+
+  /**
+   * Map NetInfo type to our simplified type
+   */
+  private mapNetInfoType(type: string): NetworkState['type'] {
+    switch (type) {
+      case 'wifi':
+        return 'wifi';
+      case 'cellular':
+        return 'cellular';
+      case 'ethernet':
+        return 'ethernet';
+      case 'bluetooth':
+        return 'bluetooth';
+      case 'vpn':
+        return 'vpn';
+      case 'none':
+        return 'none';
+      default:
+        return 'unknown';
+    }
+  }
+
+  /**
+   * Initialize with expo-network
+   */
+  private async initializeWithExpoNetwork(): Promise<void> {
+    const Network = this.expoNetworkModule;
+
+    // Get initial state
+    try {
+      const networkState = await Network.getNetworkStateAsync();
+      this.updateStateFromExpoNetwork(networkState);
+    } catch (error) {
+      errorLog('Failed to fetch initial network state from expo-network:', error as Error);
+    }
+
+    // Note: expo-network doesn't have a listener API like netinfo
+    // We'll poll periodically or rely on app state changes
+    this.startExpoNetworkPolling();
+  }
+
+  /**
+   * Update state from expo-network response
+   */
+  private updateStateFromExpoNetwork(networkState: any): void {
+    const previouslyConnected = this.state.isConnected;
+
+    this.state = {
+      isConnected: networkState.isConnected ?? true,
+      isInternetReachable: networkState.isInternetReachable ?? null,
+      type: this.mapExpoNetworkType(networkState.type),
+    };
+
+    if (previouslyConnected !== this.state.isConnected) {
+      debugLog(`Network status changed: ${this.state.isConnected ? 'online' : 'offline'} (${this.state.type})`);
+      this.notifyListeners();
+    }
+  }
+
+  /**
+   * Map expo-network type to our simplified type
+   */
+  private mapExpoNetworkType(type: string): NetworkState['type'] {
+    switch (type) {
+      case 'WIFI':
+        return 'wifi';
+      case 'CELLULAR':
+        return 'cellular';
+      case 'ETHERNET':
+        return 'ethernet';
+      case 'BLUETOOTH':
+        return 'bluetooth';
+      case 'VPN':
+        return 'vpn';
+      case 'NONE':
+        return 'none';
+      default:
+        return 'unknown';
+    }
+  }
+
+  /**
+   * Poll expo-network for changes (since it doesn't have a listener API)
+   */
+  private pollingInterval: NodeJS.Timeout | null = null;
+
+  private startExpoNetworkPolling(): void {
+    // Poll every 5 seconds for network changes
+    this.pollingInterval = setInterval(async () => {
+      try {
+        if (this.expoNetworkModule) {
+          const networkState = await this.expoNetworkModule.getNetworkStateAsync();
+          this.updateStateFromExpoNetwork(networkState);
+        }
+      } catch (error) {
+        // Ignore polling errors
+      }
+    }, 5000);
+  }
+
+  /**
+   * Notify all listeners of state change
+   */
+  private notifyListeners(): void {
+    this.listeners.forEach((listener) => {
+      try {
+        listener(this.state);
+      } catch (error) {
+        errorLog('Error in network state listener:', error as Error);
+      }
+    });
+  }
+
+  /**
+   * Get current network state
+   */
+  getState(): NetworkState {
+    return { ...this.state };
+  }
+
+  /**
+   * Check if device is currently online
+   */
+  isOnline(): boolean {
+    // Consider online if connected OR if we're not sure about internet reachability
+    return this.state.isConnected && (this.state.isInternetReachable !== false);
+  }
+
+  /**
+   * Get current network type
+   */
+  getNetworkType(): NetworkState['type'] {
+    return this.state.type;
+  }
+
+  /**
+   * Subscribe to network state changes
+   * Returns an unsubscribe function
+   */
+  subscribe(listener: NetworkStateListener): () => void {
+    this.listeners.add(listener);
+
+    // Immediately call with current state
+    try {
+      listener(this.state);
+    } catch (error) {
+      errorLog('Error calling network state listener:', error as Error);
+    }
+
+    // Return unsubscribe function
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /**
+   * Refresh network state manually
+   * Useful when returning from background
+   */
+  async refresh(): Promise<NetworkState> {
+    if (this.netInfoModule) {
+      try {
+        const netState = await this.netInfoModule.fetch();
+        this.updateStateFromNetInfo(netState);
+      } catch (error) {
+        errorLog('Failed to refresh network state:', error as Error);
+      }
+    } else if (this.expoNetworkModule) {
+      try {
+        const networkState = await this.expoNetworkModule.getNetworkStateAsync();
+        this.updateStateFromExpoNetwork(networkState);
+      } catch (error) {
+        errorLog('Failed to refresh network state from expo-network:', error as Error);
+      }
+    }
+
+    return this.state;
+  }
+
+  /**
+   * Cleanup and stop monitoring
+   */
+  destroy(): void {
+    if (this.unsubscribe) {
+      this.unsubscribe();
+      this.unsubscribe = null;
+    }
+
+    if (this.pollingInterval) {
+      clearInterval(this.pollingInterval);
+      this.pollingInterval = null;
+    }
+
+    this.listeners.clear();
+    this.initialized = false;
+
+    debugLog('Network status manager destroyed');
+  }
+}
+
+// Export singleton instance
+export const networkStatusManager = new NetworkStatusManager();
+
+// Export for direct access
+export default networkStatusManager;

package/src/types.ts

@@ -40,37 +40,105 @@ export interface DeferredDeepLinkResult {
   adId?: string;
 }
 
-// Core SDK Configuration
+/**
+ * Core SDK Configuration
+ *
+ * @example
+ * ```typescript
+ * await Datalyr.initialize({
+ *   apiKey: 'dk_your_api_key',
+ *   debug: true,
+ *   enableAutoEvents: true,
+ *   enableAttribution: true,
+ *   skadTemplate: 'ecommerce',
+ *   meta: { appId: 'FB_APP_ID' },
+ *   tiktok: { appId: 'APP_ID', tiktokAppId: 'TIKTOK_APP_ID' },
+ * });
+ * ```
+ */
 export interface DatalyrConfig {
-  apiKey: string; // Required for server-side tracking
-  workspaceId?: string; // Optional for backward compatibility
+  /** Required: API key from Datalyr dashboard (starts with 'dk_') */
+  apiKey: string;
+
+  /** Optional: Workspace ID for multi-workspace setups */
+  workspaceId?: string;
+
+  /** Enable console logging for debugging. Default: false */
   debug?: boolean;
+
+  /**
+   * API endpoint URL. Default: 'https://api.datalyr.com'
+   * @deprecated Use `endpoint` instead
+   */
   apiUrl?: string;
+
+  /** API endpoint URL. Default: 'https://api.datalyr.com' */
   endpoint?: string;
-  useServerTracking?: boolean; // Default: true for v1.0.0
+
+  /** Use server-side tracking. Default: true */
+  useServerTracking?: boolean;
+
+  /** Maximum retry attempts for failed requests. Default: 3 */
   maxRetries?: number;
+
+  /** Delay between retries in milliseconds. Default: 1000 */
   retryDelay?: number;
+
+  /** Request timeout in milliseconds. Default: 15000 */
   timeout?: number;
+
+  /** Number of events per batch. Default: 10 */
   batchSize?: number;
+
+  /** Interval between automatic flushes in milliseconds. Default: 30000 */
   flushInterval?: number;
+
+  /** Maximum events to store in queue. Default: 100 */
   maxQueueSize?: number;
+
+  /**
+   * Maximum events to store in queue. Default: 100
+   * @deprecated Use `maxQueueSize` instead
+   */
   maxEventQueueSize?: number;
+
+  /** Respect browser Do Not Track setting. Default: true */
   respectDoNotTrack?: boolean;
+
+  /** Enable automatic event tracking (sessions, app lifecycle). Default: false */
   enableAutoEvents?: boolean;
+
+  /** Enable attribution tracking (deep links, install referrer). Default: false */
   enableAttribution?: boolean;
+
+  /** Enable web-to-app attribution matching via email. Default: true */
   enableWebToAppAttribution?: boolean;
+
+  /**
+   * Auto-events configuration
+   * @deprecated Use `autoEventConfig` instead
+   */
   autoEvents?: AutoEventConfig;
+
+  /** Auto-events configuration */
   autoEventConfig?: AutoEventConfig;
+
+  /**
+   * Retry configuration
+   * @deprecated Use `maxRetries` and `retryDelay` instead
+   */
   retryConfig?: {
     maxRetries: number;
     retryDelay: number;
   };
+
+  /** SKAdNetwork template for automatic conversion value encoding (iOS only) */
   skadTemplate?: 'ecommerce' | 'gaming' | 'subscription';
 
-  // Meta (Facebook) SDK Configuration
+  /** Meta (Facebook) SDK Configuration */
   meta?: MetaConfig;
 
-  // TikTok SDK Configuration
+  /** TikTok SDK Configuration */
   tiktok?: TikTokConfig;
 }
 // Event Types

package/src/utils.ts

@@ -124,12 +124,50 @@ export const getOrCreateSessionId = async (): Promise<string> => {
   }
 };
 
+// Cached device info to avoid repeated async calls
+let cachedDeviceInfo: DeviceInfoType | null = null;
+let deviceInfoPromise: Promise<DeviceInfoType> | null = null;
+
 /**
- * Collect comprehensive device information
+ * Collect comprehensive device information (cached after first call)
+ * Device info is cached because it rarely changes during app session
  */
 export const getDeviceInfo = async (): Promise<DeviceInfoType> => {
+  // Return cached info if available
+  if (cachedDeviceInfo) {
+    return cachedDeviceInfo;
+  }
+
+  // If a fetch is already in progress, wait for it (prevents concurrent fetches)
+  if (deviceInfoPromise) {
+    return deviceInfoPromise;
+  }
+
+  // Start fetching and cache the promise
+  deviceInfoPromise = fetchDeviceInfoInternal();
+
+  try {
+    cachedDeviceInfo = await deviceInfoPromise;
+    return cachedDeviceInfo;
+  } finally {
+    deviceInfoPromise = null;
+  }
+};
+
+/**
+ * Clear the cached device info (useful for testing or after app update)
+ */
+export const clearDeviceInfoCache = (): void => {
+  cachedDeviceInfo = null;
+  deviceInfoPromise = null;
+};
+
+/**
+ * Internal function to fetch device info
+ */
+const fetchDeviceInfoInternal = async (): Promise<DeviceInfoType> => {
   const { width, height } = Dimensions.get('window');
-  
+
   // If DeviceInfo is not available (like in Expo Go), use fallback
   if (!DeviceInfo) {
     return {
@@ -147,7 +185,7 @@ export const getDeviceInfo = async (): Promise<DeviceInfoType> => {
       isEmulator: false,
     };
   }
-  
+
   try {
     const [
       deviceId,
@@ -174,7 +212,7 @@ export const getDeviceInfo = async (): Promise<DeviceInfoType> => {
       DeviceInfo.getCarrier().catch(() => undefined),
       DeviceInfo.isEmulator(),
     ]);
-    
+
     return {
       deviceId,
       model,
@@ -192,7 +230,7 @@ export const getDeviceInfo = async (): Promise<DeviceInfoType> => {
     };
   } catch (error) {
     console.warn('Failed to collect device info:', error);
-    
+
     // Fallback device info
     return {
       deviceId: generateUUID(),
@@ -232,11 +270,29 @@ export const createFingerprintData = async (): Promise<FingerprintData> => {
   }
 };
 
+// Import network status manager for network type detection
+let networkStatusManagerRef: any = null;
+
+// Lazy load to avoid circular dependencies
+const getNetworkStatusManager = () => {
+  if (!networkStatusManagerRef) {
+    try {
+      networkStatusManagerRef = require('./network-status').networkStatusManager;
+    } catch {
+      // Module not loaded yet
+    }
+  }
+  return networkStatusManagerRef;
+};
+
 /**
  * Get network connection type
  */
 export const getNetworkType = (): string => {
-  // This will be enhanced with react-native-netinfo if needed
+  const manager = getNetworkStatusManager();
+  if (manager) {
+    return manager.getNetworkType();
+  }
   return 'unknown';
 };