@flopay/js 1.4.0 → 1.4.2

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as _flopay_shared from '@flopay/shared';
-import { PaymentProviderAdapter, ElementOptions, ElementType, MountedElement, FloPayError, FloPayConfig, CreatePaymentMethodResult, ConfirmCardPaymentParams, ConfirmCardPaymentResult, CardCaptureAdapter, ConfirmPaymentParams, PaymentResult, CheckoutSession, NormalizedCheckoutSession, BillingDetails, CheckoutGateways, VaultCaptureBlock, ProcessPaymentParams, InlineSessionDraft, CardCaptureProviderId, CardCaptureMountOptions, CardCaptureEventType, CardCaptureOutcomeEvent, VaultCardThemeColors, VaultCardFieldKey, CreateSessionParams, CheckoutSessionResult } from '@flopay/shared';
+import { PaymentProviderAdapter, ElementOptions, ElementType, MountedElement, FloPayError, FloPayConfig, CardCaptureAdapter, PayPalPaymentResult, ConfirmPaymentParams, PaymentResult, CheckoutSession, NormalizedCheckoutSession, CheckoutGateways, VaultCaptureBlock, ProcessPaymentParams, CreateSessionIntentRequest, SessionIntent, SessionIntentDeclineRequest, InlineSessionDraft, CardCaptureProviderId, CardCaptureMountOptions, CardCaptureEventType, CardCaptureOutcomeEvent, VaultCardThemeColors, VaultCardFieldKey, CreateSessionParams, CheckoutSessionResult } from '@flopay/shared';
 
 /**
  * Manages the creation and lifecycle of payment elements.
@@ -43,7 +43,6 @@ declare class FloPay {
     private readonly config;
     private readonly telemetryReporter?;
     private currentElements;
-    private readonly cardThreeDsStartedAt;
     private now;
     constructor(provider: PaymentProviderAdapter, config: FloPayConfig);
     /**
@@ -57,17 +56,9 @@ declare class FloPay {
     submitElements(): Promise<{
         error?: _flopay_shared.FloPayError;
     }>;
-    /** Create a payment method from the current elements (tokenize card). */
-    createPaymentMethod(billingDetails?: _flopay_shared.BillingDetails): Promise<CreatePaymentMethodResult>;
-    /** Confirm a card payment with a known client secret and payment method ID. */
-    confirmCardPayment(params: ConfirmCardPaymentParams): Promise<ConfirmCardPaymentResult>;
-    private trackCardThreeDsAttempt;
-    private takeCardThreeDsAttempt;
-    private pruneExpiredCardThreeDsAttempts;
     /**
      * Create a {@link CardCaptureAdapter} for collecting card details through the
-     * backend-rendered hosted vault PCI widget instead of provider-owned (Stripe)
-     * card fields (TeamFloPay/backend#823).
+     * backend-rendered hosted vault PCI widget (TeamFloPay/backend#823).
      *
      * The returned adapter injects the server-supplied widget HTML (the session's
      * {@link CheckoutSession.vault} block, or one fetched via
@@ -87,15 +78,14 @@ declare class FloPay {
         email: string;
         returnUrl: string;
         /**
-         * Session-bound checkout token. Forwarded as `x-checkout-session-token`
-         * on the internal `POST /v1/checkouts/payments/intents` call so post-#640
-         * backends don't reject the round-trip with a 401.
+         * Session-bound checkout token forwarded to the session-scoped non-card
+         * intent contract as `x-checkout-session-token`.
          */
         nonce?: string;
-    }): Promise<ConfirmCardPaymentResult>;
+    }): Promise<PayPalPaymentResult>;
     /** Resume a PayPal payment after redirect return. Returns null if no PayPal params in URL. */
-    resumePayPalPayment(): Promise<ConfirmCardPaymentResult | null>;
-    /** Confirms a payment using the mounted elements. */
+    resumePayPalPayment(): Promise<PayPalPaymentResult | null>;
+    /** Confirms a non-card wallet/APM payment using the mounted PaymentElement. */
     confirmPayment(params: ConfirmPaymentParams): Promise<PaymentResult>;
     /**
      * Retrieves a checkout session by ID via the billing API.
@@ -142,9 +132,9 @@ declare class FloPay {
  * import { loadFloPay } from '@flopay/js';
  *
  * const flopay = await loadFloPay('pk_test_...');
- * const elements = flopay.elements();
- * const cardElement = await elements.create('card');
- * cardElement.mount('#card-container');
+ * const elements = flopay.elements({ paymentMethodTypes: ['cashapp', 'ideal'] });
+ * const paymentElement = await elements.create('payment');
+ * paymentElement.mount('#payment-container');
  * ```
  */
 declare function loadFloPay(publishableKey: string, options?: Omit<FloPayConfig, 'publishableKey'>): Promise<FloPay>;
