@flopay/js 1.4.0 → 1.4.2

package/README.md

@@ -24,43 +24,35 @@ const flopay = await loadFloPay('pk_test_...', {
 });
 ```
 
-`loadFloPay` caches the instance -- calling it again with the same key returns the cached `FloPay` instance. The optional second argument accepts a `FloPayConfig` with `billingApiUrl`, `locale`, `appearance`, and `telemetry`; set `telemetry: false` to opt out of privacy-safe operational telemetry.
+`loadFloPay` caches by publishable key and behavior-affecting options. Concurrent
+calls with the same key and options share one in-flight provider initialization
+and resolve to the same `FloPay` instance. A failed initialization is evicted so
+a later call can retry. The optional second argument accepts
+`Omit<FloPayConfig, 'publishableKey'>`, including `billingApiUrl`, `locale`,
+`appearance`, and `telemetry`; set `telemetry: false` to opt out of privacy-safe
+operational telemetry.
 
-### Create and Mount Elements
+### Create and Mount Non-card Elements
 
 ```ts
 const elements = flopay.elements({
   amount: 2999,       // in cents
   currency: 'usd',
+  paymentMethodTypes: ['cashapp', 'ideal'],
 });
 
-const cardElement = await elements.create('card');
-cardElement.mount(document.getElementById('card-container')!);
+const paymentElement = await elements.create('payment');
+paymentElement.mount(document.getElementById('payment-container')!);
 ```
 
-### Tokenize and Confirm Payment
-
-```ts
-// 1. Validate elements
-const { error: submitError } = await flopay.submitElements();
-if (submitError) throw submitError;
-
-// 2. Tokenize card into a PaymentMethod
-const { paymentMethodId, error } = await flopay.createPaymentMethod();
-if (error || !paymentMethodId) throw error;
-
-// 3. Confirm card payment with a client secret from your server
-const result = await flopay.confirmCardPayment({
-  clientSecret: 'pi_xxx_secret_yyy',
-  paymentMethodId,
-});
-
-if (result.error) {
-  console.error(result.error.message);
-} else {
-  console.log('Payment status:', result.status);
-}
-```
+`paymentMethodTypes` is required for `payment` elements and must contain at
+least one wallet/APM method. Any `card` entry is removed; a missing or empty
+non-card allowlist throws `FloPayError('validation_error')`. When Elements are
+initialized with a `clientSecret`, the provider intent is verified against the
+explicit non-card allowlist before mounting; the allowlist remains required and
+any extra provider method is rejected. Use
+`@flopay/react`'s `FloPayCheckout` or `SplitCardForm` for card checkout; both
+mount the backend-hosted vault widget supplied in the session's `vault` block.
 
 ### PayPal Payment
 
@@ -68,6 +60,7 @@ if (result.error) {
 const result = await flopay.confirmPayPalPayment({
   billingApiUrl: 'https://billing.example.com',
   sessionId: 'session_uuid',
+  nonce: sessionNonce,
   email: 'user@example.com',
   returnUrl: window.location.href,
 });
@@ -113,15 +106,28 @@ const session = await api.getUnifiedCheckoutSession('session_uuid', sessionNonce
 // session.data.session.clientSecret carries the same nonce so downstream
 // code can re-use it.
 
-// Create a PaymentIntent — nonce becomes the `x-checkout-session-token`
-// header automatically.
-const intentResponse = await api.createPaymentIntent(
+// Create an Apple Pay intent. Direct-card requests are not part of this union.
+const intent = await api.createSessionIntent(
   'session_uuid',
-  'user@example.com',
-  'pm_xxx',
-  { nonce: sessionNonce },
+  sessionNonce,
+  {
+    provider: 'stripe',
+    paymentMethodCategory: 'wallet',
+    paymentMethodType: 'apple_pay',
+    paymentMethodId: 'pm_xxx',
+    intentKind: 'payment',
+  },
 );
 
+// Report a client-observed non-card decline using a provider classification
+// code only. Messages, identifiers, card data, credentials, and PII are rejected.
+await api.reportSessionIntentDecline('session_uuid', sessionNonce, {
+  provider: 'stripe',
+  paymentMethodCategory: 'wallet',
+  paymentMethodType: 'apple_pay',
+  providerDeclineReason: 'payment_failed',
+});
+
 // Process a tokenized payment. `nonce` is required: the SDK throws a
 // `FloPayError` with code `MissingCheckoutSessionToken` when it is missing,
 // and otherwise POSTs to `/v1/checkouts/sessions/<id>/process` with the
@@ -267,12 +273,12 @@ The same default-on behavior and boolean opt-out apply to direct `FloPay`,
 
 | Export | Description |
 |--------|-------------|
-| `loadFloPay(publishableKey, options?)` | Initializes the SDK. Returns a `Promise<FloPay>`. Caches by key. |
-| `FloPay` | Main SDK class. Methods: `elements()`, `submitElements()`, `createPaymentMethod()`, `confirmCardPayment()`, `cardCapture()`, `confirmPayment()`, `confirmPayPalPayment()`, `resumePayPalPayment()`, `retrieveSession()`, `retrieveUnifiedSession()`, `getRawProvider()`, `destroy()` |
+| `loadFloPay(publishableKey, options?)` | Initializes the SDK. Returns a `Promise<FloPay>`. Shares successful and in-flight work by key; failed work remains retryable. |
+| `FloPay` | Main SDK class. Methods: `elements()`, `submitElements()`, `cardCapture()`, `confirmPayment()`, `confirmPayPalPayment()`, `resumePayPalPayment()`, `retrieveSession()`, `retrieveUnifiedSession()`, `getRawProvider()`, `destroy()` |
 | `FloPayElements` | Element group manager. Methods: `create(type, options?)`, `getElement(type)`, `submit()`, `destroy()` |
 | `StripeAdapter` | `PaymentProviderAdapter` implementation for Stripe |
 | `PciVaultCardCapture` | `CardCaptureAdapter` implementation that injects the backend-served hosted vault card widget. See [Vault card capture](#vault-card-capture). |
-| `PaymentAPI` | Billing API client. Methods: `getCheckoutSession()`, `getVaultCapture()`, `getUnifiedCheckoutSession()`, `processPayment()`, `waitForCheckoutSessionCompletion()`, `createPaymentIntent()`, `createSetupIntent()`, `getPaymentsByEmail()`, `destroy()` |
+| `PaymentAPI` | Billing API client. Includes session retrieval/creation, vault recovery, `/process`, `createSessionIntent()`, `reportSessionIntentDecline()`, completion polling, and saved-payment lookup. |
 | `createCheckoutSession(options)` | Creates a checkout session and redirects. Returns `CheckoutSessionResult`. |
 | `createCheckoutSessionWithRetries(options)` | Same as above with automatic retries (default 3, exponential backoff). |
 
@@ -282,12 +288,10 @@ The same default-on behavior and boolean opt-out apply to direct `FloPay`,
 |--------|---------|-------------|
 | `elements(options?)` | `FloPayElements` | Creates a new elements group. Destroys previous group. |
 | `submitElements()` | `Promise<{ error? }>` | Validates all mounted elements |
-| `createPaymentMethod()` | `Promise<CreatePaymentMethodResult>` | Tokenizes card fields into a `pm_xxx` ID. Auto-detects split fields vs unified PaymentElement. |
-| `confirmCardPayment(params)` | `Promise<ConfirmCardPaymentResult>` | Confirms with `clientSecret` + `paymentMethodId`. Handles 3DS. |
 | `cardCapture(options?)` | `CardCaptureAdapter` | Creates a hosted vault card-widget adapter (`PciVaultCardCapture`). See [Vault card capture](#vault-card-capture). |
-| `confirmPayment(params)` | `Promise<PaymentResult>` | Confirms using mounted elements + `clientSecret` |
-| `confirmPayPalPayment(params)` | `Promise<ConfirmCardPaymentResult>` | Full PayPal flow: create PM -> create intent -> confirm/redirect |
-| `resumePayPalPayment()` | `Promise<ConfirmCardPaymentResult \| null>` | Resumes after PayPal redirect. Returns `null` if no PayPal params in URL. |
+| `confirmPayment(params)` | `Promise<PaymentResult>` | Confirms a mounted wallet/APM using `clientSecret`, `paymentMethodCategory`, and `paymentMethodType`; rejects `card`. |
+| `confirmPayPalPayment(params)` | `Promise<PayPalPaymentResult>` | Stripe-hosted PayPal flow through the nonce-protected session intent contract, followed by confirmation/redirect. |
+| `resumePayPalPayment()` | `Promise<PayPalPaymentResult \| null>` | Resumes after PayPal redirect. Returns `null` if no PayPal params in URL. |
 | `retrieveSession(sessionId, billingApiUrl?)` | `Promise<CheckoutSession>` | Retrieves a checkout session by ID via `GET /v1/checkouts/sessions/{id}`. Uses `billingApiUrl` from config or the optional second argument. |
 | `retrieveUnifiedSession(sessionId, billingApiUrl?)` | `Promise<NormalizedCheckoutSession>` | Retrieves and normalizes a checkout session, including provider-specific data (Stripe `clientSecret`/`publishableKey`, etc.). |
 | `getRawProvider()` | `unknown` | Returns the raw underlying provider instance (e.g. Stripe object) |
@@ -295,26 +299,22 @@ The same default-on behavior and boolean opt-out apply to direct `FloPay`,
 
 ### Supported Element Types
 
-- `payment` -- Unified PaymentElement (cards, wallets, etc.)
-- `card` -- Combined card input (number + expiry + CVC)
-- `cardNumber` -- Card number field (for split card forms)
-- `cardExpiry` -- Card expiry field
-- `cardCvc` -- Card CVC field
+- `payment` -- Provider PaymentElement for supported non-card methods
 - `address` -- Address input element
 
 ### Vault card capture
 
 `flopay.cardCapture()` returns a `CardCaptureAdapter` that injects a
-**backend-served, self-contained hosted vault widget** in place of provider-owned
-(Stripe) card fields (TeamFloPay/backend#823, Model A). The widget owns the PCI
+**backend-served, self-contained hosted vault widget**
+(TeamFloPay/backend#823, Model A). The widget owns the PCI
 card fields, its own submit button, card tokenization, the PaymentIntent (created
 **and** confirmed server-side), **3DS**, and the result — so **no Stripe.js runs
 on the card path** and PAN / CVC never enter the SDK runtime. The SDK's only job
 is to inject the widget HTML and relay its terminal `postMessage` outcome.
 
 ```ts
