@flopay/react 1.1.0 → 1.1.4

package/README.md

@@ -215,7 +215,8 @@ Use `onButtonClick` to track button interactions, `onDecline` to track declines/
   layout="buttons"
   createSession={{
     clientId: 'your-client-id',
-    items: [{ providerItemId: 'product-1', providerItemName: 'Widget', totalAmount: 29.99, currency: 'EUR' }],
+    currency: 'EUR',
+    items: [{ providerItemId: 'product-1', providerItemName: 'Widget', totalAmount: 29.99 }],
     account: { userId: 'user_1', email: 'test@email.com' },
     successUrl: '/success',
     cancelUrl: '/cancel',
@@ -258,7 +259,8 @@ Skip the backend API route — create the session directly in the component:
   layout="buttons"
   createSession={{
     clientId: 'your-client-id',
-    items: [{ providerItemId: 'product-1', providerItemName: 'Widget', totalAmount: 29.99, currency: 'EUR' }],
+    currency: 'EUR',
+    items: [{ providerItemId: 'product-1', providerItemName: 'Widget', totalAmount: 29.99 }],
     account: { userId: 'user_1', email: 'user@example.com', firstName: 'Jane', lastName: 'Doe' },
     successUrl: '/success',
     cancelUrl: '/cancel',
@@ -269,6 +271,8 @@ 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.
 
+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.
 
 ### Advanced: Manual Provider Setup
@@ -396,6 +400,8 @@ The SDK supports two PayPal paths, selected per-session based on what the billin
 
 Renderer selection is mutually exclusive per session — direct PayPal takes priority over Stripe-rendered PayPal. Consumer props such as `showPayPal` continue to gate visibility on the client side.
 
+**PayPal-only sessions:** When the backend advertises only `gateways.paypal` (no `gateways.stripe`), `FloPayCheckout` skips Stripe Elements entirely and renders `<DirectPayPalButton>` as the sole payment surface. Sessions that advertise no supported gateway at all throw a `validation_error` explaining the expected shape.
+
 The SDK exposes the relevant pieces in three ways:
 
 - **`SplitCardForm`** / **`FloPayCheckout`**: pick the renderer automatically based on `gateways.*`. No additional configuration needed.

package/dist/index.cjs

@@ -495,15 +495,37 @@ function mergeInlineSessionPatch(params, patch) {
   };
 }
 function buildSyntheticSession(params, checkoutModeOverride) {
-  const totalAmount = [
-    ...(params.items ?? []).map((item) => item.overrideAmount ?? item.totalAmount ?? 0),
-    ...(params.subscriptions ?? []).map((subscription) => subscription.overrideAmount ?? subscription.totalAmount ?? 0)
-  ].reduce((sum, value) => sum + value, 0);
-  const currency = params.currency ?? params.items?.find((i) => i.currency)?.currency ?? params.subscriptions?.find((s) => s.currency)?.currency ?? "USD";
+  const inputProducts = params.products ?? [
+    ...(params.subscriptions ?? []).map((s) => ({
+      type: "subscription",
+      code: s.code ?? s.providerPlanId,
+      name: s.subscriptionName ?? s.providerPlanName ?? s.code ?? s.providerPlanId ?? null,
+      quantity: s.quantity ?? 1,
+      totalAmount: s.totalAmount,
+      overrideAmount: s.overrideAmount,
+      currency: s.currency,
+      metadata: s.metadata
+    })),
+    ...(params.items ?? []).map((i) => ({
+      type: "item",
+      code: i.code ?? i.providerItemId,
+      name: i.itemName ?? i.providerItemName ?? i.code ?? i.providerItemId ?? null,
+      quantity: i.quantity ?? 1,
+      totalAmount: i.totalAmount,
+      overrideAmount: i.overrideAmount,
+      currency: i.currency,
+      metadata: i.metadata
+    }))
+  ];
+  const totalAmount = inputProducts.reduce(
+    (sum, p) => sum + (p.overrideAmount ?? p.totalAmount ?? 0),
+    0
+  );
+  const currency = params.currency ?? inputProducts.find((p) => p.currency)?.currency ?? "USD";
   return {
     id: "",
     clientSecret: "",
-    mode: "payment",
+    mode: inputProducts.some((p) => p.type === "subscription") ? "subscription" : "payment",
     amount: Math.round(totalAmount * 100),
     currency,
     status: "open",
@@ -521,40 +543,18 @@ function buildSyntheticSession(params, checkoutModeOverride) {
     successUrl: params.successUrl,
     cancelUrl: params.cancelUrl,
     checkoutMode: checkoutModeOverride ?? params.checkoutMode ?? "full",
-    items: (params.items ?? []).map((item, idx) => {
-      const code = item.code ?? item.providerItemId;
-      const itemName = item.itemName ?? item.providerItemName ?? code;
-      return {
-        uuid: `synthetic-item-${idx}`,
-        checkoutSessionId: "",
-        code,
-        providerItemId: code,
-        itemName,
-        providerItemName: itemName,
-        quantity: item.quantity ?? 1,
-        totalAmount: item.totalAmount,
-        overrideAmount: item.overrideAmount ?? null,
-        currency: item.currency ?? currency,
-        metadata: item.metadata ?? null
-      };
-    }),
-    subscriptions: (params.subscriptions ?? []).map((subscription, idx) => {
-      const code = subscription.code ?? subscription.providerPlanId;
-      const subscriptionName = subscription.subscriptionName ?? subscription.providerPlanName ?? code;
-      return {
-        uuid: `synthetic-sub-${idx}`,
-        checkoutSessionId: "",
-        code,
-        providerPlanId: code,
-        subscriptionName,
-        providerPlanName: subscriptionName,
-        quantity: subscription.quantity ?? 1,
-        totalAmount: subscription.totalAmount,
-        overrideAmount: subscription.overrideAmount ?? null,
-        currency: subscription.currency ?? currency,
-        metadata: subscription.metadata ?? null
-      };
-    })
+    products: inputProducts.map((p, idx) => ({
+      uuid: `synthetic-${p.type}-${idx}`,
+      checkoutSessionId: "",
+      type: p.type,
+      code: p.code,
+      name: p.name ?? null,
+      quantity: p.quantity ?? 1,
+      totalAmount: p.totalAmount,
+      overrideAmount: p.overrideAmount ?? null,
+      currency: p.currency ?? currency,
+      metadata: p.metadata ?? null
+    }))
   };
 }
 function mergeAccountPatch(base, patch) {
@@ -582,9 +582,25 @@ function readString(payload, key) {
   const value = payload?.[key];
   return typeof value === "string" && value.trim() ? value : void 0;
 }
+var FRIENDLY_MESSAGE_OVERRIDES = [
+  {
+    match: /^paypal authorization required\.?$/i,
+    replacement: "For your additional security, please re-authenticate this payment via PayPal."
+  }
+];
+function applyFriendlyMessageOverride(message) {
+  if (typeof message !== "string") return message ?? void 0;
+  const trimmed = message.trim();
+  if (!trimmed) return message;
+  for (const { match, replacement } of FRIENDLY_MESSAGE_OVERRIDES) {
+    if (match.test(trimmed)) return replacement;
+  }
+  return message;
+}
 function buildFloPayApiError(payload, fallbackMessage) {
   const nestedError = isRecord(payload?.error) ? payload.error : null;
-  const message = readString(payload, "message") ?? readString(nestedError, "message") ?? fallbackMessage;
+  const rawMessage = readString(payload, "message") ?? readString(nestedError, "message") ?? fallbackMessage;
+  const message = applyFriendlyMessageOverride(rawMessage) ?? rawMessage;
   const code = readString(payload, "code") ?? readString(payload, "gatewayErrorCode") ?? readString(nestedError, "code");
   const declineCode = readString(payload, "declineCode") ?? readString(payload, "gatewayDeclineReason") ?? readString(payload, "decline_code") ?? readString(nestedError, "decline_code");
   return new import_shared3.FloPayError(message, "api_error", {
@@ -775,7 +791,7 @@ function DirectPayPalButton({
     if (!clientId) {
       appendDebug("FAIL: clientId empty \u2014 gateway misconfigured");
       setFailed(true);
-      onErrorChangeRef.current?.("Direct PayPal gateway is misconfigured.");
+      console.error("[FloPay] DirectPayPal: clientId empty \u2014 gateway misconfigured");
       return;
     }
     if (!containerRef.current) {
@@ -886,7 +902,8 @@ function DirectPayPalButton({
     const forwardError = (message) => {
       if (cancelled) return;
       if (isZoidLifecycleMessage(message)) return;
-      onErrorChangeRef.current?.(message);
+      const friendly = applyFriendlyMessageOverride(message) ?? message;
+      onErrorChangeRef.current?.(friendly);
     };
     const markRenderFailed = (message) => {
       if (cancelled) return;
@@ -895,7 +912,7 @@ function DirectPayPalButton({
         return;
       }
       setFailed(true);
-      forwardError(message);
+      console.error("[FloPay] DirectPayPal load/render failure:", message);
     };
     setFailed(false);
     const dispatchTokenizedBody = async (body) => {
@@ -933,14 +950,16 @@ function DirectPayPalButton({
           return;
         }
         const json = await response.json().catch(() => null);
-        const message = json?.["message"] ?? "PayPal payment failed.";
+        const rawMessage = json?.["message"] ?? "PayPal payment failed.";
+        const message = applyFriendlyMessageOverride(rawMessage) ?? rawMessage;
         forwardError(message);
         onDeclineRef.current?.(buildDeclineEvent("paypal", message, {
           code: json?.["code"],
           declineCode: json?.["declineCode"]
         }));
       } catch (err) {
-        const message = err instanceof Error ? err.message : "PayPal payment failed.";
+        const rawMessage = err instanceof Error ? err.message : "PayPal payment failed.";
+        const message = applyFriendlyMessageOverride(rawMessage) ?? rawMessage;
         forwardError(message);
         onDeclineRef.current?.(buildDeclineEvent("paypal", message));
       }
@@ -3090,9 +3109,11 @@ function getRedirectResultFromCheckoutProcessError(error) {
 }
 function checkoutProcessErrorToFloPayError(error, fallbackMessage = "Payment failed. Please try again.", options) {
   const checkoutMethod = options?.checkoutMethod ?? error?.checkoutMethod ?? (error?.type === "paypal_redirect_required" ? "paypal" : "card");
+  const rawMessage = error?.message ?? fallbackMessage;
+  const message = applyFriendlyMessageOverride(rawMessage) ?? rawMessage;
   return Object.assign(
     new import_shared7.FloPayError(
-      error?.message ?? fallbackMessage,
+      message,
       "api_error",
       {
         code: error?.gatewayErrorCode
@@ -3549,21 +3570,36 @@ async function handleSavedPaymentRedirectResult(redirectResult, {
 }
 function normalizeSavedPaymentError(err) {
   if (err instanceof import_shared7.FloPayError) {
+    const friendly = applyFriendlyMessageOverride(err.message);
+    if (friendly && friendly !== err.message) {
+      return Object.assign(
+        new import_shared7.FloPayError(friendly, err.type, {
+          code: err.code,
+          declineCode: err.declineCode,
+          param: err.param,
+          statusCode: err.statusCode
+        }),
+        { checkoutMethod: err.checkoutMethod }
+      );
+    }
     return err;
   }
-  return new import_shared7.FloPayError(
-    err instanceof Error ? err.message : "Payment failed. Please try again.",
-    "api_error"
-  );
+  const rawMessage = err instanceof Error ? err.message : "Payment failed. Please try again.";
+  const message = applyFriendlyMessageOverride(rawMessage) ?? rawMessage;
+  return new import_shared7.FloPayError(message, "api_error");
 }
 function resolveSavedPaymentPublishableKeys(unified) {
   const publishableKey = unified.data.stripe?.publishableKey;
-  if (!publishableKey) {
+  const hasDirectPaypal = Boolean(unified.data.paypal?.publishableKey);
+  if (!publishableKey && !hasDirectPaypal) {
     throw new import_shared7.FloPayError(
-      "No publishable key found in the checkout session. Ensure the session advertises gateways.stripe.",
+      "Session advertises no supported gateways (expected `gateways.stripe` and/or `gateways.paypal`).",
       "validation_error"
     );
   }
+  if (!publishableKey) {
+    return {};
+  }
   return {
     publishableKey,
     // Direct-PayPal sessions can still use Stripe's PayPal Element for the
@@ -3580,6 +3616,9 @@ async function loadSavedPaymentProviders({
   billingApiUrl,
   locale
 }) {
+  if (!publishableKey) {
+    return { flopay: null, paypalFlopay: null };
+  }
   const needsSeparatePaypal = Boolean(paypalPublishableKey) && paypalPublishableKey !== publishableKey;
   const [instance, paypalInstanceOrError] = await Promise.all([
     (0, import_js3.loadFloPay)(publishableKey, {
@@ -3616,6 +3655,11 @@ function resolveDirectPaypalConfig(unified) {
     environment: unified?.data.paypal?.environment
   };
 }
+function isPayPalOnlyUnified(unified) {
+  if (!unified) return false;
+  if (unified.data.stripe?.publishableKey) return false;
+  return Boolean(resolveDirectPaypalConfig(unified)?.clientId);
+}
 function canUseStorage() {
   return typeof window !== "undefined" && typeof window.sessionStorage !== "undefined";
 }
@@ -3794,7 +3838,7 @@ function FloPayCheckout({
         const redirectResult = getRedirectResultFromCheckoutProcessError(options?.initialAutoProcessingError);
         let paymentResult;
         if (redirectResult) {
-          if (redirectResult.type === "paypal_redirect_required" && savedPaymentKeysRef.current) {
+          if (redirectResult.type === "paypal_redirect_required" && savedPaymentKeysRef.current?.publishableKey) {
             persistPayPalResumeState({
               sessionId: activeSessionId2,
               publishableKey: savedPaymentKeysRef.current.publishableKey,
@@ -3846,7 +3890,7 @@ function FloPayCheckout({
           if (result.type === "success") {
             paymentResult = result.result;
           } else {
-            if (result.type === "paypal_redirect_required" && savedPaymentKeysRef.current) {
+            if (result.type === "paypal_redirect_required" && savedPaymentKeysRef.current?.publishableKey) {
               persistPayPalResumeState({
                 sessionId: activeSessionId2,
                 publishableKey: savedPaymentKeysRef.current.publishableKey,
@@ -3937,7 +3981,7 @@ function FloPayCheckout({
           billingApiUrl: resolvedBillingUrl,
           locale
         });
-        const paypalStripe = (resumePaypalFlopay ?? resumeFlopay).getRawProvider();
+        const paypalStripe = (resumePaypalFlopay ?? resumeFlopay)?.getRawProvider();
         if (!paypalStripe) {
           throw Object.assign(
             new import_shared8.FloPayError("PayPal is not available.", "api_error"),
@@ -4205,7 +4249,8 @@ function FloPayCheckout({
           const resolved = await bootstrapInlineSession();
           const resolvedSession = resolved.result.data.session ?? null;
           savedPaymentKeysRef.current = resolveSavedPaymentPublishableKeys(resolved.result);
-          if (!cancelled && shouldAutoProcessInlineSession && resolvedSession) {
+          const resolvedPaypalOnly = isPayPalOnlyUnified(resolved.result);
+          if (!cancelled && shouldAutoProcessInlineSession && resolvedSession && !resolvedPaypalOnly) {
             autoCheckoutAttempted.current = true;
             await runSavedPaymentFlow(resolvedSession, {
               attempt3DS: true,
@@ -4219,6 +4264,9 @@ function FloPayCheckout({
             return;
           }
           if (!cancelled && shouldAutoProcessInlineSession) {
+            if (resolvedPaypalOnly) {
+              autoCheckoutAttempted.current = true;
+            }
             setModeOverlayStatus(null);
             setModeOverlayError(null);
           }
@@ -4273,7 +4321,8 @@ function FloPayCheckout({
         const effectiveMode = checkoutModeProp ?? sess.checkoutMode ?? "full";
         setCurrentMode(effectiveMode);
         const hasPayPalRedirectParams = typeof window !== "undefined" && new URLSearchParams(window.location.search).has("payment_intent");
-        if (effectiveMode === "auto" && !autoCheckoutAttempted.current && !hasPayPalRedirectParams) {
+        const paypalOnly = isPayPalOnlyUnified(result);
+        if (effectiveMode === "auto" && !autoCheckoutAttempted.current && !hasPayPalRedirectParams && !paypalOnly) {
           autoCheckoutAttempted.current = true;
           const stripeInitPromise = initStripe(result);
           try {
@@ -4353,8 +4402,10 @@ function FloPayCheckout({
       setConfirmProcessing(false);
     }
   }, [activeSessionId, confirmProcessing, runSavedPaymentFlow, session]);
+  const directPaypalConfig = resolveDirectPaypalConfig(unified);
+  const isPaypalOnlySession = isPayPalOnlyUnified(unified);
   const providerOptions = (0, import_react9.useMemo)(() => {
-    if (!unified || !session) return void 0;
+    if (!unified || !session || !unified.data.stripe?.publishableKey) return void 0;
     const opts = {
       appearance,
       paymentMethodCreation: "manual",
@@ -4393,7 +4444,7 @@ function FloPayCheckout({
       cardBootstrapPending
     ]
   );
-  const shouldShowInterimButtons = Boolean(createSessionParams) && layout === "buttons" && (!flopay || !providerOptions);
+  const shouldShowInterimButtons = Boolean(createSessionParams) && layout === "buttons" && !isPaypalOnlySession && (!flopay || !providerOptions);
   const modeOverlay = modeOverlayStatus ? /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(
     ProcessingOverlay,
     {
@@ -4476,6 +4527,48 @@ function FloPayCheckout({
       modeOverlay
     ] });
   }
+  if (isPaypalOnlySession && session && directPaypalConfig) {
+    return /* @__PURE__ */ (0, import_jsx_runtime7.jsxs)(import_jsx_runtime7.Fragment, { children: [
+      /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(CheckoutContext.Provider, { value: checkoutValue, children: /* @__PURE__ */ (0, import_jsx_runtime7.jsxs)("div", { className, style: { display: "flex", flexDirection: "column", gap: "0.5rem" }, children: [
+        modeError && /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(
+          "div",
+          {
+            role: "alert",
+            "data-testid": "flopay-error",
+            style: {
+              padding: "0.625rem 0.875rem",
+              background: "#FEF2F2",
+              border: "1px solid #FECACA",
+              borderRadius: "8px",
+              color: "#991B1B",
+              fontSize: "0.85rem",
+              fontWeight: 600
+            },
+            children: modeError
+          }
+        ),
+        /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(
+          DirectPayPalButton,
+          {
+            sessionId: activeSessionId,
+            billingApiUrl: resolvedBillingUrl,
+            email: session.customer?.email,
+            clientId: directPaypalConfig.clientId,
+            environment: directPaypalConfig.environment,
+            currency: (session.currency ?? "usd").toUpperCase(),
+            isSubscription: session.mode === "subscription",
+            onComplete,
+            onErrorChange: setModeError,
+            onDecline,
+            onButtonClick,
+            session,
+            debug
+          }
+        )
+      ] }) }),
+      modeOverlay
+    ] });
+  }
   if (!flopay || !providerOptions) {
     return /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(import_jsx_runtime7.Fragment, { children: modeOverlay });
   }
@@ -5630,7 +5723,7 @@ function FloPayAutomaticPaymentButton({
           publishableKey,
           paypalPublishableKey
         } = resolveSavedPaymentPublishableKeys(apiResult);
-        if (redirectResult.type === "paypal_redirect_required") {
+        if (redirectResult.type === "paypal_redirect_required" && publishableKey) {
           persistPayPalResumeState2({
             sessionId: session.id || resolvedSessionId,
             publishableKey,
@@ -5686,7 +5779,7 @@ function FloPayAutomaticPaymentButton({
             publishableKey,
             paypalPublishableKey
           } = resolveSavedPaymentPublishableKeys(apiResult);
-          if (result.type === "paypal_redirect_required") {
+          if (result.type === "paypal_redirect_required" && publishableKey) {
             persistPayPalResumeState2({
               sessionId: session.id || resolvedSessionId,
               publishableKey,
@@ -5747,6 +5840,13 @@ function FloPayAutomaticPaymentButton({
             billingApiUrl: resolvedBillingUrl,
             locale
           });
+          if (!flopay) {
+            throw new import_shared11.FloPayError(
+              "Stripe is not available for 3DS authentication.",
+              "api_error",
+              { code: "authentication_required" }
+            );
+          }
           const paymentResult = await processSavedPaymentWithIntent({
             billingApiUrl: resolvedBillingUrl,
             sessionId: fallbackSessionId,
@@ -5933,7 +6033,7 @@ function FloPayAutomaticPaymentButton({
           billingApiUrl: resolvedBillingUrl,
           locale
         });
-        const paypalStripe = (paypalFlopay ?? flopay).getRawProvider();
+        const paypalStripe = (paypalFlopay ?? flopay)?.getRawProvider();
         if (!paypalStripe) {
           throw Object.assign(
             new import_shared11.FloPayError("PayPal is not available.", "api_error"),