@@ -159,26 +149,20 @@ declare class StripeAdapter implements PaymentProviderAdapter {
     readonly name = "stripe";
     private stripe;
     private elements;
-    private readonly pendingCardThreeDsAttempts;
-    private cardThreeDsAttemptSequence;
     private appliedAppearanceKey;
+    private appliedPaymentMethodTypesKey;
+    private appliedClientSecret;
+    private verifiedClientSecret;
+    private verifiedPaymentMethodTypesKey;
     initialize(config: FloPayConfig): Promise<void>;
     /** Lazily creates the Stripe Elements group for the given options. */
     private getElements;
+    private assertClientSecretPaymentMethods;
     createElement(type: ElementType, options: ElementOptions): Promise<MountedElement>;
     getElement(type: ElementType): MountedElement | null;
     submitElements(): Promise<{
         error?: FloPayError;
     }>;
-    createPaymentMethod(billingDetails?: BillingDetails): Promise<CreatePaymentMethodResult>;
-    confirmCardPayment(params: ConfirmCardPaymentParams): Promise<ConfirmCardPaymentResult>;
-    /**
-     * Bind provider-observed 3DS milestones to the exact confirmation context.
-     * The sensitive client secret/payment method pair stays only in this private,
-     * in-memory key; callers and telemetry receive an unrelated opaque id.
-     */
-    private withCardThreeDsLifecycle;
-    private pruneExpiredCardThreeDsAttempts;
     confirmPayment(params: ConfirmPaymentParams): Promise<PaymentResult>;
     private extractPaymentMethodId;
     confirmPayPalPayment(params: {
@@ -187,8 +171,8 @@ declare class StripeAdapter implements PaymentProviderAdapter {
         email: string;
         returnUrl: string;
         nonce?: string;
-    }): Promise<ConfirmCardPaymentResult>;
-    resumePayPalPayment(): Promise<ConfirmCardPaymentResult | null>;
+    }): Promise<PayPalPaymentResult>;
+    resumePayPalPayment(): Promise<PayPalPaymentResult | null>;
     getRawProvider(): unknown;
     createPayPalElements(options: ElementOptions): unknown;
     destroy(): void;
@@ -466,39 +450,15 @@ declare class PaymentAPI {
         signal?: AbortSignal;
         timeoutMs?: number;
     }): Promise<void>;
