Description

This draft PR stacks the Headless Buy proof-of-concept work through Phase 4 on top of main. It continues the incremental sequence started by #29144 (Phases 1–3 + 3.1) and is intended for incremental review and CI validation before follow-up phases (Headless Host, skip-BuildQuote, routing callbacks).

Scope vs main (full branch)

• Phases 1–3 + 3.1 — unchanged from #29144 (playground, useHeadlessBuy, sessionRegistry, startHeadlessBuy, BuildQuote headlessSessionId plumbing).
• Phase 4 — this PR — pure refactor of the post-quote continuation logic. Extract handleWidgetProviderContinue (~111 lines) and handleNativeProviderContinue (~60 lines) plus the local navigateAfterExternalBrowser helper out of BuildQuote.tsx into a new useContinueWithQuote(quote, ctx) hook so both BuildQuote and the upcoming Headless Host (Phase 5) can drive the post-quote flow without copy-paste. No user-visible change and no new public surface — the hook is internal to app/components/UI/Ramp.

Diff vs previous POC branches (incremental)

Full branch vs main: main...poc/headless-buy-phase-4.

What Phase 4 actually does

• New app/components/UI/Ramp/hooks/useContinueWithQuote.ts:
  • Signature: useContinueWithQuote(): { continueWithQuote: (quote: Quote, ctx: { amount: number; assetId: string }) => Promise<void> }.
  • Internally dispatches via isNativeProvider(quote) to a private native path (Transak: checkExistingToken → getBuyQuote → routeAfterAuthentication, or EnterEmail / VerifyIdentity when unauthenticated) or widget path (fetch widget URL via getBuyWidgetData, then either in-app Checkout or external browser via Linking / InAppBrowser with a navigateAfterExternalBrowser reset).
  • Error contract: on failure the hook calls reportRampsError (preserves Logger/Sentry side effect) exactly once per failure and throws an Error whose message is a user-facing string. Widget path uses two sequential try/catch blocks (fetch, then use) so the no-URL branch can report with its own context without the outer catch double-reporting. Callers catch to drive their own UI.
  • Not managed by the hook: isContinueLoading, rampsError, and RAMPS_CONTINUE_BUTTON_CLICKED analytics. Those stay with the caller.
• Refactored app/components/UI/Ramp/Views/BuildQuote/BuildQuote.tsx:
  • Drops the two handlers, navigateAfterExternalBrowser, and the now-unused useTransakController / useTransakRouting / selectHasAgreedTransakNativePolicy / getBuyWidgetData / addPrecreatedOrder wiring (~18 imports removed).
  • handleContinuePress is now a thin wrapper: fires RAMPS_CONTINUE_BUTTON_CLICKED analytics, then awaits continueWithQuote(selectedQuote, { amount, assetId }) inside try/catch/finally around isContinueLoading and rampsError.
• Tests:
  • Three behavior describes migrated verbatim from BuildQuote.test.tsx into useContinueWithQuote.test.ts (native provider, widget provider, navigateAfterExternalBrowser), plus a new error contract describe asserting the thrown Error.message matches reportRampsError's return value and that reporting fires exactly once.
  • BuildQuote.test.tsx gets a slim handleContinuePress wiring describe that mocks useContinueWithQuote and asserts (a) correct args, (b) analytics fires before the hook call, (c) rejection surfaces in the rampsError banner, (d) no call when selectedProvider is null.
• PLAN.md: Phase 4 checkbox ticked. No body edits.

Intentionally out of scope for this PR (follow-up phases)

• Phase 4b — Headless Host screen + parameterized useTransakRouting reset base. The hook still reads currency / selectedToken.chainId / selectedPaymentMethod.id / selectedProvider.name from useRampsController — these will return null for headless callers who don't pre-seed the controller (Phase 3.1). A // TODO(phase-5) comment in the hook flags the debt.
• Phase 5 — Skip BuildQuote in headless mode; Headless Host consumes the hook directly.
• Phase 6 — Bypass order-processing redirect + fire onOrderCreated.

Changelog

CHANGELOG entry: (Internal) Extracted post-quote continuation logic from BuildQuote into a new useContinueWithQuote hook — no user-visible change.

Related issues

Fixes:

Jira: TRAM-3527

Manual testing steps

Feature: Buy flow regression (Phase 4 is a pure refactor — behavior must match main)

  Scenario: Aggregator widget provider (in-app Checkout)
    Given the user is on BuildQuote with a valid amount and an aggregator provider (e.g. MoonPay) selected
    When the user taps Continue
    Then the in-app Checkout WebView opens with the widget URL and correct provider branding
    And no rampsError banner is shown

  Scenario: Aggregator widget provider (external browser / PayPal custom action)
    Given the user is on BuildQuote with a valid amount and a widget provider with useExternalBrowser=true
    When the user taps Continue
    Then the widget URL opens in the external browser (or in-app browser when available)
    And on success the app resets to the order-details screen with the callback URL
    And on cancel the app resets back to BuildQuote

  Scenario: Native provider (Transak), authenticated
    Given the user is on BuildQuote with a valid amount and Transak selected
    And the user already has a valid Transak token
    When the user taps Continue
    Then a fresh Transak buy quote is fetched and the post-authentication flow advances (KYC / webview / bank details)

  Scenario: Native provider (Transak), unauthenticated — first time
    Given the user is on BuildQuote with a valid amount and Transak selected
    And the user has NOT agreed to the Transak native policy
    When the user taps Continue
    Then the VerifyIdentity screen opens with amount / currency / assetId

  Scenario: Native provider (Transak), unauthenticated — returning
    Given the user is on BuildQuote with a valid amount and Transak selected
    And the user has previously agreed to the Transak native policy
    When the user taps Continue
    Then the EnterEmail screen opens with amount / currency / assetId

  Scenario: Widget fetch error surfaces the same banner as before
    Given the user is on BuildQuote with a valid amount and a widget provider selected
    And the widget-data endpoint fails (e.g. network error, missing URL)
    When the user taps Continue
    Then the rampsError banner shows the same user-facing message as on main
    And the continue button becomes enabled again (spinner stops)

  Scenario: Headless Playground flow unchanged
    Given the user is on the Headless Buy playground (internal build)
    When the user taps Start headless buy and then Cancel headless session
    Then the session lifecycle + event log behaves exactly as on Phase 3 (BuildQuote opens, cancel fires onClose consumer_cancelled)

Screenshots/Recordings

Before

N/A

After

N/A — Phase 4 is a pure refactor. No UI changes.

Pre-merge author checklist

• I've followed MetaMask Contributor Docs and MetaMask Mobile Coding Standards.
• I've completed the PR template to the best of my ability
• I've included tests if applicable
• I've documented my code using JSDoc format if applicable
• I've applied the right labels on the PR (see labeling guidelines). Not required for external contributors.

Performance checks (if applicable)

• I've tested on Android
  • Ideally on a mid-range device; emulator is acceptable
• I've tested with a power user scenario
  • Use these power-user SRPs to import wallets with many accounts and tokens
• I've instrumented key operations with Sentry traces for production performance metrics
  • See trace() for usage and addToken for an example

For performance guidelines and tooling, see the Performance Guide.

Pre-merge reviewer checklist

• I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed).
• I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots.