@flopay/react 1.3.0 → 1.3.2

package/README.md

@@ -464,6 +464,53 @@ The `SplitCardForm` layout:
 6. Full Name input
 7. Submit button
 
+#### AVS postcode validation
+
+When AVS collection is enabled (`enableAVS`) and the postcode field is shown,
+`SplitCardForm` validates the postcode **format against the live selected
+country before the card is captured**, on both the Stripe and vault card paths.
+It reuses `@flopay/shared`'s country-aware
+[postcode helpers](../shared/README.md#postal-code-helpers) (the same
+`validator` rules the billing API applies), so client and server agree.
+
+- **Supported country + malformed postcode** → the submit is blocked (the vault
+  widget's submit button is gated; the Stripe path returns before tokenizing)
+  and an inline, country-specific message shows the expected format
+  (e.g. *"Enter a valid ZIP Code (e.g. 12345 or 12345-6789)"*). On the vault
+  path the inline message appears once the field is blurred, since the disabled
+  submit means it can't be reached by a submit attempt.
+- **Supported country + empty postcode** → the same submit gate applies, and
+  once the field is blurred (or a submit is attempted) an inline *required*
+  message shows (e.g. *"ZIP Code is required"*) rather than the expected-format
+  copy.
+- **Country with no postal system** (or a locale `validator` doesn't recognise)
+  → 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 {
@@ -1447,6 +1450,18 @@ function getButtonMethodLabel(method) {
       return "Card";
   }
 }
+function malformedPostcodeMessage(country) {
+  const example = (0, import_shared5.getPostalCodeExample)(country);
+  return `Enter a valid ${(0, import_shared5.getPostalCodeLabel)(country)}${example ? ` (e.g. ${example})` : ""}`;
+}
+function computePostalCodeState(country, zip, visible) {
+  const supported = (0, import_shared5.isPostalCodeSupported)(country);
+  const trimmed = zip.trim();
+  const required = visible && supported;
+  const empty = required && !trimmed;
+  const malformed = required && !!trimmed && !(0, import_shared5.isValidPostalCode)(country, trimmed);
+  return { visible, supported, required, empty, malformed };
+}
 function normalizeBeforeButtonClickError(method, err) {
   return err instanceof import_shared6.FloPayError ? err : new import_shared6.FloPayError(
     err instanceof Error ? err.message : `${getButtonMethodLabel(method)} before-click hook failed.`,
@@ -2679,6 +2694,11 @@ function SplitCardFormInner({
     if (!flopay || !vaultActive || !sessionId) return null;
     return flopay.cardCapture({ sessionId });
   }, [flopay, vaultActive, sessionId]);
+  const postalCodeState = (0, import_react9.useMemo)(() => {
+    const cc = selectedCountry;
+    const visible = avsConfig ? (0, import_shared5.isAVSFieldVisible)(avsConfig.postal_code, cc) : false;
+    return computePostalCodeState(cc, zipCode, visible);
+  }, [avsConfig, selectedCountry, zipCode]);
   const { avsInvalid, invalidAvsFields } = (0, import_react9.useMemo)(() => {
     const none = { line1: false, city: false, state: false, zip: false };
     if (!vaultActive || !avsConfig) return { avsInvalid: false, invalidAvsFields: none };
@@ -2688,12 +2708,15 @@ function SplitCardFormInner({
       line1: isEmpty(avsConfig.address_line_1, addressLine1),
       city: isEmpty(avsConfig.city, city),
       state: isEmpty(avsConfig.state, stateValue),
-      zip: isEmpty(avsConfig.postal_code, zipCode)
+      // Empty (required) or malformed both block; unsupported/no-postcode
+      // locales never block (`postalCodeState` fails open above).
+      zip: postalCodeState.empty || postalCodeState.malformed
     };
     const avsInvalid2 = invalidAvsFields2.line1 || invalidAvsFields2.city || invalidAvsFields2.state || invalidAvsFields2.zip;
     return { avsInvalid: avsInvalid2, invalidAvsFields: invalidAvsFields2 };
-  }, [vaultActive, avsConfig, selectedCountry, addressLine1, city, stateValue, zipCode]);
+  }, [vaultActive, avsConfig, selectedCountry, addressLine1, city, stateValue, postalCodeState]);
   const [hasAttemptedSubmit, setHasAttemptedSubmit] = (0, import_react9.useState)(false);
+  const [zipTouched, setZipTouched] = (0, import_react9.useState)(false);
   const [vaultMount, setVaultMount] = (0, import_react9.useState)(
     () => toVaultMount(session?.vault)
   );
@@ -2846,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);
@@ -2903,73 +2922,118 @@ function SplitCardFormInner({
     nonce,
     updateError
   ]);
+  const vaultOutcomeRef = (0, import_react9.useRef)({
+    onComplete,
+    onError,
+    updateError,
+    emitDecline,
+    resolvedAccount,
+    fullName,
+    avsConfig,
+    avsCheckProp,
+    sessionId,
+    nonce,
+    baseUrl
+  });
+  vaultOutcomeRef.current = {
+    onComplete,
+    onError,
+    updateError,
+    emitDecline,
+    resolvedAccount,
+    fullName,
+    avsConfig,
+    avsCheckProp,
+    sessionId,
+    nonce,
+    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;
     let cancelled = false;
     const offSubmitting = cardCapture.on("submitting", () => {
       setHasAttemptedSubmit(true);
       setOverlayStatus("processing");
-      if (!sessionId || !nonce) return;
-      const cc = selectedCountryRef.current || resolvedAccount.country || "US";
-      const stateVisible = avsConfig ? (0, import_shared5.isAVSFieldVisible)(avsConfig.state, cc) : false;
-      const line1Visible = avsConfig ? (0, import_shared5.isAVSFieldVisible)(avsConfig.address_line_1, cc) : false;
-      const zipVisible = avsConfig ? (0, import_shared5.isAVSFieldVisible)(avsConfig.postal_code, cc) : false;
-      const cityVisible = avsConfig ? (0, import_shared5.isAVSFieldVisible)(avsConfig.city, cc) : false;
-      const line2Visible = avsConfig ? (0, import_shared5.isAVSFieldVisible)(avsConfig.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(baseUrl).patchAccountSnapshot(sessionId, nonce, {
-        accountData: {
-          userId: resolvedAccount.userId ?? "",
-          email: resolvedAccount.email ?? "",
-          firstName: resolvedAccount.firstName ?? fullName.trim().split(/\s+/)[0] ?? "",
-          lastName: resolvedAccount.lastName ?? fullName.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
-        },
-        ...avsCheckProp !== void 0 ? { avsCheck: avsCheckProp } : {},
-        ...avsConfig ? {
-          avsConfig: {
-            country: (0, import_shared5.isAVSFieldVisible)(avsConfig.country, cc),
-            postal_code: zipVisible,
-            address_line_1: line1Visible,
-            address_line_2: line2Visible,
-            city: cityVisible,
-            state: stateVisible
-          }
-        } : {}
-      }).catch(() => {
+      const { baseUrl: baseUrl2, sessionId: sessionId2, nonce: nonce2, updateError: updateError2, onError: onError2 } = vaultOutcomeRef.current;
+      if (!sessionId2 || !nonce2) return;
+      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) => {
-      markSessionRecentlyCompleted(event.sessionId ?? sessionId);
+      markSessionRecentlyCompleted(event.sessionId ?? vaultOutcomeRef.current.sessionId);
       setOverlayStatus("success");
       await new Promise((r) => setTimeout(r, PROCESSING_OVERLAY_SUCCESS_DELAY_MS));
-      if (cancelled) return;
-      onComplete?.({
+      if (vaultCompletedRef.current) return;
+      vaultCompletedRef.current = true;
+      vaultOutcomeRef.current.onComplete?.({
         status: "succeeded",
         paymentIntentId: event.intentId,
         checkoutMethod: "card"
       });
     });
     const offDecline = cardCapture.on("decline", async (event) => {
+      const { updateError: updateError2, emitDecline: emitDecline2 } = vaultOutcomeRef.current;
       const message = event.message ?? "Your payment was declined. Please try another card or contact your bank.";
-      updateError(message);
+      updateError2(message);
       setOverlayStatus("error");
-      emitDecline("card", message, event.declineReason ? { declineCode: event.declineReason } : void 0);
+      emitDecline2("card", message, event.declineReason ? { declineCode: event.declineReason } : void 0);
       await new Promise((r) => setTimeout(r, PROCESSING_OVERLAY_ERROR_DELAY_MS));
       if (cancelled) return;
       setOverlayStatus(null);
     });
     const offError = cardCapture.on("error", async (event) => {
+      const { updateError: updateError2, onError: onError2 } = vaultOutcomeRef.current;
       const message = event.message ?? "There was a problem processing your payment. Please try again.";
-      updateError(message);
+      updateError2(message);
       setOverlayStatus("error");
-      onError?.(new import_shared6.FloPayError(message, "api_error"));
+      onError2?.(new import_shared6.FloPayError(message, "api_error"));
       await new Promise((r) => setTimeout(r, PROCESSING_OVERLAY_ERROR_DELAY_MS));
       if (cancelled) return;
       setOverlayStatus(null);
@@ -2981,25 +3045,7 @@ function SplitCardFormInner({
       offDecline();
       offError();
     };
-  }, [
-    vaultActive,
-    cardCapture,
-    sessionId,
-    nonce,
-    baseUrl,
-    avsConfig,
-    avsCheckProp,
-    resolvedAccount.userId,
-    resolvedAccount.email,
-    resolvedAccount.firstName,
-    resolvedAccount.lastName,
-    resolvedAccount.country,
-    fullName,
-    onComplete,
-    onError,
-    updateError,
-    emitDecline
-  ]);
+  }, [vaultActive, cardCapture]);
   const directPaypalConfigured = !!directPaypal?.clientId;
   const hasEnabledMethodsPayload = Array.isArray(enabledPaymentMethods);
   const hasEnabledMethods = hasEnabledMethodsPayload && enabledPaymentMethods.length > 0;
@@ -3187,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,
@@ -3501,10 +3547,21 @@ function SplitCardFormInner({
       try {
         if (avsConfig) {
           const country = selectedCountryRef.current;
-          if ((0, import_shared5.isAVSFieldVisible)(avsConfig.postal_code, country) && !zipCodeRef.current.trim()) {
+          const postal = computePostalCodeState(
+            country,
+            zipCodeRef.current,
+            (0, import_shared5.isAVSFieldVisible)(avsConfig.postal_code, country)
+          );
+          if (postal.empty) {
+            setZipTouched(true);
             updateError((0, import_shared5.getPostalCodeLabel)(country) + " is required");
             return;
           }
+          if (postal.malformed) {
+            setZipTouched(true);
+            updateError(malformedPostcodeMessage(country));
+            return;
+          }
           if ((0, import_shared5.isAVSFieldVisible)(avsConfig.address_line_1, country) && !addressLine1Ref.current.trim()) {
             updateError("Street address is required");
             return;
@@ -3645,6 +3702,8 @@ function SplitCardFormInner({
   const resolvedBorder = bStyles.cardInputBorder ?? (isButtons ? "#e5e7eb" : "#A4A4FF");
   const resolvedDangerColor = appearanceVars?.colorDanger ?? "#dc2626";
   const avsBorderColor = (fieldInvalid) => hasAttemptedSubmit && fieldInvalid ? resolvedDangerColor : resolvedBorder;
+  const showPostcodeError = (postalCodeState.malformed || postalCodeState.empty) && (zipTouched || hasAttemptedSubmit);
+  const zipBorderColor = showPostcodeError ? resolvedDangerColor : avsBorderColor(invalidAvsFields.zip);
   const cardBg = bStyles.cardFormContainer?.backgroundColor ?? themedWrapperBg ?? (isButtons ? "white" : "#EDEDFF");
   const cardInputBg = bStyles.cardInputBackground ?? appearanceVars?.colorBackground ?? "white";
   const hideBackButtonLabel = isEmptySlotContent(cardBackButtonContent);
@@ -4074,7 +4133,7 @@ function SplitCardFormInner({
           (0, import_shared5.isAVSFieldVisible)(avsConfig.postal_code, cc) && /* @__PURE__ */ (0, import_jsx_runtime7.jsx)("div", { style: {
             flex: avsLayoutProp === "row" ? 1 : void 0,
             backgroundColor: cardInputBg,
-            border: `1px solid ${avsBorderColor(invalidAvsFields.zip)}`,
+            border: `1px solid ${zipBorderColor}`,
             padding: "10px",
             ...avsLayoutProp === "row" && (0, import_shared5.isAVSFieldVisible)(avsConfig.country, cc) ? { borderRadius: "0", borderTopRightRadius: resolvedBorderRadius, borderBottomRightRadius: resolvedBorderRadius } : { borderRadius: resolvedBorderRadius }
           }, children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(
@@ -4091,13 +4150,31 @@ function SplitCardFormInner({
                 setZipCode(e.target.value);
                 onZipChange?.(e.target.value);
               },
+              onBlur: () => setZipTouched(true),
               disabled: isSubmitting,
-              required: true,
+              required: postalCodeState.required,
+              "aria-invalid": showPostcodeError || void 0,
+              "aria-describedby": showPostcodeError ? "flopay-billing-postal-code-error" : void 0,
               "data-testid": "flopay-zip",
               style: inputFieldStyle()
             }
           ) })
-        ] })
+        ] }),
+        showPostcodeError && /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(
+          "div",
+          {
+            id: "flopay-billing-postal-code-error",
+            role: "alert",
+            "data-testid": "flopay-zip-error",
+            style: {
+              marginTop: "0.375rem",
+              color: resolvedDangerColor,
+              ...sharedInputTypography,
+              fontSize: "0.75rem"
+            },
+            children: postalCodeState.empty ? `${(0, import_shared5.getPostalCodeLabel)(cc)} is required` : malformedPostcodeMessage(cc)
+          }
+        )
       ] });
     })() }),
     vaultActive && cardPreFormSlot && /* @__PURE__ */ (0, import_jsx_runtime7.jsx)("div", { style: { order: -2, width: "100%" }, children: cardPreFormSlot }),