@flopay/react 1.4.20 → 1.4.22

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, CardCaptureAdapter, VaultCardThemeColors, CheckoutProduct, CheckoutItem, CheckoutSubscription, ThemeId, ButtonsLayoutTheme, ButtonsLayoutStyles } from '@flopay/shared';
+import { FloPayAppearance, InlineSessionDraft, FloPayError, PaymentResult, DeclineEvent, CheckoutButtonMethod, BeforeButtonClickEvent, InlineSessionPatch, CheckoutMode, CheckoutSession, ElementOptions, ElementChangeEvent, TokenizedBody, AVSFieldConfig, GatewayEnvironment, CardCaptureAdapter, VaultCardThemeColors, ThemeId, SavedCardDisplay, FloPayErrorType, CheckoutProduct, CheckoutItem, CheckoutSubscription, ButtonsLayoutTheme, ButtonsLayoutStyles } from '@flopay/shared';
 export { BeforeButtonClickEvent, CheckoutButtonMethod, DeclineEvent, InlineSessionDraft, InlineSessionPatch, SentryEventLike, SentryStackFrameLike, dropThirdPartyOnlyError } from '@flopay/shared';
 
 /** Props for the `FloPayProvider` component. */
@@ -342,6 +342,7 @@ declare const PaymentElement: React.FC<PaymentElementProps>;
 declare const AddressElement: React.FC<ElementComponentProps>;
 
 type MaybePromise<T> = T | Promise<T>;
