@billdog.io/react-native 1.0.0-beta.2

package/src/notifications/useDeviceToken.ts

@@ -0,0 +1,116 @@
+import { useEffect, useRef } from 'react';
+import PushNotification from 'react-native-push-notification';
+import { Platform } from 'react-native';
+import { ApiClient } from '../utils/ApiClient';
+
+interface UseDeviceTokenOptions {
+  userId: string;
+  projectId: string;
+  /** @deprecated Use BillDogConfiguration.configure({ apiKey }) instead */
+  apiKey?: string;
+  onTokenRegistered?: (token: string) => void;
+  onError?: (error: Error) => void;
+}
+
+/**
+ * Hook to register device token for push notifications.
+ * Automatically registers the device token when the component mounts.
+ * 
+ * Credentials are resolved from `BillDogConfiguration` by default.
+ * 
+ * @example
+ * ```tsx
+ * import { useDeviceToken } from '@billdog.io/react-native';
+ * 
+ * function App() {
+ *   useDeviceToken({
+ *     userId: 'user-123',
+ *     projectId: 'project-456',
+ *     onTokenRegistered: (token) => console.log('Token registered:', token),
+ *   });
+ *   
+ *   return <YourApp />;
+ * }
+ * ```
+ */
+export function useDeviceToken({
+  userId,
+  projectId,
+  apiKey: apiKeyOverride,
+  onTokenRegistered,
+  onError,
+}: UseDeviceTokenOptions) {
+  const registeredRef = useRef(false);
+
+  useEffect(() => {
+    if (registeredRef.current) return;
+
+    const registerToken = async () => {
+      try {
+        PushNotification.configure({
+          onRegister: async (tokenData: any) => {
+            try {
+              const token = tokenData.token;
+              const platform = Platform.OS;
+
+              await ApiClient.post('register-device-token', {
+                userId,
+                projectId,
+                token,
+                platform,
+              }, {
+                apiKey: apiKeyOverride,
+              });
+
+              registeredRef.current = true;
+              onTokenRegistered?.(token);
+            } catch (error) {
+              console.error('Failed to register device token:', error);
+              onError?.(error as Error);
+            }
+          },
+          onNotification: (notification: any) => {
+            console.log('Notification received:', notification);
+          },
+          permissions: {
+            alert: true,
+            badge: true,
+            sound: true,
+          },
+          popInitialNotification: true,
+          requestPermissions: true,
+        });
+      } catch (error) {
+        console.error('Failed to register device token:', error);
+        onError?.(error as Error);
+      }
+    };
+
+    registerToken();
+
+    return () => {
+      PushNotification.unregister();
+    };
+  }, [userId, projectId, apiKeyOverride, onTokenRegistered, onError]);
+}
+
+/**
+ * Manually register a device token.
+ * Resolves the endpoint from BillDogConfiguration (api.billdog.io/v1).
+ */
+export async function registerDeviceToken(
+  token: string,
+  userId: string,
+  projectId: string,
+  apiKey?: string,
+  platform?: 'ios' | 'android'
+): Promise<void> {
+  await ApiClient.post('register-device-token', {
+    userId,
+    projectId,
+    token,
+    platform: platform || 'ios',
+  }, {
+    apiKey,
+  });
+}

package/src/notifications/useLiveActivity.ts

