From idea to income: How to build seamless subscriptions with Expo and RevenueCat

EXPO_PUBLIC_REVENUECAT_IOS=<your_public_ios_sdk_key>
EXPO_PUBLIC_REVENUECAT_ANDROID=<your_public_android_sdk_key>

/**
 * usePurchasesInitialize.ts
 *
 * A custom React hook for initializing and managing RevenueCat in-app purchases.
 * This hook handles:
 * - One-time RevenueCat SDK initialization
 * - Subscription status verification with retry logic
 *
 * Created by @brandtnewlabs (www.brandtnewlabs.com)
 * A developer and designer helping teams build beautiful, reliable apps with React Native.
 *
 * This code is running in the Roamwise app (www.roamwise.app)
 *
 * Prerequisites:
 * - RevenueCat account setup (https://www.revenuecat.com/)
 * - API keys configured in your environment variables
 * - react-native-purchases package installed
 *
 * @see https://docs.revenuecat.com/docs/reactnative for official documentation
 */

import { useCallback, useEffect, useState } from 'react';
import { Platform } from 'react-native';
import Purchases from 'react-native-purchases';

import { useAppStore } from '@/store';

// Configuration constants
const MAX_RETRIES = 3;
const RETRY_DELAY = 2000; // Base delay in milliseconds before exponential backoff

// Get platform-specific API key from environment variables
const API_KEY = Platform.select({
  ios: process.env.EXPO_PUBLIC_REVENUECAT_API_KEY,
  android: process.env.EXPO_PUBLIC_REVENUECAT_API_KEY,
});

/**
 * A hook to initialize RevenueCat and verify subscription status
 *
 * @returns isInitialized - boolean indicating if RevenueCat was successfully initialized
 *
 * @example
 * // In your App.tsx or a high-level component:
 * function App() {
 *   // Initialize RevenueCat on component mount
 *   const isPurchasesInitialized = usePurchasesInitialize();
 *
 *   return (
 *     // Your app components
 *   );
 * }
 */
export function usePurchasesInitialize(): boolean {
  const setSubscriptionStatus = useAppStore((state) => state.setSubscriptionStatus);

  const [isInitialized, setIsInitialized] = useState(false);

  const initializePurchases = useCallback(async () => {
    if (!API_KEY) {
      console.error('[usePurchasesInitialize] Missing RevenueCat API key');
      setIsInitialized(false);
      return;
    }

    try {
      // Configure RevenueCat SDK
      Purchases.configure({ apiKey: API_KEY });

      // Verify subscription status
      const { hasActiveSubscription } = await verifySubscriptionStatus();

      // Update app state
      setSubscriptionStatus(hasActiveSubscription);
      setIsInitialized(true);
    } catch (error) {
      setIsInitialized(false);

      // Provide detailed error log
      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
      console.error(`[usePurchasesInitialize] Initialization failed: ${errorMessage}`);
    }
  }, [setSubscriptionStatus]);

  useEffect(() => {
    if (!isInitialized) {
      initializePurchases();
    }
  }, [initializePurchases, isInitialized]);

  return isInitialized;
}

/**
 * Interface for the return value of verifySubscriptionStatus
 */
interface SubscriptionStatusResult {
  /** Whether the user has an active subscription */
  hasActiveSubscription: boolean;
}

/**
 * Verifies the user's subscription status with exponential backoff retry
 * This function handles temporary network issues by retrying with increasing delays
 *
 * @param retryAttempt - Current retry attempt count
 * @returns Promise resolving to the subscription status
 */
export async function verifySubscriptionStatus(
  retryAttempt = 0,
): Promise<SubscriptionStatusResult> {
  try {
    // Get the latest customer information from RevenueCat
    const customerInfo = await Purchases.getCustomerInfo();

    // Check for active entitlements/subscriptions
    const activeSubscriptions = Object.values(customerInfo.entitlements.active);
    // Consider user subscribed if they have any active entitlement.
    // This allows for flexible A/B testing and future entitlements (not tied to a specific name).
    const hasActiveSubscription = activeSubscriptions.length > 0;

    return {
      hasActiveSubscription,
    };
  } catch (error) {
    // Implement exponential backoff for retries
    if (retryAttempt < MAX_RETRIES) {
      // Calculate delay with exponential backoff (2s, 3s, 4.5s)
      const backoffDelay = RETRY_DELAY * Math.pow(1.5, retryAttempt);

      // Wait for the calculated delay
      await new Promise((resolve) => setTimeout(resolve, backoffDelay));

      // Retry the verification with incremented attempt count
      return verifySubscriptionStatus(retryAttempt + 1);
    }

    // If we've exhausted all retry attempts, rethrow the error
    throw error;
  }
}

