feat(inbox): migrate the inbox socket from legacy to iwpv=v2

[mikemilla]

Ticket: C-19800

Important

Do not merge before trycourier/services#1527 is deployed. The server downgrades an unrecognized iwpv to the legacy protocol rather than rejecting the connection, so shipping this first would silently move clients onto the legacy shape with no error.

This is "Riley's changes"

InboxMessage.clickTrackingId has carried // TODO: Make this cleaner. Need Riley's Changes. for a long time. This is that change.

The reason it existed: this SDK sent no iwpv query parameter at all, which the server treats as the legacy protocol. On legacy the socket nests tracking ids under data while the GraphQL read returns them at the root — so the property had to check both places and guess:

val clickTrackingId: String? get() = trackingIdsData?.get("clickTrackingId") as? String ?: trackingIds?.clickTrackingId

Legacy → v2 is a protocol change, not a version bump

All four pieces have to move together:

	before (legacy)	after (iwpv=v2)
URL	?auth=… only	+ cid and + iwpv — the IWP handler rejects a connection missing either
Subscribe	{action, data}, no tid	IWP envelope: tid + action at root
Heartbeat	{action:"keepAlive"}	IWP ping, and answers server pings
Frame	message fields at the frame root	{"event":"message","iwpv":"v2","data":{…}}

Details worth flagging in review:

• cid on the client-key path. buildUrl previously returned before any params were appended on that branch. A client id is also generated when the caller never set connectionId, so that path yields a valid connection rather than a rejected one.
• Answering pings is mandatory. The server terminates a connection that fails to pong within its timeout, echoing the tid it's waiting on. A v2 client that ignores pings gets dropped mid-session.
• keepAlive had to go. It isn't a valid IWP action and carries no tid, so under v2 it would fail envelope validation and return an error frame every interval. It's now an IWP ping.
• Control frames are parsed first. A ping has no event, so if it fell through to the message decode it would surface as a spurious error every heartbeat.
• version: on sendSubscribe is retained but no longer sent — the server hardcodes clientVersion for every IWP subscription, so passing it implied a negotiation that doesn't happen. Kept in the signature for source compatibility.

The fallback removal is safe because of the protocol move

clickTrackingId now reads the root-level value only. Dropping the nested branch on its own would have broken click tracking outright, since on legacy the nested copy is the only one present. The two changes are not separable.

A mismatched iwpv on an incoming frame is logged — without it, a silent downgrade stays invisible until tracking quietly stops.

Tests

11 new JVM unit tests via :android:testDebugUnitTest — 11 tests, 0 failures, full unit suite still green:

• protocol version and cid present on both auth paths; generated client id when connectionId is unset; JWT auth preserved
• root-level tracking id read; nested-only copy correctly ignored (asserts the fallback is really gone); null when absent
• canonical frame decodes the message from data, incl. trackingIds and the promoted-key-free data
• ping and ack decode as control frames

Not verified

Superseded — dev is healthy again (inbox-dev UPDATE_COMPLETE, ws-api task def rev 52, 1/1 running). The earlier blocker was not what I first diagnosed: the working DRAGONFLY_API_KEY lives in 1Password, and the /courier/dev/dragonfly/* entries in SSM/Secrets Manager describe a different Dragonfly instance than dev dials, which is why they returned WRONGPASS rather than being merely stale. The C-19789 trackingIds lift is now confirmed on a live dev socket end to end.

🤖 Generated with Claude Code

[linear]

C-19800

[mikemilla]

Parking this PR during a PR-cleanup pass. The branch is kept (not deleted) and the work is tracked in C-19800 (cycle 367). Reopening restores everything — branch, commits, and this thread.