feat(username): claim a handle, and reach a tip card by it

[bmc08gt]

Usernames get an entry screen, a balance-gated nudge on the You tab, and a place in every surface that until now showed only an opaque user id. Figma nodes 9491:6295 through 9491:6299.

Claiming a handle

UpdateProfileStep.Username joins the update-profile stack as a conditional step alongside display name, so the same screen serves first-time setup and a later change. AppRoute.UpdateUserProfile gains includeUsername, threaded into buildUpdateUserProfileStack(includeName, includeUsername, includePhoto). Two entry points: the You tab's progress card (node 9491:6295) and a new Change Username row in My Account (node 9491:6297).

The server enforces a minimum balance on submit (SetUsernameError.InsufficientBalance). usernameGate(username, minimum, balance) reads the same usernameMinBalance flag locally so the card can show the distance rather than let someone type a handle into a rejection. It fails open on a zero or unresolved minimum, and clamps its progress fraction to 0f..1f — a negative balance previously drew the bar backwards.

Every rejection surfaces through showInfo, not showError: taken, too short, too long, reserved, moderated all describe what was typed and are fixed by typing something else, so the destructive style would read as a fault in the app. Only a failed check stays an error. Length is checked locally so "Too Short" and "Too Long" name the actual problem instead of arriving as a generic INVALID_USERNAME.

Addressing a tip card by handle

TipCardOwner is a sealed type — ById(userId) or ByUsername(username) — and replaces the bare ID at three seams: DeeplinkAction.PresentTipCard, SessionController.resolveTipCard, and Linkify.tipcard. Resolving a handle is a server round trip, so it stays a handle from the router all the way to the session, which owns the fetch.

The link row renders flipcash.com/sally_streamer whole (node 9442:3673) and abbreviates only an opaque id to app.flipcash.com/tip/b0ced… (node 9276:4753) — the handle is the point of claiming one, and cutting it would hide the part that identifies the person. The test is the handle's own shape, so nothing else is ever truncated.

flipcash.com/{username} deeplinks

A new autoVerify intent-filter claims flipcash.com and www.flipcash.com, narrowed to the handle charset with pathAdvancedPattern="/[a-z0-9_]{2,15}".

Android verifies App Links per host, not per path — assetlinks.json has no path scoping — and pathAdvancedPattern is API 31+ with no negative lookahead. So the website's own single-segment paths (/download, /privacy, /terms) satisfy the filter too. AppRouter keeps the reserved list and answers those with DeeplinkAction.OpenExternally, which hands the URL to a named browser rather than dead-ending the tap on the home screen. It has to be named: a package-less ACTION_VIEW on a host we are a verified handler for resolves straight back to us and loops.

This differs from iOS deliberately — their AASA supports path exclusions, so the same list lives in their apple-app-site-association file rather than in code. iOS also makes no www.flipcash.com claim; if that stays true the two platforms will disagree about www links.

Following your own handle

Two self-checks already existed, in AppRouter and in TipCardOwner.isSelf, and both compare handles — which they cannot do until this account's own profile has loaded. That is exactly the window a cold-started link lands in, so a link to your own handle got past both.

TippingCoordinator.resolveTipCard now compares the id off the wire after the fetch and raises OwnTipCard, which TipCardDelegate answers with TipCardEvent.OwnCardScanned — the same answer as the pre-dispatch guard. Raised as a failure rather than returning a card so the resolve stops short of its side effects (arming the tip modal, vibrating) for a card nobody will tip. Mirrors iOS TipFlow.prepare's second guard.

Elsewhere

• ChatParticipant.handle exposes the handle to chat rows; Handle.kt centralises the @ prefix, the length bounds, and the shape regex that all three consumers depend on.
• Analytics.AddMoneySource.UsernameShortfall reports a deposit prompted by the gate, so it is not counted as a deliberate visit to Add Money. The wire string matches iOS.

Depends on

assetlinks.json must be served from https://flipcash.com/.well-known/ before Android will verify the new host. Until it is, the links open in a browser instead of the app.