feat: searches can carry a partner code, so a search deal can pay us

[aamancio]

Part 1 of candoa-cloud#37 — the precondition for search-deal revenue.

Why

An engine pays for traffic it can attribute to us, and the only thing that reaches it is the search URL. So the code it issues has to ride in that URL. SearchProvider.searchURL(for:) appended just the query, which meant Candoa could not have accepted a deal if one were offered today.

What changed

SearchPartnerCode carries the engine's own parameter name — DuckDuckGo reads t, Ecosia reads tt — because the name is the engine's choice, not ours.

It also carries an expiry, which is not decoration: search deals lapse. Vivaldi moved its default off Bing in some regions when that deal ended. A code that outlives its deal tags every search for a partner who is no longer paying for it. Codes arrive as configuration rather than living in the binary, so one can be issued, rotated, or revoked without shipping a release.

Partner codes are a required argument, deliberately

A call site that forgot an optional partnerCodes: would still return a perfectly good search URL — the search works, the money quietly doesn't. That failure is invisible in testing and in production. Making it required means the compiler asks at every site.

It immediately earned its keep: WebViewCoordinator.searchInNewTab was building a search URL directly off the provider rather than through NavigationService, so it would have been the one path silently dropping the code. It now routes through the service like every other search.

Behaviour today: none

No deal exists, so partnerCodes is .none, nothing is appended, and a search URL is byte-for-byte identical to before. That's asserted rather than assumed — testSearchURLIsUnchangedWithNoPartnerCode pins the exact query items.

No privacy-policy change ships with this, because nothing new leaves the machine yet. The policy line lands with the commit that activates a real code, per the standing rule.

Tests

CandoaTests: 101 passed (94 + 7), Debug build clean.

• no code → URL unchanged, exact query items pinned
• code appended under the engine's own parameter name
• each engine names its own parameter (t vs tt)
• an expired code is not sent
• a code is sent right up to its expiry
• a code for one engine never leaks onto another
• a code joins query items the engine's own base URL already requires

Next in #37

Search volume per provider, and the privacy-policy line that ships with it. Also open: the default is Google, the one major engine that doesn't pay independents — so most search volume currently routes to the non-paying option.

🤖 Generated with Claude Code