@tryheliumai/paywall-sdk-react-native 0.2.22 → 3.0.3

package/src/native-interface.tsx

@@ -1,128 +1,42 @@
-import { findNodeHandle, NativeModules, View, NativeEventEmitter, requireNativeComponent } from 'react-native';
-import React, { createRef, useEffect, useState, createContext, useContext } from 'react';
-import type { HeliumConfig, HeliumUpsellViewProps, HeliumDownloadStatus, PaywallInfo } from './types';
+import {
+  NativeModules,
+  NativeEventEmitter,
+  requireNativeComponent,
+} from 'react-native';
+import type {
+  HeliumConfig,
+  HeliumUpsellViewProps,
+  HeliumDownloadStatus,
+  PaywallInfo,
+  PresentUpsellParams,
+  PaywallEventHandlers,
+  HeliumPaywallEvent,
+} from './types';
 
 const { HeliumBridge } = NativeModules;
 const heliumEventEmitter = new NativeEventEmitter(HeliumBridge);
 
 // Register the native component once at module level
-// This ensures it's only registered once, even during hot reloading
-export const NativeHeliumUpsellView = requireNativeComponent<HeliumUpsellViewProps>('HeliumUpsellView');
+export const NativeHeliumUpsellView =
+  requireNativeComponent<HeliumUpsellViewProps>('HeliumUpsellView');
 
-let isProviderMounted = false;
 // Add a flag to track if initialization has occurred
 let isInitialized = false;
-// Add a promise to track when the provider is mounted
-let providerMountedPromise: Promise<void>;
-let resolveProviderMounted: () => void;
-
-// Initialize the promise
-providerMountedPromise = new Promise<void>((resolve) => {
-  resolveProviderMounted = resolve;
-  // If provider is already mounted, resolve immediately
-  if (isProviderMounted) {
-    resolve();
-  }
-});
-
 // Add module-level download status tracking
 let globalDownloadStatus: HeliumDownloadStatus = 'notStarted';
 export const getDownloadStatus = () => globalDownloadStatus;
 
-// Create a context for the download status
-interface HeliumContextType {
-  downloadStatus: HeliumDownloadStatus;
-  setDownloadStatus: (status: HeliumDownloadStatus) => void;
-}
-
-const HeliumContext = createContext<HeliumContextType | undefined>(undefined);
-
-// Update the setter ref to also update global status
-let setDownloadStatusRef: ((status: HeliumDownloadStatus) => void) | null = null;
 const updateDownloadStatus = (status: HeliumDownloadStatus) => {
   globalDownloadStatus = status;
-  setDownloadStatusRef?.(status);
-};
-
-// Hook to use the Helium context
-export const useHelium = () => {
-  const context = useContext(HeliumContext);
-  if (!context) {
-    throw new Error('useHelium must be used within a HeliumProvider');
-  }
-  return context;
 };
 
