@moonpay/platform-sdk-react-native 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,370 @@
+# @moonpay/platform-sdk-react-native
+
+React Native SDK for the [MoonPay Developer Platform](https://dev.moonpay.com). Connect customers to MoonPay, fetch quotes and payment methods, and render MoonPay frames (widget, Apple Pay, Google Pay, buy, add-card, challenge) as WebViews in your React Native app.
+
+> React Native guides are not yet published on [dev.moonpay.com](https://dev.moonpay.com) — this README is the current starting point. The platform concepts (sessions, connections, quotes, frames) are the same as for the [web SDK](https://www.npmjs.com/package/@moonpay/platform-sdk-web), so the existing guides still apply.
+
+## Installation
+
+```bash
+npm install @moonpay/platform-sdk-react-native react-native-webview
+```
+
+For Expo projects:
+
+```bash
+npx expo install react-native-webview
+npm install @moonpay/platform-sdk-react-native
+```
+
+Peer dependencies:
+
+- `react` >= 18
+- `react-native` >= 0.73 (Hermes supported)
+- `react-native-webview` >= 13
+
+The SDK's crypto layer is pure JavaScript (`@noble` libraries) — no native modules or polyfills required.
+
+## Quick start
+
+**1. Create a session server-side** with [`@moonpay/platform-sdk-node`](https://www.npmjs.com/package/@moonpay/platform-sdk-node) and pass the session token to your app:
+
+```typescript
+// On your server — never ship your API key in the app
+import { createServerClient } from '@moonpay/platform-sdk-node';
+
+const server = createServerClient({ apiKey: process.env.MOONPAY_API_KEY });
+
+const result = await server.createSession({
+  externalCustomerId: 'customer-123',
+  deviceIp: customerIp,
+});
+
+if (result.ok) {
+  // Send result.value.sessionToken to your app
+}
+```
+
+**2. Wrap your app in `MoonPayProvider`** with the session token:
+
+```tsx
+import { MoonPayProvider } from '@moonpay/platform-sdk-react-native';
+
+export function App() {
+  return (
+    <MoonPayProvider sessionToken={sessionToken}>
+      <YourApp />
+    </MoonPayProvider>
+  );
+}
+```
+
+`MoonPayProvider` also accepts optional `apiBaseUrl` and `frameBaseUrl` props that point the SDK at a different MoonPay environment — useful if MoonPay gives you test endpoints during onboarding. Leave them unset to use production.
+
+**3. Check the connection and connect the customer:**
+
+```tsx
+import { Button } from 'react-native';
+import { useMoonPay } from '@moonpay/platform-sdk-react-native';
+
+function BuyScreen() {
+  const { client } = useMoonPay();
+
+  const startConnect = async () => {
+    const connection = await client.getConnection();
+    if (!connection.ok) {
+      console.error(connection.error);
+      return;
+    }
+
+    if (connection.value.status === 'connectionRequired') {
+      // Presents the connect flow full-screen so the customer can sign in to MoonPay
+      await client.connect({
+        onEvent: (event) => console.log(event.kind),
+      });
+    }
+  };
+
+  return <Button title="Get started" onPress={startConnect} />;
+}
+```
+
+All client methods return a `Result<T, E>` discriminated union instead of throwing — check `result.ok` before using `result.value`.
+
+## Connection statuses
+
+`getConnection()` resolves with one of six statuses. Handle `connectionRequired` and `active` at minimum:
+
+| Status | Meaning | What to do |
+|--------|---------|------------|
+| `connectionRequired` | New or expired customer | Run the connect flow — `client.connect()` or `<MoonPayConnect>`. Headless integrations: `<MoonPayAuth>` |
+| `active` | Customer is connected | Proceed — quotes, payment methods, and payment frames are ready to use |
+| `pending` | KYC decision is delayed | Show a waiting state; the status can resolve to `active` on a later visit |
+| `failed` | Terminal failure, such as a KYC rejection | Do not retry the connect flow; the `reason` field describes the failure |
+| `unavailable` | Customer is in a restricted location | Hide MoonPay functionality |
+| `termsAcceptanceRequired` | Headless integrations only — the customer has no valid Terms of Use attestation on file | Show the Terms of Use in your UI, capture acceptance via `POST /platform/v1/terms/attestations`, then check the connection again |
+
+## Two ways to render frames
+
+The SDK supports both a declarative and an imperative style:
+
+- **Components** (`<MoonPayWidget>`, `<MoonPayApplePayButton>`, …) render inline wherever you place them in your layout. Prefer these — you keep full control over placement, styling, and navigation.
+- **Client methods** (`client.setupWidget()`, `client.connect()`, …) present the frame in a full-screen modal managed by the SDK. Useful when you want a flow to take over the screen without layout work.
+
+Headless frames (`<MoonPayConnectionCheck>`, `<MoonPayBuyFrame>`, `<MoonPayConnectionReset>`) render nothing visible — they run a flow in a hidden WebView and report results through `onEvent`.
+
+## Examples
+
+### Connect a customer inline
+
+Render the connect flow as part of your own screen instead of a modal:
+
+```tsx
+import { MoonPayConnect } from '@moonpay/platform-sdk-react-native';
+
+function ConnectScreen({ onConnected }: { onConnected: () => void }) {
+  return (
+    <MoonPayConnect
+      theme={{ appearance: 'dark' }}
+      onEvent={(event) => {
+        if (event.kind === 'complete') onConnected();
+      }}
+    />
+  );
+}
+```
+
+On completion, credentials are applied to the shared client automatically — you can call payment methods right away.
+
+### Authenticate with email and OTP (headless)
+
+Identity API partners can use `<MoonPayAuth>` instead of the full connect flow — it drives the customer through email and OTP authentication only. The auth frame needs a `clientToken`, which the SDK stores automatically when `getConnection()` resolves with `connectionRequired`, so always check the connection first:
+
+```tsx
+import { useState } from 'react';
+import { Button } from 'react-native';
+import { MoonPayAuth, useMoonPay } from '@moonpay/platform-sdk-react-native';
+
+function SignInScreen({ onAuthenticated }: { onAuthenticated: () => void }) {
+  const { client } = useMoonPay();
+  const [showAuth, setShowAuth] = useState(false);
+
+  const start = async () => {
+    const connection = await client.getConnection();
+    if (connection.ok && connection.value.status === 'connectionRequired') {
+      setShowAuth(true); // the clientToken is now stored on the client
+    }
+  };
+
+  if (!showAuth) {
+    return <Button title="Sign in" onPress={start} />;
+  }
+
+  return (
+    <MoonPayAuth
+      onEvent={(event) => {
+        if (event.kind === 'complete') onAuthenticated();
+      }}
+    />
+  );
+}
+```
+
+Mounting `<MoonPayAuth>` — or calling `setupAuth()` — without that prior `getConnection()` call emits an `error` event. On completion, credentials are applied to the shared client automatically, and `event.payload.status` is either `active` or `termsAcceptanceRequired` (see [Connection statuses](#connection-statuses)).
+
+### Get a quote and render the widget
+
+```tsx
+import { useState } from 'react';
+import { Button } from 'react-native';
+import { MoonPayWidget, useMoonPay } from '@moonpay/platform-sdk-react-native';
+
+function WidgetScreen() {
+  const { client } = useMoonPay();
+  const [quote, setQuote] = useState<string | null>(null);
+
+  const loadQuote = async () => {
+    const result = await client.getQuote({
+      source: { asset: { code: 'USD' }, amount: '100' },
+      destination: { asset: { code: 'BTC' } },
+    });
+    if (result.ok) {
+      setQuote(result.value.data.signature);
+    }
+  };
+
+  if (!quote) {
+    return <Button title="Get quote" onPress={loadQuote} />;
+  }
+
+  return (
+    <MoonPayWidget
+      quote={quote}
+      onEvent={(event) => {
+        if (event.kind === 'complete') {
+          console.log('Transaction complete', event.payload.transaction.id);
+        }
+      }}
+    />
+  );
+}
+```
+
+### Render an Apple Pay button
+
+The button mounts inline at its natural size (height 48 by default). Quote updates are pushed into the frame without remounting:
+
+```tsx
+import { MoonPayApplePayButton } from '@moonpay/platform-sdk-react-native';
+
+<MoonPayApplePayButton
+  quote={quoteSignature}
+  onEvent={(event) => {
+    switch (event.kind) {
+      case 'complete':
+        console.log('Paid', event.payload.transaction.id);
+        break;
+      case 'challenge':
+        // Card issuer requires 3DS — see "Handle a 3DS challenge" below
+        setChallengeUrl(event.payload.url);
+        break;
+      case 'quoteExpired':
+        // Fetch a fresh quote and push it without remounting
+        refreshQuote().then((signature) => event.payload.setQuote(signature));
+        break;
+      case 'unsupported':
+        // Device or region does not support Apple Pay — render a fallback
+        break;
+    }
+  }}
+/>
+```
+
+`<MoonPayGooglePayButton>` and `<MoonPayBuyButton>` follow the same pattern.
+
+### Execute a buy headlessly
+
+`<MoonPayBuyFrame>` executes a buy in a hidden WebView — your own UI stays in control the whole time. It needs an executable quote: one created with a `wallet` and `paymentMethod`. Render the frame when the customer confirms the purchase:
+
+```tsx
+import { MoonPayBuyFrame } from '@moonpay/platform-sdk-react-native';
+
+<MoonPayBuyFrame
+  quote={quoteSignature}
+  externalTransactionId="order-123"
+  onEvent={(event) => {
+    switch (event.kind) {
+      case 'complete':
+        console.log('Transaction complete', event.payload.transaction.id);
+        break;
+      case 'challenge':
+        // Card issuer requires 3DS — see "Handle a 3DS challenge" below
+        setChallengeUrl(event.payload.url);
+        break;
+      case 'error':
+        console.error(event.payload.code, event.payload.message);
+        break;
+    }
+  }}
+/>
+```
+
+Like the payment buttons, `quote` is reactive — pushing a fresh signature does not remount the frame.
+
+### Handle a 3DS challenge
+
+Payment frames (buy, buy button, Apple Pay, Google Pay) emit a `challenge` event when the card issuer requires verification. The event payload carries the full challenge URL:
+
+```tsx
+// In the payment frame's onEvent handler:
+case 'challenge':
+  setChallengeUrl(event.payload.url);
+  break;
+```
+
+Mount `<MoonPayChallenge>` with that URL. The challenge frame reports the final outcome itself — `complete` carries the finished transaction, and `cancelled` means the customer dismissed the verification. Unmount it on either event:
+
+```tsx
+import { MoonPayChallenge } from '@moonpay/platform-sdk-react-native';
+
+{challengeUrl && (
+  <MoonPayChallenge
+    url={challengeUrl}
+    onEvent={(event) => {
+      if (event.kind === 'complete' && event.payload.flow === 'buy') {
+        console.log('Transaction complete', event.payload.transaction.id);
+      }
+      if (event.kind === 'complete' || event.kind === 'cancelled') {
+        setChallengeUrl(null);
+      }
+    }}
+  />
+)}
+```
+
+## Error handling
+
+Methods never throw — they return `Result<T, E>`:
+
+```typescript
+const result = await client.getPaymentMethods();
+
+if (result.ok) {
+  console.log(result.value.data);
+} else {
+  console.error(result.error.code, result.error.message);
+}
+```
+
+## What the SDK provides
+
+**Hook**
+
+- `useMoonPay()` — returns the `client` from the nearest `MoonPayProvider`
+
+**Client methods**
+
+- **Connection** — `getConnection()`, `connect()`, `setupAuth()` (requires a prior `getConnection()` call), `resetConnection()`
+- **Payments data** — `getQuote()`, `getPaymentMethods()`, `deletePaymentMethod()`, `listTransactions()`, `getTransaction()`
+- **Frames** — `setupWidget()`, `setupBuy()`, `setupChallenge()`, `setupAddCard()`
+- **Identity** — `createIdentity()`, `getIdentity()`, `updateIdentity()`, `verifyIdentity()` and file upload helpers for headless integrations
+
+**Components**
+
+| Component | Renders |
+|-----------|---------|
+| `<MoonPayConnect>` | Connect flow, inline |
+| `<MoonPayConnectionCheck>` | Headless connection check (nothing visible) |
+| `<MoonPayConnectionReset>` | Headless connection reset (nothing visible) |
+| `<MoonPayAuth>` | Email/OTP auth for headless / Identity API integrations — check the connection first |
+| `<MoonPayWidget>` | Full buy widget, inline |
+| `<MoonPayApplePayButton>` | Apple Pay button, inline |
+| `<MoonPayGooglePayButton>` | Google Pay button, inline |
+| `<MoonPayBuyButton>` | Card buy button, inline |
+| `<MoonPayBuyFrame>` | Headless buy execution (nothing visible) |
+| `<MoonPayAddCard>` | Card entry form, inline |
+| `<MoonPayChallenge>` | 3DS challenge, inline |
+
+All visible components accept a `style` prop and an `onEvent` callback typed to that frame's events.
+
+## Related packages
+
+| Package | Use it for |
+|---------|------------|
+| `@moonpay/platform-sdk-node` | Server-side session creation |
+| `@moonpay/platform-sdk-web` | Web apps |
+| `@moonpay/platform-protocol` | Shared protocol and API types |
+
+## Documentation
+
+Platform guides and API reference: [dev.moonpay.com](https://dev.moonpay.com)
+
+- [Introduction](https://dev.moonpay.com/platform/overview/introduction)
+- [API & SDK credentials](https://dev.moonpay.com/platform/guides/api-and-sdk-credentials)
+- [Connect a customer](https://dev.moonpay.com/platform/guides/connect-a-customer)
+- [Pay with Widget](https://dev.moonpay.com/platform/guides/pay-with-widget)
+- [Pay with Apple Pay](https://dev.moonpay.com/platform/guides/pay-with-apple-pay)
+
+## License
+
+MIT

package/dist/index.cjs

@@ -180,7 +180,10 @@ function applyCredentialsOnComplete(msg, ctx) {
   if (msg.kind !== "complete" || !ctx.privateKey)
     return;
   const connection = msg.payload;
-  if (connection.status !== import_connection.ConnectionStatus.active)
+  if (connection.status !== import_connection.ConnectionStatus.active && connection.status !== import_connection.ConnectionStatus.connectionRequired) {
+    return;
+  }
+  if (!connection.credentials)
     return;
   const creds = (0, import_platform_sdk_core.decryptCredentials)(connection.credentials, ctx.privateKey);
   ctx.core.context.setAccessToken(creds.accessToken);
@@ -555,8 +558,13 @@ function createFrameSession(spec, ctx, props, overrides = {}) {
       }
     };
     handle.onMessage((msg) => {
-      spec.onMessageEffect?.(msg, { ...ctx, privateKey: keyPair?.privateKey });
-      const event = spec.mapMessage(msg, commands);
+      let event;
+      try {
+        spec.onMessageEffect?.(msg, { ...ctx, privateKey: keyPair?.privateKey });
+        event = spec.mapMessage(msg, commands);
+      } catch (e) {
+        event = spec.errorEvent(e instanceof Error ? e.message : "Failed to process frame message");
+      }
       if (event !== null) {
         for (const handler of [...eventHandlers]) {
           handler(event);