@@ -0,0 +1,125 @@
+import { useState, useEffect, useCallback } from 'react';
+import { liveActivities, LiveActivityConfig, LiveActivityUpdate } from './LiveActivitiesManager';
+
+export interface UseLiveActivityOptions {
+  autoStart?: boolean;
+  config?: LiveActivityConfig;
+}
+
+export interface UseLiveActivityReturn {
+  activityId: string | null;
+  isActive: boolean;
+  isSupported: boolean;
+  areEnabled: boolean;
+  startActivity: (config: LiveActivityConfig) => Promise<string>;
+  updateActivity: (update: LiveActivityUpdate) => Promise<void>;
+  endActivity: (finalState?: Record<string, any>) => Promise<void>;
+  error: Error | null;
+}
+
+/**
+ * React hook for managing a Live Activity
+ * 
+ * @example
+ * ```tsx
+ * const { activityId, isActive, startActivity, updateActivity, endActivity } = useLiveActivity();
+ * 
+ * // Start activity
+ * await startActivity({
+ *   activityType: 'order_tracking',
+ *   attributes: { orderNumber: '12345' },
+ *   contentState: { status: 'preparing' }
+ * });
+ * 
+ * // Update activity
+ * await updateActivity({
+ *   contentState: { status: 'shipped' }
+ * });
+ * 
+ * // End activity
+ * await endActivity({ status: 'delivered' });
+ * ```
+ */
+export function useLiveActivity(options: UseLiveActivityOptions = {}): UseLiveActivityReturn {
+  const [activityId, setActivityId] = useState<string | null>(null);
+  const [isSupported, setIsSupported] = useState(false);
+  const [areEnabled, setAreEnabled] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    const checkSupport = async () => {
+      const supported = liveActivities.isSupported();
+      setIsSupported(supported);
+
+      if (supported) {
+        const enabled = await liveActivities.areActivitiesEnabled();
+        setAreEnabled(enabled);
+      }
+    };
+
+    checkSupport();
+  }, []);
+
+  useEffect(() => {
+    if (options.autoStart && options.config && isSupported && areEnabled && !activityId) {
+      startActivity(options.config).catch((err) => {
+        console.error('[useLiveActivity] Auto-start failed:', err);
+      });
+    }
+  }, [options.autoStart, options.config, isSupported, areEnabled, activityId]);
+
+  const startActivity = useCallback(async (config: LiveActivityConfig): Promise<string> => {
+    try {
+      setError(null);
+      const id = await liveActivities.startActivity(config);
+      setActivityId(id);
+      return id;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error('Failed to start activity');
+      setError(error);
+      throw error;
+    }
+  }, []);
+
+  const updateActivity = useCallback(async (update: LiveActivityUpdate): Promise<void> => {
+    if (!activityId) {
+      throw new Error('No active activity to update');
+    }
+
+    try {
+      setError(null);
+      await liveActivities.updateActivity(activityId, update);
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error('Failed to update activity');
+      setError(error);
+      throw error;
+    }
+  }, [activityId]);
+
+  const endActivity = useCallback(async (finalState?: Record<string, any>): Promise<void> => {
+    if (!activityId) {
+      throw new Error('No active activity to end');
+    }
+
+    try {
+      setError(null);
+      await liveActivities.endActivity(activityId, finalState);
+      setActivityId(null);
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error('Failed to end activity');
+      setError(error);
+      throw error;
+    }
+  }, [activityId]);
+
+  return {
+    activityId,
+    isActive: !!activityId,
+    isSupported,
+    areEnabled,
+    startActivity,
+    updateActivity,
+    endActivity,
+    error,
+  };
+}

package/src/review/ReviewAnalytics.ts

@@ -0,0 +1,89 @@
+import { Platform } from 'react-native';
+import { BillDogConfiguration } from '../BillDogConfiguration';
+import { ApiClient } from '../utils/ApiClient';
+
+export interface ReviewAnalyticsEvent {
+  eventType: 'requested' | 'shown' | 'dismissed' | 'completed' | 'error';
+  platform: 'ios' | 'android' | 'other';
+  customerId?: string;
+  sdkVersion?: string;
+  appVersion?: string;
+  osVersion?: string;
+  deviceModel?: string;
+  success?: boolean;
+  errorMessage?: string;
+  timeToShowMs?: number;
+  userContext?: Record<string, any>;
+  metadata?: Record<string, any>;
+}
+
+export class ReviewAnalytics {
+  /**
+   * @deprecated No longer needed. Credentials are read from BillDogConfiguration.
+   * This method is a no-op retained for backward compatibility.
+   */
+  static initialize(_apiKey: string, _projectUrl: string) {
+    console.warn(
+      '[ReviewAnalytics] initialize() is deprecated. ' +
+      'Credentials are now read from BillDogConfiguration.configure(). This call is a no-op.'
+    );
+  }
+
+  /**
+   * Track a review event via the canonical `ingest-events` pipeline.
+   *
+   * Event naming follows `review_<eventType>` to preserve historical
+   * `bdanalytics_events.event_name` values written by the deprecated
+   * `track?type=review` router. Analytics surfaces (MessagingAnalytics,
+   * useReport, analytics-query) require no schema change.
+   *
+   * Per `mem://architecture/analytics-system-standard`: `ingest-events` is
+   * the sole analytics ingestion endpoint. Do not introduce alternative paths.
+   */
+  static async trackEvent(event: ReviewAnalyticsEvent): Promise<void> {
+    if (BillDogConfiguration.config.analyticsEnabled === false) {
+      console.log('[ReviewAnalytics] Analytics disabled, skipping event:', event.eventType);
+      return;
+    }
+
+    if (!BillDogConfiguration.isConfigured()) {
+      console.warn('[ReviewAnalytics] BillDogConfiguration not configured. Call BillDogConfiguration.configure() first.');
+      return;
+    }
+
+    const platform = event.platform || this.getPlatform();
+    const properties: Record<string, unknown> = {
+      platform,
+      sdk_version: event.sdkVersion,
+      app_version: event.appVersion,
+      os_version: event.osVersion || Platform.Version.toString(),
+      device_model: event.deviceModel,
+      success: event.success,
+      error_message: event.errorMessage,
+      time_to_show_ms: event.timeToShowMs,
+      user_context: event.userContext,
+      ...(event.metadata || {}),
+    };
+
+    try {
+      await ApiClient.post('ingest-events', {
+        events: [
+          {
+            event_name: `review_${event.eventType}`,
+            timestamp: new Date().toISOString(),
+            distinct_id: event.customerId,
+            properties,
+          },
+        ],
+      });
+    } catch (error) {
+      console.error('[ReviewAnalytics] Error tracking event:', error);
+    }
+  }
+
+  private static getPlatform(): 'ios' | 'android' | 'other' {
+    if (Platform.OS === 'ios') return 'ios';
+    if (Platform.OS === 'android') return 'android';
+    return 'other';
+  }
+}