-interface HeliumProviderProps {
-  children: React.ReactNode;
-  fallbackView?: React.ComponentType;
-}
-
-// Create a ref to store the fallback view reference
-const fallbackRef = createRef<View>();
-// Store a reference to the fallback view component
-let FallbackViewComponent: React.ComponentType | null = null;
-
-// Provider component to be rendered at the app root
-export const HeliumProvider = ({ children, fallbackView }: HeliumProviderProps) => {
-  // TODO - deprecate fallbackView (and maybe HeliumProvider too?)
-  if (fallbackView) {
-    console.warn('HeliumProvider: fallbackView is deprecated. Use onFallback passed to presentUpsell instead.');
-  }
-  const FallbackView = (() => null);
-  // Add state for download status
-  const [downloadStatus, setDownloadStatus] = useState<HeliumDownloadStatus>('notStarted');
-
-  // Store the setter in the ref so it can be accessed outside of components
-  useEffect(() => {
-    setDownloadStatusRef = setDownloadStatus;
-    // Store the fallback view component for later use
-    FallbackViewComponent = FallbackView;
-  }, [setDownloadStatus, FallbackView]);
-
-  useEffect(() => {
-    isProviderMounted = true;
-    // Resolve the promise when the provider is mounted
-    resolveProviderMounted();
-    return () => {
-      isProviderMounted = false;
-      setDownloadStatusRef = null;
-    };
-  }, []);
-
-  return (
-    <HeliumContext.Provider value={{ downloadStatus, setDownloadStatus }}>
-      <View 
-        ref={fallbackRef}
-        collapsable={false}
-        style={{ 
-          display: 'none'
-        }}
-      >
-        <FallbackView />
-      </View>
-      {children}
-    </HeliumContext.Provider>
-  );
-};
-
-// Update initialize to accept full config
 export const initialize = async (config: HeliumConfig) => {
   // Early return if already initialized
   if (isInitialized) {
+    console.log('[Helium] Already initialized, skipping...');
     return;
   }
 
-  // Wait for the provider to be mounted if it's not already
-  if (!isProviderMounted) {
-    await providerMountedPromise;
-  }
-
-  const viewTag = findNodeHandle(fallbackRef.current);
-  if (!viewTag) {
-    throw new Error('Failed to get fallback view reference. Make sure HeliumProvider is mounted with a fallback view.');
-  }
-
   const purchaseHandler = {
     makePurchase: config.purchaseConfig.makePurchase,
     restorePurchases: config.purchaseConfig.restorePurchases,
@@ -131,36 +45,36 @@ export const initialize = async (config: HeliumConfig) => {
   // Update download status to inProgress
   updateDownloadStatus('inProgress');
 
+  // Ensure these don't get added more than once
+  heliumEventEmitter.removeAllListeners('helium_paywall_event');
+  heliumEventEmitter.removeAllListeners('paywallEventHandlers');
+  heliumEventEmitter.removeAllListeners('helium_make_purchase');
+  heliumEventEmitter.removeAllListeners('helium_restore_purchases');
+
   // Set up event listeners
   heliumEventEmitter.addListener(
     'helium_paywall_event',
-    (event: any) => {
+    (event: HeliumPaywallEvent) => {
       // Handle download status events
       if (event.type === 'paywallsDownloadSuccess') {
         updateDownloadStatus('success');
       } else if (event.type === 'paywallsDownloadError') {
         updateDownloadStatus('failed');
       }
-      // Handle fallback view visibility
-      else if (event.type === 'paywallOpen' && event.paywallTemplateName === 'Fallback') {
-        if (fallbackRef.current) {
-          fallbackRef.current.setNativeProps({
-            style: { display: 'flex' }
-          });
-        }
-      } else if (event.type === 'paywallClose' && event.paywallTemplateName === 'Fallback') {
-        if (fallbackRef.current) {
-          fallbackRef.current.setNativeProps({
-            style: { display: 'none' }
-          });
-        }
-      }
 
       // Forward all events to the callback provided in config
       config.onHeliumPaywallEvent(event);
     }
   );
 
+  // Set up paywall event handlers listener
+  heliumEventEmitter.addListener(
+    'paywallEventHandlers',
+    (event: HeliumPaywallEvent) => {
+      callPaywallEventHandlers(event);
+    }
+  );
+
   // Set up purchase event listener using the determined handler
   heliumEventEmitter.addListener(
     'helium_make_purchase',
@@ -169,7 +83,7 @@ export const initialize = async (config: HeliumConfig) => {
       HeliumBridge.handlePurchaseResponse({
         transactionId: event.transactionId,
         status: result.status,
-        error: result.error
+        error: result.error,
       });
     }
   );
@@ -181,7 +95,7 @@ export const initialize = async (config: HeliumConfig) => {
       const success = await purchaseHandler.restorePurchases();
       HeliumBridge.handleRestoreResponse({
         transactionId: event.transactionId,
-        status: success ? 'restored' : 'failed'
+        status: success ? 'restored' : 'failed',
       });
     }
   );
@@ -212,30 +126,30 @@ export const initialize = async (config: HeliumConfig) => {
   HeliumBridge.initialize(
     {
       apiKey: config.apiKey,
-      fallbackPaywall: viewTag,
-      triggers: config.triggers || [],
       customUserId: config.customUserId || null,
       customAPIEndpoint: config.customAPIEndpoint || null,
-      customUserTraits: config.customUserTraits == null ? {} : config.customUserTraits,
+      customUserTraits:
+        config.customUserTraits == null ? {} : config.customUserTraits,
       revenueCatAppUserId: config.revenueCatAppUserId,
       fallbackBundleUrlString: fallbackBundleUrlString,
       fallbackBundleString: fallbackBundleString,
+      paywallLoadingConfig: config.paywallLoadingConfig,
     },
     {}
   );
-  
+
   // Mark as initialized after successful initialization
   isInitialized = true;
 };
 
-// Update the other methods to be synchronous
+let paywallEventHandlers: PaywallEventHandlers | undefined;
+let presentOnFallback: (() => void) | undefined;
 export const presentUpsell = ({
   triggerName,
   onFallback,
-}: {
-  triggerName: string;
-  onFallback?: () => void;
-}) => {
+  eventHandlers,
+  customPaywallTraits,
+}: PresentUpsellParams) => {
   HeliumBridge.canPresentUpsell(
     triggerName,
     (canPresent: boolean, reason: string) => {
@@ -249,9 +163,13 @@ export const presentUpsell = ({
       }
 
       try {
-        HeliumBridge.presentUpsell(triggerName);
+        paywallEventHandlers = eventHandlers;
+        presentOnFallback = onFallback;
+        HeliumBridge.presentUpsell(triggerName, customPaywallTraits || null);
       } catch (error) {
         console.log('[Helium] Present error', error);
+        paywallEventHandlers = undefined;
+        presentOnFallback = undefined;
         onFallback?.();
         HeliumBridge.fallbackOpenOrCloseEvent(triggerName, true, 'presented');
       }
@@ -259,6 +177,60 @@ export const presentUpsell = ({
   );
 };
 
+function callPaywallEventHandlers(event: HeliumPaywallEvent) {
+  if (paywallEventHandlers) {
+    switch (event.type) {
+      case 'paywallOpen':
+        paywallEventHandlers?.onOpen?.({
+          type: 'paywallOpen',
+          triggerName: event.triggerName ?? 'unknown',
+          paywallName: event.paywallName ?? 'unknown',
+          isSecondTry: event.isSecondTry ?? false,
+          viewType: 'presented',
+        });
+        break;
+      case 'paywallClose':
+        paywallEventHandlers?.onClose?.({
+          type: 'paywallClose',
+          triggerName: event.triggerName ?? 'unknown',
+          paywallName: event.paywallName ?? 'unknown',
+          isSecondTry: event.isSecondTry ?? false,
+        });
+        if (!event.isSecondTry) {
+          paywallEventHandlers = undefined;
+        }
+        presentOnFallback = undefined;
+        break;
+      case 'paywallDismissed':
+        paywallEventHandlers?.onDismissed?.({
+          type: 'paywallDismissed',
+          triggerName: event.triggerName ?? 'unknown',
+          paywallName: event.paywallName ?? 'unknown',
+          isSecondTry: event.isSecondTry ?? false,
+        });
+        break;
+      case 'purchaseSucceeded':
+        paywallEventHandlers?.onPurchaseSucceeded?.({
+          type: 'purchaseSucceeded',
+          productId: event.productId ?? 'unknown',
+          triggerName: event.triggerName ?? 'unknown',
+          paywallName: event.paywallName ?? 'unknown',
+          isSecondTry: event.isSecondTry ?? false,
+        });
+        break;
+      case 'paywallSkipped':
+        paywallEventHandlers = undefined;
+        presentOnFallback = undefined;
+        break;
+      case 'paywallOpenFailed':
+        paywallEventHandlers = undefined;
+        presentOnFallback?.();
+        presentOnFallback = undefined;
+        break;
+    }
+  }
+}
+
 export const hideUpsell = () => {
   HeliumBridge.hideUpsell();
 };
@@ -295,52 +267,13 @@ export const handleDeepLink = async (url: string | null): Promise<boolean> => {
         console.log('[Helium] Handled deep link:', handled);
         resolve(handled);
       });
+    } else {
+      resolve(false);
     }
   });
 };
 
-// Update the UpsellView component to handle the style prop
-export const UpsellView: React.FC<HeliumUpsellViewProps & {
-  fallbackViewProps?: Record<string, any>;
-  fallbackViewWrapperStyles?: Record<string, any>;
-}> = ({ trigger, fallbackViewProps, fallbackViewWrapperStyles }) => {
-  const { downloadStatus } = useHelium();
-
-  const showFallback = downloadStatus === 'notStarted' ||
-    downloadStatus === 'inProgress' ||
-    downloadStatus === 'failed';
-
-  useEffect(() => {
-    if (showFallback && FallbackViewComponent) {
-      HeliumBridge.fallbackOpenOrCloseEvent(trigger, true, 'embedded');
-    }
-    return () => {
-      if (showFallback && FallbackViewComponent) {
-        HeliumBridge.fallbackOpenOrCloseEvent(trigger, false, 'embedded');
-      }
-    };
-  }, [showFallback, trigger]);
-
-  // If download status is notStarted or inProgress, we haven't fully initialized yet
-  // In this case, we should render the fallback view
-  if (showFallback) {
-    // If we have a fallback view component, render it
-    if (FallbackViewComponent) {
-      return (
-        <View style={fallbackViewWrapperStyles}>
-          <FallbackViewComponent {...fallbackViewProps} />
-        </View>
-      );
-    }
-    
-    return null;
-  }
-  
-  // Use NativeHeliumUpsellView directly
-  return <NativeHeliumUpsellView trigger={trigger} />;
-};
-
 export const HELIUM_CTA_NAMES = {
   SCHEDULE_CALL: 'schedule_call',
   SUBSCRIBE_BUTTON: 'subscribe_button',
-}
+};

