@flopay/react 1.6.0 → 1.8.1

package/dist/index.d.ts

@@ -1,63 +1,215 @@
-import React from 'react';
-import { FloPay, FloPayElements } from '@flopay/js';
 import * as _flopay_shared from '@flopay/shared';
-import { FloPayAppearance, InlineSessionDraft, FloPayError, PaymentResult, DeclineEvent, CheckoutButtonMethod, BeforeButtonClickEvent, InlineSessionPatch, CheckoutMode, CheckoutSession, ElementOptions, ElementChangeEvent, TokenizedBody, AVSFieldConfig, GatewayEnvironment, PayPalProviderObjectType, CardCaptureAdapter, VaultCardThemeColors, CheckoutProduct, CheckoutItem, CheckoutSubscription, ThemeId, ButtonsLayoutTheme, ButtonsLayoutStyles } from '@flopay/shared';
-export { BeforeButtonClickEvent, CheckoutButtonMethod, DeclineEvent, InlineSessionDraft, InlineSessionPatch, SentryEventLike, SentryStackFrameLike, dropThirdPartyOnlyError } from '@flopay/shared';
+import { InlineSessionDraft, CheckoutButtonMethod, CheckoutProduct, CheckoutItem, CheckoutSubscription, ThemeId, FloPayAppearance, ButtonsLayoutTheme, ButtonsLayoutStyles, PaymentResult, CheckoutSession, FloPayError, DeclineEvent, GatewayEnvironment, PayPalProviderObjectType, TokenizedBody, InlineSessionPatch, FloInstrumentEvent, BeforeButtonClickEvent, CheckoutMode, AVSFieldConfig, CardCaptureAdapter, VaultCardThemeColors } from '@flopay/shared';
+export { BeforeButtonClickEvent, CheckoutButtonMethod, DeclineEvent, FloInstrumentEvent, InlineSessionDraft, InlineSessionPatch, SentryEventLike, SentryStackFrameLike, dropThirdPartyOnlyError } from '@flopay/shared';
+import React from 'react';
 export { FloPayCardSetup, FloPayCardSetupCancelEvent, FloPayCardSetupCompleteEvent, FloPayCardSetupDeclineEvent, FloPayCardSetupError, FloPayCardSetupProps } from './card-setup-entry.js';
+import { FloPay } from '@flopay/js';
 
