@stripe/stripe-react-native 0.58.0 → 0.59.1

package/src/connect/Components.tsx

@@ -24,6 +24,39 @@ import { useConnectComponents } from './ConnectComponentsProvider';
 export { NavigationBar } from './NavigationBar';
 export type { NavigationBarProps } from './NavigationBar';
 
+/**
+ * A full-screen modal component for Connect account onboarding.
+ * Guides connected accounts through the process of providing required information.
+ *
+ * **Platform differences:**
+ * - iOS: Uses native modal with UIKit navigation bar
+ * - Android: Uses React Native Modal with custom navigation bar
+ *
+ * @param props.title - Optional title displayed in navigation bar
+ * @param props.onExit - Required callback when user closes the onboarding flow
+ * @param props.onStepChange - Optional callback fired when onboarding step changes
+ * @param props.recipientTermsOfServiceUrl - URL for recipient terms of service
+ * @param props.fullTermsOfServiceUrl - URL for full terms of service
+ * @param props.privacyPolicyUrl - URL for privacy policy
+ * @param props.collectionOptions - Configuration for which account fields to collect
+ * @param props.onLoaderStart - Callback when component begins loading
+ * @param props.onLoadError - Callback when component fails to load
+ * @param props.onPageDidLoad - Callback when component finishes loading
+ *
+ * @example
+ * ```tsx
+ * <ConnectAccountOnboarding
+ *   title="Complete your account setup"
+ *   onExit={() => navigation.goBack()}
+ *   onStepChange={({ step }) => console.log('Current step:', step)}
+ *   collectionOptions={{
+ *     fields: 'currently_due',
+ *     futureRequirements: 'include'
+ *   }}
+ * />
+ * ```
+ * @category Connect
+ */
 export function ConnectAccountOnboarding({
   title,
   onExit,
@@ -178,6 +211,28 @@ export function ConnectAccountOnboarding({
   );
 }
 
+/**
+ * Displays a list of payments for the connected account with optional filtering.
+ * Embed this component to show payment history and details.
+ *
+ * @param props.defaultFilters - Optional filters to apply to the payments list
+ * @param props.onLoaderStart - Callback when component begins loading
+ * @param props.onLoadError - Callback when component fails to load
+ * @param props.onPageDidLoad - Callback when component finishes loading
+ * @param props.style - Optional styling for the component container
+ *
+ * @example
+ * ```tsx
+ * <ConnectPayments
+ *   defaultFilters={{
+ *     status: ['successful', 'pending'],
+ *     date: { after: new Date('2024-01-01') }
+ *   }}
+ *   style={{ flex: 1 }}
+ * />
+ * ```
+ * @category Connect
+ */
 export function ConnectPayments({
   defaultFilters,
   onLoaderStart,
@@ -205,6 +260,21 @@ export function ConnectPayments({
   );
 }
 
+/**
+ * Displays payout information for the connected account.
+ * Shows payout history, schedules, and details.
+ *
+ * @param props.onLoaderStart - Callback when component begins loading
+ * @param props.onLoadError - Callback when component fails to load
+ * @param props.onPageDidLoad - Callback when component finishes loading
+ * @param props.style - Optional styling for the component container
+ *
+ * @example
+ * ```tsx
+ * <ConnectPayouts style={{ flex: 1 }} />
+ * ```
+ * @category Connect
+ */
 export function ConnectPayouts({
   onLoaderStart,
   onLoadError,
@@ -222,6 +292,27 @@ export function ConnectPayouts({
   );
 }
 
+/**
+ * Displays detailed information for a specific payment.
+ * Typically used in a modal or detail view after selecting a payment from ConnectPayments.
+ *
+ * @param props.payment - The payment ID to display details for
+ * @param props.onClose - Required callback when user closes the detail view
+ * @param props.onLoaderStart - Callback when component begins loading
+ * @param props.onLoadError - Callback when component fails to load
+ * @param props.onPageDidLoad - Callback when component finishes loading
+ * @param props.style - Optional styling for the component container
+ *
+ * @example
+ * ```tsx
+ * <ConnectPaymentDetails
+ *   payment="py_1234567890"
+ *   onClose={() => setShowDetails(false)}
+ *   style={{ flex: 1 }}
+ * />
+ * ```
+ * @category Connect
+ */
 export function ConnectPaymentDetails({
   payment,
   onClose,

package/src/connect/ConnectComponentsProvider.tsx

@@ -5,6 +5,8 @@ import type {
   LoadConnectAndInitialize,
   StripeConnectInstance,
 } from './connectTypes';
+import { AnalyticsClient } from './analytics/AnalyticsClient';
+import { Constants } from '../functions';
 
 class ConnectInstance implements StripeConnectInstance {
   initParams: StripeConnectInitParams;
@@ -19,6 +21,29 @@ class ConnectInstance implements StripeConnectInstance {
   }
 }
 
+/**
+ * Creates a Connect instance for use with ConnectComponentsProvider.
+ * This instance manages the configuration and state for Connect embedded components.
+ *
+ * @param initParams - Initialization parameters including publishableKey and fetchClientSecret
+ * @returns A StripeConnectInstance that can be passed to ConnectComponentsProvider
+ *
+ * @example
+ * ```ts
+ * const connectInstance = loadConnectAndInitialize({
+ *   publishableKey: 'pk_test_123',
+ *   fetchClientSecret: async () => {
+ *     const response = await fetch('/account_session');
+ *     const { client_secret } = await response.json();
+ *     return client_secret;
+ *   },
+ *   appearance: {
+ *     variables: { colorPrimary: '#635BFF' }
+ *   }
+ * });
+ * ```
+ * @category Connect
+ */
 export const loadConnectAndInitialize: LoadConnectAndInitialize = (
   initParams: StripeConnectInitParams
 ): StripeConnectInstance => {
@@ -34,6 +59,7 @@ export type ConnectComponentsPayload = {
   appearance: StripeConnectInitParams['appearance'];
   locale: StripeConnectInitParams['locale'];
   connectInstance: ConnectInstance;
+  analyticsClient: AnalyticsClient;
 };
 
 const ConnectComponentsContext =
@@ -41,6 +67,42 @@ const ConnectComponentsContext =
 
 ConnectComponentsContext.displayName = 'ConnectComponents';
 
+/**
+ * Context provider that makes Connect instance configuration available to embedded components.
+ * Wrap your Connect components with this provider to enable them to access the shared configuration.
+ *
+ * @param props.connectInstance - Instance created via loadConnectAndInitialize
+ * @param props.children - React components to render within the provider
+ * @returns JSX.Element
+ *
+ * @throws Error if connectInstance is not created via loadConnectAndInitialize
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const [connectInstance] = useState(() => {
+ *     const fetchClientSecret = async () => {
+ *       const response = await fetch('/account_session', { method: "POST" });
+ *       const { client_secret: clientSecret } = await response.json();
+ *       return clientSecret;
+ *     };
+ *
+ *     return loadConnectAndInitialize({
+ *       publishableKey: 'pk_test_123',
+ *       fetchClientSecret: fetchClientSecret,
+ *       appearance,
+ *     });
+ *   });
+ *
+ *   return (
+ *     <ConnectComponentsProvider connectInstance={connectInstance}>
+ *       <ConnectPayouts />
+ *     </ConnectComponentsProvider>
+ *   );
+ * }
+ * ```
+ * @category Connect
+ */
 export const ConnectComponentsProvider = ({
   children,
   connectInstance,
@@ -59,6 +121,11 @@ export const ConnectComponentsProvider = ({
     connectInstance.initParams.locale
   );
 
+  // Initialize analytics client with native system info
+  const analyticsClient = useMemo(() => {
+    return new AnalyticsClient(Constants.SYSTEM_INFO);
+  }, []);
+
   if (!connectInstance.onUpdate) {
     connectInstance.onUpdate = (options: StripeConnectUpdateParams) => {
       if (options.appearance) {
@@ -71,8 +138,8 @@ export const ConnectComponentsProvider = ({
   }
 
   const value = useMemo(
-    () => ({ connectInstance, locale, appearance }),
-    [connectInstance, locale, appearance]
+    () => ({ connectInstance, locale, appearance, analyticsClient }),
+    [connectInstance, locale, appearance, analyticsClient]
   );
 
   return (

package/src/connect/EmbeddedComponent.tsx

@@ -26,6 +26,7 @@ import type {
   StripeConnectInitParams,
 } from './connectTypes';
 import type { FinancialConnections } from '../types';
+import { ComponentAnalyticsClient } from './analytics/ComponentAnalyticsClient';
 
 const DEVELOPMENT_MODE = false;
 const DEVELOPMENT_URL =
@@ -35,6 +36,12 @@ const BASE_URL = DEVELOPMENT_MODE ? DEVELOPMENT_URL : PRODUCTION_URL;
 
 const sdkVersion = pjson.version;
 
+// Android deep link polling configuration
+// These constants control the polling mechanism that prevents Expo Router from dismissing screens
+const POLLING_INTERVAL_MS = 500; // How often to check for pending deep links
+const URL_DEDUPLICATION_TIMEOUT_MS = 1000; // How long to remember handled URLs
+const DEEP_LINK_GRACE_PERIOD_MS = 500; // Time to wait for deep link after app resumes
+
 // react-native-webview.html will only load versions in the format X.Y.Z
 if (!/^\d+\.\d+\.\d+$/.test(sdkVersion)) {
   throw new Error(
@@ -139,11 +146,18 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
     WebView: typeof WebView | null;
   } | null>(null);
 
-  // Store pending authenticated webview promise (for Android Custom Tabs)
-  const pendingAuthWebViewPromise = useRef<{
-    id: string;
-    callback: (id: string, url: string | null) => void;
-  } | null>(null);
+  // Store pending authenticated webview promises (for Android Custom Tabs)
+  // Uses a Map keyed by auth session ID to support multiple auth flows.
+  // Currently processes promises in FIFO order (first entry resolved first).
+  const pendingAuthWebViewPromises = useRef<
+    Map<
+      string,
+      {
+        callback: (id: string, url: string | null) => void;
+        timeoutId?: NodeJS.Timeout;
+      }
+    >
+  >(new Map());
 
   // Store pending Financial Connections promise
   const pendingFinancialConnectionsPromise = useRef<{
@@ -151,6 +165,10 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
     cleanup: () => void;
   } | null>(null);
 
+  // Track recently handled URLs to prevent duplicate processing
+  // This is needed because the SDK uses dual delivery paths (setIntent + direct emit)
+  const recentlyHandledUrls = useRef<Set<string>>(new Set());
+
   const loadWebViewComponent = useCallback(async () => {
     if (dynamicWebview) return;
 
@@ -170,16 +188,106 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
 
   const appState = useRef<AppStateStatus>(AppState.currentState);
 
+  // Android deep link polling mechanism (Android-only)
+  //
+  // PROBLEM: On Android, completing auth in Custom Tabs causes a stripe-connect:// deep link
+  // that gets broadcast to React Native's Linking module, which triggers Expo Router and
+  // dismisses the current screen.
+  //
+  // SOLUTION: This polling mechanism intercepts the deep link before Expo Router receives it:
+  // 1. MainActivity.onNewIntent() captures stripe-connect:// URLs and stores them
+  // 2. This effect polls for pending URLs while auth is active
+  // 3. URLs are processed directly and never broadcast to Expo Router
+  // 4. Deduplication prevents the same URL from being processed twice
+  //
+  // This preserves the navigation stack and prevents unwanted screen dismissals.
+  useEffect(() => {
+    if (Platform.OS !== 'android') return;
+
+    const pollInterval = setInterval(async () => {
+      if (pendingAuthWebViewPromises.current.size === 0) {
+        return;
+      }
+
+      try {
+        const pendingUrls =
+          await NativeStripeSdk.pollAndClearPendingStripeConnectUrls();
+
+        if (pendingUrls && pendingUrls.length > 0) {
+          pendingUrls.forEach((url: string) => {
+            if (url.startsWith('stripe-connect://')) {
+              // Deduplication: Skip if we've handled this exact URL
+              if (recentlyHandledUrls.current.has(url)) {
+                return;
+              }
+
+              // Mark as handled
+              recentlyHandledUrls.current.add(url);
+
+              // Clear from the set after deduplication timeout
+              setTimeout(() => {
+                recentlyHandledUrls.current.delete(url);
+              }, URL_DEDUPLICATION_TIMEOUT_MS);
+
+              const firstEntry = pendingAuthWebViewPromises.current
+                .entries()
+                .next().value;
+
+              if (firstEntry) {
+                const [id, promiseData] = firstEntry;
+
+                // Clear the timeout if it exists
+                if (promiseData.timeoutId) {
+                  clearTimeout(promiseData.timeoutId);
+                }
+
+                // Remove from Map and invoke callback
+                pendingAuthWebViewPromises.current.delete(id);
+                promiseData.callback(id, url);
+
+                // Reset the Android flag
+                NativeStripeSdk.authWebViewDeepLinkHandled(id).catch(() => {
+                  // Intentionally silent - flag reset is not critical
+                });
+              }
+            }
+          });
+        }
+      } catch (_error) {
+        // Intentionally silent - polling will retry on next interval
+      }
+    }, POLLING_INTERVAL_MS);
+
+    return () => {
+      clearInterval(pollInterval);
+    };
+  }, []);
+
+  // Handle app state changes to detect when user returns from auth flow
   useEffect(() => {
     const subscription = AppState.addEventListener('change', (nextAppState) => {
       if (
         appState.current.match(/inactive|background/) &&
         nextAppState === 'active'
       ) {
-        if (pendingAuthWebViewPromise.current) {
-          const { id, callback } = pendingAuthWebViewPromise.current;
-          pendingAuthWebViewPromise.current = null;
-          callback(id, null);
+        if (pendingAuthWebViewPromises.current.size > 0) {
+          // Give the deep link handler time to process the URL
+          // If no deep link arrives within the grace period, assume the user cancelled
+          pendingAuthWebViewPromises.current.forEach((promiseData, id) => {
+            // Only set timeout if one doesn't already exist
+            if (!promiseData.timeoutId) {
+              const timeoutId = setTimeout(() => {
+                const stillPending = pendingAuthWebViewPromises.current.get(id);
+                if (stillPending) {
+                  pendingAuthWebViewPromises.current.delete(id);
+                  stillPending.callback(id, null);
+                }
+              }, DEEP_LINK_GRACE_PERIOD_MS);
+
+              // Store the timeout ID so we can clear it later if needed
+              promiseData.timeoutId = timeoutId;
+            }
+          });
         }
       }
 
@@ -187,13 +295,23 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
     });
 
     return () => {
-      pendingAuthWebViewPromise.current = null;
+      // Clear all pending timeouts and promises
+      // We intentionally want the latest ref value at cleanup time
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      const promises = pendingAuthWebViewPromises.current;
+      promises.forEach((promiseData, _id) => {
+        if (promiseData.timeoutId) {
+          clearTimeout(promiseData.timeoutId);
+        }
+      });
+      promises.clear();
       pendingFinancialConnectionsPromise.current?.cleanup();
       subscription.remove();
     };
   }, []);
 
-  const { connectInstance, appearance, locale } = useConnectComponents();
+  const { connectInstance, appearance, locale, analyticsClient } =
+    useConnectComponents();
   const { fonts, publishableKey, fetchClientSecret, overrides } =
     connectInstance.initParams as StripeConnectInitParamsInternal;
 
@@ -207,6 +325,22 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
     style,
   } = props;
 
+  // Initialize component analytics client
+  const componentAnalytics = useMemo(
+    () =>
+      new ComponentAnalyticsClient(analyticsClient, {
+        publishableKey,
+        platformId: overrides?.platformId,
+        merchantId: overrides?.merchantId,
+        livemode:
+          typeof overrides?.livemode === 'boolean'
+            ? overrides.livemode
+            : publishableKey?.startsWith('pk_live_'),
+        component,
+      }),
+    [analyticsClient, publishableKey, overrides, component]
+  );
+
   const hashParams = {
     component,
     publicKey: publishableKey,
@@ -292,6 +426,21 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
     return undefined;
   }, [WebViewComponent]);
 
+  // Track component lifecycle events
+  useEffect(() => {
+    // Log component created
+    componentAnalytics.logComponentCreated();
+  }, [componentAnalytics]);
+
+  // Track component viewed (when web view is visible)
+  const [hasBeenViewed, setHasBeenViewed] = useState(false);
+  const handleLayout = useCallback(() => {
+    if (!hasBeenViewed) {
+      setHasBeenViewed(true);
+      componentAnalytics.logComponentViewed();
+    }
+  }, [hasBeenViewed, componentAnalytics]);
+
   const handleAuthWebViewResult = (id: string, resultUrl: string | null) => {
     ref.current?.injectJavaScript(`
       (function() {
@@ -339,10 +488,16 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
 
   const onMessageCallback = useCallback(
     async (event: WebViewMessageEvent) => {
-      const message = JSON.parse(event.nativeEvent.data) as {
-        type: string;
-        data?: unknown;
-      };
+      let message: { type: string; data?: unknown };
+      try {
+        message = JSON.parse(event.nativeEvent.data);
+      } catch (error) {
+        componentAnalytics.logDeserializeMessageError(
+          'unknown',
+          error instanceof Error ? error : new Error(String(error))
+        );
+        return;
+      }
 
       if (message.type === 'fetchClientSecret') {
         const clientSecret = await fetchClientSecret().catch((error) => {
@@ -360,7 +515,13 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
         // message.data is of type string
         console.debug(`[EmbeddedComponent ${component}]: ${message.data}`);
       } else if (message.type === 'pageDidLoad') {
+        const pageViewId = (message.data as { pageViewId?: string })
+          ?.pageViewId;
+        componentAnalytics.logComponentWebPageLoaded(pageViewId);
         onPageDidLoad?.();
+      } else if (message.type === 'componentLoaded') {
+        // Connect JS fully initialized
+        componentAnalytics.logComponentLoaded();
       } else if (message.type === 'accountSessionClaimed') {
         // message.data is of type {elementTagName: string, merchantId: string}
       } else if (message.type === 'openFinancialConnections') {
@@ -488,7 +649,12 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
           // remove the 'set' prefix and lowercase the first letter
           const functionName =
             setter.charAt(3).toLowerCase() + setter.substring(4);
-          callbacks?.[functionName]?.(value);
+          if (callbacks?.[functionName]) {
+            callbacks[functionName](value);
+          } else {
+            // Unrecognized setter function
+            componentAnalytics.logUnrecognizedSetter(setter);
+          }
         }
       } else if (message.type === 'openAuthenticatedWebView') {
         const { url, id } = message.data as { id: string; url: string };
@@ -501,22 +667,51 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
           return;
         }
 
+        // Log authenticated web view opened
+        componentAnalytics.logAuthenticatedWebViewOpened(id);
+
         // On Android, we need to wait for the deep link callback
         // On iOS, the promise resolves with the redirect URL
         NativeStripeSdk.openAuthenticatedWebView(id, url)
           .then((result) => {
             if (Platform.OS === 'ios') {
               // iOS returns the redirect URL directly
-              handleAuthWebViewResult(id, result?.url ?? null);
+              const resultUrl = result?.url ?? null;
+              if (resultUrl) {
+                componentAnalytics.logAuthenticatedWebViewRedirected(id);
+              } else {
+                componentAnalytics.logAuthenticatedWebViewCanceled(id);
+              }
+              handleAuthWebViewResult(id, resultUrl);
             } else {
-              // Android: Store promise to be resolved by deep link listener
-              pendingAuthWebViewPromise.current = {
-                id,
-                callback: handleAuthWebViewResult,
-              };
+              // Android: Store promise in Map to be resolved by deep link listener
+              pendingAuthWebViewPromises.current.set(id, {
+                callback: (authId: string, resultUrl: string | null) => {
+                  if (resultUrl) {
+                    componentAnalytics.logAuthenticatedWebViewRedirected(
+                      authId
+                    );
+                  } else {
+                    componentAnalytics.logAuthenticatedWebViewCanceled(authId);
+                  }
+                  handleAuthWebViewResult(authId, resultUrl);
+                },
+              });
             }
           })
-          .catch(handleUnexpectedError);
+          .catch((error) => {
+            if (__DEV__) {
+              console.error(
+                `[EmbeddedComponent] Error opening authenticated webview:`,
+                error
+              );
+            }
+            componentAnalytics.logAuthenticatedWebViewError(
+              id,
+              error instanceof Error ? error : new Error(String(error))
+            );
+            handleUnexpectedError(error);
+          });
       } else {
         // unhandled message
       }
@@ -524,6 +719,7 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
     [
       callbacks,
       component,
+      componentAnalytics,
       fetchClientSecret,
       handleUnexpectedError,
       onLoadError,
@@ -534,19 +730,33 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
 
   const onShouldStartLoadWithRequest = useCallback(
     (event: ShouldStartLoadRequest) => {
-      const { url } = event;
+      const { url, navigationType } = event;
+
+      // Handle CSV export downloads
+      if (isCsvExportUrl(url)) {
+        NativeStripeSdk.downloadAndShareFile(url, null)
+          .then((result) => {
+            if (!result.success) {
+              console.warn('CSV export share failed:', result.error);
+            }
+          })
+          .catch((error) => {
+            handleUnexpectedError(error);
+          });
+        return false; // Block WebView navigation
+      }
+
+      if (navigationType !== 'click') return true;
 
       // Allow navigation within allowed Stripe domains (matching iOS SDK behavior)
       if (ALLOWED_STRIPE_HOSTS.some((host) => url.includes(host))) {
         return true; // Allow in-WebView navigation
       }
 
-      // Validate and open external links in system browser
-      if (isValidUrl(url)) {
-        Linking.openURL(url).catch((error) => {
-          handleUnexpectedError(error);
-        });
-      }
+      // Open external links in system browser
+      Linking.openURL(url).catch((error) => {
+        handleUnexpectedError(error);
+      });
 
       return false; // Block in-WebView navigation for external links
     },
@@ -582,6 +792,7 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
       injectedJavaScriptBeforeContentLoaded={'(function() {})();'}
       onMessage={onMessageCallback}
       onShouldStartLoadWithRequest={onShouldStartLoadWithRequest}
+      onLayout={handleLayout}
       // Camera/Media Permissions - matches iOS SDK behavior
       mediaCapturePermissionGrantType="grantIfSameHostElsePrompt"
       allowsInlineMediaPlayback={true}
@@ -616,3 +827,16 @@ function isValidUrl(url: string): boolean {
     return false;
   }
 }
+
+// Detects Stripe CSV export URLs
+function isCsvExportUrl(url: string): boolean {
+  try {
+    const parsedUrl = new URL(url);
+    return (
+      parsedUrl.hostname.includes('stripe-data-exports') ||
+      parsedUrl.pathname.includes('stripe-data-exports')
+    );
+  } catch {
+    return false;
+  }
+}