@easypayment/medusa-paypal-ui 1.1.0 → 1.2.0

package/src/components/PayPalSmartButtons.tsx

@@ -1,8 +1,13 @@
 "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"
+import {
+  clearCartCaptured,
+  markCartCaptured,
+  wasCartCaptured,
+} from "../utils/captured-state"
 import { isNextRouterError } from "../utils/next-errors"
 import { showProcessingOverlay, hideProcessingOverlay } from "../utils/processing-overlay"
 
@@ -35,13 +40,79 @@ 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)
+  }, [])
+
+  // A reload/crash between capture and finalization loses the in-memory
+  // capturedRef — restore it from the persisted per-cart flag so the buyer
+  // gets the finalize-only Retry button instead of payment buttons that would
+  // fail confusingly against an already-captured PayPal order.
+  useEffect(() => {
+    if (capturedRef.current || !wasCartCaptured(cartId)) return
+    capturedRef.current = {}
+    setCompletionPending(true)
+    const msg =
+      "Your payment was already received for this cart. Please use the button below to finish placing your order — do not pay again."
+    setError(msg)
+  }, [cartId])
+
+  // 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)
+      // The order is finalized — the persisted "captured" flag has served its
+      // purpose. Clear it before the consumer callback (which may redirect).
+      clearCartCaptured(cartId)
+      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 +241,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 +325,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 +339,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 +363,10 @@ 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>
+              // Persist across reloads: from here on, only finalization may
+              // ever be retried for this cart — never a fresh payment.
+              markCartCaptured(cartId)
             } catch (e: unknown) {
               if (isNextRouterError(e)) return
               hideProcessingOverlay()
@@ -273,7 +374,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 +395,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/constants.ts

@@ -0,0 +1,22 @@
+/**
+ * Provider ids registered by `@easypayment/medusa-payment-paypal`.
+ *
+ * Single source of truth — `PayPalPaymentSection`, `MedusaNextPayPalAdapter`,
+ * and the server-safe `order` entrypoint all re-export from here so the ids
+ * can never drift between entrypoints.
+ */
+export const PAYPAL_WALLET_PROVIDER_ID = "pp_paypal_paypal" as const
+export const PAYPAL_CARD_PROVIDER_ID = "pp_paypal_card_paypal_card" as const
+
+export const PAYPAL_PROVIDER_IDS = [
+  PAYPAL_WALLET_PROVIDER_ID,
+  PAYPAL_CARD_PROVIDER_ID,
+] as const
+
+/** True when the provider id belongs to this PayPal plugin. */
+export function isPayPalProviderId(providerId?: string | null): boolean {
+  if (!providerId) return false
+  return PAYPAL_PROVIDER_IDS.includes(
+    providerId as (typeof PAYPAL_PROVIDER_IDS)[number]
+  )
+}

package/src/hooks/usePayPalPaymentMethods.ts

@@ -17,6 +17,13 @@ type Result = {
   cardEnabled: boolean
   cardTitle: string
   loading: boolean
+  /**
+   * Non-null when the config fetch failed and the returned flags are the
+   * optimistic defaults rather than the merchant's real settings. Storefronts
+   * can use this to hide or annotate the PayPal options instead of advertising
+   * methods that will fail once selected.
+   */
+  error: string | null
 }
 
 const MAX_CACHE_ENTRIES = 50
@@ -41,6 +48,7 @@ const DEFAULT_RESULT: Result = {
   cardEnabled: true,
   cardTitle: "Credit or Debit Card",
   loading: false,
+  error: null,
 }
 
 export function usePayPalPaymentMethods({
@@ -97,6 +105,7 @@ export function usePayPalPaymentMethods({
               ? cfg.card_title
               : "Credit or Debit Card",
           loading: false,
+          error: null,
         }
 
         cacheSet(k, { result: next, at: Date.now() })
@@ -112,12 +121,17 @@ export function usePayPalPaymentMethods({
             paypalEnabled: false,
             cardEnabled: false,
             loading: false,
+            error: msg || "PayPal is disabled",
           }
           setResult(disabled)
           return
         }
 
-        setResult({ ...DEFAULT_RESULT, loading: false })
+        setResult({
+          ...DEFAULT_RESULT,
+          loading: false,
+          error: msg || "Failed to load PayPal payment methods",
+        })
       }
     })()
 

package/src/index.ts

@@ -9,3 +9,8 @@ export * from "./adapters/MedusaNextPayPalAdapter"
 export * from "./components/PayPalPaymentSection"
 export * from "./hooks/usePayPalPaymentMethods"
 export { showProcessingOverlay, hideProcessingOverlay } from "./utils/processing-overlay"
+export {
+  markCartCaptured,
+  wasCartCaptured,
+  clearCartCaptured,
+} from "./utils/captured-state"

package/src/order.ts

@@ -24,8 +24,13 @@
  * </Text>
  */
 
-export const PAYPAL_WALLET_PROVIDER_ID = "pp_paypal_paypal"
-export const PAYPAL_CARD_PROVIDER_ID = "pp_paypal_card_paypal_card"
+import {
+  PAYPAL_WALLET_PROVIDER_ID,
+  PAYPAL_CARD_PROVIDER_ID,
+  isPayPalProviderId,
+} from "./constants"
+
+export { PAYPAL_WALLET_PROVIDER_ID, PAYPAL_CARD_PROVIDER_ID, isPayPalProviderId }
 
 export type PayPalPaymentInfo = { title: string }
 
@@ -41,14 +46,6 @@ export type PayPalConfigTitles = {
   card_title?: string | null
 }
 
-/** True when the provider id belongs to this PayPal plugin. */
-export function isPayPalProviderId(providerId?: string | null): boolean {
-  return (
-    providerId === PAYPAL_WALLET_PROVIDER_ID ||
-    providerId === PAYPAL_CARD_PROVIDER_ID
-  )
-}
-
 /**
  * Null-safe payment label resolver for order / confirmation pages.
  *

package/src/utils/captured-state.ts

@@ -0,0 +1,44 @@
+/**
+ * Per-cart "money was captured" flag, persisted in sessionStorage.
+ *
+ * The in-memory `capturedRef` protects a buyer within one page lifetime, but a
+ * reload/crash between the capture and the order finalization loses it — the
+ * buyer would then see fresh payment buttons for a cart whose money is already
+ * taken. Persisting the flag lets the components restore the finalize-only
+ * Retry path after a reload instead of offering a second payment.
+ *
+ * sessionStorage is deliberately chosen over localStorage: it is scoped to the
+ * tab/session, so an abandoned flag can't leak into a future visit after the
+ * cart id is reused, and it needs no expiry logic. Every access is guarded —
+ * private browsing modes and storage-blocking settings throw on access, and a
+ * storage failure must never break the payment flow.
+ */
+
+const KEY_PREFIX = "__pp_captured::"
+
+export function markCartCaptured(cartId: string): void {
+  if (!cartId) return
+  try {
+    window.sessionStorage.setItem(`${KEY_PREFIX}${cartId}`, String(Date.now()))
+  } catch {
+    // storage unavailable — in-memory state still covers the common path
+  }
+}
+
+export function wasCartCaptured(cartId: string): boolean {
+  if (!cartId) return false
+  try {
+    return window.sessionStorage.getItem(`${KEY_PREFIX}${cartId}`) !== null
+  } catch {
+    return false
+  }
+}
+
+export function clearCartCaptured(cartId: string): void {
+  if (!cartId) return
+  try {
+    window.sessionStorage.removeItem(`${KEY_PREFIX}${cartId}`)
+  } catch {
+    // ignore
+  }
+}

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
   }