-    /**
-     * Create a PaymentIntent on the backend.
-     *
-     * Used by the Stripe flow to create a server-side PaymentIntent
-     * with the client's payment method attached.
-     *
-     * Forwards `options.nonce` as `x-checkout-session-token` when supplied — the
-     * session-bound checkout token returned by session creation. Post-#640
-     * backends reject this call with a 401 when the header is missing or does
-     * not match the session's stored nonce.
-     *
-     * `paymentMethodType` is optional for the vault card-capture flow
-     * (TeamFloPay/backend#823): the frontend starts checkout *without* an upfront
-     * card payment method, so it may be omitted (or `null`). The hosted vault PCI
-     * form captures the card afterwards and the backend attaches the resulting
-     * payment method to the PaymentIntent it returns here. Legacy callers keep
-     * passing the concrete payment method id / type.
-     */
-    createPaymentIntent(sessionId: string, email: string, paymentMethodType?: string | null, options?: {
+    /** Create a wallet/APM/PayPal intent through the session-scoped contract. */
+    createSessionIntent(sessionId: string, nonce: string, request: CreateSessionIntentRequest, options?: {
         signal?: AbortSignal;
-        isPaypal?: string;
-        nonce?: string;
-    }): Promise<Response>;
-    /**
-     * Create a SetupIntent for saving payment methods.
-     *
-     * Forwards `options.nonce` as `x-checkout-session-token` when supplied —
-     * required by post-#640 backends, ignored by earlier versions.
-     */
-    createSetupIntent(sessionId: string, email: string, paymentMethodType: 'card' | 'google_pay' | 'apple_pay' | 'paypal_express_checkout', options?: {
+        idempotencyKey?: string;
+    }): Promise<SessionIntent>;
+    /** Record a provider-neutral non-card decline without sensitive identifiers. */
+    reportSessionIntentDecline(sessionId: string, nonce: string, request: SessionIntentDeclineRequest, options?: {
         signal?: AbortSignal;
-        nonce?: string;
-    }): Promise<Response>;
+    }): Promise<void>;
     /**
      * Fetch user's prior payments by email.
      * Used to determine if saved card UX should be shown.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _flopay_shared from '@flopay/shared';
-import { PaymentProviderAdapter, ElementOptions, ElementType, MountedElement, FloPayError, FloPayConfig, CreatePaymentMethodResult, ConfirmCardPaymentParams, ConfirmCardPaymentResult, CardCaptureAdapter, ConfirmPaymentParams, PaymentResult, CheckoutSession, NormalizedCheckoutSession, BillingDetails, CheckoutGateways, VaultCaptureBlock, ProcessPaymentParams, InlineSessionDraft, CardCaptureProviderId, CardCaptureMountOptions, CardCaptureEventType, CardCaptureOutcomeEvent, VaultCardThemeColors, VaultCardFieldKey, CreateSessionParams, CheckoutSessionResult } from '@flopay/shared';
+import { PaymentProviderAdapter, ElementOptions, ElementType, MountedElement, FloPayError, FloPayConfig, CardCaptureAdapter, PayPalPaymentResult, ConfirmPaymentParams, PaymentResult, CheckoutSession, NormalizedCheckoutSession, CheckoutGateways, VaultCaptureBlock, ProcessPaymentParams, CreateSessionIntentRequest, SessionIntent, SessionIntentDeclineRequest, InlineSessionDraft, CardCaptureProviderId, CardCaptureMountOptions, CardCaptureEventType, CardCaptureOutcomeEvent, VaultCardThemeColors, VaultCardFieldKey, CreateSessionParams, CheckoutSessionResult } from '@flopay/shared';
 
 /**
  * Manages the creation and lifecycle of payment elements.
@@ -43,7 +43,6 @@ declare class FloPay {
     private readonly config;
     private readonly telemetryReporter?;
     private currentElements;
-    private readonly cardThreeDsStartedAt;
     private now;
     constructor(provider: PaymentProviderAdapter, config: FloPayConfig);
     /**
@@ -57,17 +56,9 @@ declare class FloPay {
     submitElements(): Promise<{
         error?: _flopay_shared.FloPayError;
     }>;
-    /** Create a payment method from the current elements (tokenize card). */
-    createPaymentMethod(billingDetails?: _flopay_shared.BillingDetails): Promise<CreatePaymentMethodResult>;
-    /** Confirm a card payment with a known client secret and payment method ID. */
-    confirmCardPayment(params: ConfirmCardPaymentParams): Promise<ConfirmCardPaymentResult>;
-    private trackCardThreeDsAttempt;
-    private takeCardThreeDsAttempt;
-    private pruneExpiredCardThreeDsAttempts;
     /**
      * Create a {@link CardCaptureAdapter} for collecting card details through the
-     * backend-rendered hosted vault PCI widget instead of provider-owned (Stripe)
-     * card fields (TeamFloPay/backend#823).
+     * backend-rendered hosted vault PCI widget (TeamFloPay/backend#823).
      *
      * The returned adapter injects the server-supplied widget HTML (the session's
      * {@link CheckoutSession.vault} block, or one fetched via
@@ -87,15 +78,14 @@ declare class FloPay {
         email: string;
         returnUrl: string;
         /**
-         * Session-bound checkout token. Forwarded as `x-checkout-session-token`
-         * on the internal `POST /v1/checkouts/payments/intents` call so post-#640
-         * backends don't reject the round-trip with a 401.
+         * Session-bound checkout token forwarded to the session-scoped non-card
+         * intent contract as `x-checkout-session-token`.
          */
         nonce?: string;
-    }): Promise<ConfirmCardPaymentResult>;
+    }): Promise<PayPalPaymentResult>;
     /** Resume a PayPal payment after redirect return. Returns null if no PayPal params in URL. */
-    resumePayPalPayment(): Promise<ConfirmCardPaymentResult | null>;
-    /** Confirms a payment using the mounted elements. */
+    resumePayPalPayment(): Promise<PayPalPaymentResult | null>;
+    /** Confirms a non-card wallet/APM payment using the mounted PaymentElement. */
     confirmPayment(params: ConfirmPaymentParams): Promise<PaymentResult>;
     /**
      * Retrieves a checkout session by ID via the billing API.
@@ -142,9 +132,9 @@ declare class FloPay {
  * import { loadFloPay } from '@flopay/js';
  *
  * const flopay = await loadFloPay('pk_test_...');
- * const elements = flopay.elements();
- * const cardElement = await elements.create('card');
- * cardElement.mount('#card-container');
+ * const elements = flopay.elements({ paymentMethodTypes: ['cashapp', 'ideal'] });
+ * const paymentElement = await elements.create('payment');
+ * paymentElement.mount('#payment-container');
  * ```
  */
 declare function loadFloPay(publishableKey: string, options?: Omit<FloPayConfig, 'publishableKey'>): Promise<FloPay>;