/**
 * NOTE: For blog readers
 *
 * The useAppStore is a global state management solution using Zustand
 * It should contain these methods:
 *
 * - setSubscriptionStatus(isActive: boolean): Sets whether user has active subscription
 */

function RootLayout() {
  // Initialize RevenueCat and perform initial check for pro access
  // Sets up the SDK and validates subscription status at app startup
  const isPurchasesInitialized = usePurchasesInitialize();

  return (
    <SafeAreaProvider>
      <GestureHandlerRootView>
        <Slot />
      </GestureHandlerRootView>
    </SafeAreaProvider>
  );
}

/**
 * usePurchasesMonitor.ts
 *
 * A custom React hook for monitoring RevenueCat in-app purchase status in real time.
 * This hook handles:
 * - Ongoing monitoring of RevenueCat subscription status after initialization
 * - Updating global app state when subscription status changes
 * - Listening for app foreground events and RevenueCat updates
 *
 * Created by @brandtnewlabs (www.brandtnewlabs.com)
 * A developer and designer helping teams build beautiful, reliable apps with React Native.
 *
 * This code is running in the Roamwise app (www.roamwise.app)
 *
 * Prerequisites:
 * - RevenueCat account setup (https://www.revenuecat.com/)
 * - API keys configured in your environment variables
 * - react-native-purchases package installed
 * - RevenueCat must be initialized before using this hook (see usePurchasesInitialize)
 *
 * @see https://docs.revenuecat.com/docs/reactnative for official documentation
 */

import { useCallback, useEffect, useState } from 'react';
import { AppState, AppStateStatus } from 'react-native';
import Purchases from 'react-native-purchases';

import { useAppStore } from '@/store';

import { verifySubscriptionStatus } from './usePurchasesInitialize';

// Interval (ms) to poll for Purchases SDK configuration
const PURCHASES_CONFIG_CHECK_INTERVAL = 1000;

/**
 * A hook to monitor RevenueCat subscription status and update app state on changes
 *
 * This hook should be used after RevenueCat has been initialized (see usePurchasesInitialize).
 * It listens for app foreground events and RevenueCat customer info updates, and will update
 * the global app state if the user's subscription status or info changes.
 *
 * @returns isPurchaseMonitorSetUp - boolean indicating if purchase monitoring is fully set up
 *
 * @example
 * // In your App.tsx or a high-level component:
 * function App() {
 *   const isPurchaseMonitorSetUp = usePurchasesMonitor();
 *   // ...
 * }
 */
export function usePurchasesMonitor(): boolean {
  const setSubscriptionStatus = useAppStore((state) => state.setSubscriptionStatus);

  // Tracks if Purchases SDK is configured
  const [arePurchasesConfigured, setArePurchasesConfigured] = useState(false);
  // Tracks if monitoring (listeners) is set up
  const [isPurchaseMonitorSetUp, setIsPurchaseMonitorSetUp] = useState(false);

  /**
   * Fetches and updates subscription status and info if changed.
   *
   * - Considers user subscribed if any entitlement is active (A/B test friendly)
   * - Batches state updates for efficiency
   */
  const refreshSubscriptionStatus = useCallback(async () => {
    if (!arePurchasesConfigured) return;

    try {
      const { hasActiveSubscription } = await verifySubscriptionStatus();
      setSubscriptionStatus(hasActiveSubscription);
    } catch (error) {
      console.error('[usePurchasesMonitor] Error refreshing subscription status:', error);
    }
  }, [arePurchasesConfigured, setSubscriptionStatus]);

  // Poll until Purchases SDK is configured
  useEffect(() => {
    const intervalId = setInterval(async () => {
      const configured = await Purchases.isConfigured();
      if (configured) {
        setArePurchasesConfigured(true);
        clearInterval(intervalId);
      }
    }, PURCHASES_CONFIG_CHECK_INTERVAL);

    return () => clearInterval(intervalId);
  }, []);

  // Listen for app foreground and RevenueCat updates
  useEffect(() => {
    if (!arePurchasesConfigured) {
      setIsPurchaseMonitorSetUp(false);
      return;
    }

    // Refresh on app foreground
    const appStateListener = AppState.addEventListener('change', (nextAppState: AppStateStatus) => {
      if (nextAppState === 'active') {
        refreshSubscriptionStatus();
      }
    });

    // Refresh on RevenueCat customer info updates
    Purchases.addCustomerInfoUpdateListener(refreshSubscriptionStatus);

    setIsPurchaseMonitorSetUp(true);

    return () => {
      appStateListener.remove();
      setIsPurchaseMonitorSetUp(false);
    };
  }, [refreshSubscriptionStatus, arePurchasesConfigured]);

  return isPurchaseMonitorSetUp;
}

