@easypayment/medusa-paypal-ui 1.1.0 → 1.1.1

package/src/client/http.ts

@@ -35,6 +35,21 @@ function isRetryableError(err: unknown): boolean {
 
 const wait = (ms: number) => new Promise((r) => setTimeout(r, ms))
 
+/** Best-effort extraction of a `{ message: string }` payload from a response body. */
+function extractJsonMessage(text: string): string | null {
+  if (!text) return null
+  try {
+    const parsed = JSON.parse(text)
+    const message = parsed?.message
+    if (typeof message === "string" && message.trim()) {
+      return message.trim().slice(0, 500)
+    }
+  } catch {
+    // not JSON — caller falls back to the raw text
+  }
+  return null
+}
+
 function toHeaderRecord(headers?: RequestInit["headers"]): Record<string, string> {
   if (!headers) {
     return {}
@@ -65,41 +80,70 @@ export function createHttpClient(opts: HttpOptions) {
       headers["x-publishable-api-key"] = opts.publishableApiKey
     }
 
+    // Always arm the timeout — a caller-supplied signal composes with it
+    // rather than replacing it. Without this, hook-issued requests (which
+    // always pass an abort signal) could hang forever on a stalled
+    // connection. The timer also covers reading the body: a server that sends
+    // headers then stalls the response stream would otherwise hang the
+    // request indefinitely with the old header-only timeout.
     const timeoutMs = 30_000
-    let timeoutId: ReturnType<typeof setTimeout> | undefined
     const controller = new AbortController()
-    if (!init?.signal) {
-      timeoutId = setTimeout(() => controller.abort(), timeoutMs)
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs)
+    const callerSignal = init?.signal ?? null
+    const onCallerAbort = () => controller.abort()
+    if (callerSignal) {
+      if (callerSignal.aborted) controller.abort()
+      else callerSignal.addEventListener("abort", onCallerAbort)
     }
-    const effectiveSignal = init?.signal || controller.signal
     let res: Response
+    let text: string
     try {
-      res = await fetch(url, { ...init, headers, credentials: "include", signal: effectiveSignal })
+      res = await fetch(url, {
+        ...init,
+        headers,
+        credentials: "include",
+        signal: controller.signal,
+      })
+      text = await res.text().catch(() => "")
     } catch (err) {
-      if (err instanceof Error && err.name === "AbortError" && !init?.signal) {
+      if (
+        err instanceof Error &&
+        err.name === "AbortError" &&
+        !(callerSignal && callerSignal.aborted)
+      ) {
         throw new Error(`[PayPal] Request to ${path} timed out after ${timeoutMs / 1000}s`)
       }
       throw err
     } finally {
-      if (timeoutId !== undefined) clearTimeout(timeoutId)
+      clearTimeout(timeoutId)
+      if (callerSignal) callerSignal.removeEventListener("abort", onCallerAbort)
     }
-    const text = await res.text().catch(() => "")
 
     if (!res.ok) {
+      // Backend routes return structured JSON errors ({ message }) written for
+      // the buyer (e.g. unsupported currency, rate-limit, "payment processed
+      // but order not finalized"). Prefer that message over raw response text
+      // or a generic hint so the user sees something actionable instead of a
+      // JSON blob.
+      const parsedMessage = extractJsonMessage(text)
       if (res.status === 401) {
         throw new HttpError(
-          "[PayPal] Unauthorized (401) — check that your publishable API key is correct and set in NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY",
+          parsedMessage ||
+            "[PayPal] Unauthorized (401) — check that your publishable API key is correct and set in NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY",
           401
         )
       }
       if (res.status === 403) {
         throw new HttpError(
-          "[PayPal] Forbidden (403) — this request is not allowed. Check your CORS and API key settings.",
+          parsedMessage ||
+            "[PayPal] Forbidden (403) — this request is not allowed. Check your CORS and API key settings.",
           403
         )
       }
       throw new HttpError(
-        text.slice(0, 500).replace(/<[^>]*>/g, "") || `Request failed (${res.status})`,
+        parsedMessage ||
+          text.slice(0, 500).replace(/<[^>]*>/g, "") ||
+          `Request failed (${res.status})`,
         res.status
       )
     }

package/src/client/types.ts

@@ -21,6 +21,16 @@ export type PayPalConfig = {
 }
 
 export type PayPalSettingsResponse = {
+  /**
+   * What `GET /store/paypal/settings` actually returns: the configured
+   * payment action and whether advanced card fields are enabled.
+   */
+  paymentAction?: "capture" | "authorize"
+  advancedCardEnabled?: boolean
+  /**
+   * @deprecated The settings endpoint has never returned a `data` envelope —
+   * kept only so existing (already-null-safe) consumer code keeps compiling.
+   */
   data?: {
     api_details?: { currency_code?: string }
     paypal_settings?: Record<string, unknown>

package/src/components/PayPalAdvancedCard.tsx

@@ -68,10 +68,12 @@ function SubmitButton({
   disabled,
   label,
   onSubmit,
+  onSubmitError,
 }: {
   disabled: boolean
   label: string
   onSubmit: () => void
+  onSubmitError: (message: string) => void
 }) {
   const { cardFieldsForm } = usePayPalCardFields()
   const isDisabled = disabled || !cardFieldsForm
@@ -83,11 +85,18 @@ function SubmitButton({
       aria-busy={disabled}
       onClick={() => {
         onSubmit()
-        try {
-          cardFieldsForm?.submit()
-        } catch {
-          // submit() error is handled by PayPalCardFieldsProvider onError
-        }
+        // submit() returns a promise and its rejection is NOT routed to the
+        // provider's onError — PayPal's contract is that the caller catches
+        // it. A sync try/catch here would miss it entirely, leaving the buyer
+        // stuck under the full-screen processing overlay forever (e.g. on a
+        // card-field validation error).
+        Promise.resolve(cardFieldsForm?.submit()).catch((e: unknown) => {
+          const msg =
+            e instanceof Error && e.message
+              ? e.message
+              : "Card payment could not be submitted. Please check your card details."
+          onSubmitError(msg)
+        })
       }}
       style={{
         width: "100%",
@@ -150,8 +159,55 @@ export function PayPalAdvancedCard(props: {
   const [submitting, setSubmitting] = useState(false)
   const submittingRef = useRef(false)
   const creatingOrderRef = useRef(false)
+  // Once a capture succeeded the buyer's money is taken: any later failure
+  // must retry ONLY the order finalization, never a fresh order/capture.
+  const capturedRef = useRef<Record<string, unknown> | null>(null)
+  const [completionPending, setCompletionPending] = useState(false)
   const [{ isPending, isResolved, isRejected }] = usePayPalScriptReducer()
 
+  const resetSubmitState = React.useCallback(() => {
+    hideProcessingOverlay()
+    creatingOrderRef.current = false
+    submittingRef.current = false
+    setSubmitting(false)
+  }, [])
+
+  // bfcache restore (Back button after a redirect) revives this page with the
+  // old React state — clear the submitting flag so the buyer isn't stuck
+  // behind the in-component overlay.
+  React.useEffect(() => {
+    const onPageShow = (e: PageTransitionEvent) => {
+      if (e.persisted) {
+        creatingOrderRef.current = false
+        submittingRef.current = false
+        setSubmitting(false)
+      }
+    }
+    window.addEventListener("pageshow", onPageShow)
+    return () => window.removeEventListener("pageshow", onPageShow)
+  }, [])
+
+  const finalizeCapturedPayment = React.useCallback(async () => {
+    const captured = capturedRef.current
+    if (!captured) return
+    setSubmitting(true)
+    showProcessingOverlay()
+    setError(null)
+    try {
+      const completeResult = await markPaymentComplete(baseUrl, cartId, publishableApiKey)
+      await onPaid?.({ ...captured, ...completeResult })
+      setCompletionPending(false)
+    } catch (e: unknown) {
+      if (isNextRouterError(e)) return
+      resetSubmitState()
+      setCompletionPending(true)
+      const msg =
+        "Your payment was received, but finalizing your order failed. Please use the Retry button below — do not pay again."
+      setError(msg)
+      onError?.(msg)
+    }
+  }, [baseUrl, cartId, publishableApiKey, onPaid, onError, resetSubmitState])
+
   if (!config.currency_supported) return null
 
   if (isRejected) {
@@ -331,6 +387,12 @@ export function PayPalAdvancedCard(props: {
         style={cardStyle}
         createOrder={async () => {
           if (creatingOrderRef.current) throw new Error("Payment already processing")
+          if (capturedRef.current) {
+            // Money was already captured for this cart — retry the order
+            // finalization instead of creating (and charging) a new order.
+            void finalizeCapturedPayment()
+            throw new Error("Your payment was already received — finalizing your order.")
+          }
           creatingOrderRef.current = true
           try {
             setError(null)
@@ -346,21 +408,20 @@ export function PayPalAdvancedCard(props: {
             setError(null)
             showProcessingOverlay()
             const orderId = String(data?.orderID || "")
+            if (!orderId) throw new Error("PayPal order ID is missing from approval response")
             const result = await api.captureOrder(cartId, orderId)
-
-            const completeResult = await markPaymentComplete(baseUrl, cartId, publishableApiKey)
-
-            await onPaid?.({ ...result, ...completeResult })
+            capturedRef.current = (result || {}) as Record<string, unknown>
           } catch (e: unknown) {
             if (isNextRouterError(e)) return
-            hideProcessingOverlay()
-            creatingOrderRef.current = false
-            submittingRef.current = false
-            setSubmitting(false)
+            resetSubmitState()
             const msg = e instanceof Error ? e.message : "Card payment failed"
             setError(msg)
             onError?.(msg)
+            return
           }
+          // Past this point the buyer has been charged: completion failures
+          // surface a finalize-only Retry, never a fresh payment.
+          await finalizeCapturedPayment()
         }}
         onCancel={() => {
           hideProcessingOverlay()
@@ -458,17 +519,46 @@ export function PayPalAdvancedCard(props: {
             <span>Your payment is secured with 256-bit SSL encryption</span>
           </div>
 
-          <SubmitButton
-            disabled={submitting}
-            label={submitting ? "Processing…" : "Pay by Card"}
-            onSubmit={() => {
-              if (submittingRef.current) return
-              submittingRef.current = true
-              setError(null)
-              setSubmitting(true)
-              showProcessingOverlay()
-            }}
-          />
+          {completionPending ? (
+            <button
+              type="button"
+              onClick={() => void finalizeCapturedPayment()}
+              disabled={submitting}
+              aria-busy={submitting}
+              style={{
+                width: "100%",
+                height: 48,
+                padding: "0 20px",
+                borderRadius: 8,
+                border: "none",
+                background: "#0070ba",
+                color: "#ffffff",
+                fontSize: 15,
+                fontWeight: 600,
+                cursor: submitting ? "not-allowed" : "pointer",
+                opacity: submitting ? 0.7 : 1,
+              }}
+            >
+              Retry — finish placing my order
+            </button>
+          ) : (
+            <SubmitButton
+              disabled={submitting}
+              label={submitting ? "Processing…" : "Pay by Card"}
+              onSubmit={() => {
+                if (submittingRef.current) return
+                submittingRef.current = true
+                setError(null)
+                setSubmitting(true)
+                showProcessingOverlay()
+              }}
+              onSubmitError={(msg) => {
+                resetSubmitState()
+                setError(msg)
+                onError?.(msg)
+              }}
+            />
+          )}
 
           {error && (
             <div

package/src/components/PayPalSmartButtons.tsx

@@ -1,5 +1,5 @@
 "use client"
-import React, { useCallback, useMemo, useState } from "react"
+import React, { useCallback, useEffect, useMemo, useRef, useState } from "react"
 import { PayPalButtons, usePayPalScriptReducer } from "@paypal/react-paypal-js"
 import { createPayPalStoreApi, markPaymentComplete } from "../client/paypal"
 import type { PayPalConfig } from "../client/types"
@@ -35,13 +35,63 @@ export function PayPalSmartButtons(props: {
   const [error, setError] = useState<string | null>(null)
   const [processing, setProcessing] = useState(false)
   const [buttonsReady, setButtonsReady] = useState(false)
+  const [loadTimedOut, setLoadTimedOut] = useState(false)
+  // Once a capture succeeded, the buyer's money is taken — any later failure
+  // (order finalization, consumer callback) must retry ONLY the finalization,
+  // never a fresh createOrder/capture, or a retry click would charge again.
+  const capturedRef = useRef<Record<string, unknown> | null>(null)
+  const [completionPending, setCompletionPending] = useState(false)
   const [{ isPending, isResolved, isRejected }] = usePayPalScriptReducer()
 
   const handleInit = useCallback(() => {
     setButtonsReady(true)
   }, [])
 
-  const showSpinner = isPending || (isResolved && !buttonsReady)
+  // bfcache restore (Back button after a redirect) revives this page with the
+  // old React state — clear the processing flag so the buyer isn't stuck
+  // behind the in-component overlay.
+  useEffect(() => {
+    const onPageShow = (e: PageTransitionEvent) => {
+      if (e.persisted) setProcessing(false)
+    }
+    window.addEventListener("pageshow", onPageShow)
+    return () => window.removeEventListener("pageshow", onPageShow)
+  }, [])
+
+  // The PayPal SDK never calls onInit when the buttons are ineligible (wrong
+  // country/currency/funding) — it silently renders nothing. Without a
+  // fallback the buyer stares at "Loading PayPal…" forever.
+  useEffect(() => {
+    if (!isResolved || buttonsReady) {
+      return
+    }
+    const t = setTimeout(() => setLoadTimedOut(true), 10_000)
+    return () => clearTimeout(t)
+  }, [isResolved, buttonsReady])
+
+  const finalizeCapturedPayment = useCallback(async () => {
+    const captured = capturedRef.current
+    if (!captured) return
+    setProcessing(true)
+    showProcessingOverlay()
+    setError(null)
+    try {
+      const completeResult = await markPaymentComplete(baseUrl, cartId, publishableApiKey)
+      await onPaid?.({ ...captured, ...completeResult })
+      setCompletionPending(false)
+    } catch (e: unknown) {
+      if (isNextRouterError(e)) return
+      hideProcessingOverlay()
+      setProcessing(false)
+      setCompletionPending(true)
+      const msg =
+        "Your payment was received, but finalizing your order failed. Please use the Retry button below — do not pay again."
+      setError(msg)
+      onError?.(msg)
+    }
+  }, [baseUrl, cartId, publishableApiKey, onPaid, onError])
+
+  const showSpinner = (isPending || (isResolved && !buttonsReady)) && !loadTimedOut
 
   if (!config.currency_supported) return null
 
@@ -170,6 +220,30 @@ export function PayPalSmartButtons(props: {
         </div>
       )}
 
+      {loadTimedOut && !buttonsReady && !isRejected && (
+        <div
+          role="alert"
+          style={{
+            display: "flex",
+            alignItems: "flex-start",
+            gap: 8,
+            padding: "10px 14px",
+            background: "#fef2f2",
+            border: "1px solid #fecaca",
+            borderRadius: 8,
+            fontSize: 13,
+            color: "#b91c1c",
+            lineHeight: 1.5,
+          }}
+        >
+          <span style={{ flexShrink: 0, fontSize: 15 }}>⚠️</span>
+          <span>
+            PayPal is not available for this purchase. Please try a different
+            payment method.
+          </span>
+        </div>
+      )}
+
       {isRejected && (
         <div
           role="alert"
@@ -230,7 +304,7 @@ export function PayPalSmartButtons(props: {
         </div>
       )}
 
-      {isResolved && (
+      {isResolved && !completionPending && (
         <div style={buttonsReady ? undefined : { position: "absolute", left: -9999, opacity: 0, pointerEvents: "none" }}>
         <PayPalButtons
           forceReRender={[config.currency, config.intent, cartId]}
@@ -244,6 +318,12 @@ export function PayPalSmartButtons(props: {
           }}
           createOrder={async () => {
             if (processing) throw new Error("Payment already processing")
+            if (capturedRef.current) {
+              // Money was already captured for this cart — retry the order
+              // finalization instead of creating (and charging) a new order.
+              void finalizeCapturedPayment()
+              throw new Error("Your payment was already received — finalizing your order.")
+            }
             setError(null)
             setProcessing(true)
             try {
@@ -262,10 +342,7 @@ export function PayPalSmartButtons(props: {
               const orderId = String(data?.orderID || "")
               if (!orderId) throw new Error("PayPal order ID is missing from approval response")
               const result = await api.captureOrder(cartId, orderId)
-
-              const completeResult = await markPaymentComplete(baseUrl, cartId, publishableApiKey)
-
-              await onPaid?.({ ...result, ...completeResult })
+              capturedRef.current = (result || {}) as Record<string, unknown>
             } catch (e: unknown) {
               if (isNextRouterError(e)) return
               hideProcessingOverlay()
@@ -273,7 +350,11 @@ export function PayPalSmartButtons(props: {
               const msg = e instanceof Error ? e.message : "Payment capture failed"
               setError(msg)
               onError?.(msg)
+              return
             }
+            // Past this point the buyer has been charged: completion failures
+            // surface a finalize-only Retry, never a fresh payment.
+            await finalizeCapturedPayment()
           }}
           onCancel={() => {
             hideProcessingOverlay()
@@ -290,6 +371,30 @@ export function PayPalSmartButtons(props: {
         </div>
       )}
 
+      {completionPending && (
+        <button
+          type="button"
+          onClick={() => void finalizeCapturedPayment()}
+          disabled={processing}
+          aria-busy={processing}
+          style={{
+            width: "100%",
+            padding: "12px 16px",
+            marginTop: 4,
+            background: "#0070ba",
+            color: "#ffffff",
+            border: "none",
+            borderRadius: 8,
+            fontSize: 14,
+            fontWeight: 600,
+            cursor: processing ? "not-allowed" : "pointer",
+            opacity: processing ? 0.7 : 1,
+          }}
+        >
+          Retry — finish placing my order
+        </button>
+      )}
+
       {error ? (
         <div
           role="alert"

package/src/utils/next-errors.ts

@@ -12,6 +12,10 @@ export function isNextRouterError(e: unknown): boolean {
   const digest = (e as { digest: unknown }).digest
   return (
     typeof digest === "string" &&
-    (digest.startsWith("NEXT_REDIRECT") || digest.startsWith("NEXT_NOT_FOUND"))
+    (digest.startsWith("NEXT_REDIRECT") ||
+      digest.startsWith("NEXT_NOT_FOUND") ||
+      // Next.js 15: notFound()/forbidden()/unauthorized() throw
+      // HTTPAccessFallbackError with digest "NEXT_HTTP_ERROR_FALLBACK;<status>".
+      digest.startsWith("NEXT_HTTP_ERROR_FALLBACK"))
   )
 }

package/src/utils/processing-overlay.ts

@@ -69,8 +69,20 @@ export function showProcessingOverlay() {
     onNav()
   }
 
+  // bfcache restore: the overlay intentionally survives the unload of a
+  // full-page navigation (that's its purpose), but when the buyer presses
+  // Back the browser restores this page from the back/forward cache with the
+  // overlay element still in the DOM and the URL equal to startUrl — no nav
+  // listener ever fires, leaving checkout permanently covered. `pageshow`
+  // with `persisted: true` is exactly that restore.
+  const onPageShow = (e: PageTransitionEvent) => {
+    if (e.persisted) hideProcessingOverlay()
+  }
+  window.addEventListener("pageshow", onPageShow)
+
   cleanupNavListener = () => {
     window.removeEventListener("popstate", onNav)
+    window.removeEventListener("pageshow", onPageShow)
     history.pushState = origPush
     history.replaceState = origReplace
   }