feat(mobile): Plaid Link SDK cutover for Bridge external accounts [ENG-524]

[islandbitcoin]

Why

Client side of backend PR lnflash/flash#446 (deployed to TEST and PROD 2026-07-17), which replaced the hosted Bridge Plaid linkUrl webview with the Plaid Link SDK + server-side public_token exchange (the Api-Key never leaves the backend). Closes ENG-524.

Backend contract:

• bridgeAddExternalAccount returns linkToken: String! (+ expiresAt); linkUrl is nullable and @deprecated.
• bridgeExchangePlaidPublicToken(input: { linkToken, publicToken }): { errors, message }.
• Error codes BRIDGE_INVALID_PLAID_TOKEN, BRIDGE_PLAID_NOT_AVAILABLE.

What changed

• Dependency: react-native-plaid-link-sdk@12.8.3 (exact pin) — the last line with the classic imperative create()/open() API and no Expo-modules dependency.
• usePlaidLink hook (app/hooks/use-plaid-link.ts) owns the whole flow — extraction mirrors useBridgeKyc, and makes it testable. linkBankAccount is the full entry point (request linkToken → open Plaid Link → exchange; BRIDGE_PLAID_NOT_AVAILABLE → caller's manual-entry fallback), consumed by both entry points: TopupCashout's settle path and the Bank accounts hub's "Add bank account" CTA (device testing found the hub still went straight to the manual form — the path users with existing accounts actually take):
  • In-flight session guard: the SDK's native module is a singleton; a second create()/open() while a session is up cross-wires stored callbacks and {linkToken, publicToken} pairs. The guard spans the whole flow — including the link-token request, so a double-tap can't mint two tokens — until the session terminates.
  • Exit errors detected by content, not presence: the iOS bridge always embeds an error object with empty-string fields on a plain user cancel (Android omits the key). A real failure requires non-empty errorCode/errorMessage/displayMessage; the alert prefers Plaid's user-facing displayMessage. Cancels are silent on both platforms.
  • Success is decided by the exchange alone: after a clean bridgeExchangePlaidPublicToken, the onLinked refetch is best-effort — its failure is never reported as a link failure (which would invite re-linking and duplicate external accounts). The linked account arrives asynchronously via Bridge's external_account webhook; the success copy says it will appear shortly.
• TopupCashout.tsx: checkBridgeKyc requires linkToken (error alert if absent) and addExternalAccount is try/caught so a thrown mutation can't strand the activity spinner. The hosted-URL fallback branch is removed — against a pre-[Bug] - improve on-chain receive copy string to be compatible with CashApp #446 backend the linkToken-selecting operation fails validation entirely, so the branch was unreachable dead code, and the backend is deployed. The BridgeExternalAccountWebView screen/route stay registered (currently unreferenced) as an operational escape hatch until on-device SDK verification; removing them is a tracked follow-up.
• Schema snapshot + codegen regenerated; linkUrl is no longer selected anywhere, so its deprecation adds no new deprecated-field note — graphql-check output is unchanged from main (its one pre-existing note covers username/contacts/price-fragment fields untouched by this PR). BRIDGE_PLAID_NOT_AVAILABLE → manual bank entry path unchanged.
• i18n: all new user-facing copy under PlaidLink.* (en + 23 locales).
• jest: manual mock for the native module; the spec inventory lives in Testing below.

Testing

• __tests__/hooks/use-plaid-link.spec.tsx — 15 tests (plus a three-rung exit-copy case): six linkBankAccount cases (token→Plaid, manual fallback, payload error, missing token, thrown mutation, one-guard-across-request+session double-tap; each pins guard re-arm); exchange payload/variables, refetch settle-order pinned via a deferred promise (no success alert while the refetch is in flight), refetch-rejection-still-succeeds, payload-error and thrown-error paths (indicator always cleared, no refetch, guard re-arms for retry), in-flight guard with re-arm on every session-termination path (cancel exit, error exit, completed, failed), content-based exit errors preferring displayMessage, both platform cancel shapes silent.
• Full suite green (see CI); yarn tsc:check clean; changed files lint clean; translation-drift clean; codegen deterministic.
• Hardened by iterative multi-agent adversarial review until a clean round (findings verified against the vendored Plaid SDK 12.8.3 iOS/Android bridge sources; test findings verified by empirically running mutants). All code defects were confirmed and fixed in the first round; every later round confirmed only test-hardening and doc-wording findings.

Not in this PR / needs device testing

• OAuth-bank redirect config — iOS associated domains + AppDelegate redirect handler, Android intent-filter, plus a redirect URI registered in the Plaid dashboard. Non-OAuth Link works without it; tracked follow-up.
• Device/simulator run — pod install (autolinked) and an end-to-end link against TEST remain to be exercised before release. Expect [!] Plaid has been deprecated from pod install: the CocoaPods Plaid pod is deprecated upstream with no successor (Plaid moved iOS distribution to SPM); 6.4.7 — what ~> 6.4.3 resolves — is the final version it will ever carry. Harmless today; LinkKit updates beyond 6.4.7 arrive only via the RN SDK v13+ (Expo-modules) line, which is the eventual migration trigger.

🤖 Generated with Claude Code

[linear]

ENG-524