function RootLayout() {
  // Initialize RevenueCat and perform initial check for pro access
  // Sets up the SDK and validates subscription status at app startup
  const isPurchasesInitialized = usePurchasesInitialize();

  // Monitor ongoing subscription status changes
  // Updates store when app returns to foreground or when subscription changes
  const isPurchaseMonitorSetUp = usePurchasesMonitor();

  return (
    <SafeAreaProvider>
      <GestureHandlerRootView>
        <Slot />
      </GestureHandlerRootView>
    </SafeAreaProvider>
  );
}

/**
 * usePurchases.ts
 *
 * A custom React hook for interacting with RevenueCat in-app purchases.
 * Handles:
 * - Fetching available purchase packages (products)
 * - Fetching and updating customer info
 * - Purchasing and restoring packages
 * - Exposing loading, processing, and error states
 * - Checks if RevenueCat Purchases SDK is initialized before making SDK calls
 *
 * Usage:
 *   const {
 *     availablePackages,
 *     customerInfo,
 *     isLoading,
 *     isProcessing,
 *     error, // { message: string, code?: string }
 *     purchasePackage,
 *     restorePurchases,
 *     hasActiveEntitlement,
 *   } = usePurchases();
 *
 * Notes:
 * - Does not update global state; use usePurchasesMonitor for global subscription state.
 * - Does not initialize RevenueCat; use usePurchasesInitialize for SDK setup.
 * - The `error` object is structured: { message: string, code?: string }
 * - If the SDK is not initialized, error.code will be 'NOT_INITIALIZED'
 */

import { useCallback, useEffect, useRef, useState } from 'react';
import Purchases, {
  CustomerInfo,
  PURCHASES_ERROR_CODE,
  PurchasesError,
  PurchasesPackage,
} from 'react-native-purchases';

/**
 * Type guard for RevenueCat PurchasesError
 */
function isPurchasesError(error: unknown): error is PurchasesError {
  return typeof error === 'object' && error !== null && 'code' in error;
}

/**
 * Structured error type for usePurchases
 * error: { message: string, code?: string }
 */
export interface PurchasesHookError {
  message: string;
  code?: string;
}

/**
 * Return type for usePurchases hook
 */
export interface UsePurchasesResult {
  availablePackages: readonly PurchasesPackage[];
  customerInfo: CustomerInfo | null;
  isLoading: boolean;
  isProcessing: boolean;
  error: PurchasesHookError | null;
  purchasePackage: (pkg: PurchasesPackage) => Promise<CustomerInfo>;
  restorePurchases: () => Promise<CustomerInfo>;
  hasActiveEntitlement: (info: CustomerInfo, entitlementId?: string) => boolean;
}

/**
 * usePurchases
 *
 * Provides RevenueCat product offerings, customer info, and purchase/restore actions.
 * Checks if Purchases SDK is initialized before making SDK calls.
 * Returns a structured error object for UI consumption.
 */
