feat(redirect): optional click-id passthrough on web destinations

[onamfc]

Summary

Adds an opt-in (default off) per-link capability to append ?lf_click=<click id> to HTTP(S) redirect destinations, so a downstream tool can correlate a landing visit back to the exact click that sent it (industry-standard click-id passthrough, à la gclid/fbclid).

Why / Usage

Every click is already recorded in click_events, but that click id never leaves the server - so a destination site can't tie a later conversion back to the specific click that drove it. This adds the standard click-identifier passthrough (the same pattern as gclid, fbclid, msclkid): when enabled, the redirect forwards the click's id on the destination URL as lf_click, so first-party analytics or your own backend can correlate the landing visit - and any downstream conversion - to that exact row in click_events. This makes per-click attribution possible without any extra server round-trip.

Example. A link points to https://shop.example/landing. With append_click_id enabled, the visitor lands on https://shop.example/landing?lf_click=<uuid>; the page reads the param and stores it alongside the resulting signup/purchase, so conversions can be attributed to individual clicks. It's opt-in and default-off, so destination URLs are left untouched unless you turn it on per link.

Details

• New links.append_click_id column, default false - the redirect never alters a destination's query string unless a link explicitly opts in. [CREATE TABLE] [idempotent ALTER]
• The click id is now generated up front (rather than defaulted by the DB on insert), so the synchronous 302 carries the same id the asynchronous click row is written with. [generate up front] [insert with id]
• Web/HTTPS destinations only. App-scheme / deep-link destinations are never modified. [passthrough]
• Stale-cache safe: an absent/false flag leaves the destination untouched. [guard]

Tests

npm test - 132 passing (incl. 32 redirect tests).

[codecov]

Codecov Report

❌ Patch coverage is 2.22222% with 44 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/routes/redirect.ts	3.84%	25 Missing ⚠️
src/lib/database.ts	0.00%	19 Missing ⚠️

📢 Thoughts on this report? Let us know!