@flopay/react 1.3.0 → 1.3.1

package/README.md

@@ -464,6 +464,29 @@ 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.
+
 ### Vault PCI card form
 
 When the billing API returns a hosted vault card form on the session

package/dist/index.cjs

@@ -1447,6 +1447,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 +2691,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 +2705,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)
   );
@@ -2903,27 +2923,56 @@ 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);
   (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 { resolvedAccount: resolvedAccount2, avsConfig: avsConfig2, fullName: fullName2, avsCheckProp: avsCheckProp2, baseUrl: baseUrl2, sessionId: sessionId2, nonce: nonce2 } = 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(baseUrl).patchAccountSnapshot(sessionId, nonce, {
+      void new import_js2.PaymentAPI(baseUrl2).patchAccountSnapshot(sessionId2, nonce2, {
         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(" ") ?? "",
+          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 } : {},
@@ -2931,10 +2980,10 @@ function SplitCardFormInner({
           ...line2Visible && addressLine2Ref.current ? { addressLine2: addressLine2Ref.current } : {},
           country: cc
         },
-        ...avsCheckProp !== void 0 ? { avsCheck: avsCheckProp } : {},
-        ...avsConfig ? {
+        ...avsCheckProp2 !== void 0 ? { avsCheck: avsCheckProp2 } : {},
+        ...avsConfig2 ? {
           avsConfig: {
-            country: (0, import_shared5.isAVSFieldVisible)(avsConfig.country, cc),
+            country: (0, import_shared5.isAVSFieldVisible)(avsConfig2.country, cc),
             postal_code: zipVisible,
             address_line_1: line1Visible,
             address_line_2: line2Visible,
@@ -2946,30 +2995,33 @@ function SplitCardFormInner({
       });
     });
     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 +3033,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;
@@ -3501,10 +3535,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 +3690,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 +4121,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 +4138,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 }),