@flopay/react 1.3.1 → 1.3.3

package/README.md

@@ -329,6 +329,33 @@ Skip the backend API route — create the session directly in the component:
 
 The component POSTs to the billing API, gets the full session back, and renders the form — zero backend code needed.
 
+That create POST sends a stable `Idempotency-Key` header automatically whenever a
+secure RNG is available, so a timeout or lost response never mints a second
+session. `FloPayCheckout` already coalesces concurrent mounts (StrictMode
+double-mount, Suspense remount, navigation flicker) into a single create, and
+rerenders during an in-flight create do **not** replace the key. You normally
+don't need to think about it.
+
+To control the key yourself — for example to keep it stable across your own
+server retries — pass `idempotencyKey` on `createSession`:
+
+```tsx
+<FloPayCheckout
+  createSession={{
+    /* … */
+    idempotencyKey: `checkout:${orderId}`, // one logical checkout; never reuse for a new purchase
+  }}
+/>
+```
+
+The key must be non-empty and at most 255 characters; an invalid value throws a
+`FloPayError('validation_error')` before any request. Omit it and the SDK
+generates a fresh cryptographically random key per logical create when a secure
+RNG is available; without one it omits the header, and a merchant-supplied
+`idempotencyKey` stays the way to remain idempotent. See the
+[`@flopay/js` idempotency docs](../js/README.md#idempotent-checkout-creation)
+for the full contract.
+
 Session-level `currency` is now **required**. The backend (#760) enforces `@IsNotEmpty` on the field; the SDK pre-validates and throws `FloPayError({ type: 'validation_error', code: 'CurrencyRequired' })` before issuing the request when neither the session nor any item/subscription/product carries a currency. Pass `currency` at the top of `createSession` (preferred), or rely on the legacy fallback to the first item/subscription/product `currency`.
 
 When you use `onBeforeButtonClick` with `createSession`, any returned `InlineSessionPatch` is merged into the draft session params before the selected buttons-layout flow continues. That lets you add tracking data or update account fields just in time without pre-creating a separate backend session.
@@ -487,6 +514,30 @@ It reuses `@flopay/shared`'s country-aware
   → the postcode field is shown but **optional**: empty and format checks are
   both skipped, so these buyers are never blocked.
 
+On the **vault card path** the widget's submit button is gated **synchronously**
+on the client-side AVS check above. Because the client postcode rules mirror the
+backend validator (`validator@13.15.35`) verbatim, a postcode the server's
+`PATCH /v1/checkouts/sessions/{id}/account` would reject is already blocked here —
+before the button ever enables — with no network round-trip in the critical path.
+The gate is **never** held pending an async request: the hosted widget silently
+swallows a click that lands while the button is disabled and offers no way to
+auto-resubmit on release, so an async gate would strand any buyer (or single-click
+preview) who clicked before it resolved — the checkout would write no attempt and
+time out (sdk#124).
+
+When the buyer submits, `SplitCardForm` persists the billing snapshot
+best-effort **in parallel** with the widget's charge:
+
+- **Backend rejects the address (a `4xx`)** — a residual, non-postcode drift, since
+  the postcode is already client-validated — the specific message (e.g. *"Postal/ZIP
+  code is not valid for the selected country…"*) shows inline **and** fires `onError`
+  with the parsed `FloPayError`, and the processing overlay clears so the buyer can
+  correct and retry. The charge cannot be cancelled once submitted, so this surfaces
+  for the buyer's *next* attempt rather than stopping the in-flight one.
+- **Transient failure (`5xx` / network)** → best-effort and silent: the backend
+  listener falls back to the session's baseline address while the widget completes
+  the charge.
+
 ### Vault PCI card form
 
 When the billing API returns a hosted vault card form on the session

package/dist/index.cjs

@@ -1365,6 +1365,9 @@ var import_jsx_runtime7 = require("react/jsx-runtime");
 var STRIPE_RESUME_KEY = "flopay_stripe_resume";
 var LEGACY_WALLET_RESUME_KEY = "flopay_wallet_resume";
 var PAYPAL_RESUME_KEY = "flopay_paypal_resume";
+function isAccountValidationError(err) {
+  return err instanceof import_shared6.FloPayError && typeof err.statusCode === "number" && err.statusCode >= 400 && err.statusCode < 500;
+}
 function toVaultMount(block) {
   if (!block?.html) return null;
   return {
@@ -2866,10 +2869,6 @@ function SplitCardFormInner({
     },
     [onErrorChange]
   );
-  (0, import_react9.useEffect)(() => {
-    if (!vaultActive || !cardCapture) return;
-    cardCapture.setSubmitGate?.(avsInvalid);
-  }, [vaultActive, cardCapture, avsInvalid]);
   (0, import_react9.useEffect)(() => {
     if (!vaultActive || !cardCapture) return;
     cardCapture.setCardFieldOrder?.(cardFieldOrder ?? null, avsConfig == null);
@@ -2950,6 +2949,46 @@ function SplitCardFormInner({
     baseUrl
   };
   const vaultCompletedRef = (0, import_react9.useRef)(false);
+  const buildVaultAccountSnapshot = (0, import_react9.useCallback)(() => {
+    const { resolvedAccount: resolvedAccount2, avsConfig: avsConfig2, fullName: fullName2, avsCheckProp: avsCheckProp2 } = vaultOutcomeRef.current;
+    const cc = selectedCountryRef.current || resolvedAccount2.country || "US";
+    const stateVisible = avsConfig2 ? (0, import_shared5.isAVSFieldVisible)(avsConfig2.state, cc) : false;
+    const line1Visible = avsConfig2 ? (0, import_shared5.isAVSFieldVisible)(avsConfig2.address_line_1, cc) : false;
+    const zipVisible = avsConfig2 ? (0, import_shared5.isAVSFieldVisible)(avsConfig2.postal_code, cc) : false;
+    const cityVisible = avsConfig2 ? (0, import_shared5.isAVSFieldVisible)(avsConfig2.city, cc) : false;
+    const line2Visible = avsConfig2 ? (0, import_shared5.isAVSFieldVisible)(avsConfig2.address_line_2, cc) : false;
+    const derivedState = line1Visible && !stateVisible && zipVisible ? (0, import_shared5.getStateFromPostalCode)(cc, (zipCodeRef.current ?? "").trim()) : null;
+    const stateValue2 = stateVisible ? stateRef.current : derivedState;
+    return {
+      accountData: {
+        userId: resolvedAccount2.userId ?? "",
+        email: resolvedAccount2.email ?? "",
+        firstName: resolvedAccount2.firstName ?? fullName2.trim().split(/\s+/)[0] ?? "",
+        lastName: resolvedAccount2.lastName ?? fullName2.trim().split(/\s+/).slice(1).join(" ") ?? "",
+        ...zipVisible && zipCodeRef.current ? { zip: zipCodeRef.current } : {},
+        ...cityVisible && cityRef.current ? { city: cityRef.current } : {},
+        ...stateValue2 ? { state: stateValue2 } : {},
+        ...line1Visible && addressLine1Ref.current ? { addressLine1: addressLine1Ref.current } : {},
+        ...line2Visible && addressLine2Ref.current ? { addressLine2: addressLine2Ref.current } : {},
+        country: cc
+      },
+      ...avsCheckProp2 !== void 0 ? { avsCheck: avsCheckProp2 } : {},
+      ...avsConfig2 ? {
+        avsConfig: {
+          country: (0, import_shared5.isAVSFieldVisible)(avsConfig2.country, cc),
+          postal_code: zipVisible,
+          address_line_1: line1Visible,
+          address_line_2: line2Visible,
+          city: cityVisible,
+          state: stateVisible
+        }
+      } : {}
+    };
+  }, []);
+  (0, import_react9.useEffect)(() => {
+    if (!vaultActive || !cardCapture) return;
+    cardCapture.setSubmitGate?.(avsInvalid);
+  }, [vaultActive, cardCapture, avsInvalid]);
   (0, import_react9.useEffect)(() => {
     if (!vaultActive || !cardCapture) return;
     vaultCompletedRef.current = false;
@@ -2957,41 +2996,14 @@ function SplitCardFormInner({
     const offSubmitting = cardCapture.on("submitting", () => {
       setHasAttemptedSubmit(true);
       setOverlayStatus("processing");
-      const { resolvedAccount: resolvedAccount2, avsConfig: avsConfig2, fullName: fullName2, avsCheckProp: avsCheckProp2, baseUrl: baseUrl2, sessionId: sessionId2, nonce: nonce2 } = vaultOutcomeRef.current;
+      const { baseUrl: baseUrl2, sessionId: sessionId2, nonce: nonce2, updateError: updateError2, onError: onError2 } = vaultOutcomeRef.current;
       if (!sessionId2 || !nonce2) return;
-      const cc = selectedCountryRef.current || resolvedAccount2.country || "US";
-      const stateVisible = avsConfig2 ? (0, import_shared5.isAVSFieldVisible)(avsConfig2.state, cc) : false;
-      const line1Visible = avsConfig2 ? (0, import_shared5.isAVSFieldVisible)(avsConfig2.address_line_1, cc) : false;
-      const zipVisible = avsConfig2 ? (0, import_shared5.isAVSFieldVisible)(avsConfig2.postal_code, cc) : false;
-      const cityVisible = avsConfig2 ? (0, import_shared5.isAVSFieldVisible)(avsConfig2.city, cc) : false;
-      const line2Visible = avsConfig2 ? (0, import_shared5.isAVSFieldVisible)(avsConfig2.address_line_2, cc) : false;
-      const derivedState = line1Visible && !stateVisible && zipVisible ? (0, import_shared5.getStateFromPostalCode)(cc, zipCodeRef.current ?? "") : null;
-      const stateValue2 = stateVisible ? stateRef.current : derivedState;
-      void new import_js2.PaymentAPI(baseUrl2).patchAccountSnapshot(sessionId2, nonce2, {
-        accountData: {
-          userId: resolvedAccount2.userId ?? "",
-          email: resolvedAccount2.email ?? "",
-          firstName: resolvedAccount2.firstName ?? fullName2.trim().split(/\s+/)[0] ?? "",
-          lastName: resolvedAccount2.lastName ?? fullName2.trim().split(/\s+/).slice(1).join(" ") ?? "",
-          ...zipVisible && zipCodeRef.current ? { zip: zipCodeRef.current } : {},
-          ...cityVisible && cityRef.current ? { city: cityRef.current } : {},
-          ...stateValue2 ? { state: stateValue2 } : {},
-          ...line1Visible && addressLine1Ref.current ? { addressLine1: addressLine1Ref.current } : {},
-          ...line2Visible && addressLine2Ref.current ? { addressLine2: addressLine2Ref.current } : {},
-          country: cc
-        },
-        ...avsCheckProp2 !== void 0 ? { avsCheck: avsCheckProp2 } : {},
-        ...avsConfig2 ? {
-          avsConfig: {
-            country: (0, import_shared5.isAVSFieldVisible)(avsConfig2.country, cc),
-            postal_code: zipVisible,
-            address_line_1: line1Visible,
-            address_line_2: line2Visible,
-            city: cityVisible,
-            state: stateVisible
-          }
-        } : {}
-      }).catch(() => {
+      void new import_js2.PaymentAPI(baseUrl2).patchAccountSnapshot(sessionId2, nonce2, buildVaultAccountSnapshot()).catch((err) => {
+        if (!isAccountValidationError(err)) return;
+        const message = err instanceof Error ? err.message : "Please check your billing address and try again.";
+        updateError2(message);
+        setOverlayStatus(null);
+        onError2?.(err instanceof import_shared6.FloPayError ? err : new import_shared6.FloPayError(message, "api_error"));
       });
     });
     const offComplete = cardCapture.on("complete", async (event) => {
@@ -3221,7 +3233,7 @@ function SplitCardFormInner({
               const stateVisible = (0, import_shared5.isAVSFieldVisible)(avsConfig.state, c);
               const line1Visible = (0, import_shared5.isAVSFieldVisible)(avsConfig.address_line_1, c);
               const zipVisible = (0, import_shared5.isAVSFieldVisible)(avsConfig.postal_code, c);
-              const derivedState = line1Visible && !stateVisible && zipVisible ? (0, import_shared5.getStateFromPostalCode)(c, zipCodeRef.current ?? "") : null;
+              const derivedState = line1Visible && !stateVisible && zipVisible ? (0, import_shared5.getStateFromPostalCode)(c, (zipCodeRef.current ?? "").trim()) : null;
               const stateValue2 = stateVisible ? stateRef.current : derivedState;
               return {
                 country: c,