export function usePurchases(): UsePurchasesResult {
  // List of available purchase packages (products)
  const [availablePackages, setAvailablePackages] = useState<readonly PurchasesPackage[]>([]);
  // RevenueCat customer info (entitlements, etc.)
  const [currentCustomerInfo, setCurrentCustomerInfo] = useState<CustomerInfo | null>(null);
  // Loading state for initial fetch
  const [isLoading, setIsLoading] = useState(true);
  // Processing state for purchase/restore actions
  const [isProcessing, setIsProcessing] = useState(false);
  // Structured error object for UI consumption
  const [error, setError] = useState<PurchasesHookError | null>(null);
  // Tracks if the component has mounted to prevent state updates on unmounted components during async operations
  const hasMounted = useRef(true);

  /**
   * Centralized error handler
   * Ignores user-cancelled purchase errors
   * Sets a structured error object for UI consumption
   */
  const handlePurchasesError = useCallback((error: unknown) => {
    if (isPurchasesError(error) && error.code === PURCHASES_ERROR_CODE.PURCHASE_CANCELLED_ERROR) {
      return;
    }
    if (isPurchasesError(error)) {
      setError({ message: error.message, code: String(error.code) });
    } else if (error instanceof Error) {
      setError({ message: error.message });
    } else {
      setError({ message: String(error) });
    }
  }, []);

  /**
   * Fetch available packages and customer info on mount
   * Checks if Purchases SDK is initialized before making SDK calls
   * Sets a structured error if not initialized
   */
  useEffect(() => {
    hasMounted.current = true;

    // Fetch offerings and customer info in parallel
    const fetchPurchasesData = async () => {
      setError(null);
      try {
        // Check if Purchases SDK is configured
        const isConfigured = await Purchases.isConfigured();
        if (!isConfigured) {
          setError({ message: 'Purchases SDK is not initialized.', code: 'NOT_INITIALIZED' });
          setIsLoading(false);
          return;
        }
        const [offerings, info] = await Promise.all([
          Purchases.getOfferings(),
          Purchases.getCustomerInfo(),
        ]);
        if (hasMounted.current) {
          setAvailablePackages(offerings.current?.availablePackages ?? []);
          setCurrentCustomerInfo(info);
        }
      } catch (error) {
        handlePurchasesError(error);
      } finally {
        if (hasMounted.current) setIsLoading(false);
      }
    };

    fetchPurchasesData();

    // Cleanup: mark as unmounted to prevent state updates
    return () => {
      hasMounted.current = false;
    };
  }, [handlePurchasesError]);

  /**
   * Purchase a package and update customer info
   * Checks if Purchases SDK is initialized before making SDK calls
   * Sets a structured error if not initialized
   */
  const purchasePackage = useCallback(
    async (pkg: PurchasesPackage) => {
      setIsProcessing(true);
      setError(null);
      try {
        // Check if Purchases SDK is configured
        const isConfigured = await Purchases.isConfigured();
        if (!isConfigured) {
          const notInitError = {
            message: 'Purchases SDK is not initialized.',
            code: 'NOT_INITIALIZED',
          };
          setError(notInitError);
          throw notInitError;
        }
        const { customerInfo } = await Purchases.purchasePackage(pkg);
        setCurrentCustomerInfo(customerInfo);
        return customerInfo;
      } catch (error) {
        handlePurchasesError(error);
        throw error;
      } finally {
        setIsProcessing(false);
      }
    },
    [handlePurchasesError],
  );

  /**
   * Restore previous purchases and update customer info
   * Checks if Purchases SDK is initialized before making SDK calls
   * Sets a structured error if not initialized
   */
  const restorePurchases = useCallback(async () => {
    setIsProcessing(true);
    setError(null);
    try {
      // Check if Purchases SDK is configured
      const isConfigured = await Purchases.isConfigured();
      if (!isConfigured) {
        const notInitError = {
          message: 'Purchases SDK is not initialized.',
          code: 'NOT_INITIALIZED',
        };
        setError(notInitError);
        throw notInitError;
      }
      const info = await Purchases.restorePurchases();
      setCurrentCustomerInfo(info);
      return info;
    } catch (error) {
      handlePurchasesError(error);
      throw error;
    } finally {
      setIsProcessing(false);
    }
  }, [handlePurchasesError]);

  /**
   * Check if a CustomerInfo object has an active entitlement
   * If entitlementId is omitted, returns true if any entitlement is active
   */
  const hasActiveEntitlement = useCallback(
    (info: CustomerInfo, entitlementId?: string): boolean => {
      if (!info?.entitlements?.active) return false;
      const activeEntitlements = info.entitlements.active;
      if (!entitlementId) {
        return Object.keys(activeEntitlements).length > 0;
      }
      return activeEntitlements[entitlementId] !== undefined;
    },
    [],
  );

  return {
    availablePackages,
    customerInfo: currentCustomerInfo,
    isLoading,
    isProcessing,
    error,
    purchasePackage,
    restorePurchases,
    hasActiveEntitlement,
  };
}

export default usePurchases;