package/src/types.ts

@@ -1,9 +1,18 @@
-export type HeliumTransactionStatus = 'purchased' | 'failed' | 'cancelled' | 'pending' | 'restored';
+export type HeliumTransactionStatus =
+  | 'purchased'
+  | 'failed'
+  | 'cancelled'
+  | 'pending'
+  | 'restored';
 export type HeliumPurchaseResult = {
   status: HeliumTransactionStatus;
   error?: string; // Optional error message
 };
-export type HeliumDownloadStatus = 'success' | 'failed' | 'inProgress' | 'notStarted';
+export type HeliumDownloadStatus =
+  | 'success'
+  | 'failed'
+  | 'inProgress'
+  | 'notStarted';
 
 // --- Purchase Configuration Types ---
 
@@ -28,6 +37,133 @@ export function createCustomPurchaseConfig(callbacks: {
   };
 }
 
+export type TriggerLoadingConfig = {
+  /** Whether to show loading state for this trigger. Set to nil to use the global `useLoadingState` setting. */
+  useLoadingState?: boolean;
+  /** Maximum seconds to show loading for this trigger. Set to nil to use the global `loadingBudget` setting. */
+  loadingBudget?: number;
+};
+
+export type HeliumPaywallLoadingConfig = {
+  /**
+   * Whether to show a loading state while fetching paywall configuration.
+   * When true, shows a loading view for up to `loadingBudget` seconds before falling back.
+   * Default: true
+   */
+  useLoadingState?: boolean;
+  /**
+   * Maximum time (in seconds) to show the loading state before displaying fallback.
+   * After this timeout, the fallback view will be shown even if the paywall is still downloading.
+   * Default: 2.0 seconds
+   */
+  loadingBudget?: number;
+  /**
+   * Optional per-trigger loading configuration overrides.
+   * Use this to customize loading behavior for specific triggers.
+   * Keys are trigger names, values are TriggerLoadingConfig instances.
+   * Example: Disable loading for "onboarding" trigger while keeping it for others.
+   */
+  perTriggerLoadingConfig?: Record<string, TriggerLoadingConfig>;
+};
+
+// Event handler types for per-presentation event handling
+export interface PaywallEventHandlers {
+  onOpen?: (event: PaywallOpenEvent) => void;
+  onClose?: (event: PaywallCloseEvent) => void;
+  onDismissed?: (event: PaywallDismissedEvent) => void;
+  onPurchaseSucceeded?: (event: PurchaseSucceededEvent) => void;
+}
+
+// Typed event interfaces
+export interface PaywallOpenEvent {
+  type: 'paywallOpen';
+  triggerName: string;
+  paywallName: string;
+  isSecondTry: boolean;
+  viewType?: 'presented' | 'embedded' | 'triggered';
+}
+
+export interface PaywallCloseEvent {
+  type: 'paywallClose';
+  triggerName: string;
+  paywallName: string;
+  isSecondTry: boolean;
+}
+
+export interface PaywallDismissedEvent {
+  type: 'paywallDismissed';
+  triggerName: string;
+  paywallName: string;
+  isSecondTry: boolean;
+}
+
+export interface PurchaseSucceededEvent {
+  type: 'purchaseSucceeded';
+  productId: string;
+  triggerName: string;
+  paywallName: string;
+  isSecondTry: boolean;
+}
+
+export type HeliumPaywallEvent = {
+  type:
+    | 'paywallOpen'
+    | 'paywallClose'
+    | 'paywallDismissed'
+    | 'paywallOpenFailed'
+    | 'paywallSkipped'
+    | 'paywallButtonPressed'
+    | 'productSelected'
+    | 'purchasePressed'
+    | 'purchaseSucceeded'
+    | 'purchaseCancelled'
+    | 'purchaseFailed'
+    | 'purchaseRestored'
+    | 'purchaseRestoreFailed'
+    | 'purchasePending'
+    | 'initializeStart'
+    | 'paywallsDownloadSuccess'
+    | 'paywallsDownloadError'
+    | 'paywallWebViewRendered';
+  triggerName?: string;
+  paywallName?: string;
+  /**
+   * @deprecated Use `paywallName` instead.
+   */
+  paywallTemplateName?: string;
+  productId?: string;
+  /**
+   * @deprecated Use `productId` instead.
+   */
+  productKey?: string;
+  ctaName?: string;
+  paywallDownloadTimeTakenMS?: number;
+  templateDownloadTimeTakenMS?: number;
+  imagesDownloadTimeTakenMS?: number;
+  stylesDownloadTimeTakenMS?: number;
+  fontsDownloadTimeTakenMS?: number;
+  bundleDownloadTimeMS?: number;
+  dismissAll?: boolean;
+  isSecondTry?: boolean;
+  error?: string;
+  /**
+   * @deprecated Use `error` instead.
+   */
+  errorDescription?: string;
+  /**
+   * Unix timestamp in seconds
+   */
+  timestamp?: number;
+};
+
+export type PresentUpsellParams = {
+  triggerName: string;
+  /** Optional. This will be called when paywall fails to show due to an unsuccessful paywall download or if an invalid trigger is provided. */
+  onFallback?: () => void;
+  eventHandlers?: PaywallEventHandlers;
+  customPaywallTraits?: Record<string, any>;
+};
+
 // --- Main Helium Configuration ---
 export interface HeliumConfig {
   /** Your Helium API Key */
@@ -35,12 +171,13 @@ export interface HeliumConfig {
   /** Configuration for handling purchases. Can be custom functions or a pre-built handler config. */
   purchaseConfig: HeliumPurchaseConfig;
   /** Callback for receiving all Helium paywall events. */
-  onHeliumPaywallEvent: (event: any) => void; // Still mandatory
+  onHeliumPaywallEvent: (event: HeliumPaywallEvent) => void;
 
   // Optional configurations
-  fallbackView?: number;
+  /** Fallback bundle in the rare situation that paywall is not ready to be shown. Highly recommended. See docs at https://docs.tryhelium.com/guides/fallback-bundle#react-native */
   fallbackBundle?: object;
-  triggers?: string[];
+  /** Configure loading behavior for paywalls that are mid-download. */
+  paywallLoadingConfig?: HeliumPaywallLoadingConfig;
   customUserId?: string;
   customAPIEndpoint?: string;
   customUserTraits?: Record<string, any>;