@@ -159,26 +149,20 @@ declare class StripeAdapter implements PaymentProviderAdapter {
     readonly name = "stripe";
     private stripe;
     private elements;
-    private readonly pendingCardThreeDsAttempts;
-    private cardThreeDsAttemptSequence;
     private appliedAppearanceKey;
+    private appliedPaymentMethodTypesKey;
+    private appliedClientSecret;
+    private verifiedClientSecret;
+    private verifiedPaymentMethodTypesKey;
     initialize(config: FloPayConfig): Promise<void>;
     /** Lazily creates the Stripe Elements group for the given options. */
     private getElements;
+    private assertClientSecretPaymentMethods;
     createElement(type: ElementType, options: ElementOptions): Promise<MountedElement>;
     getElement(type: ElementType): MountedElement | null;
     submitElements(): Promise<{
         error?: FloPayError;
     }>;
-    createPaymentMethod(billingDetails?: BillingDetails): Promise<CreatePaymentMethodResult>;
-    confirmCardPayment(params: ConfirmCardPaymentParams): Promise<ConfirmCardPaymentResult>;
-    /**
-     * Bind provider-observed 3DS milestones to the exact confirmation context.
-     * The sensitive client secret/payment method pair stays only in this private,
-     * in-memory key; callers and telemetry receive an unrelated opaque id.
-     */
-    private withCardThreeDsLifecycle;
-    private pruneExpiredCardThreeDsAttempts;
     confirmPayment(params: ConfirmPaymentParams): Promise<PaymentResult>;
     private extractPaymentMethodId;
     confirmPayPalPayment(params: {
@@ -187,8 +171,8 @@ declare class StripeAdapter implements PaymentProviderAdapter {
         email: string;
         returnUrl: string;
         nonce?: string;
-    }): Promise<ConfirmCardPaymentResult>;
-    resumePayPalPayment(): Promise<ConfirmCardPaymentResult | null>;
+    }): Promise<PayPalPaymentResult>;
+    resumePayPalPayment(): Promise<PayPalPaymentResult | null>;
     getRawProvider(): unknown;
     createPayPalElements(options: ElementOptions): unknown;
     destroy(): void;
@@ -466,39 +450,15 @@ declare class PaymentAPI {
         signal?: AbortSignal;
         timeoutMs?: number;
     }): Promise<void>;
-    /**
-     * Create a PaymentIntent on the backend.
-     *
-     * Used by the Stripe flow to create a server-side PaymentIntent
-     * with the client's payment method attached.
-     *
-     * Forwards `options.nonce` as `x-checkout-session-token` when supplied — the
-     * session-bound checkout token returned by session creation. Post-#640
-     * backends reject this call with a 401 when the header is missing or does
-     * not match the session's stored nonce.
-     *
-     * `paymentMethodType` is optional for the vault card-capture flow
-     * (TeamFloPay/backend#823): the frontend starts checkout *without* an upfront
-     * card payment method, so it may be omitted (or `null`). The hosted vault PCI
-     * form captures the card afterwards and the backend attaches the resulting
-     * payment method to the PaymentIntent it returns here. Legacy callers keep
-     * passing the concrete payment method id / type.
-     */
-    createPaymentIntent(sessionId: string, email: string, paymentMethodType?: string | null, options?: {
+    /** Create a wallet/APM/PayPal intent through the session-scoped contract. */
+    createSessionIntent(sessionId: string, nonce: string, request: CreateSessionIntentRequest, options?: {
         signal?: AbortSignal;
-        isPaypal?: string;
-        nonce?: string;
-    }): Promise<Response>;
-    /**
-     * Create a SetupIntent for saving payment methods.
-     *
-     * Forwards `options.nonce` as `x-checkout-session-token` when supplied —
-     * required by post-#640 backends, ignored by earlier versions.
-     */
-    createSetupIntent(sessionId: string, email: string, paymentMethodType: 'card' | 'google_pay' | 'apple_pay' | 'paypal_express_checkout', options?: {
+        idempotencyKey?: string;
+    }): Promise<SessionIntent>;
+    /** Record a provider-neutral non-card decline without sensitive identifiers. */
+    reportSessionIntentDecline(sessionId: string, nonce: string, request: SessionIntentDeclineRequest, options?: {
         signal?: AbortSignal;
-        nonce?: string;
-    }): Promise<Response>;
+    }): Promise<void>;
     /**
      * Fetch user's prior payments by email.
      * Used to determine if saved card UX should be shown.