@flopay/react 0.3.14 → 0.3.17

package/README.md

@@ -131,14 +131,16 @@ Use `onButtonClick` to track button interactions, `onDecline` to track declines/
   createSession={{
     clientId: 'your-client-id',
     items: [{ providerItemId: 'product-1', providerItemName: 'Widget', totalAmount: 29.99, currency: 'EUR' }],
-    account: { userId: 'user_1' },
+    account: { userId: 'user_1', email: 'test@email.com' },
     successUrl: '/success',
     cancelUrl: '/cancel',
   }}
-  onBeforeButtonClick={async ({ method }) => {
+  onBeforeButtonClick={async ({ method, createSession }) => {
     if (method !== 'card') return;
 
-    const email = await openEmailCaptureModal();
+    const email = await openEmailCaptureModal({
+      initialEmail: createSession?.account.email ?? '',
+    });
     if (!email) return false;
 
     return {
@@ -178,7 +180,7 @@ 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.
 
-When you use `onBeforeButtonClick`, `createSession.account.email` can be filled in later for the card-button flow. PayPal and wallets still need all required data before they render.
+When you use `onBeforeButtonClick`, `createSession.account.email` should still be present when checkout renders. If you only have a temporary address such as `test@email.com`, pass it first and replace it in `onBeforeButtonClick` before the card flow continues. PayPal and wallet buttons still bootstrap normally, but this hook does not run for them, so collect any data those methods require before the user uses them.
 
 ### Advanced: Manual Provider Setup
 

package/dist/index.cjs

@@ -351,15 +351,6 @@ function buildSyntheticSession(params, checkoutModeOverride) {
     }))
   };
 }
-function ensureInlineSessionReady(params) {
-  if (!params.account.email?.trim()) {
-    throw new import_shared3.FloPayError(
-      "Email is required before continuing with card checkout.",
-      "validation_error",
-      { param: "createSession.account.email" }
-    );
-  }
-}
 function mergeAccountPatch(base, patch) {
   if (!patch) return base;
   return {
@@ -414,6 +405,52 @@ function toCssWeight(value) {
   if (typeof value === "number" || typeof value === "string") return value;
   return void 0;
 }
+function resolveExpressCheckoutLoadState(event, methods) {
+  const available = event.availablePaymentMethods;
+  if (!available) return "unavailable";
+  return methods.some((method) => available[method]) ? "ready" : "unavailable";
+}
+function ExpressCheckoutReadySwap({
+  state,
+  placeholderTestId,
+  children
+}) {
+  if (state === "unavailable") return null;
+  return /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)("div", { style: { position: "relative", minHeight: 44 }, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
+      "div",
+      {
+        "data-testid": placeholderTestId,
+        "aria-hidden": state === "ready",
+        style: {
+          position: "absolute",
+          inset: 0,
+          height: 44,
+          borderRadius: 8,
+          background: "#e5e7eb",
+          animation: state === "ready" ? void 0 : "flopay-pulse 1.5s ease-in-out infinite",
+          opacity: state === "ready" ? 0 : 1,
+          transform: state === "ready" ? "scale(0.985)" : "scale(1)",
+          transition: "opacity 140ms ease-out, transform 140ms ease-out",
+          pointerEvents: "none"
+        }
+      }
+    ),
+    /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
+      "div",
+      {
+        style: {
+          minHeight: 44,
+          opacity: state === "ready" ? 1 : 0,
+          transform: state === "ready" ? "translateY(0)" : "translateY(2px)",
+          transition: "opacity 140ms ease-out, transform 140ms ease-out",
+          pointerEvents: state === "ready" ? "auto" : "none"
+        },
+        children
+      }
+    )
+  ] });
+}
 function ProcessingOverlay({ status, errorMessage }) {
   return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("div", { style: {
     position: "fixed",
@@ -531,7 +568,7 @@ function PayPalButtonInner({
 }) {
   const stripe = (0, import_react_stripe_js.useStripe)();
   const elements = (0, import_react_stripe_js.useElements)();
-  const [ready, setReady] = (0, import_react6.useState)(false);
+  const [loadState, setLoadState] = (0, import_react6.useState)("loading");
   const [submitting, setSubmitting] = (0, import_react6.useState)(false);
   const paypalResumeAttempted = (0, import_react6.useRef)(false);
   const baseUrl = billingApiUrl.replace(/\/+$/, "");
@@ -643,12 +680,11 @@ function PayPalButtonInner({
     }
   }, [stripe, elements, sessionId, email, baseUrl, onTokenizedBody, onErrorChange, onDecline]);
   return /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)(import_jsx_runtime4.Fragment, { children: [
-    /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("div", { children: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
+    /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(ExpressCheckoutReadySwap, { state: loadState, placeholderTestId: "flopay-paypal-placeholder", children: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
       import_react_stripe_js.ExpressCheckoutElement,
       {
-        onReady: () => setReady(true),
-        onLoadError: () => {
-        },
+        onReady: (event) => setLoadState(resolveExpressCheckoutLoadState(event, ["paypal"])),
+        onLoadError: () => setLoadState("unavailable"),
         onConfirm: handlePayPalConfirm,
         onCancel: () => {
           onDecline?.(buildDeclineEvent("paypal", "PayPal checkout was cancelled."));
@@ -680,7 +716,7 @@ function WalletButtonInner({
 }) {
   const stripe = (0, import_react_stripe_js.useStripe)();
   const elements = (0, import_react_stripe_js.useElements)();
-  const [ready, setReady] = (0, import_react6.useState)(false);
+  const [loadState, setLoadState] = (0, import_react6.useState)("loading");
   const [submitting, setSubmitting] = (0, import_react6.useState)(false);
   const baseUrl = billingApiUrl.replace(/\/+$/, "");
   const lastWalletMethodRef = (0, import_react6.useRef)("card");
@@ -746,12 +782,11 @@ function WalletButtonInner({
     [stripe, elements, sessionId, email, baseUrl, onTokenizedBody, onErrorChange, onDecline]
   );
   return /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)(import_jsx_runtime4.Fragment, { children: [
-    /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("div", { children: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
+    /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(ExpressCheckoutReadySwap, { state: loadState, placeholderTestId: "flopay-wallet-placeholder", children: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
       import_react_stripe_js.ExpressCheckoutElement,
       {
-        onReady: () => setReady(true),
-        onLoadError: () => {
-        },
+        onReady: (event) => setLoadState(resolveExpressCheckoutLoadState(event, ["applePay", "googlePay"])),
+        onLoadError: () => setLoadState("unavailable"),
         onClick: (event) => {
           lastWalletMethodRef.current = event.expressPaymentType === "apple_pay" ? "apple_pay" : "google_pay";
           event.resolve();
@@ -795,6 +830,7 @@ function SplitCardFormInner({
   isProcessing: externalProcessing,
   error: externalError,
   onErrorChange,
+  onFullNameChange,
   onFirstNameChange,
   onLastNameChange,
   showPayPal = true,
@@ -821,6 +857,7 @@ function SplitCardFormInner({
 }) {
   const flopay = useFloPay();
   const elements = useElements();
+  const checkout = (0, import_react6.useContext)(CheckoutContext);
   const contextBillingUrl = useBillingApiUrl();
   const [processing, setProcessing] = (0, import_react6.useState)(false);
   const [error, setError] = (0, import_react6.useState)(null);
@@ -866,7 +903,8 @@ function SplitCardFormInner({
       title: { ...base.title, ...buttonsStylesOverride.title }
     };
   }, [buttonsTheme, buttonsStylesOverride]);
-  const isSubmitting = externalProcessing ?? processing;
+  const isInlineSessionPatchProcessing = checkout.inlineSessionPatchProcessing ?? false;
+  const isSubmitting = (externalProcessing ?? processing) || isInlineSessionPatchProcessing;
   const isSelfContained = !onTokenizedBody;
   const baseUrl = resolvedBillingApiUrl.replace(/\/+$/, "");
   const resolvedAccount = (0, import_react6.useMemo)(() => mergeAccountPatch({
@@ -911,10 +949,11 @@ function SplitCardFormInner({
   const showWallets = showApplePay || showGooglePay;
   const handleNameChange = (0, import_react6.useCallback)((value) => {
     setFullName(value);
+    onFullNameChange?.(value);
     const parts = value.trim().split(/\s+/);
     onFirstNameChange?.(parts[0] ?? "");
     onLastNameChange?.(parts.length > 1 ? parts.slice(1).join(" ") : "");
-  }, [onFirstNameChange, onLastNameChange]);
+  }, [onFullNameChange, onFirstNameChange, onLastNameChange]);
   const runBeforeCardButtonClick = (0, import_react6.useCallback)(async () => {
     if (!onBeforeButtonClick) return true;
     try {
@@ -925,8 +964,11 @@ function SplitCardFormInner({
       if (result === false) {
         return false;
       }
-      if (result?.account) {
-        setAccountPatch((prev) => ({ ...prev ?? {}, ...result.account }));
+      if (result && typeof result === "object") {
+        await checkout.applyInlineSessionPatch?.(result);
+        if (result.account) {
+          setAccountPatch((prev) => ({ ...prev ?? {}, ...result.account }));
+        }
       }
       return true;
     } catch (err) {
@@ -938,7 +980,7 @@ function SplitCardFormInner({
       onError?.(floPayErr);
       return false;
     }
-  }, [onBeforeButtonClick, sessionId, updateError, onError]);
+  }, [checkout.applyInlineSessionPatch, onBeforeButtonClick, sessionId, updateError, onError]);
   const processPaymentInternal = (0, import_react6.useCallback)(
     async (tokenizedBody) => {
       if (processingRef.current) return;
@@ -1547,11 +1589,13 @@ function SplitCardFormInner({
             {
               type: "button",
               onClick: async () => {
+                if (isSubmitting) return;
                 const shouldContinue = await runBeforeCardButtonClick();
                 if (!shouldContinue) return;
                 onButtonClick?.("card");
                 expandToCard();
               },
+              disabled: isSubmitting,
               style: {
                 width: "100%",
                 padding: "0.9rem 1rem",
@@ -1561,7 +1605,7 @@ function SplitCardFormInner({
                 borderRadius: "8px",
                 fontSize: bStyles.cardButtonFontSize ?? "0.95rem",
                 fontWeight: 600,
-                cursor: "pointer",
+                cursor: isSubmitting ? "not-allowed" : "pointer",
                 display: "flex",
                 alignItems: "center",
                 justifyContent: "center",
@@ -1569,6 +1613,7 @@ function SplitCardFormInner({
                 transition: "border-color 0.2s, box-shadow 0.2s, transform 0.1s",
                 boxShadow: "0 1px 2px rgba(0,0,0,0.04)",
                 position: "relative",
+                opacity: isSubmitting ? 0.6 : 1,
                 ...bStyles.cardButton
               },
               onMouseDown: (e) => {
@@ -1652,6 +1697,12 @@ function SplitCardFormInner({
 
 // src/flopay-checkout.tsx
 var import_jsx_runtime5 = require("react/jsx-runtime");
+function hasInlineSessionPatchData(patch) {
+  if (!patch) return false;
+  return Boolean(
+    patch.account && Object.keys(patch.account).length > 0 || patch.couponCodes !== void 0 || patch.tagsData !== void 0 || patch.utmMetadata !== void 0
+  );
+}
 function FloPayCheckout({
   sessionId: sessionIdProp,
   createSession: createSessionParams,
@@ -1664,6 +1715,9 @@ function FloPayCheckout({
   onComplete,
   onError,
   onDecline,
+  onFullNameChange,
+  onCountryChange,
+  onZipChange,
   showPayPal = true,
   showApplePay = true,
   showGooglePay = true,
@@ -1699,7 +1753,6 @@ function FloPayCheckout({
   const [createSessionPatch, setCreateSessionPatch] = (0, import_react7.useState)(void 0);
   const [createSessionPatchBaseHash, setCreateSessionPatchBaseHash] = (0, import_react7.useState)("");
   const [cardBootstrapPending, setCardBootstrapPending] = (0, import_react7.useState)(false);
-  const [deferredCardOpen, setDeferredCardOpen] = (0, import_react7.useState)(false);
   const autoCheckoutAttempted = (0, import_react7.useRef)(false);
   const onCompleteRef = (0, import_react7.useRef)(onComplete);
   onCompleteRef.current = onComplete;
@@ -1834,9 +1887,6 @@ function FloPayCheckout({
   );
   const inflightRef = (0, import_react7.useRef)(/* @__PURE__ */ new Map());
   const initializedHashRef = (0, import_react7.useRef)(null);
-  const deferInlineSessionUntilCardClick = Boolean(
-    effectiveCreateSession && !children && layout === "buttons" && onBeforeButtonClick && (effectiveCreateSession.checkoutMode ?? checkoutModeProp ?? "full") === "full"
-  );
   function hashCreateParams(params) {
     const key = JSON.stringify({
       c: params?.clientId,
@@ -1866,7 +1916,6 @@ function FloPayCheckout({
     setResolvedSessionId(sessionIdProp ?? "");
   }, [sessionIdProp]);
   async function resolveInlineSession(params, cacheKey) {
-    ensureInlineSessionReady(params);
     const api = new import_js.PaymentAPI(resolvedBillingUrl);
     let sid = typeof window !== "undefined" ? window.sessionStorage.getItem(cacheKey) : null;
     let realResult = null;
@@ -1911,104 +1960,64 @@ function FloPayCheckout({
       } finally {
         inflightRef.current.delete(cacheKey);
       }
-      if (patch) {
-        setCreateSessionPatchBaseHash(baseCreateSessionHash);
-        setCreateSessionPatch((prev) => mergeInlineSessionPatches(prev, patch));
-      }
-      const { sid, result: realResult } = resolved;
-      setUnified(realResult);
-      if (realResult.data.session) {
-        setSession(realResult.data.session);
-      }
-      if (sid) {
-        setResolvedSessionId(sid);
-      }
-      let publishableKey;
-      if (realResult.provider === "stripe") {
-        publishableKey = realResult.data.stripe?.publishableKey;
-      }
-      if (!publishableKey) publishableKey = fallbackPublishableKey;
-      if (!publishableKey) {
-        throw new import_shared6.FloPayError(
-          "No publishable key found. Provide fallbackPublishableKey or ensure the session includes gatewayData.publishableKey.",
-          "validation_error"
-        );
-      }
-      const instance = await (0, import_js.loadFloPay)(publishableKey, {
-        billingApiUrl: resolvedBillingUrl,
-        locale
-      });
-      flopayRef.current = instance;
-      setFloPay(instance);
       initializedHashRef.current = cacheKey;
-      setIsLoading(false);
+      try {
+        if (patch) {
+          setCreateSessionPatchBaseHash(baseCreateSessionHash);
+          setCreateSessionPatch((prev) => mergeInlineSessionPatches(prev, patch));
+        }
+        const { sid, result: realResult } = resolved;
+        setUnified(realResult);
+        if (realResult.data.session) {
+          setSession(realResult.data.session);
+        }
+        if (sid) {
+          setResolvedSessionId(sid);
+        }
+        let publishableKey;
+        if (realResult.provider === "stripe") {
+          publishableKey = realResult.data.stripe?.publishableKey;
+        }
+        if (!publishableKey) publishableKey = fallbackPublishableKey;
+        if (!publishableKey) {
+          throw new import_shared6.FloPayError(
+            "No publishable key found. Provide fallbackPublishableKey or ensure the session includes gatewayData.publishableKey.",
+            "validation_error"
+          );
+        }
+        const instance = await (0, import_js.loadFloPay)(publishableKey, {
+          billingApiUrl: resolvedBillingUrl,
+          locale
+        });
+        flopayRef.current = instance;
+        setFloPay(instance);
+        setIsLoading(false);
+      } catch (err) {
+        if (initializedHashRef.current === cacheKey) {
+          initializedHashRef.current = null;
+        }
+        throw err;
+      }
       return resolved;
     },
     [fallbackPublishableKey, locale, resolvedBillingUrl]
   );
-  const handleDeferredCardButtonClick = (0, import_react7.useCallback)(async () => {
-    if (cardBootstrapPending) return;
-    setLoadError(null);
+  const handleInlineSessionPatch = (0, import_react7.useCallback)(async (patch) => {
+    if (!hasInlineSessionPatchData(patch) || cardBootstrapPending) return;
     setCardBootstrapPending(true);
     try {
-      const beforeClickResult = await onBeforeButtonClick?.({
-        method: "card",
-        createSession: effectiveCreateSession
-      });
-      if (beforeClickResult === false) {
-        setDeferredCardOpen(false);
-        return;
-      }
-      const patch = beforeClickResult && typeof beforeClickResult === "object" ? beforeClickResult : void 0;
-      const baseParams = createSessionParamsRef.current;
-      if (!baseParams) {
-        throw new import_shared6.FloPayError(
-          "createSession is required to bootstrap checkout.",
-          "validation_error"
-        );
-      }
-      ensureInlineSessionReady(mergeInlineSessionPatch(baseParams, patch));
-      setDeferredCardOpen(true);
-      onButtonClick?.("card");
       await bootstrapInlineSession(patch);
-    } catch (err) {
-      setDeferredCardOpen(false);
-      const floPayErr = err instanceof import_shared6.FloPayError ? err : new import_shared6.FloPayError(
-        err instanceof Error ? err.message : "Failed to start card checkout.",
-        "api_error"
-      );
-      setLoadError(floPayErr);
-      onErrorRef.current?.(floPayErr);
     } finally {
       setCardBootstrapPending(false);
     }
   }, [
     bootstrapInlineSession,
-    baseCreateSessionHash,
-    cardBootstrapPending,
-    effectiveCreateSession,
-    onButtonClick,
-    onBeforeButtonClick
+    cardBootstrapPending
   ]);
   (0, import_react7.useEffect)(() => {
     let cancelled = false;
     setLoadError(null);
     if (createSessionHash) {
-      if (deferInlineSessionUntilCardClick) {
-        if (initializedHashRef.current !== createSessionHash) {
-          setSession(null);
-          setUnified(null);
-          setFloPay(null);
-          setResolvedSessionId("");
-          setDeferredCardOpen(false);
-          flopayRef.current = null;
-        }
-        setCurrentMode(createSessionParamsRef.current?.checkoutMode ?? checkoutModeProp ?? "full");
-        setIsLoading(false);
-        return () => {
-          cancelled = true;
-        };
-      }
       if (initializedHashRef.current === createSessionHash) return;
       const params = createSessionParamsRef.current;
       setSession(buildSyntheticSession(params, checkoutModeProp));
@@ -2104,7 +2113,7 @@ function FloPayCheckout({
     return () => {
       cancelled = true;
     };
-  }, [resolvedSessionId, createSessionHash, checkoutModeProp, deferInlineSessionUntilCardClick, bootstrapInlineSession]);
+  }, [resolvedSessionId, createSessionHash, checkoutModeProp, bootstrapInlineSession]);
   const handleConfirmCheckout = (0, import_react7.useCallback)(async () => {
     if (confirmProcessing || !session) return;
     setConfirmProcessing(true);
@@ -2147,17 +2156,29 @@ function FloPayCheckout({
     }
     return opts;
   }, [unified, session, appearance, resolvedBillingUrl]);
+  const shouldHandleInlineSessionPatch = Boolean(
+    createSessionParams && !children && layout === "buttons" && onBeforeButtonClick && (effectiveCreateSession?.checkoutMode ?? checkoutModeProp ?? "full") === "full"
+  );
   const checkoutValue = (0, import_react7.useMemo)(
     () => ({
       session,
       loading: isLoading,
       error: loadError,
-      checkoutMode: currentMode
+      checkoutMode: currentMode,
+      applyInlineSessionPatch: shouldHandleInlineSessionPatch ? handleInlineSessionPatch : void 0,
+      inlineSessionPatchProcessing: cardBootstrapPending
     }),
-    [session, isLoading, loadError, currentMode]
+    [
+      session,
+      isLoading,
+      loadError,
+      currentMode,
+      shouldHandleInlineSessionPatch,
+      handleInlineSessionPatch,
+      cardBootstrapPending
+    ]
   );
   const shouldShowInterimButtons = Boolean(createSessionParams) && layout === "buttons" && (!flopay || !providerOptions);
-  const shouldKeepDeferredInterimVisible = shouldShowInterimButtons && deferInlineSessionUntilCardClick;
   if (isLoading) {
     if (loadingNode) return /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(import_jsx_runtime5.Fragment, { children: loadingNode });
     if (layout === "buttons") {
@@ -2186,7 +2207,7 @@ function FloPayCheckout({
       /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("style", { children: `@keyframes spin { to { transform: rotate(360deg); } }` })
     ] });
   }
-  if (loadError && !shouldKeepDeferredInterimVisible) {
+  if (loadError) {
     if (errorNode) return /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(import_jsx_runtime5.Fragment, { children: errorNode(loadError) });
     return /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(
       "div",
@@ -2206,13 +2227,9 @@ function FloPayCheckout({
       InterimButtonsView,
       {
         onButtonClick,
-        onCardButtonClick: deferInlineSessionUntilCardClick ? handleDeferredCardButtonClick : void 0,
-        cardLoading: cardBootstrapPending,
-        cardOpen: deferInlineSessionUntilCardClick ? deferredCardOpen : void 0,
-        errorMessage: shouldKeepDeferredInterimVisible ? loadError?.message ?? null : null,
-        showPayPal: deferInlineSessionUntilCardClick ? false : showPayPal,
-        showApplePay: deferInlineSessionUntilCardClick ? false : showApplePay,
-        showGooglePay: deferInlineSessionUntilCardClick ? false : showGooglePay,
+        showPayPal,
+        showApplePay,
+        showGooglePay,
         buttonsTheme,
         buttonsStyles,
         cardButtonContent,
@@ -2299,6 +2316,7 @@ function FloPayCheckout({
         onComplete,
         onError,
         onDecline,
+        onFullNameChange,
         showPayPal,
         showApplePay,
         showGooglePay,
@@ -2313,7 +2331,8 @@ function FloPayCheckout({
         enableAVS,
         avsLayout,
         country: session?.customer?.country,
-        initialCardOpen: deferredCardOpen,
+        onCountryChange,
+        onZipChange,
         submitLabel,
         className
       }