feat(redirect): isWebLinkRequest hook for hosts reserved for web links; remove web-only templates

[onamfc]

Replaces the template-level webOnly flag from 1.29.0 (#64) with a host-level hook.

Why

The template flag couldn't keep its promise. It relied on excluding the template's path from apple-app-site-association and assetlinks.json, but:

• iOS and Android act on cached copies of those files, which they refresh on their own schedule (hours or longer).
• Android 14 and earlier ignore the exclusions entirely.

So a link documented as "never opens the app" could still open it, with nothing an operator can do to speed that up.

What does keep a link in the browser immediately, on every OS version, is a host the app doesn't claim. The redirect still has to cooperate: without that, a mobile visitor on such a host can be sent to the Launchpad page or a store. That cooperation is now keyed on the host.

Changes

• New option RedirectRouteOptions.isWebLinkRequest(request). When it returns true, every link sends every device to its web destination (the desktop destination: web_fallback_url chain, else original_url, decorated with UTM, deep link parameters and click id) as a plain 302. No Launchpad page, no scheme interstitial, no store.
  • Click events record the reason web_link_host.
  • A hook that throws is logged and treated as false.
  • Documented in the README and llms.txt, with the advice to serve no association files on that host.
• Removed: settings.webOnly on templates, isWebOnlyTemplate, buildAppleAppSiteAssociation, buildAssetLinks and AASA_EXCLUSION_BUDGET_BYTES. The well-known routes go back to claiming every path, without a database lookup.
  • well-known.ts, templates.ts, types/index.ts and index.ts are byte-for-byte what they were in 1.28.2.

Compatibility

• Removing exports is technically breaking.
• They were published two days ago, and their behaviour (excluding paths from the association files) is exactly what's being withdrawn. So this ships as a minor rather than a major.
• A template that still has settings.webOnly: true stored is ignored.

Tests

• redirect.web-link.test.ts:
  • iPhone, Android, an iOS in-app browser and desktop all 302 to the web on the reserved host, including with Launchpad page mode and with store, scheme and Universal Link set;
  • destination order with UTMs;
  • the same link on another host still gets the Launchpad page;
  • a throwing hook is treated as false.
• Full suite: 402 passed. tsc clean.

[codecov]

Codecov Report

❌ Patch coverage is 58.00000% with 21 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/routes/well-known.ts	0.00%	21 Missing ⚠️

📢 Thoughts on this report? Let us know!