@easypayment/medusa-payment-paypal 0.9.20 → 0.9.22

package/src/admin/routes/settings/paypal/connection/page.tsx

@@ -36,13 +36,18 @@ declare global {
 
 
 const SERVICE_URL = "/admin/paypal/onboarding-link"
-// The mini-browser popup is opened by us (see openOnboardingPopup). We give it a
-// stable window name so that, even if PayPal's partner.js *also* intercepts the
-// click, window.open() with the same name re-targets the one window instead of
-// spawning a second one.
-const POPUP_NAME = "PPMiniBrowser"
+// PayPal's conventional mini-browser window name; also used as the anchor's
+// `target` so partner.js opens the flow in a popup.
+const POPUP_NAME = "PPFrame"
+
+// The onboarding link is cached in the browser for 6 hours. This is the heart of
+// the integration: partner.js can only wire the mini-browser + completion
+// callback if the anchor already carries a valid onboarding href when partner.js
+// initializes. By caching the link (and reloading once to populate the cache on
+// a cold start) the link is always present on page load, so partner.js can take
+// over the click and run its flow exactly as documented.
 const CACHE_PREFIX = "pp_onboard_cache"
-const CACHE_EXPIRY = 10 * 60 * 1000
+const CACHE_EXPIRY = 6 * 60 * 60 * 1000 // 6 hours
 
 const ONBOARDING_COMPLETE_ENDPOINT = "/admin/paypal/onboard-complete"
 const STATUS_ENDPOINT = "/admin/paypal/status"
@@ -52,9 +57,9 @@ const ENVIRONMENT_ENDPOINT = "/admin/paypal/environment"
 
 type Env = "sandbox" | "live"
 
-// Onboarding URLs are environment-specific and short-lived, so the cache must be
-// keyed per environment — a single shared key let a stale sandbox URL leak into
-// the live flow (and vice-versa) after a reload.
+// Onboarding URLs are environment-specific, so the cache is keyed per
+// environment — a single shared key let a stale sandbox URL leak into the live
+// flow (and vice-versa).
 const cacheKeyFor = (env: Env) => `${CACHE_PREFIX}_${env}`
 
 function readCachedUrl(env: Env): string | null {
@@ -76,11 +81,14 @@ function readCachedUrl(env: Env): string | null {
   return null
 }
 
-function writeCachedUrl(env: Env, url: string) {
+// Returns true only if the value was actually persisted (storage enabled), which
+// lets the caller decide whether reloading to pick up the cache is safe.
+function writeCachedUrl(env: Env, url: string): boolean {
   try {
     localStorage.setItem(cacheKeyFor(env), JSON.stringify({ url, ts: Date.now() }))
+    return readCachedUrl(env) === url
   } catch {
-    /* ignore quota / disabled storage */
+    return false
   }
 }
 
@@ -97,84 +105,22 @@ function clearCachedUrl(env?: Env) {
   }
 }
 
-// PayPal delivers the seamless-onboarding result by posting a message to
-// window.opener. We validate the sender is actually a PayPal origin before
-// trusting authCode/sharedId.
-function isPayPalOrigin(origin: string): boolean {
-  try {
-    const host = new URL(origin).hostname.toLowerCase()
-    return (
-      host === "www.paypal.com" ||
-      host === "www.sandbox.paypal.com" ||
-      host.endsWith(".paypal.com") ||
-      host.endsWith(".paypalobjects.com")
-    )
-  } catch {
-    return false
-  }
-}
-
-// The completion message shape is not strongly documented, so extract
-// authCode/sharedId defensively from objects, JSON strings, or query strings.
-// We only ever act when BOTH values are present, which keeps the many unrelated
-// intermediate postMessages PayPal emits from triggering a false completion.
-function extractAuth(data: unknown): { authCode?: string; sharedId?: string } {
-  if (!data) return {}
-
-  if (typeof data === "object") {
-    const obj = data as Record<string, any>
-    const authCode = obj.authCode ?? obj.auth_code ?? obj.authcode
-    const sharedId = obj.sharedId ?? obj.shared_id ?? obj.sharedid
-    if (authCode && sharedId) {
-      return { authCode: String(authCode), sharedId: String(sharedId) }
-    }
-    for (const key of ["data", "payload", "message", "detail", "body"]) {
-      if (obj[key] && typeof obj[key] === "object") {
-        const inner = extractAuth(obj[key])
-        if (inner.authCode && inner.sharedId) return inner
-      }
-    }
-    return {}
-  }
-
-  if (typeof data === "string") {
-    const s = data.trim()
-    if (!s) return {}
-    if (s.startsWith("{")) {
-      try {
-        return extractAuth(JSON.parse(s))
-      } catch {
-        /* not JSON */
-      }
-    }
-    if (/auth_?code/i.test(s) && /shared_?id/i.test(s)) {
-      try {
-        const sp = new URLSearchParams(s.replace(/^[?#]/, ""))
-        const authCode = sp.get("authCode") || sp.get("auth_code") || undefined
-        const sharedId = sp.get("sharedId") || sp.get("shared_id") || undefined
-        if (authCode && sharedId) return { authCode, sharedId }
-      } catch {
-        /* not a query string */
-      }
-    }
-  }
-
-  return {}
-}
-
 
 export default function PayPalConnectionPage() {
   const [env, setEnv] = useState<Env>("live")
-  // We must not generate/fetch an onboarding link until we know which
-  // environment the server is actually on, otherwise the first fetch races the
-  // GET /environment response and can target the wrong environment.
+  // We must know the server's environment before generating/looking up a link so
+  // the per-environment cache and the generated link always match.
   const [envReady, setEnvReady] = useState(false)
 
   const [connState, setConnState] = useState<
     "loading" | "ready" | "connected" | "error"
   >("loading")
+  // True once partner.js has loaded and bound its click interceptor to the
+  // button. The button stays in the DOM but is not clickable until then, so a
+  // click can never fall through to the native anchor (which would open a tab
+  // without partner.js's onboarding flow / completion callback).
+  const [partnerReady, setPartnerReady] = useState(false)
   const [error, setError] = useState<string | null>(null)
-  const [popupBlocked, setPopupBlocked] = useState(false)
   const [finalUrl, setFinalUrl] = useState<string>("")
   const [showManual, setShowManual] = useState(false)
   const [clientId, setClientId] = useState("")
@@ -188,33 +134,16 @@ export default function PayPalConnectionPage() {
   const [onboardingInProgress, setOnboardingInProgress] = useState(false)
 
   const initLoaderRef = useRef<HTMLDivElement>(null)
-  const paypalButtonRef = useRef<HTMLAnchorElement | null>(null)
   const errorLogRef = useRef<HTMLDivElement>(null)
   const runIdRef = useRef(0)
   const currentRunId = useRef(0)
 
-  // Live mirrors of state so the document-level capture click listener (set up
-  // once) and the stable completion callback always see current values.
-  const finalUrlRef = useRef(finalUrl)
-  finalUrlRef.current = finalUrl
-  const connStateRef = useRef(connState)
-  connStateRef.current = connState
-  const inProgressRef = useRef(onboardingInProgress)
-  inProgressRef.current = onboardingInProgress
   const envRef = useRef<Env>(env)
   envRef.current = env
 
-  const popupRef = useRef<Window | null>(null)
-  const popupPollRef = useRef<ReturnType<typeof setInterval> | null>(null)
-  // Guards against the two redundant completion paths (our own message listener
-  // and partner.js's onboardingCallback bridge) both POSTing the same result.
+  // Guards against partner.js's bridge invoking the completion callback more
+  // than once.
   const completedRef = useRef(false)
-  // True once partner.js has initialized and bound its click interceptor to the
-  // button. When bound, partner.js opens the mini-browser AND wires its
-  // postMessage->onboardingCallback bridge (which auto-closes the popup and
-  // saves credentials), so we must NOT open a second window. Until it is bound
-  // (cold first click), we open the popup ourselves so the click still works.
-  const partnerBoundRef = useRef(false)
 
   const ppBtnMeasureRef = useRef<HTMLAnchorElement | null>(null)
   const [ppBtnWidth, setPpBtnWidth] = useState<number | null>(null)
@@ -228,196 +157,63 @@ export default function PayPalConnectionPage() {
     setError(msg)
   }, [])
 
-  const stopPopupPoll = useCallback(() => {
-    if (popupPollRef.current) {
-      clearInterval(popupPollRef.current)
-      popupPollRef.current = null
-    }
-  }, [])
-
-  // Open the PayPal mini-browser ourselves, synchronously, inside the click
-  // gesture. This is the crux of the fix: browsers only render window.open() as
-  // a real popup (instead of a tab — or blocking it) when it runs synchronously
-  // in a user gesture. Because finalUrl is already in state at click time, we
-  // never need an await before opening, and we never depend on winning a race
-  // with partner.js's asynchronous click binding.
-  const openOnboardingPopup = useCallback(
-    (url: string): Window | null => {
-      const w = 450
-      const h = 600
-      const baseLeft =
-        typeof window.screenX === "number" ? window.screenX : (window as any).screenLeft || 0
-      const baseTop =
-        typeof window.screenY === "number" ? window.screenY : (window as any).screenTop || 0
-      const outerW =
-        window.outerWidth || document.documentElement.clientWidth || 1024
-      const outerH =
-        window.outerHeight || document.documentElement.clientHeight || 768
-      const left = Math.round(baseLeft + Math.max(0, (outerW - w) / 2))
-      const top = Math.round(baseTop + Math.max(0, (outerH - h) / 2))
-      const features = `popup=yes,width=${w},height=${h},left=${left},top=${top},scrollbars=yes,resizable=yes`
-
-      let popup: Window | null = null
-      try {
-        popup = window.open(url, POPUP_NAME, features)
-      } catch {
-        popup = null
-      }
-
-      if (popup) {
-        popupRef.current = popup
-        try {
-          popup.focus()
-        } catch {
-          /* ignore */
+  // Generate a fresh onboarding link, cache it for 6 hours, then reload the page
+  // so that on the next load the cached link is already present for partner.js.
+  // If browser storage is unavailable we fall back to using the link in-place
+  // (no reload) so we can never get stuck in a reload loop.
+  const generateLinkAndReload = useCallback(
+    async (targetEnv: Env, runId: number) => {
+      if (initLoaderRef.current) {
+        const loaderText = initLoaderRef.current.querySelector("#loader-text")
+        if (loaderText) {
+          loaderText.textContent = "Generating onboarding session..."
         }
-        stopPopupPoll()
-        popupPollRef.current = setInterval(() => {
-          if (!popupRef.current || popupRef.current.closed) {
-            stopPopupPoll()
-          }
-        }, 1000)
       }
 
-      return popup
-    },
-    [stopPopupPoll]
-  )
-
-  // Exchange the seller authCode/sharedId for credentials. Reached from BOTH
-  // PayPal's partner.js bridge (window.onboardingCallback) and our own postMessage
-  // listener; completedRef makes it idempotent so we only POST once.
-  const completeOnboarding = useCallback(
-    async (authCode: string, sharedId: string) => {
-      if (!authCode || !sharedId) return
-      if (completedRef.current) return
-      completedRef.current = true
-
-      try {
-        window.onbeforeunload = null
-      } catch {
-        /* ignore */
-      }
-
-      const activeEnv: Env = envRef.current === "sandbox" ? "sandbox" : "live"
-
-      setOnboardingInProgress(true)
-      setConnState("loading")
-      setError(null)
-      setPopupBlocked(false)
-
       try {
-        const res = await fetch(ONBOARDING_COMPLETE_ENDPOINT, {
+        const res = await fetch(SERVICE_URL, {
           method: "POST",
           headers: { "content-type": "application/json" },
           credentials: "include",
-          body: JSON.stringify({ authCode, sharedId, env: activeEnv }),
+          body: JSON.stringify({ products: ["PPCP"], environment: targetEnv }),
         })
 
-        if (!res.ok) {
-          const txt = await res.text().catch(() => "")
-          throw new Error(txt || `Onboarding exchange failed (${res.status})`)
-        }
+        if (!res.ok) throw new Error(`Service returned ${res.status}`)
 
-        // Close the popup we opened, plus any partner.js-managed flow.
-        try {
-          popupRef.current?.close()
-        } catch {
-          /* ignore */
-        }
-        stopPopupPoll()
-        try {
-          const close1 = window.PAYPAL?.apps?.Signup?.MiniBrowser?.closeFlow
-          if (typeof close1 === "function") close1()
-        } catch {
-          /* ignore */
-        }
-        try {
-          const close2 =
-            window.PAYPAL?.apps?.Signup?.miniBrowser &&
-            (window.PAYPAL.apps.Signup.miniBrowser as any).closeFlow
-          if (typeof close2 === "function") close2()
-        } catch {
-          /* ignore */
-        }
-
-        clearCachedUrl(activeEnv)
+        const data = await res.json()
+        if (runId !== currentRunId.current) return
 
-        try {
-          const statusRes = await fetch(
-            `${STATUS_ENDPOINT}?environment=${activeEnv}`,
-            { method: "GET", credentials: "include" }
-          )
-          const refreshedStatus = await statusRes.json().catch(() => ({}))
-          setStatusInfo(refreshedStatus || null)
-        } catch {
-          /* ignore — still consider it connected below */
+        const href = data?.onboarding_url
+        if (!href) {
+          showError("Onboarding URL not returned.")
+          return
         }
 
-        setConnState("connected")
-        setShowManual(false)
-      } catch (e: any) {
-        // Allow a retry after a failed exchange.
-        completedRef.current = false
-        console.error(e)
-        setConnState("error")
-        setError(e?.message || "Exchange failed while saving credentials.")
-      } finally {
-        setOnboardingInProgress(false)
-      }
-    },
-    [stopPopupPoll]
-  )
-
-  const fetchFreshLink = useCallback(
-    (runId: number, targetEnv: Env) => {
-      if (initLoaderRef.current) {
-        const loaderText = initLoaderRef.current.querySelector("#loader-text")
-        if (loaderText)
-          loaderText.textContent = "Generating onboarding session..."
-      }
-
-      fetch(SERVICE_URL, {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        credentials: "include",
-        body: JSON.stringify({
-          products: ["PPCP"],
-          // Generate the link for the explicitly selected environment so it can
-          // never depend on a racing POST /environment having landed yet.
-          environment: targetEnv,
-        }),
-      })
-        .then((r) => {
-          if (!r.ok) throw new Error(`Service returned ${r.status}`)
-          return r.json()
-        })
-        .then((data) => {
-          if (runId !== currentRunId.current) return
-
-          const href = data?.onboarding_url
-          if (!href) {
-            showError("Onboarding URL not returned.")
-            return
-          }
+        const url =
+          href + (href.includes("?") ? "&" : "?") + "displayMode=minibrowser"
 
-          const url =
-            href + (href.includes("?") ? "&" : "?") + "displayMode=minibrowser"
+        const persisted = writeCachedUrl(targetEnv, url)
 
-          writeCachedUrl(targetEnv, url)
+        if (persisted) {
+          // The cache survived; reload so the link is present at first render and
+          // partner.js initializes against it. The post-reload load finds the
+          // cache (no regeneration), so this can't loop.
+          window.location.reload()
+          return
+        }
 
-          setFinalUrl(url)
-          setConnState("ready")
-        })
-        .catch(() => {
-          if (runId !== currentRunId.current) return
-          showError("Unable to connect to service.")
-        })
+        // Storage disabled — use the link directly without reloading.
+        setFinalUrl(url)
+        setConnState("ready")
+      } catch {
+        if (runId !== currentRunId.current) return
+        showError("Unable to connect to service.")
+      }
     },
     [showError]
   )
 
-  // Resolve the server's current environment before doing anything else.
+  // Resolve the server environment first.
   useEffect(() => {
     let alive = true
     fetch(ENVIRONMENT_ENDPOINT, { method: "GET", credentials: "include" })
@@ -435,14 +231,73 @@ export default function PayPalConnectionPage() {
     }
   }, [])
 
-  // partner.js is loaded ONLY for its postMessage->callback bridge
-  // (window.onboardingCallback), as a redundant path next to our own message
-  // listener below. It is NO LONGER responsible for opening the window — we do
-  // that synchronously in the click handler. We still init it so its message
-  // bridge registers inside this React SPA (its own DOMContentLoaded hook fired
-  // long before this route mounted). If partner.js also intercepts the click,
-  // the shared POPUP_NAME means it re-targets our single popup rather than
-  // opening a second window.
+  // Page-load flow:
+  //   1. If already connected, show the connected state.
+  //   2. Else if a valid cached link exists, use it (partner.js will bind it).
+  //   3. Else generate a link, cache it for 6h, and reload so the cached link is
+  //      present for partner.js on the next load.
+  useEffect(() => {
+    if (!envReady) return
+
+    currentRunId.current = ++runIdRef.current
+    const runId = currentRunId.current
+
+    let cancelled = false
+    completedRef.current = false
+
+    const run = async () => {
+      setConnState("loading")
+      setError(null)
+      setFinalUrl("")
+
+      try {
+        const r = await fetch(`${STATUS_ENDPOINT}?environment=${env}`, {
+          method: "GET",
+          credentials: "include",
+        })
+        const st = await r.json().catch(() => ({}))
+
+        if (cancelled || runId !== currentRunId.current) return
+
+        setStatusInfo(st)
+
+        const isConnected =
+          st?.status === "connected" && st?.seller_client_id_present === true
+
+        if (isConnected) {
+          setConnState("connected")
+          setShowManual(false)
+          return
+        }
+      } catch (e) {
+        console.error(e)
+      }
+
+      if (cancelled || runId !== currentRunId.current) return
+
+      const cached = readCachedUrl(env)
+      if (cached) {
+        setFinalUrl(cached)
+        setConnState("ready")
+        return
+      }
+
+      await generateLinkAndReload(env, runId)
+    }
+
+    run()
+
+    return () => {
+      cancelled = true
+    }
+  }, [env, envReady, generateLinkAndReload])
+
+  // Load partner.js once the anchor exists with its real (cached) href, then run
+  // PayPal's initializer. In a React SPA partner.js's own DOMContentLoaded hook
+  // already fired before this route mounted, so we must call init()/render()
+  // ourselves for it to discover the button and take over the click into the
+  // mini-browser — opening the popup, and wiring its postMessage bridge that
+  // invokes window.onboardingCallback and closes the popup on completion.
   useEffect(() => {
     if (connState !== "ready" || !finalUrl) return
 
@@ -450,6 +305,19 @@ export default function PayPalConnectionPage() {
     let cancelled = false
     let pollTimer: ReturnType<typeof setTimeout> | undefined
 
+    // The button is gated on partnerReady; reset it for this (re)load.
+    setPartnerReady(false)
+
+    // Safety net: if partner.js can't load (e.g. blocked), enable the button
+    // anyway after a few seconds rather than leaving it permanently disabled.
+    const readyFallback = setTimeout(() => {
+      if (!cancelled) setPartnerReady(true)
+    }, 6000)
+
+    const markReady = () => {
+      if (!cancelled) setPartnerReady(true)
+    }
+
     const initPartner = (attempt = 0) => {
       if (cancelled) return
 
@@ -464,26 +332,25 @@ export default function PayPalConnectionPage() {
       if (target?.init) {
         try {
           target.init()
-          // partner.js scans the DOM and binds the button synchronously inside
-          // init(), so from here a click is intercepted by partner.js (popup +
-          // callback bridge) and we should not also open our own window.
-          partnerBoundRef.current = true
         } catch (e) {
           console.error("[paypal] partner.js init failed:", e)
         }
+        markReady()
         return
       }
 
       if (typeof signup?.render === "function") {
         try {
           signup.render()
-          partnerBoundRef.current = true
         } catch (e) {
           console.error("[paypal] partner.js render failed:", e)
         }
+        markReady()
         return
       }
 
+      // The namespace may not be populated the instant onload fires; retry
+      // briefly before giving up.
       if (attempt < 40) {
         pollTimer = setTimeout(() => initPartner(attempt + 1), 50)
         return
@@ -492,12 +359,9 @@ export default function PayPalConnectionPage() {
       try {
         document.dispatchEvent(new Event("DOMContentLoaded"))
       } catch {}
+      markReady()
     }
 
-    // This load hasn't bound the button yet; until init() runs, a click should
-    // be handled by us (cold path) rather than assumed to reach partner.js.
-    partnerBoundRef.current = false
-
     // Remove any stale copy + namespace so the fresh load re-registers against
     // the current environment (sandbox vs live partner.js differ).
     const existingScript = document.getElementById("paypal-partner-js")
@@ -515,10 +379,12 @@ export default function PayPalConnectionPage() {
     ppScript.src = scriptUrl
     ppScript.async = true
     ppScript.onload = () => initPartner()
+    ppScript.onerror = () => markReady()
     document.body.appendChild(ppScript)
 
     return () => {
       cancelled = true
+      clearTimeout(readyFallback)
       if (pollTimer) {
         clearTimeout(pollTimer)
       }
@@ -528,81 +394,73 @@ export default function PayPalConnectionPage() {
     }
   }, [connState, finalUrl, env])
 
-  // Primary completion path: receive PayPal's seamless-onboarding postMessage
-  // ourselves. Independent of partner.js, so it works even when we opened the
-  // popup directly.
-  useEffect(() => {
-    const onMessage = (ev: MessageEvent) => {
-      if (!isPayPalOrigin(ev.origin)) return
-      const { authCode, sharedId } = extractAuth(ev.data)
-      if (authCode && sharedId) {
-        completeOnboarding(authCode, sharedId)
-      }
-    }
-    window.addEventListener("message", onMessage)
-    return () => window.removeEventListener("message", onMessage)
-  }, [completeOnboarding])
-
-  // Status check + link generation. Gated on envReady so we always use the
-  // correct environment. runId guards against a stale response from a previous
-  // environment overwriting the current one.
-  useEffect(() => {
-    if (!envReady) return
-
-    currentRunId.current = ++runIdRef.current
-    const runId = currentRunId.current
-
-    let cancelled = false
-    completedRef.current = false
+  // partner.js calls this (by the name in data-paypal-onboard-complete) when the
+  // seller finishes onboarding, passing the authCode + sharedId to exchange for
+  // seller credentials.
+  const completeOnboarding = useCallback(async (authCode: string, sharedId: string) => {
+    if (!authCode || !sharedId) return
+    if (completedRef.current) return
+    completedRef.current = true
 
-    const run = async () => {
-      setConnState("loading")
-      setError(null)
-      setPopupBlocked(false)
-      setFinalUrl("")
-
-      try {
-        const r = await fetch(`${STATUS_ENDPOINT}?environment=${env}`, {
-          method: "GET",
-          credentials: "include",
-        })
-        const st = await r.json().catch(() => ({}))
+    try {
+      window.onbeforeunload = null
+    } catch {}
 
-        if (cancelled || runId !== currentRunId.current) return
+    const activeEnv: Env = envRef.current === "sandbox" ? "sandbox" : "live"
 
-        setStatusInfo(st)
+    setOnboardingInProgress(true)
+    setConnState("loading")
+    setError(null)
 
-        const isConnected =
-          st?.status === "connected" && st?.seller_client_id_present === true
+    try {
+      const res = await fetch(ONBOARDING_COMPLETE_ENDPOINT, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        credentials: "include",
+        body: JSON.stringify({ authCode, sharedId, env: activeEnv }),
+      })
 
-        if (isConnected) {
-          setConnState("connected")
-          setShowManual(false)
-          return
-        }
-      } catch (e) {
-        console.error(e)
+      if (!res.ok) {
+        const txt = await res.text().catch(() => "")
+        throw new Error(txt || `Onboarding exchange failed (${res.status})`)
       }
 
-      if (cancelled || runId !== currentRunId.current) return
+      // Close the partner.js mini-browser.
+      try {
+        const close1 = window.PAYPAL?.apps?.Signup?.MiniBrowser?.closeFlow
+        if (typeof close1 === "function") close1()
+      } catch {}
+      try {
+        const close2 =
+          window.PAYPAL?.apps?.Signup?.miniBrowser &&
+          (window.PAYPAL.apps.Signup.miniBrowser as any).closeFlow
+        if (typeof close2 === "function") close2()
+      } catch {}
 
-      const cached = readCachedUrl(env)
-      if (cached) {
-        setFinalUrl(cached)
-        setConnState("ready")
-      } else {
-        fetchFreshLink(runId, env)
-      }
-    }
+      // The link has been consumed; drop it so a future flow regenerates one.
+      clearCachedUrl(activeEnv)
 
-    run()
+      try {
+        const statusRes = await fetch(`${STATUS_ENDPOINT}?environment=${activeEnv}`, {
+          method: "GET",
+          credentials: "include",
+        })
+        const refreshedStatus = await statusRes.json().catch(() => ({}))
+        setStatusInfo(refreshedStatus || null)
+      } catch {}
 
-    return () => {
-      cancelled = true
+      setConnState("connected")
+      setShowManual(false)
+    } catch (e: any) {
+      completedRef.current = false
+      console.error(e)
+      setConnState("error")
+      setError(e?.message || "Exchange failed while saving credentials.")
+    } finally {
+      setOnboardingInProgress(false)
     }
-  }, [env, envReady, fetchFreshLink])
+  }, [])
 
-  // Bridge partner.js's callback into our single idempotent completion handler.
   useLayoutEffect(() => {
     window.onboardingCallback = (authCode: string, sharedId: string) => {
       completeOnboarding(authCode, sharedId)
@@ -612,13 +470,6 @@ export default function PayPalConnectionPage() {
     }
   }, [completeOnboarding])
 
-  // Clean up the popup poll on unmount.
-  useEffect(() => {
-    return () => {
-      stopPopupPoll()
-    }
-  }, [stopPopupPoll])
-
   useLayoutEffect(() => {
     const el = ppBtnMeasureRef.current
     if (!el) return
@@ -644,40 +495,6 @@ export default function PayPalConnectionPage() {
     }
   }, [connState, env, finalUrl])
 
-  // Click handling for "Connect to PayPal".
-  //
-  // We always preventDefault so the native target can never open a new tab.
-  //
-  // - If partner.js has bound the button, its own click handler already ran (in
-  //   the capture/target phase, before this React bubble handler) and opened the
-  //   mini-browser AND wired its postMessage->onboardingCallback bridge — which
-  //   auto-closes the popup and saves credentials. We must NOT open a second
-  //   window, so we just return.
-  // - Otherwise (cold first click before partner.js finished initializing) we
-  //   open the popup ourselves so the click still works. Completion is then
-  //   handled by our own postMessage listener, and also by partner.js's bridge
-  //   once it finishes initializing a moment later.
-  const handleConnectClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
-    e.preventDefault()
-
-    if (
-      connStateRef.current !== "ready" ||
-      !finalUrlRef.current ||
-      inProgressRef.current
-    ) {
-      return
-    }
-
-    if (partnerBoundRef.current) {
-      // partner.js owns this click (popup + auto-close + callback bridge).
-      return
-    }
-
-    completedRef.current = false
-    const popup = openOnboardingPopup(finalUrlRef.current)
-    setPopupBlocked(!popup)
-  }
-
   const handleSaveManual = async () => {
     if (!canSaveManual || onboardingInProgress) return
     setOnboardingInProgress(true)
@@ -746,11 +563,12 @@ export default function PayPalConnectionPage() {
       }
 
       clearCachedUrl(env)
-
       completedRef.current = false
+
+      // Generate a fresh link for the now-disconnected environment and reload so
+      // the onboarding button is ready again.
       currentRunId.current = ++runIdRef.current
-      const runId = currentRunId.current
-      fetchFreshLink(runId, env)
+      await generateLinkAndReload(env, currentRunId.current)
     } catch (e: any) {
       console.error(e)
       setConnState("error")
@@ -762,18 +580,14 @@ export default function PayPalConnectionPage() {
 
   const handleEnvChange = async (e: React.ChangeEvent<HTMLSelectElement>) => {
     const next = e.target.value as Env
+    if (next === env || onboardingInProgress) return
 
     completedRef.current = false
-    setPopupBlocked(false)
-    // Drop both cached URLs so neither environment can serve a stale link.
     clearCachedUrl()
+    setConnState("loading")
 
-    // Update local state immediately (drives the status/link refetch with the
-    // explicit environment) and persist the choice. Because the link/status
-    // fetches are environment-explicit, correctness no longer depends on this
-    // POST winning a race.
-    setEnv(next)
-
+    // Persist the environment BEFORE switching local state so the post-reload
+    // GET /environment returns the same value the cache was keyed under.
     try {
       await fetch(ENVIRONMENT_ENDPOINT, {
         method: "POST",
@@ -782,6 +596,8 @@ export default function PayPalConnectionPage() {
         body: JSON.stringify({ environment: next }),
       })
     } catch {}
+
+    setEnv(next)
   }
 
   return (
@@ -860,9 +676,12 @@ export default function PayPalConnectionPage() {
                   </div>
 
                   <div className={`${connState === "ready" ? "block" : "hidden"}`}>
+                    {/* Standard PayPal partner onboarding button. partner.js binds
+                        this anchor (it carries the cached onboarding href) and
+                        takes over the click into the mini-browser; on completion
+                        it calls window.onboardingCallback. */}
                     <a
                       ref={(node) => {
-                        paypalButtonRef.current = node
                         ppBtnMeasureRef.current = node
                       }}
                       id="paypal-button"
@@ -870,24 +689,26 @@ export default function PayPalConnectionPage() {
                       data-paypal-button="true"
                       href={finalUrl || "#"}
                       data-paypal-onboard-complete="onboardingCallback"
-                      onClick={handleConnectClick}
+                      aria-disabled={onboardingInProgress || !partnerReady}
                       className="transition-fg relative inline-flex w-fit items-center justify-center overflow-hidden rounded-md outline-none no-underline shadow-buttons-neutral text-ui-fg-base bg-ui-button-neutral after:transition-fg after:absolute after:inset-0 after:content-[''] after:button-neutral-gradient hover:bg-ui-button-neutral-hover hover:after:button-neutral-hover-gradient active:bg-ui-button-neutral-pressed active:after:button-neutral-pressed-gradient focus-visible:shadow-buttons-neutral-focus disabled:bg-ui-bg-disabled disabled:border-ui-border-base disabled:text-ui-fg-disabled disabled:shadow-buttons-neutral disabled:after:hidden txt-compact-small-plus px-3 py-1.5"
                       style={{
-                        cursor: onboardingInProgress ? "not-allowed" : "pointer",
-                        opacity: onboardingInProgress ? 0.6 : 1,
-                        pointerEvents: onboardingInProgress ? "none" : "auto",
+                        cursor:
+                          onboardingInProgress || !partnerReady
+                            ? "not-allowed"
+                            : "pointer",
+                        opacity: onboardingInProgress || !partnerReady ? 0.6 : 1,
+                        // Keep the anchor mounted (partner.js must find it to bind)
+                        // but un-clickable until partner.js has taken over the
+                        // click — so it can never open a tab via the native href.
+                        pointerEvents:
+                          onboardingInProgress || !partnerReady ? "none" : "auto",
                       }}
                     >
-                      Connect to PayPal
+                      {partnerReady || onboardingInProgress
+                        ? "Connect to PayPal"
+                        : "Preparing PayPal…"}
                     </a>
 
-                    {popupBlocked && (
-                      <div className="mt-3 text-left text-xs bg-amber-50 text-amber-700 p-3 border border-amber-200 rounded">
-                        Your browser blocked the PayPal popup. Please allow popups
-                        for this site, then click “Connect to PayPal” again.
-                      </div>
-                    )}
-
                     <div
                       className="mt-2"
                       style={{