+
 interface SplitCardFormProps {
     /** The checkout session ID (UUID from billing API). */
     sessionId: string;
@@ -639,6 +640,77 @@ interface VaultCardFieldsProps {
  */
 declare function VaultCardFields({ capture, html, messageToken, expectedOrigin, theme, containerStyle, onReady, onError, onValidation, }: VaultCardFieldsProps): React.ReactElement;
 
+/** Verified terminal result from a no-charge card setup. */
+interface FloPayCardSetupCompleteEvent {
+    status: 'succeeded';
+    sessionId: string;
+    /** Present when the backend terminal message includes the saved-card display DTO. */
+    paymentMethod?: SavedCardDisplay;
+}
+/** Provider-neutral terminal decline from card verification. */
+interface FloPayCardSetupDeclineEvent {
+    status: 'declined';
+    sessionId: string;
+    reason?: string;
+    message?: string;
+}
+/** Abandoned setup result emitted when the component unmounts pre-terminally. */
+interface FloPayCardSetupCancelEvent {
+    status: 'cancelled';
+    sessionId: string;
+}
+/** Structured technical/validation failure from the card-setup surface. */
+declare class FloPayCardSetupError extends FloPayError {
+    readonly retryable: boolean;
+    constructor(message: string, type: FloPayErrorType, options: {
+        code: string;
+        retryable: boolean;
+        param?: string;
+        statusCode?: number;
+    });
+}
+/** Props for the browser-only secure card-setup surface. */
+interface FloPayCardSetupProps {
+    /** Opaque id returned by the merchant-authenticated setup-session endpoint. */
+    sessionId: string;
+    /** Session-bound token returned alongside {@link FloPayCardSetupProps.sessionId}. */
+    nonce: string;
+    /** Billing API base URL. Defaults to the configured FloPay environment URL. */
+    billingApiUrl?: string;
+    /** Flo-owned privacy-safe telemetry is enabled by default; set false to opt out. */
+    telemetry?: boolean;
+    /**
+     * Theme for FloPay's hosted, PCI-compliant card widget. Accepts the same
+     * high-level {@link ThemeId} as `FloPayCheckout` (resolved through the same
+     * bundle, so one value styles both surfaces identically) or raw
+     * {@link VaultCardThemeColors} for full manual control. Defaults to
+     * `'modern-light'`; pass `'classic'` for the historic FloPay look.
+     */
+    theme?: ThemeId | VaultCardThemeColors;
+    /** Inline styles for the hosted-widget container. */
+    containerStyle?: React.CSSProperties;
+    /** Optional content shown while the session and hosted widget are loading. */
+    loading?: React.ReactNode;
+    /** Fired once the hosted widget has mounted and can accept card input. */
+    onReady?: () => void;
+    /** Fired only after the backend reports that the card is verified and usable. */
+    onComplete?: (event: FloPayCardSetupCompleteEvent) => void;
+    /** Fired when verification terminally declines; never paired with `onComplete`. */
+    onDecline?: (event: FloPayCardSetupDeclineEvent) => void;
+    /** Fired exactly once if the setup surface unmounts before a terminal outcome. */
+    onCancel?: (event: FloPayCardSetupCancelEvent) => void;
+    /** Live hosted-field validation message, or `null` when validation clears. */
+    onValidation?: (message: string | null) => void;
+    /** Fired for setup-session validation, transport, or hosted-widget failures. */
+    onError?: (error: FloPayCardSetupError) => void;
+}
+/**
+ * Mounts FloPay's hosted card capture for a setup session created by the
+ * merchant's server. It has no customer-id, list, delete, purchase, or Stripe
+ * Elements surface.
+ */
+declare function FloPayCardSetup({ sessionId, nonce, billingApiUrl, telemetry, theme, containerStyle, loading, onReady, onComplete, onDecline, onCancel, onValidation, onError, }: FloPayCardSetupProps): React.ReactElement;
+
 /**
  * Props for the `PayPalButton` component.
  *
@@ -896,4 +968,4 @@ interface FloPayAutomaticPaymentButtonProps extends Omit<React.ButtonHTMLAttribu
 }
 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 { AddressElement, type CheckoutState, DirectPayPalButton, type DirectPayPalButtonProps, type DirectPayPalInitializationState, type ElementComponentProps, FloPayAutomaticPaymentButton, type FloPayAutomaticPaymentButtonProps, type FloPayAutomaticPaymentSuccessEvent, FloPayCardSetup, type FloPayCardSetupCancelEvent, type FloPayCardSetupCompleteEvent, type FloPayCardSetupDeclineEvent, FloPayCardSetupError, type FloPayCardSetupProps, FloPayCheckout, type FloPayCheckoutProps, FloPayProvider, type FloPayProviderProps, PayPalButton, type PayPalButtonProps, PaymentElement, type PaymentElementProps, SplitCardForm, type SplitCardFormProps, VaultCardFields, type VaultCardFieldsProps, 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, CardCaptureAdapter, VaultCardThemeColors, CheckoutProduct, CheckoutItem, CheckoutSubscription, ThemeId, ButtonsLayoutTheme, ButtonsLayoutStyles } from '@flopay/shared';
+import { FloPayAppearance, InlineSessionDraft, FloPayError, PaymentResult, DeclineEvent, CheckoutButtonMethod, BeforeButtonClickEvent, InlineSessionPatch, CheckoutMode, CheckoutSession, ElementOptions, ElementChangeEvent, TokenizedBody, AVSFieldConfig, GatewayEnvironment, CardCaptureAdapter, VaultCardThemeColors, ThemeId, SavedCardDisplay, FloPayErrorType, CheckoutProduct, CheckoutItem, CheckoutSubscription, ButtonsLayoutTheme, ButtonsLayoutStyles } from '@flopay/shared';
 export { BeforeButtonClickEvent, CheckoutButtonMethod, DeclineEvent, InlineSessionDraft, InlineSessionPatch, SentryEventLike, SentryStackFrameLike, dropThirdPartyOnlyError } from '@flopay/shared';
 
 /** Props for the `FloPayProvider` component. */
@@ -342,6 +342,7 @@ declare const PaymentElement: React.FC<PaymentElementProps>;
 declare const AddressElement: React.FC<ElementComponentProps>;
 
 type MaybePromise<T> = T | Promise<T>;
+
 interface SplitCardFormProps {
     /** The checkout session ID (UUID from billing API). */
     sessionId: string;
@@ -639,6 +640,77 @@ interface VaultCardFieldsProps {
  */
 declare function VaultCardFields({ capture, html, messageToken, expectedOrigin, theme, containerStyle, onReady, onError, onValidation, }: VaultCardFieldsProps): React.ReactElement;
 
+/** Verified terminal result from a no-charge card setup. */
+interface FloPayCardSetupCompleteEvent {
+    status: 'succeeded';
+    sessionId: string;
+    /** Present when the backend terminal message includes the saved-card display DTO. */
+    paymentMethod?: SavedCardDisplay;
+}
+/** Provider-neutral terminal decline from card verification. */
+interface FloPayCardSetupDeclineEvent {
+    status: 'declined';
+    sessionId: string;
+    reason?: string;
+    message?: string;
+}
+/** Abandoned setup result emitted when the component unmounts pre-terminally. */
+interface FloPayCardSetupCancelEvent {
+    status: 'cancelled';
+    sessionId: string;
+}
+/** Structured technical/validation failure from the card-setup surface. */
+declare class FloPayCardSetupError extends FloPayError {
+    readonly retryable: boolean;
+    constructor(message: string, type: FloPayErrorType, options: {
+        code: string;
+        retryable: boolean;
+        param?: string;
+        statusCode?: number;
+    });
+}
+/** Props for the browser-only secure card-setup surface. */
+interface FloPayCardSetupProps {
+    /** Opaque id returned by the merchant-authenticated setup-session endpoint. */
+    sessionId: string;
+    /** Session-bound token returned alongside {@link FloPayCardSetupProps.sessionId}. */
+    nonce: string;
+    /** Billing API base URL. Defaults to the configured FloPay environment URL. */
+    billingApiUrl?: string;
+    /** Flo-owned privacy-safe telemetry is enabled by default; set false to opt out. */
+    telemetry?: boolean;
+    /**
+     * Theme for FloPay's hosted, PCI-compliant card widget. Accepts the same
+     * high-level {@link ThemeId} as `FloPayCheckout` (resolved through the same
+     * bundle, so one value styles both surfaces identically) or raw
+     * {@link VaultCardThemeColors} for full manual control. Defaults to
+     * `'modern-light'`; pass `'classic'` for the historic FloPay look.
+     */
+    theme?: ThemeId | VaultCardThemeColors;
+    /** Inline styles for the hosted-widget container. */
+    containerStyle?: React.CSSProperties;
+    /** Optional content shown while the session and hosted widget are loading. */
+    loading?: React.ReactNode;
+    /** Fired once the hosted widget has mounted and can accept card input. */
+    onReady?: () => void;
+    /** Fired only after the backend reports that the card is verified and usable. */
+    onComplete?: (event: FloPayCardSetupCompleteEvent) => void;
+    /** Fired when verification terminally declines; never paired with `onComplete`. */
+    onDecline?: (event: FloPayCardSetupDeclineEvent) => void;
+    /** Fired exactly once if the setup surface unmounts before a terminal outcome. */
+    onCancel?: (event: FloPayCardSetupCancelEvent) => void;
+    /** Live hosted-field validation message, or `null` when validation clears. */
+    onValidation?: (message: string | null) => void;
+    /** Fired for setup-session validation, transport, or hosted-widget failures. */
+    onError?: (error: FloPayCardSetupError) => void;
+}
+/**
+ * Mounts FloPay's hosted card capture for a setup session created by the
+ * merchant's server. It has no customer-id, list, delete, purchase, or Stripe
+ * Elements surface.
+ */
+declare function FloPayCardSetup({ sessionId, nonce, billingApiUrl, telemetry, theme, containerStyle, loading, onReady, onComplete, onDecline, onCancel, onValidation, onError, }: FloPayCardSetupProps): React.ReactElement;
+
 /**
  * Props for the `PayPalButton` component.
  *
@@ -896,4 +968,4 @@ interface FloPayAutomaticPaymentButtonProps extends Omit<React.ButtonHTMLAttribu
 }
 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 { AddressElement, type CheckoutState, DirectPayPalButton, type DirectPayPalButtonProps, type DirectPayPalInitializationState, type ElementComponentProps, FloPayAutomaticPaymentButton, type FloPayAutomaticPaymentButtonProps, type FloPayAutomaticPaymentSuccessEvent, FloPayCardSetup, type FloPayCardSetupCancelEvent, type FloPayCardSetupCompleteEvent, type FloPayCardSetupDeclineEvent, FloPayCardSetupError, type FloPayCardSetupProps, FloPayCheckout, type FloPayCheckoutProps, FloPayProvider, type FloPayProviderProps, PayPalButton, type PayPalButtonProps, PaymentElement, type PaymentElementProps, SplitCardForm, type SplitCardFormProps, VaultCardFields, type VaultCardFieldsProps, useCheckout, useElements, useFloPay, usePayPalFloPay };