@unifold/connect-react-native 0.1.25 → 0.1.27

package/README.md

@@ -4,15 +4,24 @@ React Native/Expo SDK for crypto deposits and onramp with Unifold.
 
 ## Installation
 
-```bash
-# npm
-npm install @unifold/connect-react-native react-native-svg react-native-webview
-
-# yarn
-yarn add @unifold/connect-react-native react-native-svg react-native-webview
+Native-linked libraries are **peer dependencies** so your app (or Expo) owns a single version. That avoids duplicate `react-native-svg` / `react-native-webview` installs and the `overrides` workarounds that come from nested copies.
 
-# Expo (recommended)
-npx expo install @unifold/connect-react-native react-native-svg react-native-webview
+```bash
+# Expo (recommended) — versions aligned with your SDK
+npx expo install @unifold/connect-react-native \
+  @react-native-async-storage/async-storage \
+  @stripe/stripe-react-native \
+  react-native-gesture-handler \
+  react-native-svg \
+  react-native-webview
+
+# npm / yarn — install the same peers your Expo SDK would use
+npm install @unifold/connect-react-native \
+  @react-native-async-storage/async-storage \
+  @stripe/stripe-react-native \
+  react-native-gesture-handler \
+  react-native-svg \
+  react-native-webview
 ```
 
 ### iOS (bare React Native only)
@@ -21,6 +30,29 @@ npx expo install @unifold/connect-react-native react-native-svg react-native-web
 cd ios && pod install
 ```
 
