feat(invite): invite/refer-a-friend mobile client

[islandbitcoin]

Invite / refer-a-friend — mobile client

The mobile half of the invite/refer feature, freshly grafted onto current main (RN 0.77). Pairs with the backend lnflash/flash#462 and the ops page lnflash/frappe-flash-admin#57.

What's here

• Invite flow: InviteFriend screen (Contacts / WhatsApp / Email methods), InviteFriendSuccess, a contact picker, and email/phone inputs.
• Deep-link redemption: HandleInviteDeepLink + InviteDeepLinkHandler — parses flash://invite?token=…, stores the token, previews the invite, and redeems on onboarding (welcome.tsx), routing new users into registration with the invite context.
• Wiring: GraphQL ops (createInvite, redeemInvite, invitePreview), generated types, i18n strings, navigation (routes + deep-link skip), a Settings entry, and a Home-screen QuickStart entry.

How it was built

This branch was re-grafted onto current main rather than merged from the ~8-month-old original branch (which was pinned to RN 0.72). The graft kept npubByUsername (the old branch's diff wrongly deleted it), hand-grafted the generated GraphQL types (the backend invite schema isn't in the published schema yet), and added the native bits (contacts permission, a separate flash://invite Android intent that leaves the widget deep-link untouched).

Tests

• 18 green: InviteFriend (5), InviteFriendSuccess (3), HandleInviteDeepLink/redeemPendingInvite + deep-link parsing (10).
• yarn jest app/screens/invite-friend/
• Full tsc --noEmit clean across the app.

Notes for review

• Gated on the backend: the GraphQL ops call schema types that ship in flash#462 — the feature only works end-to-end once that's merged + deployed.
• iOS build not verified here (no Xcode/bench in the build environment); pod install ran clean and regenerated Podfile.lock. react-native-permissions ^4.1.5 may want a v5 bump for RN 0.77's New Architecture at build time (JS API is stable v4→v5, so it doesn't affect the graft).
• Deliberately skipped: the 4 phone-auth pre-fill deltas from the old branch — they alter a shared auth-hook signature main has evolved and are only UX polish (deep-link redemption works without them; the route params degrade gracefully).

Activation dependency (out of repo)

The backend sends invite links as https://getflash.io/invite?token=…. The app registers only the flash://invite scheme — HTTPS links require either a getflash.io/invite landing page that redirects to flash://invite?token=… (recommended, no app change) or App Links / Universal Links (assetlinks.json + AASA served on getflash.io). Until one exists, HTTPS invite links open the browser, not the app.

Post-review hardening (Simon review, addressed)

• Launch URL is processed exactly once (no token resurrection or spurious alerts on auth flips).
• Token parsing is format-agnostic ([^&#\s]+ + decode) — the backend owns validation.
• The pending token is stored only for unauthenticated sessions, as {token, storedAt} with a 24h TTL — no cross-account leak.
• The stored token is cleared only on success or terminal errors; transient failures keep it for retry. In-flight guard prevents double redemption.
• Dead X-Invite-Recipient header, dead getStarted invite branch, and unused invite route params removed.

🤖 Generated with Claude Code

https://claude.ai/code/session_01C7z7o9J18BWbUnYJcemMtg

[islandbitcoin]

🎤 Simon Review — mobile client

Adversarial senior review.

Verdict: NEEDS WORK

The InviteFriend create-invite screen and redeemPendingInvite are solid and well-tested. But the deep-link entry and redemption layer — the part that actually onboards a referred user — has a cluster of real correctness bugs. It's gated on the backend so nothing's on fire, but it is below the bar as-is.

Blocking

1. app/screens/invite-friend/HandleInviteDeepLink.tsx:41 — invite links are https://getflash.io/invite?… per the code's own comment, but nothing registers HTTPS links with either OS. Android adds only a flash://invite scheme filter; iOS adds no associated-domains/AASA. Custom flash:// schemes aren't tappable in WhatsApp/SMS/email — the primary delivery channels — so a real invite opens Safari, not the app, and redemption never starts. Confirm what the backend notification emits: if https, this is a hard blocker (register Android App Links + iOS Universal Links); if genuinely flash://, delete the misleading https claim.
2. HandleInviteDeepLink.tsx:19-35 — the deep-link effect keys on isAuthed and re-runs Linking.getInitialURL(), which keeps returning the launch URL for the whole process, re-storing the just-redeemed token and firing a wrong "new users only" alert at the user who just onboarded. Process the initial URL once (ref guard), and don't setItem the token in the pre-auth branch.

Should fix

3. HandleInviteDeepLink.tsx:56 — invite token is stored globally in AsyncStorage before the auth check and never namespaced/expired, so it leaks across accounts. An already-authed user taps an invite → token stored, never cleared → next login of a different account on that device redeems it, crediting the referral to the wrong person. Namespace + expire the token; never store it for an already-authed session.
4. HandleInviteDeepLink.tsx:45 — token regex is ([a-f0-9]{40}), unanchored. It matches the backend's current 20-byte hex token, but any change (UUID, uppercase, base64url) silently no-matches (dead-end, no alert), and a longer token is truncated to 40 chars and sent anyway. Capture generically ([^&#\s]+) and let the backend validate.
5. HandleInviteDeepLink.tsx:148 — token removeItem'd before checking success, so a transient/server error in errors[] burns a valid invite forever. Only clear on success or known-terminal errors.
6. app/screens/get-started-screen/get-started-screen.tsx:82-96 — the invite-token registration branch is dead code (nothing navigates to getStarted with those params; redemption actually runs via AsyncStorage + Welcome). Delete it or wire it; as-is it's misleading and untested.

Notes

• Deep-link tests cover redeemPendingInvite well but skip the risky useInviteDeepLink paths (malformed token, authed-user branch, invitePreview.isValid===false, phone-flow nav) — exactly where the bugs above live.
• X-Invite-Recipient: true (:63) is client-spoofable; confirm the backend doesn't widen invitePreview.contact based on it.

---

🤖 Simon-style adversarial review generated with Claude Code. Findings are advisory — verify before acting.