-// 1. Obtain the vault capture block — embedded on the create-session response
-//    (session.vault) for SDKs ≥ 1.3.0, or fetched explicitly. The first
+// 1. Obtain the vault capture block — normally embedded on every card-capable
+//    create/read response, or fetched through the explicit recovery route. The first
 //    argument is the checkout session id (`getVaultCapture(checkoutSessionId, nonce?)`):
 const { html, messageToken, expectedOrigin } =
   await new PaymentAPI(billingApiUrl).getVaultCapture(checkoutSessionId, nonce);
@@ -338,7 +338,7 @@ adapter rejects terminal `complete` / `decline` outcomes that are not bound to
 the mounted `sessionId`, that mismatch the mounted `messageToken` (when one was
 supplied), or that arrive from a non-matching `expectedOrigin` (when set).
 
-> Backend contract: TeamFloPay/backend#823. The SDK declares
-> `X-Flo-SDK-Version: 1.3.0` (`FLO_SDK_VERSION_HEADER`) on `POST /v1/checkouts/sessions`
-> so the backend embeds the `vault` block; otherwise it fetches the widget via
-> `PaymentAPI.getVaultCapture()` (`POST /v1/checkouts/sessions/{id}/vault/capture`).
+> Backend contract: TeamFloPay/backend#823. Card-capable session create/read
+> responses include the `vault` block without SDK-version dispatch.
+> `PaymentAPI.getVaultCapture()` keeps
+> `POST /v1/checkouts/sessions/{id}/vault/capture` available for recovery/retry.