+### Stripe Link Pay (native)
+
+Link Pay uses `@stripe/stripe-react-native`, which includes **native** code (Apple Pay, onramp Turbo Module). In **Expo**, add the [Stripe config plugin](https://docs.expo.dev/guides/using-stripe/) to `app.json` (for example `merchantIdentifier`, `enableApplePay`, `includeOnramp: true`). You need a **development build** or EAS build — **Expo Go** does not ship Stripe’s onramp native module.
+
+Importing `@unifold/connect-react-native` loads the Stripe UI registration in the same JS bundle as the provider. Ensure the peer dependencies in **Installation** above are installed so Metro does not duplicate native modules.
+
+`expo-constants` is an **optional** peer (pulled in by Expo). It is used only to read `merchantIdentifier` from your Stripe plugin config in JS; bare React Native apps should pass `config.stripeMerchantIdentifier` on `UnifoldProvider` instead.
+
+#### Expo Go vs development build vs prebuild
+
+- **Expo Go** is a generic client: it does **not** include this app’s Stripe onramp native code, so Link Pay / onramp will not work there. That is a limitation of Expo Go, not of “Expo” as a whole.
+- A **development build** is *your* app binary (Stripe plugin + native modules baked in). Create it with **`npx expo prebuild`** (generates `ios/` / `android/`) and then **`npx expo run:ios`** / **`run:android`**, or with **EAS Build** (`eas build --profile development`). Day to day you still use **`expo start`** for JS; only the **installed** app is custom, not Expo Go.
+- **Simulator**: A development build usually runs on the **iOS Simulator** without the same provisioning hassle as a physical device for many flows. **Apple Pay** can still be picky (wallet sheet, merchant validation); use a **real device** when Apple Pay misbehaves on the simulator, and ensure the **merchant ID** exists in your [Apple Developer](https://developer.apple.com) account and matches `app.json` / Stripe.
+- **Certificates / signing**: Debug builds for Simulator often work with **Xcode automatic signing** and a free Apple ID. **Device** distribution (TestFlight, App Store) needs your normal certificates and team. Apple Pay production behavior also depends on merchant configuration in Apple and Stripe dashboards—not only the simulator.
+
+## Integration checklist
+
+1. **Peer dependencies** — Install everything in **Installation** (or `expo install …`). Missing peers often show up as duplicate native modules or Metro resolution errors.
+2. **`react-native-gesture-handler`** — In bare React Native, import it at the **entry file** first (see [React Navigation](https://reactnavigation.org/docs/getting-started/#installing-dependencies-into-a-bare-react-native-project)); Expo Router projects usually already satisfy this.
+3. **`UnifoldProvider` placement** — Wrap near the root so `beginDeposit` and theme context are available app-wide. Call `setDevApiUrl` **before** the provider if you use staging in development (see example app).
+4. **Stripe Link Pay** — Requires a **development / EAS build** on Expo (not Expo Go), the Stripe **config plugin** in `app.json`, and `config.enableStripeLinkPay: true`. Apple Pay needs a matching `merchantIdentifier` (plugin and/or `config.stripeMerchantIdentifier`; Expo apps can rely on plugin + `expo-constants` auto-read in `StripeOnramp`).
+5. **Theme** — `UnifoldProvider` applies `ThemeProvider` to **all** children. If you use another theme system, nest it inside or outside deliberately so `useTheme` resolves as you expect.
+
 ## Quick Start
 
 ### 1. Wrap your app with UnifoldProvider
@@ -160,6 +192,8 @@ await beginDeposit({
 | `config.fonts` | `FontConfig` | No | Granular font weight configuration |
 | `config.components` | `ComponentConfig` | No | Component-specific token overrides |
 | `config.sheetBorderRadius` | `SheetBorderRadius` | No | Border radius configuration for all bottom sheets (see below) |
+| `config.enableStripeLinkPay` | `boolean` | No | Show Pay with Link (Stripe) in the deposit menu (default: omit / falsy hides it). Stripe is bundled with Connect. |
+| `config.stripeMerchantIdentifier` | `string` | No | Apple Pay merchant id for Link Pay. Must match the Stripe Expo plugin in app.json. On Expo, omit if the id is only in the plugin (read from `expo-constants`). |
 
 ### SheetBorderRadius
 
@@ -269,8 +303,12 @@ import type {
 |------------|---------|
 | React Native | >= 0.72.0 |
 | Expo (optional) | >= 49.0.0 |
+| @react-native-async-storage/async-storage | >= 1.19.0 |
+| @stripe/stripe-react-native | >= 0.62.0 |
+| react-native-gesture-handler | >= 2.14.0 |
 | react-native-svg | >= 13.0.0 |
-| react-native-webview | >= 11.0.0 |
+| react-native-webview | >= 13.0.0 |
+| expo-constants (Expo only, optional) | >= 14.0.0 — used to mirror `merchantIdentifier` from the Stripe plugin into JS; omit on bare RN and set `config.stripeMerchantIdentifier` instead |
 
 ## Support
 

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React$1, { ReactNode } from 'react';
+export { AmountScreen, CreateSessionParams, CustomerVerification, KYCData, KYCWizardScreen, OnrampConfig, OnrampCustomer, OnrampError, OnrampErrorCode, OnrampScreen, OnrampSession, OnrampSessionTransactionDetails, OnrampStep, OnrampTransaction, StripeOnramp, StripeOnrampHook, StripeOnrampPreconfigure, StripeOnrampProps, getStripePublishableKey, setStripeOnrampApiUrl, setStripeOnrampPublishableKey, useStripeOnramp } from '@unifold/ui-react-native/stripe';
 
 /**
  * Unifold color palette for React Native
@@ -297,12 +298,18 @@ interface DepositModalProps {
     hideDepositTracker?: boolean;
     /** Show "Pay with Link" (Stripe) option in the deposit menu */
     enableStripeLinkPay?: boolean;
-    /** Injected StripeOnramp component — avoids bundling Stripe into the main entry */
+    /** Registered Stripe onramp component (Connect sets this from `enableStripeLinkPay`) */
     StripeOnrampComponent?: React$1.ComponentType<any>;
     /** Pre-fills Stripe Link Pay email — set via `beginDeposit({ stripeOnrampEmail })` (forwarded as `email` on `StripeOnramp`) */
     stripeOnrampEmail?: string;
     /** Pre-fills Stripe Link Pay phone — set via `beginDeposit({ stripeOnrampPhone })` (forwarded as `phone` on `StripeOnramp`) */
     stripeOnrampPhone?: string;
+    /**
+     * Apple Pay merchant id for Stripe Link Pay. Forwarded to `StripeOnramp` as `merchantIdentifier`.
+     * On Expo, you can omit this if the same value is set on the `@stripe/stripe-react-native` plugin
+     * in app.json (the UI reads it via `expo-constants`).
+     */
+    stripeMerchantIdentifier?: string;
     /**
      * Same ThemeProvider options as `UnifoldProvider` (`theme`, `components`, fonts, etc.).
      * Re-wrapped around the Stripe Link Pay sheet so nested modals receive theme context and
@@ -361,8 +368,9 @@ interface DepositModalProps {
 }
 
 /**
- * Set development API URL (only works in __DEV__ mode)
- * For internal Unifold developers testing against localhost
+ * Opt-in dev-only API base URL (staging, localhost, etc.).
+ * Stored on `globalThis` so it applies everywhere this file is inlined (e.g. Connect’s prebundle).
+ * No-op when not `__DEV__`; empty / whitespace clears the override.
  */
 declare function setDevApiUrl(url: string): void;
 
@@ -408,11 +416,10 @@ declare function useAllowedCountry(publishableKey: string, enabled?: boolean): A
 
 /**
  * Register the StripeOnramp component so the deposit menu can render it.
- * Called automatically by `@unifold/connect-react-native/stripe` when imported,
- * or manually by the consumer.
+ * Connect calls this once at SDK load (`register-stripe-onramp.ts`); you may call
+ * `registerStripeOnramp` again to swap in a custom implementation.
  *
- * Uses globalThis so the registration survives across separately-bundled entries
- * (tsup bundles index.js and stripe.js with splitting:false, creating isolated scopes).
+ * Uses globalThis so a custom registration can still be read consistently.
  */
 declare function registerStripeOnramp(component: React.ComponentType<any>): void;
 
@@ -439,10 +446,16 @@ interface UnifoldConnectProviderConfig {
         sheetBorderRadius?: DepositModalProps["sheetBorderRadius"];
         /**
          * Show "Pay with Link" (Stripe) option in the deposit menu.
-         * Requires `import "@unifold/connect-react-native/stripe"` in your app entry
-         * and `@stripe/stripe-react-native` to be installed.
+         * Stripe onramp is bundled with Connect; set to false to hide the option.
          */
         enableStripeLinkPay?: boolean;
+        /**
+         * Apple Pay merchant id (`merchant.com...`) for Stripe Link Pay. Must match the
+         * `merchantIdentifier` in the `@stripe/stripe-react-native` Expo plugin (app.json).
+         * On Expo you can omit this if it is only set in the plugin — `StripeOnramp` reads it from
+         * `expo-constants`. Use this for bare React Native or to override.
+         */
+        stripeMerchantIdentifier?: string;
     };
 }
 interface DepositResult {

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React$1, { ReactNode } from 'react';
+export { AmountScreen, CreateSessionParams, CustomerVerification, KYCData, KYCWizardScreen, OnrampConfig, OnrampCustomer, OnrampError, OnrampErrorCode, OnrampScreen, OnrampSession, OnrampSessionTransactionDetails, OnrampStep, OnrampTransaction, StripeOnramp, StripeOnrampHook, StripeOnrampPreconfigure, StripeOnrampProps, getStripePublishableKey, setStripeOnrampApiUrl, setStripeOnrampPublishableKey, useStripeOnramp } from '@unifold/ui-react-native/stripe';
 
 /**
  * Unifold color palette for React Native
@@ -297,12 +298,18 @@ interface DepositModalProps {
     hideDepositTracker?: boolean;
     /** Show "Pay with Link" (Stripe) option in the deposit menu */
     enableStripeLinkPay?: boolean;
-    /** Injected StripeOnramp component — avoids bundling Stripe into the main entry */
+    /** Registered Stripe onramp component (Connect sets this from `enableStripeLinkPay`) */
     StripeOnrampComponent?: React$1.ComponentType<any>;
     /** Pre-fills Stripe Link Pay email — set via `beginDeposit({ stripeOnrampEmail })` (forwarded as `email` on `StripeOnramp`) */
     stripeOnrampEmail?: string;
     /** Pre-fills Stripe Link Pay phone — set via `beginDeposit({ stripeOnrampPhone })` (forwarded as `phone` on `StripeOnramp`) */
     stripeOnrampPhone?: string;
+    /**
+     * Apple Pay merchant id for Stripe Link Pay. Forwarded to `StripeOnramp` as `merchantIdentifier`.
+     * On Expo, you can omit this if the same value is set on the `@stripe/stripe-react-native` plugin
+     * in app.json (the UI reads it via `expo-constants`).
+     */
+    stripeMerchantIdentifier?: string;
     /**
      * Same ThemeProvider options as `UnifoldProvider` (`theme`, `components`, fonts, etc.).
      * Re-wrapped around the Stripe Link Pay sheet so nested modals receive theme context and
@@ -361,8 +368,9 @@ interface DepositModalProps {
 }
 
 /**
- * Set development API URL (only works in __DEV__ mode)
- * For internal Unifold developers testing against localhost
+ * Opt-in dev-only API base URL (staging, localhost, etc.).
+ * Stored on `globalThis` so it applies everywhere this file is inlined (e.g. Connect’s prebundle).
+ * No-op when not `__DEV__`; empty / whitespace clears the override.
  */
 declare function setDevApiUrl(url: string): void;
 
@@ -408,11 +416,10 @@ declare function useAllowedCountry(publishableKey: string, enabled?: boolean): A
 
 /**
  * Register the StripeOnramp component so the deposit menu can render it.
- * Called automatically by `@unifold/connect-react-native/stripe` when imported,
- * or manually by the consumer.
+ * Connect calls this once at SDK load (`register-stripe-onramp.ts`); you may call
+ * `registerStripeOnramp` again to swap in a custom implementation.
  *
- * Uses globalThis so the registration survives across separately-bundled entries
- * (tsup bundles index.js and stripe.js with splitting:false, creating isolated scopes).
+ * Uses globalThis so a custom registration can still be read consistently.
  */
 declare function registerStripeOnramp(component: React.ComponentType<any>): void;
 
@@ -439,10 +446,16 @@ interface UnifoldConnectProviderConfig {
         sheetBorderRadius?: DepositModalProps["sheetBorderRadius"];
         /**
          * Show "Pay with Link" (Stripe) option in the deposit menu.
-         * Requires `import "@unifold/connect-react-native/stripe"` in your app entry
-         * and `@stripe/stripe-react-native` to be installed.
+         * Stripe onramp is bundled with Connect; set to false to hide the option.
          */
         enableStripeLinkPay?: boolean;
+        /**
+         * Apple Pay merchant id (`merchant.com...`) for Stripe Link Pay. Must match the
+         * `merchantIdentifier` in the `@stripe/stripe-react-native` Expo plugin (app.json).
+         * On Expo you can omit this if it is only set in the plugin — `StripeOnramp` reads it from
+         * `expo-constants`. Use this for bare React Native or to override.
+         */
+        stripeMerchantIdentifier?: string;
     };
 }
 interface DepositResult {