feat(analytics): visitor sources — referrer + UTM, aggregate-only

[thunpisit]

Adds a visitor sources view to the admin: where traffic comes from, over a 30-day window.

Storage shape is the privacy guarantee

visitor_sources (migration 0034) is keyed on the whole dimension tuple — (date, channel, source, medium, campaign, path) — with count as the only payload. Every landing UPSERTs into an existing bucket; there is no append path.

That is what makes journey reconstruction impossible rather than merely discouraged:

• no id, no session column — nothing links two landings together
• no timestamp finer than the UTC date — so rows cannot be sorted into a sequence
• no IP, user agent, fingerprint or country
• no full referring URL — a referrer arrives as https://www.google.co.th/search?q=<what they typed> and is reduced to the token google before anything is stored

A row says "N landings matched this description that day". It cannot say who, in what order, or whether N was one person N times or N people once. No session id was needed, and none was added.

Consent

Gated identically to trackView: no consent.analytics means no row and no D1 round-trip at all. A test counts prepare() calls on the D1 shim and asserts zero, so "write it then delete it later" cannot regress in.

Bounded cardinality

source, medium and campaign are partly attacker-supplied via utm_*. Each is lower-cased, held to ^[a-z0-9._+-]+$ and 64 chars, and bucketed to other otherwise — so a ?utm_source=<random> spray collapses into a single row (pinned by a test). Unknown referrer hostnames go through the same funnel.

Spoofing fix: the multi-TLD engine matcher used a substring test, so google.com.evil.example classified as organic Google traffic — anyone with a domain could forge a Referer and write their own source name into the reports. Matching now requires the engine label to own the registrable domain.

UI

A new page at /admin/analytics (editor+), not the dashboard:

• /admin/reports is shop-plugin-gated, so general site analytics cannot live there — it has to survive a site that sells nothing
• a concurrent branch is redesigning /admin/dashboard; this avoids the collision (the dashboard is untouched)
• it is a five-table drill-down that wants wide, while the dashboard is a scannable card summary

Channel breakdown, top sources, top campaigns, top landing pages, and a 30-day series, via PageShell(wide) / PageHeader / DataTable. Internal navigation is excluded from the source and landing-page tables — moving between our own pages is not an acquisition — but stays visible as its own channel row.

Message keys added to both en and th, additions only.

Docs

docs/ANALYTICS.md — what is captured and, at length, what is deliberately not, plus the cardinality strategy.

Verification

Gate: lint 0 errors · check 0 errors · 1126 tests passing (1114 pre-existing + 12 new, 79 files) · build clean · contract-guard OK (additions only) · css-inventory OK (+1 class, no re-baseline).

Driven end-to-end against wrangler dev --local with real D1 and varied referrers/UTMs:

Property	Result
No-consent request	no row written
google.co.th/search?q=very+private+terms	stored as source google — search terms absent
google.com.evil.example	referral, not organic Google
8 × 80-char random utm_source	collapsed to one other row, count 8
channels / campaigns / internal	classified correctly

Not merged, not deployed.

🤖 Generated with Claude Code