package/src/review/ReviewManager.ts

@@ -0,0 +1,355 @@
+import { Platform, Linking } from 'react-native';
+import { ReviewAnalytics } from './ReviewAnalytics';
+import { ReviewTimingManager, ReviewTimingConfig } from './ReviewTimingManager';
+import { BillDogConfiguration } from '../BillDogConfiguration';
+
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const RN = (() => {
+  try {
+    return require('react-native');
+  } catch {
+    return null;
+  }
+})();
+
+const native: any = RN?.NativeModules?.BillDog ?? null;
+
+let timingManager: ReviewTimingManager | null = null;
+
+/**
+ * Optional native in-app-review module loader.
+ *
+ * `react-native` core does NOT export `StoreReview`/`InAppReview` — the previous
+ * implementation referenced non-existent exports, so the native prompt never ran
+ * and every request silently fell through to a (placeholder) store URL. The real
+ * native prompt requires `react-native-in-app-review` (cross-platform: iOS
+ * `SKStoreReviewController` + Android Play In-App Review), declared as an OPTIONAL
+ * peer dependency. Memoized; resolves `null` when the host app hasn't installed
+ * it (we then fall back to the configured store page).
+ */
+let inAppReviewModule: unknown | undefined = undefined;
+async function loadInAppReview(): Promise<any | null> {
+  if (inAppReviewModule !== undefined) return inAppReviewModule as any;
+  try {
+    // STATIC require: React Native's Metro bundler rejects dynamic
+    // `require(variable)` ("Invalid call … require(s)"), so the optional native
+    // module must be referenced by a literal specifier. The try/catch keeps it
+    // soft at runtime; the @ts-ignore avoids TS2307 at SDK build time when the
+    // optional peer is absent. Consumers who want native in-app review install
+    // `react-native-in-app-review` (declared in peerDependenciesMeta as optional).
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    // @ts-ignore optional peer dependency, may be absent at build time
+    const mod: any = require('react-native-in-app-review');
+    inAppReviewModule = (mod?.default ?? mod) ?? null;
+  } catch {
+    inAppReviewModule = null;
+  }
+  return inAppReviewModule as any;
+}
+
+/** True only when a store-page fallback is actually possible (IDs configured). */
+function hasStoreFallback(): boolean {
+  const cfg = BillDogConfiguration.config as { appStoreId?: string; androidPackageName?: string };
+  return Platform.OS === 'ios' ? !!cfg.appStoreId : Platform.OS === 'android' ? !!cfg.androidPackageName : false;
+}
+
+/**
+ * Initialize review timing manager with configuration
+ * Call this on app launch to enable smart timing
+ * 
+ * @param config - Timing configuration options
+ * 
+ * @example
+ * ```typescript
+ * import { initializeReviewTiming } from '@billdog.io/react-native';
+ * 
+ * await initializeReviewTiming({
+ *   minDaysSinceInstall: 7,
+ *   minSessionCount: 5,
+ *   minSignificantEvents: 3,
+ *   enableAutomaticTiming: true,
+ * });
+ * ```
+ */
+export async function initializeReviewTiming(config?: ReviewTimingConfig): Promise<void> {
+  if (native && typeof native.initializeReviewTiming === 'function') {
+    try {
+      await native.initializeReviewTiming(config);
+      return;
+    } catch (error) {
+      console.error('Error invoking native initializeReviewTiming:', error);
+    }
+  }
+  timingManager = new ReviewTimingManager(config);
+  await timingManager.initialize();
+  await timingManager.recordSession();
+}
+
+/**
+ * Record a new app session (call on app launch)
+ */
+export async function recordReviewSession(): Promise<void> {
+  if (native && typeof native.recordReviewSession === 'function') {
+    try {
+      await native.recordReviewSession();
+      return;
+    } catch (e) {}
+  }
+  if (timingManager) {
+    await timingManager.recordSession();
+  }
+}
+
+/**
+ * Record a significant event (e.g., purchase, completed action)
+ * These events help determine optimal timing for review requests
+ */
+export async function recordSignificantEvent(): Promise<void> {
+  if (native && typeof native.recordSignificantEvent === 'function') {
+    try {
+      await native.recordSignificantEvent();
+      return;
+    } catch (e) {}
+  }
+  if (timingManager) {
+    await timingManager.recordSignificantEvent();
+  }
+}
+
+/**
+ * Check if it's a good time to request a review based on timing logic
+ * 
+ * @returns Object with shouldRequest flag, reason, and timing data
+ */
+export async function shouldRequestReview(): Promise<{
+  shouldRequest: boolean;
+  reason?: string;
+  timingData?: any;
+}> {
+  if (native && typeof native.shouldRequestReview === 'function') {
+    try {
+      const should = await native.shouldRequestReview();
+      return { shouldRequest: should, reason: should ? 'All timing conditions met' : 'Timing conditions not met' };
+    } catch (e) {}
+  }
+  if (!timingManager) {
+    return { shouldRequest: true, reason: 'Timing manager not initialized' };
+  }
+  return await timingManager.shouldRequestReview();
+}
+
+/**
+ * Request in-app review from the user
+ * Optionally checks timing logic before showing
+ * 
+ * @param options - Options for review request
+ * @param options.checkTiming - Whether to check timing logic before showing (default: true)
+ * @returns Promise with success status and whether review was shown
+ * 
+ * @example
+ * ```typescript
+ * import { requestReview } from '@billdog.io/react-native';
+ * 
+ * const { success, shown } = await requestReview();
+ * if (shown) {
+ *   console.log('Review prompt shown to user');
+ * }
+ * ```
+ */
+export async function requestReview(options: { checkTiming?: boolean } = {}): Promise<{ 
+  success: boolean; 
+  shown: boolean;
+  reason?: string;
+}> {
+  const { checkTiming = true } = options;
+  const startTime = Date.now();
+  
+  try {
+    if (native && typeof native.requestReview === 'function') {
+      if (checkTiming) {
+        const timingCheck = await shouldRequestReview();
+        if (!timingCheck.shouldRequest) {
+          console.log('Review request skipped:', timingCheck.reason);
+          return { 
+            success: false, 
+            shown: false, 
+            reason: timingCheck.reason 
+          };
+        }
+      }
+
+      const result = await native.requestReview();
+      await ReviewAnalytics.trackEvent({
+        eventType: 'shown',
+        platform: Platform.OS === 'ios' ? 'ios' : Platform.OS === 'android' ? 'android' : 'other',
+        success: !!result?.success,
+        timeToShowMs: Date.now() - startTime,
+      });
+      return {
+        success: !!result?.success,
+        shown: !!result?.shown,
+        reason: result?.reason
+      };
+    }
+
+    // Check timing logic if enabled
+    if (checkTiming && timingManager) {
+      const timingCheck = await timingManager.shouldRequestReview();
+      if (!timingCheck.shouldRequest) {
+        console.log('Review request skipped:', timingCheck.reason);
+        return { 
+          success: false, 
+          shown: false, 
+          reason: timingCheck.reason 
+        };
+      }
+    }
+
+    // Record that we're requesting a review
+    if (timingManager) {
+      await timingManager.recordReviewRequested();
+    }
+    // Track request event
+    await ReviewAnalytics.trackEvent({
+      eventType: 'requested',
+      platform: Platform.OS === 'ios' ? 'ios' : Platform.OS === 'android' ? 'android' : 'other',
+    });
+
+    // Native in-app review — iOS SKStoreReviewController / Android Play In-App
+    // Review — via the optional `react-native-in-app-review` module (one call
+    // handles both platforms). Audit fix: the old code imported StoreReview/
+    // InAppReview from `react-native` (no such exports) so this branch never ran.
+    const InAppReview = await loadInAppReview();
+    if (
+      InAppReview &&
+      typeof InAppReview.isAvailable === 'function' &&
+      InAppReview.isAvailable() &&
+      typeof InAppReview.RequestInAppReview === 'function'
+    ) {
+      // Resolves true when the flow launched/finished. Note: neither platform
+      // reports whether the dialog displayed or whether the user submitted a
+      // review, so `shown` is best-effort. We do NOT auto-record "completed"
+      // (that permanently blocked future prompts and made maxRequestsPerUser
+      // unreachable); recordReviewRequested() above is the correct cap.
+      const flowFinished = await InAppReview.RequestInAppReview();
+      await ReviewAnalytics.trackEvent({
+        eventType: 'shown',
+        platform: Platform.OS === 'ios' ? 'ios' : Platform.OS === 'android' ? 'android' : 'other',
+        success: !!flowFinished,
+        timeToShowMs: Date.now() - startTime,
+      });
+      return { success: !!flowFinished, shown: !!flowFinished };
+    }
+
+    // Fallback: open store page (only when store IDs are configured)
+    const result = await openStoreForReview();
+    
+    if (result.success) {
+      await ReviewAnalytics.trackEvent({
+        eventType: 'shown',
+        platform: Platform.OS === 'ios' ? 'ios' : Platform.OS === 'android' ? 'android' : 'other',
+        success: true,
+        timeToShowMs: Date.now() - startTime,
+      });
+      // Audit fix — removed the auto recordReviewCompleted() call (see above): it
+      // permanently blocked future prompts and made maxRequestsPerUser unreachable.
+      // recordReviewRequested() already counted this attempt toward the cap.
+    }
+
+    return result;
+  } catch (error) {
+    console.error('Error requesting review:', error);
+    
+    // Track error event
+    await ReviewAnalytics.trackEvent({
+      eventType: 'error',
+      platform: Platform.OS === 'ios' ? 'ios' : Platform.OS === 'android' ? 'android' : 'other',
+      success: false,
+      errorMessage: error instanceof Error ? error.message : 'Unknown error',
+    });
+    
+    return { success: false, shown: false };
+  }
+}
+
+/**
+ * Check if review request is available
+ * Respects platform rate limiting
+ * 
+ * @returns Promise with availability status
+ * 
+ * @example
+ * ```typescript
+ * import { canRequestReview } from '@billdog.io/react-native';
+ * 
+ * const { available } = await canRequestReview();
+ * if (available) {
+ *   await requestReview();
+ * }
+ * ```
+ */
+export async function canRequestReview(): Promise<{ available: boolean }> {
+  if (native && typeof native.canRequestReview === 'function') {
+    try {
+      const available = await native.canRequestReview();
+      return { available: !!available };
+    } catch (e) {}
+  }
+  try {
+    const InAppReview = await loadInAppReview();
+    if (InAppReview && typeof InAppReview.isAvailable === 'function') {
+      return { available: !!InAppReview.isAvailable() };
+    }
+    // No native module installed — only the store-page fallback is possible,
+    // and only if store IDs are configured. (Previously this returned `true`
+    // unconditionally even though the fallback URL was a placeholder.)
+    return { available: hasStoreFallback() };
+  } catch (error) {
+    console.error('Error checking review availability:', error);
+    return { available: false };
+  }
+}
+
+/**
+ * Open the app store for manual review
+ * Used as fallback when native review is unavailable
+ */
+async function openStoreForReview(): Promise<{ success: boolean; shown: boolean }> {
+  try {
+    // Audit fix — source real store IDs from BillDogConfiguration instead of the
+    // old `YOUR_APP_ID` / `YOUR_PACKAGE_NAME` placeholders (which produced a
+    // broken deep-link). If neither a native module nor a configured ID exists,
+    // report unavailable rather than opening a dead URL.
+    const cfg = BillDogConfiguration.config as { appStoreId?: string; androidPackageName?: string };
+    let storeUrl: string | null = null;
+
+    if (Platform.OS === 'ios') {
+      if (cfg.appStoreId) {
+        storeUrl = `itms-apps://itunes.apple.com/app/id${cfg.appStoreId}?action=write-review`;
+      }
+    } else if (Platform.OS === 'android') {
+      if (cfg.androidPackageName) {
+        storeUrl = `market://details?id=${cfg.androidPackageName}`;
+      }
+    }
+
+    if (!storeUrl) {
+      console.warn(
+        '[BillDog] Cannot request a review: install `react-native-in-app-review` for the native prompt, ' +
+        'or set `appStoreId` (iOS) / `androidPackageName` (Android) in BillDogConfiguration.configure() for the store-page fallback.'
+      );
+      return { success: false, shown: false };
+    }
+
+    const canOpen = await Linking.canOpenURL(storeUrl);
+    if (canOpen) {
+      await Linking.openURL(storeUrl);
+      return { success: true, shown: true };
+    }
+
+    return { success: false, shown: false };
+  } catch (error) {
+    console.error('Error opening store:', error);
+    return { success: false, shown: false };
+  }
+}