@flopay/react 1.1.6 → 1.2.1

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 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, CheckoutItem, CheckoutSubscription, ThemeId, ButtonsLayoutTheme, ButtonsLayoutStyles } from '@flopay/shared';
+import { FloPayAppearance, InlineSessionDraft, FloPayError, PaymentResult, DeclineEvent, CheckoutButtonMethod, BeforeButtonClickEvent, InlineSessionPatch, CheckoutMode, CheckoutSession, ElementOptions, ElementChangeEvent, TokenizedBody, AVSFieldConfig, GatewayEnvironment, CheckoutProduct, CheckoutItem, CheckoutSubscription, ThemeId, ButtonsLayoutTheme, ButtonsLayoutStyles } from '@flopay/shared';
 export { BeforeButtonClickEvent, CheckoutButtonMethod, DeclineEvent, InlineSessionDraft, InlineSessionPatch } from '@flopay/shared';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
@@ -50,6 +50,15 @@ declare function FloPayProvider({ flopay: floPayProp, paypalFlopay: paypalFloPay
 interface FloPayCheckoutProps {
     /** The checkout session ID (UUID from billing API). Required unless `createSession` is provided. */
     sessionId?: string;
+    /**
+     * Session-bound checkout token (the `nonce` returned when the session was
+     * created). Sent as the `x-checkout-session-token` header when fetching a
+     * session by `sessionId`. Required by post-#640 backends, which no longer
+     * let the UUID alone authorize a session read; harmless on older backends.
+     * Only consulted in the `sessionId` flow — inline `createSession` sessions
+     * carry their own freshly-minted nonce server-side.
+     */
+    nonce?: string;
     /**
      * Create a checkout session inline — no separate API route needed.
      * The component POSTs to the billing API, gets the full session back, and renders the form.
@@ -78,11 +87,30 @@ interface FloPayCheckoutProps {
     onCountryChange?: (country: string) => void;
     /** Called when the AVS ZIP/postcode input changes. */
     onZipChange?: (zip: string) => void;
-    /** Whether to show the PayPal button (default: true). */
+    /**
+     * Show the PayPal payment surface (default: `true`). Renderer is chosen
+     * from `gateways.paypal` on the session — DirectPayPalButton when present,
+     * Stripe-rendered PayPal otherwise.
+     */
     showPayPal?: boolean;
-    /** Whether to show Apple Pay button (default: true). Only renders on supported devices. */
+    /**
+     * Show the Stripe-rendered checkout — card fields, ExpressCheckoutElement,
+     * and the PaymentElement accordion (default: `true`). When `false`, only
+     * `DirectPayPalButton` can render. Both `showStripe=false` and
+     * `showPayPal=false` (with no PayPal gateway configured) triggers a
+     * bootstrap-time validation error.
+     */
+    showStripe?: boolean;
+    /**
+     * @deprecated Apple Pay availability is now driven by
+     * `gateways.stripe.enabledPaymentMethods` on the per-session response from
+     * the billing API. Setting this prop emits a one-time deprecation warning
+     * and is otherwise ignored once the backend ships the list.
+     */
     showApplePay?: boolean;
-    /** Whether to show Google Pay button (default: true). Only renders on supported devices. */
+    /**
+     * @deprecated See {@link FloPayCheckoutProps.showApplePay}.
+     */
     showGooglePay?: boolean;
     /**
      * Enables on-screen diagnostic panels (PayPal gate decision, DirectPayPalButton
@@ -193,7 +221,7 @@ interface FloPayCheckoutProps {
  * />
  * ```
  */
-declare function FloPayCheckout({ sessionId: sessionIdProp, createSession: createSessionParams, billingApiUrl, appearance: appearanceOverride, locale, loading: loadingNode, error: errorNode, onComplete, onError, onDecline, onFullNameChange, onCountryChange, onZipChange, showPayPal, showApplePay, showGooglePay, debug, layout, theme, buttonsTheme, buttonsStyles, cardButtonContent, cardBackButtonContent, cardTitleContent, showSecurityFooter: _showSecurityFooter, onButtonClick, onBeforeButtonClick, enableAVS, avsLayout, submitLabel, className, initialErrorMessage, children, checkoutMode: checkoutModeProp, confirmLabel, renderConfirmButton, onSessionCompleted, }: FloPayCheckoutProps): React.ReactElement;
+declare function FloPayCheckout({ sessionId: sessionIdProp, nonce: nonceProp, createSession: createSessionParams, billingApiUrl, appearance: appearanceOverride, locale, loading: loadingNode, error: errorNode, onComplete, onError, onDecline, onFullNameChange, onCountryChange, onZipChange, showPayPal, showStripe, showApplePay, showGooglePay, debug, layout, theme, buttonsTheme, buttonsStyles, cardButtonContent, cardBackButtonContent, cardTitleContent, showSecurityFooter: _showSecurityFooter, onButtonClick, onBeforeButtonClick, enableAVS, avsLayout, submitLabel, className, initialErrorMessage, children, checkoutMode: checkoutModeProp, confirmLabel, renderConfirmButton, onSessionCompleted, }: FloPayCheckoutProps): React.ReactElement;
 
 /**
  * Returns the current `FloPay` instance, or `null` if the provider
@@ -422,14 +450,44 @@ interface SplitCardFormProps {
     /** 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.
+     * Show the PayPal payment surface above card fields. Defaults to `true`.
+     * The renderer is chosen from `session.gateways.paypal`: when that gateway
+     * is configured, `DirectPayPalButton` (PayPal JS SDK) takes over and Stripe
+     * drops `paypal` from its express row to avoid double-rendering; otherwise
+     * PayPal renders inside `ExpressCheckoutElement` (using either a dedicated
+     * `gateways.stripe.paypalPublishableKey` sub-account or the main Stripe
+     * account when the enabled-methods list includes `paypal`).
      */
     showPayPal?: boolean;
-    /** Show Apple Pay button. Defaults to `true`. Only renders on supported devices. */
+    /**
+     * Show the Stripe-rendered checkout (card fields + ExpressCheckoutElement +
+     * PaymentElement). Defaults to `true`. When `false`, every Stripe surface
+     * is hidden — only `DirectPayPalButton` can render. Setting both
+     * `showStripe={false}` and `showPayPal={false}` (with no PayPal gateway
+     * configured) throws a bootstrap-time validation error.
+     */
+    showStripe?: boolean;
+    /**
+     * Per-session list of Stripe payment method type identifiers (as returned
+     * by the billing API on `gateways.stripe.enabledPaymentMethods`). When
+     * supplied, drives the contents of the `ExpressCheckoutElement` row and the
+     * accordion `PaymentElement` instead of the historic hardcoded
+     * Apple/Google/PayPal set. When omitted, the SDK falls back to the legacy
+     * `showApplePay`/`showGooglePay`/`showPayPal` toggles.
+     */
+    enabledPaymentMethods?: string[];
+    /**
+     * @deprecated The Apple Pay / Google Pay surface is now driven by the
+     * `gateways.stripe.enabledPaymentMethods` list returned per-session by the
+     * billing API. Pass {@link SplitCardFormProps.enabledPaymentMethods} (or
+     * upgrade the backend so `FloPayCheckout` threads it through automatically).
+     * Setting this prop emits a one-time deprecation warning and is otherwise
+     * ignored when `enabledPaymentMethods` is supplied.
+     */
     showApplePay?: boolean;
-    /** Show Google Pay button. Defaults to `true`. Only renders on supported devices. */
+    /**
+     * @deprecated See {@link SplitCardFormProps.showApplePay}.
+     */
     showGooglePay?: boolean;
     /**
      * Layout mode for the payment form.
@@ -736,6 +794,12 @@ interface FloPayAutomaticPaymentButtonProps extends Omit<React.ButtonHTMLAttribu
      */
     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'];
@@ -766,6 +830,6 @@ interface FloPayAutomaticPaymentButtonProps extends Omit<React.ButtonHTMLAttribu
     onDecline?: (decline: DeclineEvent) => void;
     children?: React.ReactNode;
 }
-declare function FloPayAutomaticPaymentButton({ sessionId, createSession, paymentMethodId: _deprecatedPaymentMethodId, checkoutMethod: _deprecatedCheckoutMethod, clientId, items, subscriptions, account, successUrl, cancelUrl, couponCodes, tagsData, utmMetadata, billingApiUrl, locale, theme, buttonsTheme, buttonsStyles: stylesOverride, onSuccess, onError, onDecline, children, disabled, type, style, ...buttonProps }: FloPayAutomaticPaymentButtonProps): react_jsx_runtime.JSX.Element;
+declare function FloPayAutomaticPaymentButton({ sessionId, createSession, paymentMethodId: _deprecatedPaymentMethodId, checkoutMethod: _deprecatedCheckoutMethod, clientId, products, items, subscriptions, account, successUrl, cancelUrl, couponCodes, tagsData, utmMetadata, billingApiUrl, locale, theme, buttonsTheme, buttonsStyles: stylesOverride, onSuccess, onError, onDecline, children, disabled, type, style, ...buttonProps }: FloPayAutomaticPaymentButtonProps): react_jsx_runtime.JSX.Element;
 
 export { AddressElement, CardCvcElement, CardElement, CardExpiryElement, CardNumberElement, CheckoutForm, type CheckoutFormProps, type CheckoutFormRef, type CheckoutState, DirectPayPalButton, type DirectPayPalButtonProps, type ElementComponentProps, FloPayAutomaticPaymentButton, type FloPayAutomaticPaymentButtonProps, type FloPayAutomaticPaymentSuccessEvent, FloPayCheckout, type FloPayCheckoutProps, FloPayProvider, type FloPayProviderProps, PayPalButton, type PayPalButtonProps, PaymentElement, SplitCardForm, type SplitCardFormProps, type SplitCardFormRef, useCheckout, useElements, useFloPay, usePayPalFloPay };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 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, CheckoutItem, CheckoutSubscription, ThemeId, ButtonsLayoutTheme, ButtonsLayoutStyles } from '@flopay/shared';
+import { FloPayAppearance, InlineSessionDraft, FloPayError, PaymentResult, DeclineEvent, CheckoutButtonMethod, BeforeButtonClickEvent, InlineSessionPatch, CheckoutMode, CheckoutSession, ElementOptions, ElementChangeEvent, TokenizedBody, AVSFieldConfig, GatewayEnvironment, CheckoutProduct, CheckoutItem, CheckoutSubscription, ThemeId, ButtonsLayoutTheme, ButtonsLayoutStyles } from '@flopay/shared';
 export { BeforeButtonClickEvent, CheckoutButtonMethod, DeclineEvent, InlineSessionDraft, InlineSessionPatch } from '@flopay/shared';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
@@ -50,6 +50,15 @@ declare function FloPayProvider({ flopay: floPayProp, paypalFlopay: paypalFloPay
 interface FloPayCheckoutProps {
     /** The checkout session ID (UUID from billing API). Required unless `createSession` is provided. */
     sessionId?: string;
+    /**
+     * Session-bound checkout token (the `nonce` returned when the session was
+     * created). Sent as the `x-checkout-session-token` header when fetching a
+     * session by `sessionId`. Required by post-#640 backends, which no longer
+     * let the UUID alone authorize a session read; harmless on older backends.
+     * Only consulted in the `sessionId` flow — inline `createSession` sessions
+     * carry their own freshly-minted nonce server-side.
+     */
+    nonce?: string;
     /**
      * Create a checkout session inline — no separate API route needed.
      * The component POSTs to the billing API, gets the full session back, and renders the form.
@@ -78,11 +87,30 @@ interface FloPayCheckoutProps {
     onCountryChange?: (country: string) => void;
     /** Called when the AVS ZIP/postcode input changes. */
     onZipChange?: (zip: string) => void;
-    /** Whether to show the PayPal button (default: true). */
+    /**
+     * Show the PayPal payment surface (default: `true`). Renderer is chosen
+     * from `gateways.paypal` on the session — DirectPayPalButton when present,
+     * Stripe-rendered PayPal otherwise.
+     */
     showPayPal?: boolean;
-    /** Whether to show Apple Pay button (default: true). Only renders on supported devices. */
+    /**
+     * Show the Stripe-rendered checkout — card fields, ExpressCheckoutElement,
+     * and the PaymentElement accordion (default: `true`). When `false`, only
+     * `DirectPayPalButton` can render. Both `showStripe=false` and
+     * `showPayPal=false` (with no PayPal gateway configured) triggers a
+     * bootstrap-time validation error.
+     */
+    showStripe?: boolean;
+    /**
+     * @deprecated Apple Pay availability is now driven by
+     * `gateways.stripe.enabledPaymentMethods` on the per-session response from
+     * the billing API. Setting this prop emits a one-time deprecation warning
+     * and is otherwise ignored once the backend ships the list.
+     */
     showApplePay?: boolean;
-    /** Whether to show Google Pay button (default: true). Only renders on supported devices. */
+    /**
+     * @deprecated See {@link FloPayCheckoutProps.showApplePay}.
+     */
     showGooglePay?: boolean;
     /**
      * Enables on-screen diagnostic panels (PayPal gate decision, DirectPayPalButton
@@ -193,7 +221,7 @@ interface FloPayCheckoutProps {
  * />
  * ```
  */
-declare function FloPayCheckout({ sessionId: sessionIdProp, createSession: createSessionParams, billingApiUrl, appearance: appearanceOverride, locale, loading: loadingNode, error: errorNode, onComplete, onError, onDecline, onFullNameChange, onCountryChange, onZipChange, showPayPal, showApplePay, showGooglePay, debug, layout, theme, buttonsTheme, buttonsStyles, cardButtonContent, cardBackButtonContent, cardTitleContent, showSecurityFooter: _showSecurityFooter, onButtonClick, onBeforeButtonClick, enableAVS, avsLayout, submitLabel, className, initialErrorMessage, children, checkoutMode: checkoutModeProp, confirmLabel, renderConfirmButton, onSessionCompleted, }: FloPayCheckoutProps): React.ReactElement;
+declare function FloPayCheckout({ sessionId: sessionIdProp, nonce: nonceProp, createSession: createSessionParams, billingApiUrl, appearance: appearanceOverride, locale, loading: loadingNode, error: errorNode, onComplete, onError, onDecline, onFullNameChange, onCountryChange, onZipChange, showPayPal, showStripe, showApplePay, showGooglePay, debug, layout, theme, buttonsTheme, buttonsStyles, cardButtonContent, cardBackButtonContent, cardTitleContent, showSecurityFooter: _showSecurityFooter, onButtonClick, onBeforeButtonClick, enableAVS, avsLayout, submitLabel, className, initialErrorMessage, children, checkoutMode: checkoutModeProp, confirmLabel, renderConfirmButton, onSessionCompleted, }: FloPayCheckoutProps): React.ReactElement;
 
 /**
  * Returns the current `FloPay` instance, or `null` if the provider
@@ -422,14 +450,44 @@ interface SplitCardFormProps {
     /** 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.
+     * Show the PayPal payment surface above card fields. Defaults to `true`.
+     * The renderer is chosen from `session.gateways.paypal`: when that gateway
+     * is configured, `DirectPayPalButton` (PayPal JS SDK) takes over and Stripe
+     * drops `paypal` from its express row to avoid double-rendering; otherwise
+     * PayPal renders inside `ExpressCheckoutElement` (using either a dedicated
+     * `gateways.stripe.paypalPublishableKey` sub-account or the main Stripe
+     * account when the enabled-methods list includes `paypal`).
      */
     showPayPal?: boolean;
-    /** Show Apple Pay button. Defaults to `true`. Only renders on supported devices. */
+    /**
+     * Show the Stripe-rendered checkout (card fields + ExpressCheckoutElement +
+     * PaymentElement). Defaults to `true`. When `false`, every Stripe surface
+     * is hidden — only `DirectPayPalButton` can render. Setting both
+     * `showStripe={false}` and `showPayPal={false}` (with no PayPal gateway
+     * configured) throws a bootstrap-time validation error.
+     */
+    showStripe?: boolean;
+    /**
+     * Per-session list of Stripe payment method type identifiers (as returned
+     * by the billing API on `gateways.stripe.enabledPaymentMethods`). When
+     * supplied, drives the contents of the `ExpressCheckoutElement` row and the
+     * accordion `PaymentElement` instead of the historic hardcoded
+     * Apple/Google/PayPal set. When omitted, the SDK falls back to the legacy
+     * `showApplePay`/`showGooglePay`/`showPayPal` toggles.
+     */
+    enabledPaymentMethods?: string[];
+    /**
+     * @deprecated The Apple Pay / Google Pay surface is now driven by the
+     * `gateways.stripe.enabledPaymentMethods` list returned per-session by the
+     * billing API. Pass {@link SplitCardFormProps.enabledPaymentMethods} (or
+     * upgrade the backend so `FloPayCheckout` threads it through automatically).
+     * Setting this prop emits a one-time deprecation warning and is otherwise
+     * ignored when `enabledPaymentMethods` is supplied.
+     */
     showApplePay?: boolean;
-    /** Show Google Pay button. Defaults to `true`. Only renders on supported devices. */
+    /**
+     * @deprecated See {@link SplitCardFormProps.showApplePay}.
+     */
     showGooglePay?: boolean;
     /**
      * Layout mode for the payment form.
@@ -736,6 +794,12 @@ interface FloPayAutomaticPaymentButtonProps extends Omit<React.ButtonHTMLAttribu
      */
     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'];
@@ -766,6 +830,6 @@ interface FloPayAutomaticPaymentButtonProps extends Omit<React.ButtonHTMLAttribu
     onDecline?: (decline: DeclineEvent) => void;
     children?: React.ReactNode;
 }
-declare function FloPayAutomaticPaymentButton({ sessionId, createSession, paymentMethodId: _deprecatedPaymentMethodId, checkoutMethod: _deprecatedCheckoutMethod, clientId, items, subscriptions, account, successUrl, cancelUrl, couponCodes, tagsData, utmMetadata, billingApiUrl, locale, theme, buttonsTheme, buttonsStyles: stylesOverride, onSuccess, onError, onDecline, children, disabled, type, style, ...buttonProps }: FloPayAutomaticPaymentButtonProps): react_jsx_runtime.JSX.Element;
+declare function FloPayAutomaticPaymentButton({ sessionId, createSession, paymentMethodId: _deprecatedPaymentMethodId, checkoutMethod: _deprecatedCheckoutMethod, clientId, products, items, subscriptions, account, successUrl, cancelUrl, couponCodes, tagsData, utmMetadata, billingApiUrl, locale, theme, buttonsTheme, buttonsStyles: stylesOverride, onSuccess, onError, onDecline, children, disabled, type, style, ...buttonProps }: FloPayAutomaticPaymentButtonProps): react_jsx_runtime.JSX.Element;
 
 export { AddressElement, CardCvcElement, CardElement, CardExpiryElement, CardNumberElement, CheckoutForm, type CheckoutFormProps, type CheckoutFormRef, type CheckoutState, DirectPayPalButton, type DirectPayPalButtonProps, type ElementComponentProps, FloPayAutomaticPaymentButton, type FloPayAutomaticPaymentButtonProps, type FloPayAutomaticPaymentSuccessEvent, FloPayCheckout, type FloPayCheckoutProps, FloPayProvider, type FloPayProviderProps, PayPalButton, type PayPalButtonProps, PaymentElement, SplitCardForm, type SplitCardFormProps, type SplitCardFormRef, useCheckout, useElements, useFloPay, usePayPalFloPay };