@flopay/react 0.1.0

package/README.md

@@ -0,0 +1,378 @@
+# @flopay/react
+
+React bindings for the FloPay SDK. Provides a context provider, drop-in checkout form components, individual element components, and hooks.
+
+## Installation
+
+```bash
+pnpm add @flopay/react @flopay/js @flopay/shared react react-dom
+```
+
+Peer dependencies: `react >= 18.0.0`, `react-dom >= 18.0.0`.
+
+## Environment Setup
+
+Configure which billing API the SDK uses. Choose one:
+
+```bash
+# Option A: Environment variable (recommended)
+# .env.production
+NEXT_PUBLIC_FLOPAY_ENV=production
+
+# .env.development
+NEXT_PUBLIC_FLOPAY_ENV=staging
+```
+
+```ts
+// Option B: Call at app startup
+import { configureFlopay } from '@flopay/shared';
+configureFlopay({ environment: 'production' });
+```
+
+If neither is set, the SDK defaults to staging.
+
+## Quick Start
+
+### Recommended: FloPayCheckout
+
+The simplest integration — one component, one prop:
+
+```tsx
+import { FloPayCheckout } from '@flopay/react';
+
+function CheckoutPage() {
+  return (
+    <FloPayCheckout
+      sessionId="sess_abc123"
+      onComplete={(result) => {
+        window.location.href = '/success';
+      }}
+      onError={(err) => console.error(err)}
+    />
+  );
+}
+```
+
+`FloPayCheckout` automatically fetches the session, initializes the correct payment provider, and renders a `SplitCardForm` with card fields, Apple Pay, Google Pay, and PayPal. Customer data (email, userId, name) is injected from the session.
+
+#### Checkout Modes
+
+`FloPayCheckout` supports three checkout modes matching the billing API's `checkoutMode` field:
+
+- **`full`** (default) — Shows the full payment form with card fields + wallet buttons.
+- **`confirm`** — Hides the payment form and shows a "Confirm Purchase" button. Uses a saved payment method on the backend.
+- **`auto`** — Auto-submits with a saved payment method after the session loads. Falls back to `full` mode on failure.
+
+```tsx
+// Confirm mode — one-click purchase with saved card
+<FloPayCheckout
+  sessionId="sess_abc123"
+  checkoutMode="confirm"
+  confirmLabel="Complete Purchase"
+  onComplete={(result) => router.push('/success')}
+/>
+
+// Auto mode — instant checkout, falls back to full form
+<FloPayCheckout
+  sessionId="sess_abc123"
+  checkoutMode="auto"
+  onComplete={(result) => router.push('/success')}
+  onSessionCompleted={(successUrl) => router.push(successUrl)}
+/>
+```
+
+The mode can also be set on the session itself via the billing API's `checkoutMode` field. The `checkoutMode` prop overrides the session value.
+
+#### Wallet Buttons
+
+Apple Pay, Google Pay, and PayPal are enabled by default. Toggle them with props:
+
+```tsx
+<FloPayCheckout
+  sessionId="sess_abc123"
+  showApplePay={true}   // default: true
+  showGooglePay={true}  // default: true
+  showPayPal={true}     // default: true
+  onComplete={handleSuccess}
+/>
+```
+
+Apple Pay and Google Pay only render on supported devices (Apple Pay on Safari/macOS/iOS, Google Pay on Chrome).
+
+### Advanced: Manual Provider Setup
+
+For full control over initialization:
+
+```tsx
+import { loadFloPay } from '@flopay/js';
+import { FloPayProvider, CheckoutForm } from '@flopay/react';
+
+const floPayPromise = loadFloPay('pk_test_...');
+
+function CheckoutPage() {
+  return (
+    <FloPayProvider
+      flopay={floPayPromise}
+      options={{
+        amount: 2999,
+        currency: 'usd',
+      }}
+    >
+      <CheckoutForm
+        sessionId="session_uuid"
+        email="user@example.com"
+        userId="user_1"
+        onComplete={(result) => {
+          if (result.status === 'succeeded') {
+            window.location.href = '/success';
+          }
+        }}
+        onError={(err) => console.error(err)}
+      />
+    </FloPayProvider>
+  );
+}
+```
+
+`CheckoutForm` handles the full payment lifecycle by default:
+
+1. Validate elements via `submitElements()`
+2. Tokenize card via `createPaymentMethod()` -> `pm_xxx`
+3. Create PaymentIntent via billing API
+4. Confirm card payment (handles 3D Secure)
+5. Submit tokenized body to `POST /v1/checkouts/sessions/process`
+6. If backend returns `3ds_required`, re-confirm with new client secret
+7. Resume wallet payments after redirect (PayPal)
+
+### Override Mode (Custom Backend)
+
+Pass `onTokenizedBody` to handle backend submission yourself:
+
+```tsx
+<CheckoutForm
+  sessionId="session_uuid"
+  billingApiUrl="https://billing.example.com"
+  email="user@example.com"
+  onTokenizedBody={(body) => {
+    // body = { id: 'pm_xxx', type: 'card', threeDSecureActionResultTokenId: 'pi_xxx' }
+    myCustomProcessPayment(body);
+  }}
+/>
+```
+
+### SplitCardForm (Split Card Fields + PayPal)
+
+`SplitCardForm` renders separate CardNumber, CardExpiry, and CardCVC fields with an integrated PayPal button. It matches the existing checkout/StripeCardForm layout.
+
+```tsx
+import { FloPayProvider, SplitCardForm } from '@flopay/react';
+import { loadFloPay } from '@flopay/js';
+
+const floPayPromise = loadFloPay('pk_test_...');
+
+function CheckoutPage() {
+  return (
+    <FloPayProvider
+      flopay={floPayPromise}
+      options={{
+        amount: 2999,
+        currency: 'usd',
+      }}
+    >
+      <SplitCardForm
+        sessionId="session_uuid"
+        billingApiUrl="https://billing.example.com"
+        email="user@example.com"
+        userId="user_1"
+        totalAmount={29.99}    // dollars (for PayPal Elements config)
+        currency="usd"
+        showPayPal={true}      // default: true
+        onComplete={(result) => {
+          if (result.status === 'succeeded') {
+            window.location.href = '/success';
+          }
+        }}
+        onError={(err) => console.error(err)}
+        onFirstNameChange={(name) => setFirstName(name)}
+        onLastNameChange={(name) => setLastName(name)}
+      />
+    </FloPayProvider>
+  );
+}
+```
+
+The `SplitCardForm` layout:
+1. Wallet buttons — Apple Pay + Google Pay (via ExpressCheckoutElement in the main Elements instance)
+2. PayPal button (via ExpressCheckoutElement in a separate Elements instance)
+3. "or pay with card" divider
+4. Card Number input
+5. Card Expiry + CVC side by side
+6. Full Name input
+7. Submit button
+
+### PayPal Handling
+
+PayPal requires its own Stripe Elements instance because it cannot share an Elements group that uses `paymentMethodCreation: 'manual'`. The SDK handles this in two ways:
+
+- **`SplitCardForm`**: Automatically manages two Elements instances internally. Card fields use the provider's elements with `paymentMethodCreation: 'manual'`. PayPal renders inside a separate `<Elements>` wrapper with `captureMethod: 'manual'` and no `paymentMethodCreation`.
+
+- **`PayPalButton`** (standalone): Must be rendered inside its own `FloPayProvider`:
+
+```tsx
+{/* Card fields provider */}
+<FloPayProvider flopay={flopay} options={{ amount, currency }}>
+  <SplitCardForm ... />
+</FloPayProvider>
+
+{/* PayPal provider (separate instance) */}
+<FloPayProvider flopay={flopay} options={{ amount, currency, paymentMethodCreation: 'auto' }}>
+  <PayPalButton
+    sessionId="session_uuid"
+    billingApiUrl="https://billing.example.com"
+    email="user@example.com"
+    onComplete={() => router.push('/success')}
+  />
+</FloPayProvider>
+```
+
+### Using Individual Elements
+
+```tsx
+import { FloPayProvider, PaymentElement, CardElement, useFloPay } from '@flopay/react';
+
+function CustomForm() {
+  const flopay = useFloPay();
+
+  const handleSubmit = async () => {
+    if (!flopay) return;
+    const { error } = await flopay.submitElements();
+    if (error) return console.error(error);
+    const { paymentMethodId } = await flopay.createPaymentMethod();
+    // Use paymentMethodId...
+  };
+
+  return (
+    <div>
+      <PaymentElement options={{ layout: 'tabs' }} />
+      <button onClick={handleSubmit}>Pay</button>
+    </div>
+  );
+}
+```
+
+### Using Hooks
+
+```tsx
+import { useFloPay, useElements, useCheckout } from '@flopay/react';
+
+function PaymentStatus() {
+  const flopay = useFloPay();       // FloPay | null
+  const elements = useElements();    // FloPayElements | null
+  const checkout = useCheckout();    // { session, loading, error }
+
+  if (!flopay) return <div>Loading SDK...</div>;
+  // ...
+}
+```
+
+## API Reference
+
+### Components
+
+| Component | Description |
+|-----------|-------------|
+| `FloPayProvider` | Context provider. Accepts `flopay` (instance or promise), `options?`, and `children`. Creates the elements group automatically. |
+| `CheckoutForm` | Drop-in form with unified PaymentElement. Self-contained by default, or override with `onTokenizedBody`. Supports `ref` for imperative `handleNextAction()`. |
+| `SplitCardForm` | Split card form (CardNumber + CardExpiry + CardCvc + Full Name). Integrates PayPal via separate Elements instance. Supports `ref` for imperative `handleNextAction()`. |
+| `PayPalButton` | Standalone PayPal button. Requires its own `FloPayProvider` with `paymentMethodCreation` set to something other than `'manual'`. |
+| `PaymentElement` | Unified payment element (cards, wallets, etc.) |
+| `CardElement` | Combined card input |
+| `CardNumberElement` | Card number field |
+| `CardExpiryElement` | Card expiry field |
+| `CardCvcElement` | Card CVC field |
+| `AddressElement` | Address input element |
+
+### Hooks
+
+| Hook | Returns | Description |
+|------|---------|-------------|
+| `useFloPay()` | `FloPay \| null` | Current FloPay instance from context. `null` while loading. |
+| `useElements()` | `FloPayElements \| null` | Current elements group from context. `null` while loading. |
+| `useCheckout()` | `CheckoutState` | `{ session, loading, error }` from CheckoutContext |
+
+### FloPayProviderProps
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `flopay` | `Promise<FloPay> \| FloPay` | SDK instance or promise from `loadFloPay()` |
+| `options.locale` | `string?` | Locale |
+| `options.appearance` | `FloPayAppearance?` | Theme appearance |
+| `options.clientSecret` | `string?` | PaymentIntent client secret (if intent already exists) |
+| `options.amount` | `number?` | Amount in cents (used when no `clientSecret`) |
+| `options.currency` | `string?` | ISO 4217 currency code (used when no `clientSecret`) |
+| `options.paymentMethodCreation` | `'manual' \| 'auto'` | How payment methods are created |
+
+### CheckoutFormProps
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `sessionId` | `string` | Checkout session UUID |
+| `billingApiUrl` | `string` | Billing API base URL |
+| `email` | `string?` | User email |
+| `userId` | `string?` | User ID |
+| `onComplete` | `(result: PaymentResult) => void` | Success callback |
+| `onError` | `(error: FloPayError) => void` | Error callback |
+| `onTokenizedBody` | `(body: TokenizedBody) => void` | Override: handle backend submission yourself |
+| `layout` | `'tabs' \| 'accordion' \| 'auto'` | PaymentElement layout (default: `'auto'`) |
+| `submitLabel` | `string` | Button text (default: `'Pay'`) |
+| `showAddress` | `boolean \| 'billing' \| 'shipping'` | Show address element (default: `false`) |
+| `className` | `string?` | CSS class for form wrapper |
+| `children` | `ReactNode?` | Custom submit button |
+| `firstName` | `string?` | Billing first name |
+| `lastName` | `string?` | Billing last name |
+| `chv` | `string?` | Checkout version for A/B tracking |
+| `isProcessing` | `boolean?` | External processing state |
+| `error` | `string?` | External error message |
+| `onErrorChange` | `(error: string \| null) => void` | Error state change callback |
+
+### SplitCardFormProps
+
+Shares most props with `CheckoutFormProps`, plus:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `showPayPal` | `boolean` | Show PayPal button (default: `true`) |
+| `showApplePay` | `boolean` | Show Apple Pay button (default: `true`) |
+| `showGooglePay` | `boolean` | Show Google Pay button (default: `true`) |
+| `totalAmount` | `number` | Amount in dollars for PayPal config |
+| `currency` | `string` | Currency code for PayPal config (default: `'usd'`) |
+| `onFirstNameChange` | `(value: string) => void` | First name change callback |
+| `onLastNameChange` | `(value: string) => void` | Last name change callback |
+| `submitLabel` | `string` | Button text (default: `'CONFIRM PAYMENT'`) |
+
+### ElementComponentProps (shared by all element components)
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `className` | `string?` | CSS class for wrapper div |
+| `id` | `string?` | HTML id for wrapper div |
+| `style` | `CSSProperties?` | Inline styles for wrapper div |
+| `options` | `Partial<ElementOptions>?` | Options for the underlying element |
+| `onChange` | `(event: ElementChangeEvent) => void` | Value change handler |
+| `onReady` | `() => void` | Element ready handler |
+| `onFocus` | `() => void` | Focus handler |
+| `onBlur` | `() => void` | Blur handler |
+| `onEscape` | `() => void` | Escape key handler |
+
+### Types
+
+| Type | Description |
+|------|-------------|
+| `FloPayProviderProps` | Props for `FloPayProvider` |
+| `CheckoutFormProps` | Props for `CheckoutForm` |
+| `CheckoutFormRef` | Ref type: `{ handleNextAction(clientSecret) }` |
+| `SplitCardFormProps` | Props for `SplitCardForm` |
+| `SplitCardFormRef` | Ref type: `{ handleNextAction(clientSecret) }` |
+| `PayPalButtonProps` | Props for `PayPalButton` |
+| `ElementComponentProps` | Shared props for all element components |
+| `CheckoutState` | `{ session, loading, error }` |