-/** Props for the `FloPayProvider` component. */
-interface FloPayProviderProps {
-    /** A `FloPay` instance or a promise that resolves to one (from `loadFloPay()`). */
-    flopay: Promise<FloPay> | FloPay;
+interface FloPayAutomaticPaymentSuccessEvent {
+    result: PaymentResult;
+    session: CheckoutSession | null;
+    sessionId: string | null;
+    autoCompleted: boolean;
+}
+interface FloPayAutomaticPaymentButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'onError'> {
+    sessionId?: string;
     /**
-     * Optional Stripe `FloPay` instance used to drive the Stripe-rendered PayPal
-     * fallback. When omitted or `null`, the Stripe-rendered PayPal button is
-     * not rendered. Direct PayPal (`gateways.paypal`) does not use this prop.
+     * Session-bound checkout token for a consumer-supplied {@link sessionId}
+     * (the `nonce` returned when that session was created). Post-#640 backends
+     * require it as `x-checkout-session-token` to read the session and to
+     * `/process` it; without it the existing-session path 401s with
+     * "Missing checkout session token.". Ignored on the create-session path,
+     * where the SDK mints and threads the nonce itself.
      */
-    paypalFlopay?: Promise<FloPay> | FloPay | null;
-    /** Optional configuration applied when creating the elements group. */
-    options?: {
-        locale?: string;
-        appearance?: FloPayAppearance;
-        /**
-         * Client secret for an existing non-card PaymentIntent or SetupIntent.
-         * The SDK verifies the provider intent against the `PaymentElement`'s
-         * explicit `paymentMethodTypes` allowlist before mounting and rejects card
-         * or undeclared methods. Card checkout uses the hosted vault.
-         */
-        clientSecret?: string;
-        /** Total amount in cents for deferred non-card Elements without a client secret. */
-        amount?: number;
-        /** ISO 4217 currency code for deferred non-card Elements without a client secret. */
-        currency?: string;
-        /** How non-card payment methods are created: `'manual'` or `'auto'` (needed for PayPal). */
-        paymentMethodCreation?: 'manual' | 'auto';
-        /** Requests reusable payment credentials for future payments. */
-        setupFutureUsage?: 'off_session' | 'on_session';
-        /** Billing API base URL. Set once here so child components don't need to repeat it. */
-        billingApiUrl?: string;
-    };
-    children: React.ReactNode;
+    nonce?: string;
+    createSession?: InlineSessionDraft;
+    /**
+     * @deprecated Ignored. The backend now picks the customer's most recent
+     * vaulted payment method via `getLatestByUserId` and rebinds the session's
+     * gateway to match it (see `apps/api`'s `createSingle` auto-checkout
+     * branch). Passing this prop has no effect — it is retained only to avoid
+     * breaking existing integrations.
+     */
+    paymentMethodId?: string;
+    /**
+     * @deprecated Ignored. The backend orchestrates gateway routing — clients
+     * no longer choose between card and PayPal at the SDK boundary. Passing
+     * this prop has no effect.
+     */
+    checkoutMethod?: CheckoutButtonMethod;
+    clientId?: string;
+    /**
+     * Unified products array (TeamFloPay/backend#760). When supplied,
+     * `items`/`subscriptions` are ignored. The SDK folds the legacy fields
+     * into this shape internally.
+     */
+    products?: CheckoutProduct[];
+    items?: CheckoutItem[];
+    subscriptions?: CheckoutSubscription[];
+    account?: InlineSessionDraft['account'];
+    successUrl?: string;
+    cancelUrl?: string;
+    couponCodes?: string[];
+    tagsData?: InlineSessionDraft['tagsData'];
+    utmMetadata?: InlineSessionDraft['utmMetadata'];
+    billingApiUrl?: string;
+    locale?: string;
+    /**
+     * High-level theme bundle that styles the button (and the fallback
+     * `FloPayCheckout` modal that opens when the saved-payment charge needs
+     * user interaction). One of: `'classic'`, `'modern-light'`, `'modern-dark'`,
+     * `'bold-light'`, `'bold-dark'`, `'glass-light'`, `'glass-dark'`. Explicit
+     * `buttonsStyles` still wins for fine-grained overrides.
+     */
+    theme?: ThemeId;
+    /**
+     * Per-checkout appearance overrides layered on top of the chosen `theme`
+     * (same shape as {@link FloPayCheckout}'s `appearance`). Its `colorPrimary` /
+     * `colorPrimaryHover` / `borderRadius` re-skin the button — and the fallback
+     * `FloPayCheckout` modal — so the auto-pay button matches the rest of the
+     * themed checkout. Without this the button only saw the bundle's defaults.
+     */
+    appearance?: FloPayAppearance;
+    /**
+     * @deprecated Use `theme` instead. Legacy buttons-layout preset
+     * (`'default' | 'minimal' | 'rounded' | 'dark'`). Still honored for
+     * back-compat.
+     */
+    buttonsTheme?: ButtonsLayoutTheme;
+    buttonsStyles?: ButtonsLayoutStyles;
+    onSuccess?: (event: FloPayAutomaticPaymentSuccessEvent) => void;
+    onError?: (error: FloPayError) => void;
+    onDecline?: (decline: DeclineEvent) => void;
+    children?: React.ReactNode;
 }
+declare function FloPayAutomaticPaymentButton({ sessionId, nonce, createSession, paymentMethodId: _deprecatedPaymentMethodId, checkoutMethod: _deprecatedCheckoutMethod, clientId, products, items, subscriptions, account, successUrl, cancelUrl, couponCodes, tagsData, utmMetadata, billingApiUrl, locale, theme, appearance, buttonsTheme, buttonsStyles: stylesOverride, onSuccess, onError, onDecline, children, disabled, type, style, ...buttonProps }: FloPayAutomaticPaymentButtonProps): React.JSX.Element;
+
 /**
- * Provides FloPay SDK context to the component tree.
- *
- * Wrap provider-context elements with this provider:
- *
- * ```tsx
- * <FloPayProvider flopay={loadFloPay('pk_test_...')}>
- *   <PaymentElement options={{ paymentMethodTypes: ['cashapp', 'ideal'] }} />
- * </FloPayProvider>
- * ```
- *
- * `FloPayCheckout` is a standalone integration that owns its provider and
- * session-specific Elements setup:
- *
- * ```tsx
- * <FloPayCheckout sessionId="sess_..." />
- * ```
+ * Overrides that `SplitCardForm`'s tokenized-body dispatcher uses to apply a
+ * `runBeforeButtonClick` patch to the in-flight processPayment call. Kept in
+ * sync structurally with `TokenizedBodyOverrides` in `split-card-form.tsx`.
  */
-declare function FloPayProvider({ flopay: floPayProp, paypalFlopay: paypalFloPayProp, options, children, }: FloPayProviderProps): React.ReactElement;
+interface DirectPayPalTokenizedOverrides {
+    accountPatch?: InlineSessionPatch['account'];
+    sessionId?: string;
+    nonce?: string;
+}
+/**
+ * Internal handler signature aligned with `SplitCardForm`'s tokenized-body
+ * dispatcher. Direct PayPal completes via the backend's process endpoint and
+ * never produces a Stripe PaymentIntent, so we still forward a synthetic
+ * `TokenizedBody` describing the captured order, optionally with the
+ * session/account patch captured at click-time.
+ */
+type DirectPayPalTokenizedHandler = (body: TokenizedBody, overrides?: DirectPayPalTokenizedOverrides) => void;
+/** Click-time `runBeforeButtonClick` result, structurally compatible with `SplitCardForm`. */
+interface DirectPayPalBeforeButtonClickResult {
+    proceed: boolean;
+    accountPatch?: InlineSessionPatch['account'];
+    sessionId?: string;
+    nonce?: string;
+}
+/**
+ * Click-time gate. Mirrors `RunBeforeButtonClick` in `SplitCardForm`: lets the
+ * consumer patch the session/account before PayPal creates the order, and lets
+ * them abort the click entirely by returning `proceed: false`.
+ */
+type DirectPayPalRunBeforeButtonClick = (method: CheckoutButtonMethod) => Promise<DirectPayPalBeforeButtonClickResult>;
+type DirectPayPalInitializationState = 'loading' | 'retrying' | 'ready' | 'exhausted';
+type DirectPayPalTechnicalFailureHandler = (method: 'paypal', err: unknown, options?: {
+    code?: string;
+    popupBlocked?: boolean;
+}) => void;
+interface DirectPayPalButtonProps {
+    /** Checkout session ID. */
+    sessionId: string;
+    /**
+     * Session-bound checkout token returned by session creation. Forwarded as
+     * `x-checkout-session-token` on every continuation request — required by
+     * post-#640 backends. `FloPayCheckout` plumbs this prop automatically.
+     */
+    nonce?: string;
+    /** Billing API base URL. */
+    billingApiUrl: string;
+    /** Buyer email. */
+    email?: string;
+    /** PayPal client identifier (`gateways.paypal.publishableKey`). */
+    clientId: string;
+    /** Gateway environment, drives the sandbox/live SDK script. */
+    environment?: GatewayEnvironment;
+    /** ISO 4217 currency code. */
+    currency: string;
+    /** Whether the session is a subscription (drives intent + flow selection). */
+    isSubscription: boolean;
+    /**
+     * Provider object the backend advertised for this PayPal continuation.
+     * When omitted, legacy sessions continue to derive the flow from
+     * `isSubscription`. An advertised `'order'`/`'setup_token'` opts intent and
+     * process requests into the Flo-owned `paypal_vaulted` payment-method
+     * channel; an advertised `'subscription'` or an omission keeps the released
+     * `paypal` requests byte-identical.
+     */
+    providerObjectType?: PayPalProviderObjectType;
+    /**
+     * If provided, called with the tokenized body once PayPal capture
+     * completes. When omitted, the component processes payment internally.
+     */
+    onTokenizedBody?: DirectPayPalTokenizedHandler;
+    /** Called when the full self-contained payment flow succeeds. */
+    onComplete?: (result: PaymentResult) => void;
+    /** Called when an error occurs. */
+    onErrorChange?: (error: string | null) => void;
+    /** Decline emitter (mirrors SplitCardForm semantics). */
+    onDecline?: (decline: DeclineEvent) => void;
+    /** Called for post-click technical failures before PayPal authorization completes. */
+    onTechnicalFailure?: DirectPayPalTechnicalFailureHandler;
+    /** External processing state. */
+    isProcessing?: boolean;
+    /** Notify the parent of the loading state for placeholder swapping. */
+    onLoadStateChange?: (ready: boolean) => void;
+    /** Notify a PayPal-only wrapper about pre-render recovery state. */
+    onInitializationStateChange?: (state: DirectPayPalInitializationState) => void;
+    /** Disable the automatic retry for a buyer-initiated single manual attempt. */
+    allowAutomaticRetry?: boolean;
+    /** Tracks button-click for analytics. */
+    onButtonClick?: (method: CheckoutButtonMethod) => void;
+    /**
+     * Click-time gate (runs before PayPal creates the order). When provided, the
+     * returned patch is applied to the in-flight create-intent and tokenized
+     * dispatch so callers using `onBeforeButtonClick` see the same session/email
+     * the Stripe-rendered PayPal flow does.
+     */
+    runBeforeButtonClick?: DirectPayPalRunBeforeButtonClick;
+    /** Backing session — used for self-contained accountData population. */
+    session?: CheckoutSession | null;
+    /**
+     * Pre-existing PayPal Order id (or Subscription id when `isSubscription` is
+     * true) to bind the button to. When set, the button skips its usual
+     * session-scoped create-intent round-trip on click and feeds this
+     * id straight into PayPal's create-order / create-subscription callback.
+     *
+     * Used by `SplitCardForm`'s `paypal_direct_required` retry path: backend
+     * creates a fresh PayPal order after a stalled process attempt and returns
+     * its id; the SDK re-renders this button bound to that id so the buyer can
+     * confirm with one more click without the backend re-creating the order on
+     * each retry.
+     *
+     * Changing this value remounts the PayPal SDK so the new createOrder
+     * binding takes effect (PayPal's render() options aren't live-updatable).
+     */
+    existingOrderId?: string;
+    /** Flo-owned privacy-safe telemetry is enabled by default; set `false` to opt out. */
+    telemetry?: boolean;
+    /**
+     * When true, renders an on-screen lifecycle tracer panel above the button
+     * (mount, loadScript, eligibility, render, errors). Intended for debugging
+     * in-app browsers (Facebook IAB, etc.) where remote console access is
+     * impractical. Off by default — leave disabled in production.
+     */
+    debug?: boolean;
+}
+/** Public direct-PayPal surface: telemetry accepts only the boolean opt-out. */
+declare function DirectPayPalButton(props: DirectPayPalButtonProps): React.ReactElement | null;
 
 /** Props for the all-in-one `FloPayCheckout` wrapper. */
 interface FloPayCheckoutProps {
@@ -94,6 +246,8 @@ interface FloPayCheckoutProps {
     onComplete?: (result: PaymentResult) => void;
     /** Called when a payment error occurs. */
     onError?: (error: FloPayError) => void;
+    /** Receives the versioned, privacy-safe checkout instrument feed. */
+    onInstrument?: (event: FloInstrumentEvent) => void;
     /** Called when a payment is declined or the authentication step fails. */
     onDecline?: (decline: DeclineEvent) => void;
     /** Called when the AVS country dropdown changes. */
@@ -189,7 +343,7 @@ interface FloPayCheckoutProps {
      * In `layout="buttons"` with `createSession`, the returned patch is merged
      * into the inline session params before the selected flow continues.
      */
-    onBeforeButtonClick?: (event: BeforeButtonClickEvent) => void | false | Promise<void | false | InlineSessionPatch> | InlineSessionPatch;
+    onBeforeButtonClick?: (event: BeforeButtonClickEvent) => undefined | false | Promise<undefined | false | InlineSessionPatch> | InlineSessionPatch;
     /**
      * Enable AVS (Address Verification).
      * - `true` — show country + postal code (backward compatible default)
@@ -261,7 +415,7 @@ interface FloPayCheckoutProps {
  * />
  * ```
  */
-declare function FloPayCheckout({ sessionId: sessionIdProp, nonce: nonceProp, createSession: createSessionParams, billingApiUrl, telemetry, appearance: appearanceOverride, locale, loading: loadingNode, error: errorNode, onComplete, onError, onDecline, onCountryChange, onZipChange, showPayPal, showStripe, enabledPaymentMethods: enabledPaymentMethodsProp, showApplePay, showGooglePay, debug, layout, theme, buttonsTheme, buttonsStyles, cardButtonContent, cardBackButtonContent, cardTitleContent, showSecurityFooter: _showSecurityFooter, onButtonClick, onBeforeButtonClick, enableAVS, cardFieldOrder, cardPreFormSlot, avsLayout, className, initialErrorMessage, children, checkoutMode: checkoutModeProp, confirmLabel, renderConfirmButton, onSessionCompleted, }: FloPayCheckoutProps): React.ReactElement;
+declare function FloPayCheckout({ sessionId: sessionIdProp, nonce: nonceProp, createSession: createSessionParams, billingApiUrl, telemetry, appearance: appearanceOverride, locale, loading: loadingNode, error: errorNode, onComplete, onError, onInstrument, onDecline, onCountryChange, onZipChange, showPayPal, showStripe, enabledPaymentMethods: enabledPaymentMethodsProp, showApplePay, showGooglePay, debug, layout, theme, buttonsTheme, buttonsStyles, cardButtonContent, cardBackButtonContent, cardTitleContent, showSecurityFooter: _showSecurityFooter, onButtonClick, onBeforeButtonClick, enableAVS, cardFieldOrder, cardPreFormSlot, avsLayout, className, initialErrorMessage, children, checkoutMode: checkoutModeProp, confirmLabel, renderConfirmButton, onSessionCompleted, }: FloPayCheckoutProps): React.ReactElement;
 
 /**
  * Returns the current `FloPay` instance, or `null` if the provider
@@ -278,13 +432,6 @@ declare function useFloPay(): FloPay | null;
  * Must be called within a `<FloPayProvider>`.
  */
 declare function usePayPalFloPay(): 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;
@@ -300,47 +447,43 @@ interface CheckoutState {
  */
 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;
-}
-/** Props for the standalone non-card Payment Element. */
-interface PaymentElementProps extends Omit<ElementComponentProps, 'options'> {
+/** Props for the `FloPayProvider` component. */
+interface FloPayProviderProps {
+    /** A `FloPay` instance or a promise that resolves to one (from `loadFloPay()`). */
+    flopay: Promise<FloPay> | FloPay;
     /**
-     * Element options with an explicit wallet/APM allowlist. `card` is removed
-     * at runtime; an empty result is rejected before the provider is called.
+     * Optional Stripe `FloPay` instance used to drive the Stripe-rendered PayPal
+     * fallback. When omitted or `null`, the Stripe-rendered PayPal button is
+     * not rendered. Direct PayPal (`gateways.paypal`) does not use this prop.
      */
-    options: Omit<Partial<ElementOptions>, 'paymentMethodTypes'> & {
-        paymentMethodTypes: readonly string[];
+    paypalFlopay?: Promise<FloPay> | FloPay | null;
+    /** Optional provider configuration. */
+    options?: {
+        /** Billing API base URL. Set once here so child components don't need to repeat it. */
+        billingApiUrl?: string;
     };
+    /** Receives the versioned, privacy-safe checkout instrument feed. */
+    onInstrument?: (event: FloInstrumentEvent) => void;
+    children: React.ReactNode;
 }
 /**
- * Renders a provider Payment Element restricted to the declared non-card
- * wallet/APM methods. Card collection is available only through the hosted
- * vault checkout surfaces.
- */
-declare const PaymentElement: React.FC<PaymentElementProps>;
-/**
- * Renders an address input element.
+ * Provides FloPay SDK context to the component tree.
+ *
+ * Wrap components that consume FloPay context with this provider:
+ *
+ * ```tsx
+ * <FloPayProvider flopay={loadFloPay('pk_test_...')}>
+ *   <YourCheckout />
+ * </FloPayProvider>
+ * ```
+ *
+ * `FloPayCheckout` is a standalone integration that owns its provider:
+ *
+ * ```tsx
+ * <FloPayCheckout sessionId="sess_..." />
+ * ```
  */
-declare const AddressElement: React.FC<ElementComponentProps>;
+declare function FloPayProvider({ flopay: floPayProp, paypalFlopay: paypalFloPayProp, options, onInstrument, children, }: FloPayProviderProps): React.ReactElement;
 
 type MaybePromise<T> = T | Promise<T>;
 
@@ -490,7 +633,7 @@ interface SplitCardFormProps {
      * Called before a payment button continues in `layout="buttons"`.
      * Runs for card, PayPal, Apple Pay, and Google Pay.
      */
-    onBeforeButtonClick?: (event: BeforeButtonClickEvent) => MaybePromise<void | false | InlineSessionPatch>;
+    onBeforeButtonClick?: (event: BeforeButtonClickEvent) => MaybePromise<undefined | false | InlineSessionPatch>;
     /**
      * Enable AVS (Address Verification).
      * - `true` — show country + postal code (backward compatible default)
@@ -642,270 +785,4 @@ interface VaultCardFieldsProps {
  */
 declare function VaultCardFields({ capture, html, messageToken, expectedOrigin, theme, containerStyle, onReady, onError, onValidation, }: VaultCardFieldsProps): React.ReactElement;
 
-/**
- * Props for the `PayPalButton` component.
- *
- * Must be rendered inside its own `FloPayProvider` with `paymentMethodCreation: undefined`
- * (not 'manual') because this PayPal flow needs automatic payment-method creation.
- */
-interface PayPalButtonProps {
-    /** The checkout session ID (UUID from billing API). */
-    sessionId: string;
-    /**
-     * Session-bound checkout token returned by session creation. Forwarded as
-     * `x-checkout-session-token` on continuation requests — required by
-     * post-#640 backends.
-     */
-    nonce?: 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` with automatic
- * payment-method creation. Keep it separate from manually created wallet/APM
- * Elements groups.
- *
- * ```tsx
- * {/* Main checkout provider *\/}
- * <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, nonce, billingApiUrl, email, userId, firstName, lastName, chv, onTokenizedBody, onComplete, onErrorChange, isProcessing, }: PayPalButtonProps): React.ReactElement;
-
-/**
- * Overrides that `SplitCardForm`'s tokenized-body dispatcher uses to apply a
- * `runBeforeButtonClick` patch to the in-flight processPayment call. Kept in
- * sync structurally with `TokenizedBodyOverrides` in `split-card-form.tsx`.
- */
-interface DirectPayPalTokenizedOverrides {
-    accountPatch?: InlineSessionPatch['account'];
-    sessionId?: string;
-    nonce?: string;
-}
-/**
- * Internal handler signature aligned with `SplitCardForm`'s tokenized-body
- * dispatcher. Direct PayPal completes via the backend's process endpoint and
- * never produces a Stripe PaymentIntent, so we still forward a synthetic
- * `TokenizedBody` describing the captured order, optionally with the
- * session/account patch captured at click-time.
- */
-type DirectPayPalTokenizedHandler = (body: TokenizedBody, overrides?: DirectPayPalTokenizedOverrides) => void;
-/** Click-time `runBeforeButtonClick` result, structurally compatible with `SplitCardForm`. */
-interface DirectPayPalBeforeButtonClickResult {
-    proceed: boolean;
-    accountPatch?: InlineSessionPatch['account'];
-    sessionId?: string;
-    nonce?: string;
-}
-/**
- * Click-time gate. Mirrors `RunBeforeButtonClick` in `SplitCardForm`: lets the
- * consumer patch the session/account before PayPal creates the order, and lets
- * them abort the click entirely by returning `proceed: false`.
- */
-type DirectPayPalRunBeforeButtonClick = (method: CheckoutButtonMethod) => Promise<DirectPayPalBeforeButtonClickResult>;
-type DirectPayPalInitializationState = 'loading' | 'retrying' | 'ready' | 'exhausted';
-type DirectPayPalTechnicalFailureHandler = (method: 'paypal', err: unknown, options?: {
-    code?: string;
-    popupBlocked?: boolean;
-}) => void;
-interface DirectPayPalButtonProps {
-    /** Checkout session ID. */
-    sessionId: string;
-    /**
-     * Session-bound checkout token returned by session creation. Forwarded as
-     * `x-checkout-session-token` on every continuation request — required by
-     * post-#640 backends. `FloPayCheckout` plumbs this prop automatically.
-     */
-    nonce?: string;
-    /** Billing API base URL. */
-    billingApiUrl: string;
-    /** Buyer email. */
-    email?: string;
-    /** PayPal client identifier (`gateways.paypal.publishableKey`). */
-    clientId: string;
-    /** Gateway environment, drives the sandbox/live SDK script. */
-    environment?: GatewayEnvironment;
-    /** ISO 4217 currency code. */
-    currency: string;
-    /** Whether the session is a subscription (drives intent + flow selection). */
-    isSubscription: boolean;
-    /**
-     * Provider object the backend advertised for this PayPal continuation.
-     * When omitted, legacy sessions continue to derive the flow from
-     * `isSubscription`. An advertised `'order'`/`'setup_token'` opts intent and
-     * process requests into the Flo-owned `paypal_vaulted` payment-method
-     * channel; an advertised `'subscription'` or an omission keeps the released
-     * `paypal` requests byte-identical.
-     */
-    providerObjectType?: PayPalProviderObjectType;
-    /**
-     * If provided, called with the tokenized body once PayPal capture
-     * completes. When omitted, the component processes payment internally.
-     */
-    onTokenizedBody?: DirectPayPalTokenizedHandler;
-    /** Called when the full self-contained payment flow succeeds. */
-    onComplete?: (result: PaymentResult) => void;
-    /** Called when an error occurs. */
-    onErrorChange?: (error: string | null) => void;
-    /** Decline emitter (mirrors SplitCardForm semantics). */
-    onDecline?: (decline: DeclineEvent) => void;
-    /** Called for post-click technical failures before PayPal authorization completes. */
-    onTechnicalFailure?: DirectPayPalTechnicalFailureHandler;
-    /** External processing state. */
-    isProcessing?: boolean;
-    /** Notify the parent of the loading state for placeholder swapping. */
-    onLoadStateChange?: (ready: boolean) => void;
-    /** Notify a PayPal-only wrapper about pre-render recovery state. */
-    onInitializationStateChange?: (state: DirectPayPalInitializationState) => void;
-    /** Disable the automatic retry for a buyer-initiated single manual attempt. */
-    allowAutomaticRetry?: boolean;
-    /** Tracks button-click for analytics. */
-    onButtonClick?: (method: CheckoutButtonMethod) => void;
-    /**
-     * Click-time gate (runs before PayPal creates the order). When provided, the
-     * returned patch is applied to the in-flight create-intent and tokenized
-     * dispatch so callers using `onBeforeButtonClick` see the same session/email
-     * the Stripe-rendered PayPal flow does.
-     */
-    runBeforeButtonClick?: DirectPayPalRunBeforeButtonClick;
-    /** Backing session — used for self-contained accountData population. */
-    session?: CheckoutSession | null;
-    /**
-     * Pre-existing PayPal Order id (or Subscription id when `isSubscription` is
-     * true) to bind the button to. When set, the button skips its usual
-     * session-scoped create-intent round-trip on click and feeds this
-     * id straight into PayPal's create-order / create-subscription callback.
-     *
-     * Used by `SplitCardForm`'s `paypal_direct_required` retry path: backend
-     * creates a fresh PayPal order after a stalled process attempt and returns
-     * its id; the SDK re-renders this button bound to that id so the buyer can
-     * confirm with one more click without the backend re-creating the order on
-     * each retry.
-     *
-     * Changing this value remounts the PayPal SDK so the new createOrder
-     * binding takes effect (PayPal's render() options aren't live-updatable).
-     */
-    existingOrderId?: string;
-    /** Flo-owned privacy-safe telemetry is enabled by default; set `false` to opt out. */
-    telemetry?: boolean;
-    /**
-     * When true, renders an on-screen lifecycle tracer panel above the button
-     * (mount, loadScript, eligibility, render, errors). Intended for debugging
-     * in-app browsers (Facebook IAB, etc.) where remote console access is
-     * impractical. Off by default — leave disabled in production.
-     */
-    debug?: boolean;
-}
-/** Public direct-PayPal surface: telemetry accepts only the boolean opt-out. */
-declare function DirectPayPalButton(props: DirectPayPalButtonProps): React.ReactElement | null;
-
-interface FloPayAutomaticPaymentSuccessEvent {
-    result: PaymentResult;
-    session: CheckoutSession | null;
-    sessionId: string | null;
-    autoCompleted: boolean;
-}
-interface FloPayAutomaticPaymentButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'onError'> {
-    sessionId?: string;
-    /**
-     * Session-bound checkout token for a consumer-supplied {@link sessionId}
-     * (the `nonce` returned when that session was created). Post-#640 backends
-     * require it as `x-checkout-session-token` to read the session and to
-     * `/process` it; without it the existing-session path 401s with
-     * "Missing checkout session token.". Ignored on the create-session path,
-     * where the SDK mints and threads the nonce itself.
-     */
-    nonce?: string;
-    createSession?: InlineSessionDraft;
-    /**
-     * @deprecated Ignored. The backend now picks the customer's most recent
-     * vaulted payment method via `getLatestByUserId` and rebinds the session's
-     * gateway to match it (see `apps/api`'s `createSingle` auto-checkout
-     * branch). Passing this prop has no effect — it is retained only to avoid
-     * breaking existing integrations.
-     */
-    paymentMethodId?: string;
-    /**
-     * @deprecated Ignored. The backend orchestrates gateway routing — clients
-     * no longer choose between card and PayPal at the SDK boundary. Passing
-     * this prop has no effect.
-     */
-    checkoutMethod?: CheckoutButtonMethod;
-    clientId?: string;
-    /**
-     * Unified products array (TeamFloPay/backend#760). When supplied,
-     * `items`/`subscriptions` are ignored. The SDK folds the legacy fields
-     * into this shape internally.
-     */
-    products?: CheckoutProduct[];
-    items?: CheckoutItem[];
-    subscriptions?: CheckoutSubscription[];
-    account?: InlineSessionDraft['account'];
-    successUrl?: string;
-    cancelUrl?: string;
-    couponCodes?: string[];
-    tagsData?: InlineSessionDraft['tagsData'];
-    utmMetadata?: InlineSessionDraft['utmMetadata'];
-    billingApiUrl?: string;
-    locale?: string;
-    /**
-     * High-level theme bundle that styles the button (and the fallback
-     * `FloPayCheckout` modal that opens when the saved-payment charge needs
-     * user interaction). One of: `'classic'`, `'modern-light'`, `'modern-dark'`,
-     * `'bold-light'`, `'bold-dark'`, `'glass-light'`, `'glass-dark'`. Explicit
-     * `buttonsStyles` still wins for fine-grained overrides.
-     */
-    theme?: ThemeId;
-    /**
-     * Per-checkout appearance overrides layered on top of the chosen `theme`
-     * (same shape as {@link FloPayCheckout}'s `appearance`). Its `colorPrimary` /
-     * `colorPrimaryHover` / `borderRadius` re-skin the button — and the fallback
-     * `FloPayCheckout` modal — so the auto-pay button matches the rest of the
-     * themed checkout. Without this the button only saw the bundle's defaults.
-     */
-    appearance?: FloPayAppearance;
-    /**
-     * @deprecated Use `theme` instead. Legacy buttons-layout preset
-     * (`'default' | 'minimal' | 'rounded' | 'dark'`). Still honored for
-     * back-compat.
-     */
-    buttonsTheme?: ButtonsLayoutTheme;
-    buttonsStyles?: ButtonsLayoutStyles;
-    onSuccess?: (event: FloPayAutomaticPaymentSuccessEvent) => void;
-    onError?: (error: FloPayError) => void;
-    onDecline?: (decline: DeclineEvent) => void;
-    children?: React.ReactNode;
-}
-declare function FloPayAutomaticPaymentButton({ sessionId, nonce, createSession, paymentMethodId: _deprecatedPaymentMethodId, checkoutMethod: _deprecatedCheckoutMethod, clientId, products, items, subscriptions, account, successUrl, cancelUrl, couponCodes, tagsData, utmMetadata, billingApiUrl, locale, theme, appearance, buttonsTheme, buttonsStyles: stylesOverride, onSuccess, onError, onDecline, children, disabled, type, style, ...buttonProps }: FloPayAutomaticPaymentButtonProps): React.JSX.Element;
-
-export { AddressElement, type CheckoutState, DirectPayPalButton, type DirectPayPalButtonProps, type DirectPayPalInitializationState, type ElementComponentProps, FloPayAutomaticPaymentButton, type FloPayAutomaticPaymentButtonProps, type FloPayAutomaticPaymentSuccessEvent, FloPayCheckout, type FloPayCheckoutProps, FloPayProvider, type FloPayProviderProps, PayPalButton, type PayPalButtonProps, PaymentElement, type PaymentElementProps, SplitCardForm, type SplitCardFormProps, VaultCardFields, type VaultCardFieldsProps, useCheckout, useElements, useFloPay, usePayPalFloPay };
+export { type CheckoutState, DirectPayPalButton, type DirectPayPalButtonProps, type DirectPayPalInitializationState, FloPayAutomaticPaymentButton, type FloPayAutomaticPaymentButtonProps, type FloPayAutomaticPaymentSuccessEvent, FloPayCheckout, type FloPayCheckoutProps, FloPayProvider, type FloPayProviderProps, SplitCardForm, type SplitCardFormProps, VaultCardFields, type VaultCardFieldsProps, useCheckout, useFloPay, usePayPalFloPay };