@flopay/react 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,402 @@
+import React from 'react';
+import { FloPay, FloPayElements } from '@flopay/js';
+import { FloPayAppearance, FloPayError, PaymentResult, CheckoutMode, CheckoutSession, ElementOptions, ElementChangeEvent, TokenizedBody } from '@flopay/shared';
+
+/** Props for the `FloPayProvider` component. */
+interface FloPayProviderProps {
+    /** A `FloPay` instance or a promise that resolves to one (from `loadFloPay()`). */
+    flopay: Promise<FloPay> | FloPay;
+    /** Optional configuration applied when creating the elements group. */
+    options?: {
+        locale?: string;
+        appearance?: FloPayAppearance;
+        clientSecret?: string;
+        /** Total amount in smallest currency unit (cents). Used when no clientSecret. */
+        amount?: number;
+        /** ISO 4217 currency code (lowercase). Used when no clientSecret. */
+        currency?: string;
+        /** How payment methods are created. 'manual' (default for cards) or 'auto' (needed for PayPal). */
+        paymentMethodCreation?: 'manual' | 'auto';
+        /** Billing API base URL. Set once here so child components don't need to repeat it. */
+        billingApiUrl?: string;
+    };
+    children: React.ReactNode;
+}
+/**
+ * Provides FloPay SDK context to the component tree.
+ *
+ * Wrap your checkout page (or your entire app) with this provider:
+ *
+ * ```tsx
+ * <FloPayProvider flopay={loadFloPay('pk_test_...')}>
+ *   <CheckoutForm />
+ * </FloPayProvider>
+ * ```
+ */
+declare function FloPayProvider({ flopay: floPayProp, options, children, }: FloPayProviderProps): React.ReactElement;
+
+/** Props for the all-in-one `FloPayCheckout` wrapper. */
+interface FloPayCheckoutProps {
+    /** The checkout session ID (UUID from billing API). */
+    sessionId: string;
+    /** Billing API base URL. Defaults to the shared `BILLING_API_URL` constant. */
+    billingApiUrl?: string;
+    /** Visual appearance for payment elements. */
+    appearance?: FloPayAppearance;
+    /** Locale for payment elements (default: 'auto'). */
+    locale?: string;
+    /**
+     * Fallback publishable key, used only if the session response
+     * doesn't include `gatewayData.publishableKey`.
+     */
+    fallbackPublishableKey?: string;
+    /** Custom loading UI. Defaults to a simple centered spinner. */
+    loading?: React.ReactNode;
+    /** Custom error UI. Receives the error. Defaults to showing the error message. */
+    error?: (error: FloPayError) => React.ReactNode;
+    /** Called when the full payment flow completes successfully. */
+    onComplete?: (result: PaymentResult) => void;
+    /** Called when a payment error occurs. */
+    onError?: (error: FloPayError) => void;
+    /** Whether to show the PayPal button (default: true). */
+    showPayPal?: boolean;
+    /** Whether to show Apple Pay button (default: true). Only renders on supported devices. */
+    showApplePay?: boolean;
+    /** Whether to show Google Pay button (default: true). Only renders on supported devices. */
+    showGooglePay?: boolean;
+    /** Label for the submit button. */
+    submitLabel?: string;
+    /** Additional CSS class for the wrapper. */
+    className?: string;
+    /**
+     * Override the default `SplitCardForm`. When provided, children are rendered
+     * inside the initialized `FloPayProvider` with session props auto-injected.
+     */
+    children?: React.ReactNode;
+    /**
+     * Override the session's checkoutMode.
+     * - `'full'` — show payment form (default)
+     * - `'confirm'` — show confirm button, uses saved payment method
+     * - `'auto'` — auto-submit with saved PM, falls back to `'full'` on failure
+     */
+    checkoutMode?: CheckoutMode;
+    /** Label for the confirm button in `confirm` mode. Default: `'Confirm Purchase'`. */
+    confirmLabel?: string;
+    /** Custom confirm button renderer for `confirm` mode. */
+    renderConfirmButton?: (props: {
+        onConfirm: () => void;
+        isProcessing: boolean;
+    }) => React.ReactNode;
+    /** Called when the session has already been completed. Receives the successUrl. */
+    onSessionCompleted?: (successUrl: string) => void;
+}
+/**
+ * All-in-one checkout component. Fetches the session, initializes the
+ * payment provider, and renders the appropriate UI based on checkout mode.
+ *
+ * **Modes:**
+ * - `full` (default) — renders `SplitCardForm` with card fields + wallet buttons
+ * - `confirm` — renders a "Confirm Purchase" button, uses saved payment method
+ * - `auto` — auto-submits with saved PM, falls back to `full` on failure
+ *
+ * ```tsx
+ * <FloPayCheckout
+ *   sessionId="sess_abc123"
+ *   onComplete={(result) => router.push('/success')}
+ *   onError={(err) => console.error(err)}
+ * />
+ * ```
+ */
+declare function FloPayCheckout({ sessionId, billingApiUrl, appearance, locale, fallbackPublishableKey, loading: loadingNode, error: errorNode, onComplete, onError, showPayPal, showApplePay, showGooglePay, submitLabel, className, children, checkoutMode: checkoutModeProp, confirmLabel, renderConfirmButton, onSessionCompleted, }: FloPayCheckoutProps): React.ReactElement;
+
+/**
+ * Returns the current `FloPay` instance, or `null` if the provider
+ * is still loading (i.e. the `loadFloPay()` promise has not resolved yet).
+ *
+ * Must be called within a `<FloPayProvider>`.
+ */
+declare function useFloPay(): FloPay | null;
+/**
+ * Returns the current `FloPayElements` instance, or `null` if the
+ * provider is still loading.
+ *
+ * Must be called within a `<FloPayProvider>`.
+ */
+declare function useElements(): FloPayElements | null;
+/** Checkout state exposed by `useCheckout()`. */
+interface CheckoutState {
+    session: CheckoutSession | null;
+    loading: boolean;
+    error: FloPayError | null;
+}
+/**
+ * Returns the current checkout session state.
+ *
+ * Must be called within a `<CheckoutProvider>` (typically rendered
+ * internally by `<CheckoutForm>`).
+ */
+declare function useCheckout(): CheckoutState;
+
+/** Common props shared by all element components. */
+interface ElementComponentProps {
+    /** Additional CSS class for the wrapper div. */
+    className?: string;
+    /** Element id attribute for the wrapper div. */
+    id?: string;
+    /** Inline styles for the wrapper div. */
+    style?: React.CSSProperties;
+    /** Options forwarded to the underlying element. */
+    options?: Partial<ElementOptions>;
+    /** Fired when the element's value changes. */
+    onChange?: (event: ElementChangeEvent) => void;
+    /** Fired when the element is fully rendered and ready. */
+    onReady?: () => void;
+    /** Fired when the element gains focus. */
+    onFocus?: () => void;
+    /** Fired when the element loses focus. */
+    onBlur?: () => void;
+    /** Fired when the Escape key is pressed inside the element. */
+    onEscape?: () => void;
+}
+/**
+ * Renders the unified Payment Element — a single component that accepts
+ * cards, wallets, and other payment methods.
+ *
+ * TODO: Will render inside an iframe for PCI compliance in a future phase.
+ */
+declare const PaymentElement: React.FC<ElementComponentProps>;
+/**
+ * Renders a combined card input (number + expiry + CVC).
+ *
+ * TODO: Will render inside an iframe for PCI compliance in a future phase.
+ */
+declare const CardElement: React.FC<ElementComponentProps>;
+/**
+ * Renders a card number input field.
+ *
+ * TODO: Will render inside an iframe for PCI compliance in a future phase.
+ */
+declare const CardNumberElement: React.FC<ElementComponentProps>;
+/**
+ * Renders a card expiry input field.
+ *
+ * TODO: Will render inside an iframe for PCI compliance in a future phase.
+ */
+declare const CardExpiryElement: React.FC<ElementComponentProps>;
+/**
+ * Renders a card CVC input field.
+ *
+ * TODO: Will render inside an iframe for PCI compliance in a future phase.
+ */
+declare const CardCvcElement: React.FC<ElementComponentProps>;
+/**
+ * Renders an address input element.
+ */
+declare const AddressElement: React.FC<ElementComponentProps>;
+
+/** Methods exposed via ref for external 3DS handling. */
+interface CheckoutFormRef {
+    handleNextAction: (clientSecret: string) => Promise<void>;
+}
+/** Props for the drop-in `CheckoutForm` component. */
+interface CheckoutFormProps {
+    /** The checkout session ID (UUID from billing API). */
+    sessionId: string;
+    /** Billing API base URL. Optional — defaults to the value from FloPayProvider or the shared constant. */
+    billingApiUrl?: string;
+    /** User's email (required for creating payment intents). */
+    email?: string;
+    /** User ID (required for processing payments). */
+    userId?: string;
+    /**
+     * Called when the full payment flow completes successfully.
+     * By default the form handles everything: tokenize → create intent →
+     * confirm → processPayment → 3DS retry. You just handle the success.
+     */
+    onComplete?: (result: PaymentResult) => void;
+    /** Called when a payment error occurs. */
+    onError?: (error: FloPayError) => void;
+    /**
+     * **Override**: If provided, the form tokenizes the card and confirms
+     * the payment, but delegates backend submission to the caller.
+     * When omitted, the form calls `processPayment` internally.
+     */
+    onTokenizedBody?: (tokenizedBody: TokenizedBody) => void;
+    /** Layout style for the PaymentElement. */
+    layout?: 'tabs' | 'accordion' | 'auto';
+    /** Label for the submit button. */
+    submitLabel?: string;
+    /** Whether to show an address element. */
+    showAddress?: boolean | 'billing' | 'shipping';
+    /** Additional CSS class for the form wrapper. */
+    className?: string;
+    /** Custom children (e.g. a custom submit button). Overrides the default button. */
+    children?: React.ReactNode;
+    /** First name for billing. */
+    firstName?: string;
+    /** Last name for billing. */
+    lastName?: string;
+    /** Checkout version for A/B tracking. */
+    chv?: string;
+    /** External processing state (used when onTokenizedBody is provided). */
+    isProcessing?: boolean;
+    /** External error message (used when onTokenizedBody is provided). */
+    error?: string | null;
+    /** Called when internal error state changes. */
+    onErrorChange?: (error: string | null) => void;
+}
+/**
+ * Drop-in checkout form that handles the full payment lifecycle by default.
+ *
+ * **Default (self-contained) mode** — just provide config + onComplete:
+ * ```tsx
+ * <CheckoutForm
+ *   sessionId="uuid"
+ *   billingApiUrl="https://api.example.com"
+ *   email="user@example.com"
+ *   userId="user_1"
+ *   onComplete={(result) => router.push('/success')}
+ * />
+ * ```
+ *
+ * The form handles internally:
+ * 1. Validate → tokenize card → create PaymentIntent → confirm (3DS)
+ * 2. Submit token to `POST /v1/checkouts/sessions/process`
+ * 3. If backend returns `3ds_required` → re-confirm with new client secret
+ * 4. Wallet resume after redirect (PayPal, etc.)
+ *
+ * **Override mode** — provide `onTokenizedBody` to handle backend submission yourself:
+ * ```tsx
+ * <CheckoutForm
+ *   ...
+ *   onTokenizedBody={(body) => myCustomProcessPayment(body)}
+ * />
+ * ```
+ */
+declare const CheckoutForm: React.ForwardRefExoticComponent<CheckoutFormProps & React.RefAttributes<CheckoutFormRef>>;
+
+/** Methods exposed via ref for external 3DS handling. */
+interface SplitCardFormRef {
+    handleNextAction: (clientSecret: string) => Promise<void>;
+}
+/** Props for the `SplitCardForm` component. */
+interface SplitCardFormProps {
+    /** The checkout session ID (UUID from billing API). */
+    sessionId: string;
+    /** Billing API base URL. Optional — defaults to the value from FloPayProvider or the shared constant. */
+    billingApiUrl?: string;
+    /** User's email (required for creating payment intents). */
+    email?: string;
+    /** User ID (required for processing payments). */
+    userId?: string;
+    /** Called when the full payment flow completes successfully. */
+    onComplete?: (result: PaymentResult) => void;
+    /** Called when a payment error occurs. */
+    onError?: (error: FloPayError) => void;
+    /**
+     * **Override**: If provided, delegates backend submission to the caller.
+     * When omitted, processes internally (calls processPayment + handles 3DS).
+     */
+    onTokenizedBody?: (tokenizedBody: TokenizedBody) => void;
+    /** First name for billing. */
+    firstName?: string;
+    /** Last name for billing. */
+    lastName?: string;
+    /** Checkout version for A/B tracking. */
+    chv?: string;
+    /** Label for the submit button. */
+    submitLabel?: string;
+    /** Additional CSS class for the form wrapper. */
+    className?: string;
+    /** Custom children (overrides default submit button). */
+    children?: React.ReactNode;
+    /** External processing state. */
+    isProcessing?: boolean;
+    /** External error message. */
+    error?: string | null;
+    /** Called when internal error state changes. */
+    onErrorChange?: (error: string | null) => void;
+    /** Callback when first name changes (from the name input). */
+    onFirstNameChange?: (value: string) => void;
+    /** Callback when last name changes (from the name input). */
+    onLastNameChange?: (value: string) => void;
+    /**
+     * Show PayPal button above card fields. Defaults to `true`.
+     * Uses Stripe's ExpressCheckoutElement in a separate Elements instance,
+     * matching checkout/StripeCardForm architecture.
+     */
+    showPayPal?: boolean;
+    /** Show Apple Pay button. Defaults to `true`. Only renders on supported devices. */
+    showApplePay?: boolean;
+    /** Show Google Pay button. Defaults to `true`. Only renders on supported devices. */
+    showGooglePay?: boolean;
+    /** Total amount in cents (smallest currency unit). Used for wallet/PayPal Elements config. */
+    totalAmount?: number;
+    /** Currency code (used for PayPal Elements config). */
+    currency?: string;
+}
+/**
+ * Split card checkout form matching `checkout/StripeCardForm`:
+ * PayPal button → divider → CardNumber → CardExpiry + CardCVC → Full Name → Submit.
+ *
+ * PayPal uses its own Stripe Elements instance (no `paymentMethodCreation`)
+ * exactly like checkout does with two separate `<Elements>` wrappers.
+ */
+declare const SplitCardForm: React.ForwardRefExoticComponent<SplitCardFormProps & React.RefAttributes<SplitCardFormRef>>;
+
+/**
+ * Props for the `PayPalButton` component.
+ *
+ * Must be rendered inside its own `FloPayProvider` with `paymentMethodCreation: undefined`
+ * (not 'manual') — PayPal cannot share the same Elements instance as card fields.
+ */
+interface PayPalButtonProps {
+    /** The checkout session ID (UUID from billing API). */
+    sessionId: string;
+    /** Billing API base URL. Optional — defaults to the value from FloPayProvider or the shared constant. */
+    billingApiUrl?: string;
+    /** User's email. */
+    email?: string;
+    /** User ID for processing payments. */
+    userId?: string;
+    /** First name for billing. */
+    firstName?: string;
+    /** Last name for billing. */
+    lastName?: string;
+    /** Checkout version for tracking. */
+    chv?: string;
+    /**
+     * Called with tokenized data after PayPal authorization.
+     * If omitted, the component calls processPayment internally.
+     */
+    onTokenizedBody?: (body: TokenizedBody) => void;
+    /** Called on successful payment (self-contained mode). */
+    onComplete?: () => void;
+    /** Called when an error occurs. */
+    onErrorChange?: (error: string | null) => void;
+    /** External processing state. */
+    isProcessing?: boolean;
+}
+/**
+ * PayPal button that handles the full PayPal payment flow.
+ *
+ * **Important**: PayPal requires its own `FloPayProvider` — it cannot share
+ * the same Stripe Elements instance as card fields when they use
+ * `paymentMethodCreation: 'manual'`. This matches `checkout/StripeCardForm`
+ * which renders PayPal in a separate `<Elements>` wrapper.
+ *
+ * ```tsx
+ * {/* Card fields provider (paymentMethodCreation: 'manual') *\/}
+ * <FloPayProvider flopay={flopay} options={{ amount, currency }}>
+ *   <SplitCardForm ... />
+ * </FloPayProvider>
+ *
+ * {/* PayPal provider (no paymentMethodCreation) *\/}
+ * <FloPayProvider flopay={flopay} options={{ amount, currency, paymentMethodCreation: 'auto' }}>
+ *   <PayPalButton ... />
+ * </FloPayProvider>
+ * ```
+ */
+declare function PayPalButton({ sessionId, billingApiUrl, email, userId, firstName, lastName, chv, onTokenizedBody, onComplete, onErrorChange, isProcessing, }: PayPalButtonProps): React.ReactElement;
+
+export { AddressElement, CardCvcElement, CardElement, CardExpiryElement, CardNumberElement, CheckoutForm, type CheckoutFormProps, type CheckoutFormRef, type CheckoutState, type ElementComponentProps, FloPayCheckout, type FloPayCheckoutProps, FloPayProvider, type FloPayProviderProps, PayPalButton, type PayPalButtonProps, PaymentElement, SplitCardForm, type SplitCardFormProps, type SplitCardFormRef, useCheckout, useElements, useFloPay };