Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
feat(ok): download click-source attribution end to end (#2427)
Andrew Mikofalvy53890844a941
diff --git a/docs/src/app/continue/page.tsx b/docs/src/app/continue/page.tsxindex 14eeb7e57..320b2979a 100644--- a/docs/src/app/continue/page.tsx+++ b/docs/src/app/continue/page.tsx@@ -9,7 +9,7 @@ import {PENDING_SHARE_COOKIE,PORT_PARAM,} from '@/lib/deferred-share';-import { DOWNLOAD_ROUTE } from '@/lib/site';+import { downloadRouteForCta } from '@/lib/site';export const dynamic = 'force-dynamic';@@ -80,7 +80,7 @@ export default async function ContinuePage({ searchParams }: ContinuePageProps)<br />Don’t have the app yet?{' '}<a- href={DOWNLOAD_ROUTE}+ href={downloadRouteForCta('continue-page')}className="font-medium text-slide-text underline underline-offset-4 transition-colors hover:text-primary">Download it for macOSdiff --git a/docs/src/app/d/[encoded]/download/route.test.ts b/docs/src/app/d/[encoded]/download/route.test.tsindex 52f2c6a6f..5799d243a 100644--- a/docs/src/app/d/[encoded]/download/route.test.ts+++ b/docs/src/app/d/[encoded]/download/route.test.ts@@ -9,11 +9,14 @@ type CaptureOpts = {properties?: Record<string, string | undefined>;};let _lastCapture: CaptureOpts | null = null;+let _isPrefetch = false;mock.module('../../../../lib/track.ts', () => ({captureServerEvent: (opts: CaptureOpts) => {_lastCapture = opts;},resolveDistinctId: () => 'splash-1',+ attribution: () => ({ referrer: 'openknowledge.ai', utm_content: 'should-be-overridden' }),+ isPrefetchRequest: () => _isPrefetch,}));// Flip the decoded-share outcome per test.@@ -45,7 +48,8 @@ describe('GET /d/[encoded]/download', () => {expect(res.headers.get('set-cookie')).toContain('ok-pending-share=valid-share');expect(_lastCapture?.event).toBe('dmg_downloaded');expect(_lastCapture?.properties?.channel).toBe('stable');- expect(_lastCapture?.properties?.source).toBe('share-splash');+ // Server-authoritative: overrides the attribution() value.+ expect(_lastCapture?.properties?.utm_content).toBe('share-splash');expect(_lastCapture?.distinctId).toBe('splash-1');});@@ -57,7 +61,7 @@ describe('GET /d/[encoded]/download', () => {expect(res.headers.get('location')).toBe(SPLASH_URL);expect(res.headers.get('set-cookie')).toBeNull();expect(_lastCapture?.event).toBe('dmg_downloaded');- expect(_lastCapture?.properties?.source).toBe('share-splash');+ expect(_lastCapture?.properties?.utm_content).toBe('share-splash');});test('unsupported-version share: no cookie, still counts', async () => {@@ -68,4 +72,18 @@ describe('GET /d/[encoded]/download', () => {expect(res.headers.get('set-cookie')).toBeNull();expect(_lastCapture?.event).toBe('dmg_downloaded');});++ test('a prefetch still redirects (with cookie) but is NOT counted', async () => {+ _viewKind = 'ok';+ _lastCapture = null;+ _isPrefetch = true;+ try {+ const res = await call('valid-share');+ expect(res.status).toBe(302);+ expect(res.headers.get('location')).toBe(SPLASH_URL);+ expect(_lastCapture).toBeNull();+ } finally {+ _isPrefetch = false;+ }+ });});diff --git a/docs/src/app/d/[encoded]/download/route.ts b/docs/src/app/d/[encoded]/download/route.tsindex 710e55f4d..0550f5fd6 100644--- a/docs/src/app/d/[encoded]/download/route.ts+++ b/docs/src/app/d/[encoded]/download/route.ts@@ -1,7 +1,7 @@import { NextResponse } from 'next/server';import { buildPendingShareCookie } from '@/lib/deferred-share';import { buildSplashViewModel, SPLASH_DOWNLOAD_URL } from '@/lib/share-splash';-import { captureServerEvent, resolveDistinctId } from '@/lib/track';+import { attribution, captureServerEvent, isPrefetchRequest, resolveDistinctId } from '@/lib/track';/*** `GET /d/<encoded>/download` — the splash Download CTA target.@@ -25,11 +25,16 @@ export async function GET(response.cookies.set(buildPendingShareCookie(encoded));}- captureServerEvent({- event: 'dmg_downloaded',- distinctId: resolveDistinctId(request),- properties: { channel: 'stable', source: 'share-splash' },- });+ // A prefetch is not a download — redirect it, don't count it. `utm_content`+ // is server-authoritative here (this route IS the share-splash CTA), so it+ // wins over any `?utm_content=` on the request.+ if (!isPrefetchRequest(request)) {+ captureServerEvent({+ event: 'dmg_downloaded',+ distinctId: resolveDistinctId(request),+ properties: { channel: 'stable', ...attribution(request), utm_content: 'share-splash' },+ });+ }return response;}diff --git a/docs/src/app/d/[encoded]/splash-share-view.tsx b/docs/src/app/d/[encoded]/splash-share-view.tsxindex dc4834134..8cf953b58 100644--- a/docs/src/app/d/[encoded]/splash-share-view.tsx+++ b/docs/src/app/d/[encoded]/splash-share-view.tsx@@ -5,7 +5,7 @@ import { SiteFooter } from '@/components/footer';import { GitHubIcon } from '@/components/icons/github';import { OkWordmark } from '@/components/ok-wordmark';import { buildCloneCommand, SPLASH_INSTALL_COMMAND, type SplashView } from '@/lib/share-splash';-import { DOWNLOAD_ROUTE } from '@/lib/site';+import { downloadRouteForCta } from '@/lib/site';import { SplashButtonLabel, splashPrimaryButton } from './splash-buttons';import { SplashCliButton } from './splash-cli-button';import { SplashCtaPanel } from './splash-cta-panel';@@ -140,7 +140,7 @@ export function SplashFallback({ heading }: { heading: string }) {</h1><div className="mt-10 flex flex-wrap items-center gap-4">- <a href={DOWNLOAD_ROUTE} className={splashPrimaryButton}>+ <a href={downloadRouteForCta('share-splash-fallback')} className={splashPrimaryButton}><SplashButtonLabel direction="down">DOWNLOAD FOR MAC</SplashButtonLabel></a><SplashCliButton installCommand={SPLASH_INSTALL_COMMAND} />diff --git a/docs/src/app/download/beta/route.test.ts b/docs/src/app/download/beta/route.test.tsindex abf73d77d..21560e5c2 100644--- a/docs/src/app/download/beta/route.test.ts+++ b/docs/src/app/download/beta/route.test.ts@@ -38,7 +38,8 @@ mock.module('../../../lib/track.ts', () => ({_lastCapture = opts;},resolveDistinctId: () => 'visitor-9',- referrerHostname: () => undefined,+ attribution: () => ({ sec_fetch_site: 'none' }),+ isPrefetchRequest: (request: Request) => request.headers.get('sec-purpose') === 'prefetch',}));// Dynamic import ensures route.ts imports the mocked modules above.@@ -80,4 +81,17 @@ describe('GET /download/beta', () => {expect(res.headers.get('cache-control')).toBe(FALLBACK_CACHE_CONTROL);expect(_lastCapture).toBeNull();});++ test('a prefetch still redirects but is NOT counted', async () => {+ _redirect = { kind: 'fresh', url: TEST_DMG_URL };+ _lastCapture = null;+ const res = await GET(+ new Request('https://openknowledge.ai/download/beta', {+ headers: { 'sec-purpose': 'prefetch' },+ }),+ );+ expect(res.status).toBe(302);+ expect(res.headers.get('location')).toBe(TEST_DMG_URL);+ expect(_lastCapture).toBeNull();+ });});diff --git a/docs/src/app/download/beta/route.ts b/docs/src/app/download/beta/route.tsindex 6150c4bc9..e15151d15 100644--- a/docs/src/app/download/beta/route.ts+++ b/docs/src/app/download/beta/route.ts@@ -1,5 +1,5 @@import { createBetaResolver, toRedirectResponse } from '@/lib/download-links';-import { captureServerEvent, referrerHostname, resolveDistinctId } from '@/lib/track';+import { attribution, captureServerEvent, isPrefetchRequest, resolveDistinctId } from '@/lib/track';/*** Perennial beta-channel download URL: openknowledge.ai/download/beta@@ -27,12 +27,13 @@ export async function GET(request: Request): Promise<Response> {if (redirect.kind === 'fallback') {console.error(`[download/beta] falling back to releases page: ${redirect.cause}`);}- // A fallback sends the user to the releases page, not a DMG — don't count it.- if (redirect.kind !== 'fallback') {+ // A fallback sends the user to the releases page, not a DMG, and a prefetch+ // is not a click — don't count either.+ if (redirect.kind !== 'fallback' && !isPrefetchRequest(request)) {captureServerEvent({event: 'dmg_downloaded',distinctId: resolveDistinctId(request),- properties: { channel: 'beta', referrer: referrerHostname(request) },+ properties: { channel: 'beta', ...attribution(request) },});}return toRedirectResponse(redirect);diff --git a/docs/src/app/download/stable/route.test.ts b/docs/src/app/download/stable/route.test.tsindex 0e85796a4..667956405 100644--- a/docs/src/app/download/stable/route.test.ts+++ b/docs/src/app/download/stable/route.test.ts@@ -15,7 +15,8 @@ mock.module('../../../lib/track.ts', () => ({_lastCapture = opts;},resolveDistinctId: () => 'visitor-1',- referrerHostname: () => 'news.ycombinator.com',+ attribution: () => ({ referrer: 'news.ycombinator.com', utm_content: 'landing-hero' }),+ isPrefetchRequest: (request: Request) => request.headers.get('sec-purpose') === 'prefetch',}));const { GET } = await import('./route.ts');@@ -32,5 +33,18 @@ describe('GET /download/stable', () => {expect(_lastCapture?.distinctId).toBe('visitor-1');expect(_lastCapture?.properties?.channel).toBe('stable');expect(_lastCapture?.properties?.referrer).toBe('news.ycombinator.com');+ expect(_lastCapture?.properties?.utm_content).toBe('landing-hero');+ });++ test('a prefetch still redirects but is NOT counted', () => {+ _lastCapture = null;+ const res = GET(+ new Request('https://openknowledge.ai/download/stable', {+ headers: { 'sec-purpose': 'prefetch' },+ }),+ );+ expect(res.status).toBe(302);+ expect(res.headers.get('location')).toBe(STABLE_DMG_URL);+ expect(_lastCapture).toBeNull();});});diff --git a/docs/src/app/download/stable/route.ts b/docs/src/app/download/stable/route.tsindex c112486a4..d2afb9f04 100644--- a/docs/src/app/download/stable/route.ts+++ b/docs/src/app/download/stable/route.ts@@ -1,5 +1,5 @@import { STABLE_DMG_URL } from '@/lib/download-links';-import { captureServerEvent, referrerHostname, resolveDistinctId } from '@/lib/track';+import { attribution, captureServerEvent, isPrefetchRequest, resolveDistinctId } from '@/lib/track';/*** Perennial stable-channel download URL: openknowledge.ai/download/stable@@ -15,11 +15,14 @@ import { captureServerEvent, referrerHostname, resolveDistinctId } from '@/lib/texport const dynamic = 'force-dynamic';export function GET(request: Request): Response {- captureServerEvent({- event: 'dmg_downloaded',- distinctId: resolveDistinctId(request),- properties: { channel: 'stable', referrer: referrerHostname(request) },- });+ // A prefetch is not a download — redirect it, don't count it.+ if (!isPrefetchRequest(request)) {+ captureServerEvent({+ event: 'dmg_downloaded',+ distinctId: resolveDistinctId(request),+ properties: { channel: 'stable', ...attribution(request) },+ });+ }return new Response(null, {status: 302,headers: {diff --git a/docs/src/app/updates/[channel]/[...path]/route.test.ts b/docs/src/app/updates/[channel]/[...path]/route.test.tsindex 7e4d550b5..0945b5aa7 100644--- a/docs/src/app/updates/[channel]/[...path]/route.test.ts+++ b/docs/src/app/updates/[channel]/[...path]/route.test.ts@@ -12,6 +12,7 @@ mock.module('../../../../lib/track.ts', () => ({_lastCapture = opts;},resolveDistinctId: () => 'updater-1',+ userAgentProperties: () => ({ ua_class: 'electron' }),}));const BETA_DMG_URL =@@ -69,6 +70,7 @@ describe('GET /updates/[channel]/[...path]', () => {expect(_lastCapture?.properties?.artifact_type).toBe('zip');expect(_lastCapture?.properties?.to_version).toBe('0.20.0');expect(_lastCapture?.properties?.from_version).toBe('0.19.1');+ expect(_lastCapture?.properties?.ua_class).toBe('electron');});test('beta zip parses the prerelease version and counts (no from_version header)', async () => {@@ -81,6 +83,15 @@ describe('GET /updates/[channel]/[...path]', () => {expect(_lastCapture?.properties?.from_version).toBeUndefined();});+ test('an ill-formed x-ok-from-version header is dropped, not forwarded to analytics', async () => {+ _lastCapture = null;+ const file = 'OpenKnowledge-0.20.0-arm64-mac.zip';+ const res = await call('stable', [file], { 'x-ok-from-version': '../etc; rm -rf' });+ expect(res.status).toBe(302);+ expect(_lastCapture?.event).toBe('app_update_downloaded');+ expect(_lastCapture?.properties?.from_version).toBeUndefined();+ });+test('blockmap 302s but is NOT counted', async () => {_lastCapture = null;const file = 'OpenKnowledge-0.20.0-arm64-mac.zip.blockmap';diff --git a/docs/src/app/updates/[channel]/[...path]/route.ts b/docs/src/app/updates/[channel]/[...path]/route.tsindex e47365964..d6dec6db8 100644--- a/docs/src/app/updates/[channel]/[...path]/route.ts+++ b/docs/src/app/updates/[channel]/[...path]/route.ts@@ -1,11 +1,12 @@import { createBetaResolver } from '@/lib/download-links';-import { captureServerEvent, resolveDistinctId } from '@/lib/track';+import { captureServerEvent, resolveDistinctId, userAgentProperties } from '@/lib/track';/*** Update-feed proxy: openknowledge.ai/updates/{stable,beta}/<asset>*- * electron-updater is pointed here (in a later desktop change) instead of at- * GitHub directly, so updates can be counted per version. Every request is a+ * electron-updater's feed points here instead of at GitHub directly (wired in+ * the desktop app's auto-updater), so updates can be counted per version.+ * Every request is a* thin 302 to the byte-identical GitHub release asset — never re-hosted, so the* manifest `sha512` and the macOS code signature both stay valid. Only the* `*-mac.zip` (the artifact Squirrel.Mac swaps in) is counted as an update; the@@ -106,6 +107,9 @@ export async function GET(artifact_type: 'zip',to_version: version,from_version: rawFrom && FROM_VERSION.test(rawFrom) ? rawFrom : undefined,+ // Confirms updates really come from electron-updater and surfaces any+ // scraper/browser traffic hitting the update feed.+ ...userAgentProperties(request),},});}diff --git a/docs/src/components/docs-sidebar-cta.tsx b/docs/src/components/docs-sidebar-cta.tsxindex 61f364fc2..d50da96c1 100644--- a/docs/src/components/docs-sidebar-cta.tsx+++ b/docs/src/components/docs-sidebar-cta.tsx@@ -1,7 +1,7 @@import { Download } from 'lucide-react';import { GitHubIcon } from '@/components/icons/github';import { MarketingButton } from '@/components/marketing-button';-import { DOWNLOAD_ROUTE, GITHUB_URL } from '@/lib/site';+import { downloadRouteForCta, GITHUB_URL } from '@/lib/site';// Compact for the button label (e.g. "1.5K"); full comma-grouped for the tooltip.const compactStars = new Intl.NumberFormat('en-US', {@@ -18,14 +18,15 @@ const fullStars = new Intl.NumberFormat('en-US');export function DocsSidebarCta({ stars }: { stars: number | null }) {return (<div className="flex gap-2">- {/* MarketingButton (matches the docs Subscribe button). DOWNLOAD_ROUTE- starts with /download/, so MarketingButton renders it as a raw <a>- via its isRedirectRoute path — next/link never prefetches it, which- would fire the 302 and inflate download counts. */}+ {/* MarketingButton (matches the docs Subscribe button). The download+ route starts with /download/, so MarketingButton renders it as a raw+ <a> via its isRedirectRoute path — next/link never prefetches it,+ which would fire the 302 and inflate download counts. rel omits+ `noreferrer` so the same-origin Referer attributes the CTA. */}<MarketingButton- href={DOWNLOAD_ROUTE}+ href={downloadRouteForCta('docs-sidebar')}target="_blank"- rel="noopener noreferrer"+ rel="noopener"aria-label="Download for macOS"title="Download for macOS"variant="primary"diff --git a/docs/src/components/download-button.tsx b/docs/src/components/download-button.tsxindex 3b0dcfdbb..2e1aaa21c 100644--- a/docs/src/components/download-button.tsx+++ b/docs/src/components/download-button.tsx@@ -1,23 +1,30 @@import { DownloadIcon } from 'lucide-react';-import { DOWNLOAD_ROUTE } from '@/lib/site';+import type { DownloadCta } from '@/lib/site';+import { downloadRouteForCta } from '@/lib/site';type DownloadButtonProps = {/** Defaults to the tracked stable-download route (fires `dmg_downloaded`). */href?: string;label?: string;+ /** CTA slug reported as `utm_content` on `dmg_downloaded`. */+ cta?: DownloadCta;};export function DownloadButton({- href = DOWNLOAD_ROUTE,+ href,label = 'DOWNLOAD FOR MAC',+ cta = 'docs-content',}: DownloadButtonProps) {// Raw <a>, not next/link: the download route is a 302 redirect handler, so// next/link would prefetch it (firing the redirect) and double-fetch on click.+ // rel intentionally omits `noreferrer`: the Referer carries the originating+ // page, which is how the download event attributes to a docs page instead+ // of counting as direct traffic.return (<a- href={href}+ href={href ?? downloadRouteForCta(cta)}target="_blank"- rel="noopener noreferrer"+ rel="noopener"className="not-prose my-4 inline-flex items-center gap-2 rounded-full bg-neutral-900 px-5 py-2.5 text-sm font-medium text-white shadow-sm transition-opacity hover:opacity-90 dark:bg-neutral-100 dark:text-neutral-900">{label}diff --git a/docs/src/lib/site.ts b/docs/src/lib/site.tsindex 68ba31675..e2117f4b6 100644--- a/docs/src/lib/site.ts+++ b/docs/src/lib/site.ts@@ -78,4 +78,30 @@ export const DOWNLOAD_URL = STABLE_DMG_URL;* CTAs and the `DownloadButton` link here so every download fires a* `dmg_downloaded` event before the 302 to GitHub.*/-export const DOWNLOAD_ROUTE = '/download/stable';+const DOWNLOAD_ROUTE = '/download/stable';++/**+ * Every internal download CTA slug this app mints, reported as+ * `utm_content` on `dmg_downloaded`. Append-only: these are analytics+ * lineage — renaming one orphans its dashboard history. Namespace:+ * `docs-*` and share slugs here; `landing-*` belongs to ok-marketing.+ * `share-splash` is minted server-side by the /d/[encoded]/download+ * route rather than via downloadRouteForCta.+ */+export type DownloadCta =+ | 'docs-content'+ | 'docs-sidebar'+ | 'continue-page'+ | 'share-splash-fallback'+ | 'share-splash';++/**+ * {@link DOWNLOAD_ROUTE} tagged with `?utm_content=<cta-slug>` so the download+ * event attributes the exact CTA even when the browser sends no Referer.+ * `utm_content` is the standard UTM field for differentiating links/CTAs;+ * `utm_source`/`utm_medium` describe the acquisition channel and are reserved+ * for genuinely external campaign links (see `attribution` in src/lib/track.ts).+ */+export function downloadRouteForCta(cta: DownloadCta): string {+ return `${DOWNLOAD_ROUTE}?utm_content=${encodeURIComponent(cta)}`;+}diff --git a/docs/src/lib/track.test.ts b/docs/src/lib/track.test.tsindex 3e973bfa4..d53b5e205 100644--- a/docs/src/lib/track.test.ts+++ b/docs/src/lib/track.test.ts@@ -1,9 +1,11 @@import { afterEach, beforeEach, describe, expect, test } from 'bun:test';import {+ attribution,buildCapturePayload,captureServerEvent,- referrerHostname,+ isPrefetchRequest,resolveDistinctId,+ userAgentProperties,} from './track.ts';const KEY = 'phc_test_key';@@ -38,7 +40,8 @@ describe('buildCapturePayload', () => {// privacy guardsexpect(p.properties.$ip).toBeNull();expect(p.properties.$geoip_disable).toBe(true);- // never carries identifying request shape+ // the builder never injects request-shape properties itself — routes opt+ // in explicitly via userAgentProperties()expect('$useragent' in p.properties).toBe(false);});});@@ -80,15 +83,182 @@ describe('resolveDistinctId', () => {});});-describe('referrerHostname', () => {- test('returns hostname only (never the path)', () => {- expect(referrerHostname(req({ referer: 'https://news.ycombinator.com/item?id=1' }))).toBe(- 'news.ycombinator.com',+function reqUrl(url: string, headers: Record<string, string> = {}): Request {+ return new Request(url, { headers });+}++describe('attribution', () => {+ test('captures utm_content from our own CTA links', () => {+ const a = attribution(+ reqUrl('https://openknowledge.ai/download/stable?utm_content=landing-hero'),+ );+ expect(a.utm_content).toBe('landing-hero');+ });++ test('captures the full standard UTM set from external campaign links', () => {+ const a = attribution(+ reqUrl(+ 'https://openknowledge.ai/download/stable?utm_source=newsletter&utm_medium=email&utm_campaign=Launch%20Week&utm_content=header-button&utm_term=knowledge%20base',+ ),+ );+ expect(a.utm_source).toBe('newsletter');+ expect(a.utm_medium).toBe('email');+ expect(a.utm_campaign).toBe('Launch Week');+ expect(a.utm_content).toBe('header-button');+ expect(a.utm_term).toBe('knowledge base');+ });++ test('sanitizes utm values: control chars stripped, length capped, empty dropped', () => {+ const a = attribution(+ reqUrl(+ `https://openknowledge.ai/download/stable?utm_content=${'a'.repeat(150)}&utm_source=%00%01ok%7f&utm_medium=%20%20`,+ ),+ );+ expect(a.utm_content).toBe('a'.repeat(100));+ expect(a.utm_source).toBe('ok');+ expect(a.utm_medium).toBeUndefined();+ });++ test('external referrer: hostname only, no path', () => {+ const a = attribution(+ reqUrl('https://openknowledge.ai/download/stable', {+ referer: 'https://news.ycombinator.com/item?id=1',+ }),+ );+ expect(a.referrer).toBe('news.ycombinator.com');+ expect(a.referrer_path).toBeUndefined();+ });++ test('missing or unparseable referer: no referrer properties', () => {+ expect(+ attribution(reqUrl('https://openknowledge.ai/download/stable')).referrer,+ ).toBeUndefined();+ const a = attribution(+ reqUrl('https://openknowledge.ai/download/stable', { referer: 'not a url' }),+ );+ expect(a.referrer).toBeUndefined();+ expect(a.referrer_path).toBeUndefined();+ });++ test('own-site referrer: hostname plus page path, never the query string', () => {+ const a = attribution(+ reqUrl('https://openknowledge.ai/download/stable', {+ referer: 'https://openknowledge.ai/docs/get-started/quickstart?token=secret',+ }),+ );+ expect(a.referrer).toBe('openknowledge.ai');+ expect(a.referrer_path).toBe('/docs/get-started/quickstart');+ });++ test('own-site subdomain referrer also gets a path', () => {+ const a = attribution(+ reqUrl('https://openknowledge.ai/download/stable', {+ referer: 'https://www.openknowledge.ai/',+ }),+ );+ expect(a.referrer_path).toBe('/');+ });++ test('own-site /d/<encoded> share referrer: hostname only, path suppressed', () => {+ const a = attribution(+ reqUrl('https://openknowledge.ai/download/stable', {+ referer: 'https://openknowledge.ai/d/aHR0cHM6Ly9naXRodWIuY29t',+ }),+ );+ expect(a.referrer).toBe('openknowledge.ai');+ expect(a.referrer_path).toBeUndefined();+ });++ test('own-site referrer path is capped at 200 chars', () => {+ const a = attribution(+ reqUrl('https://openknowledge.ai/download/stable', {+ referer: `https://openknowledge.ai/docs/${'x'.repeat(400)}`,+ }),+ );+ expect(a.referrer_path?.length).toBe(200);+ });++ test('a lookalike domain is treated as external', () => {+ const a = attribution(+ reqUrl('https://openknowledge.ai/download/stable', {+ referer: 'https://notopenknowledge.ai/phish',+ }),+ );+ expect(a.referrer).toBe('notopenknowledge.ai');+ expect(a.referrer_path).toBeUndefined();+ });++ test('sec-fetch-site passes through only known values', () => {+ const ok = attribution(+ reqUrl('https://openknowledge.ai/download/stable', { 'sec-fetch-site': 'cross-site' }),+ );+ expect(ok.sec_fetch_site).toBe('cross-site');+ const junk = attribution(+ reqUrl('https://openknowledge.ai/download/stable', { 'sec-fetch-site': 'evil' }),+ );+ expect(junk.sec_fetch_site).toBeUndefined();+ expect(+ attribution(reqUrl('https://openknowledge.ai/download/stable')).sec_fetch_site,+ ).toBeUndefined();+ });++ test('includes the user-agent properties', () => {+ const a = attribution(+ reqUrl('https://openknowledge.ai/download/stable', {+ 'user-agent': 'Mozilla/5.0 (Macintosh) Safari/605.1.15',+ }),+ );+ expect(a.$useragent).toBe('Mozilla/5.0 (Macintosh) Safari/605.1.15');+ expect(a.ua_class).toBe('browser');+ });+});++describe('userAgentProperties', () => {+ const UA_URL = 'https://openknowledge.ai/download/stable';+ function classify(ua: string): string | undefined {+ return userAgentProperties(reqUrl(UA_URL, { 'user-agent': ua })).ua_class;+ }++ test('classifies browsers, bots, cli clients, and electron', () => {+ expect(classify('Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Safari/605.1.15')).toBe(+ 'browser',+ );+ expect(classify('Mozilla/5.0 (compatible; Googlebot/2.1)')).toBe('bot');+ expect(classify('Slackbot-LinkExpanding 1.0')).toBe('bot');+ expect(classify('curl/8.4.0')).toBe('cli');+ expect(classify('Wget/1.21')).toBe('cli');+ expect(classify('electron-updater/6.3.0')).toBe('electron');+ expect(+ classify('Mozilla/5.0 OpenKnowledge/0.24.0 Chrome/128.0.0.0 Electron/32.1.0 Safari/537.36'),+ ).toBe('electron');+ expect(classify('SomethingUnrecognized/1.0')).toBe('other');+ });++ test('missing UA classifies as none with no $useragent', () => {+ const p = userAgentProperties(reqUrl(UA_URL));+ expect(p.ua_class).toBe('none');+ expect(p.$useragent).toBeUndefined();+ });++ test('caps the raw UA length', () => {+ const p = userAgentProperties(reqUrl(UA_URL, { 'user-agent': `Mozilla/${'x'.repeat(500)}` }));+ expect(p.$useragent?.length).toBe(300);+ });+});++describe('isPrefetchRequest', () => {+ const ROUTE_URL = 'https://openknowledge.ai/download/stable';+ test('true for browser and framework prefetch signals', () => {+ expect(isPrefetchRequest(reqUrl(ROUTE_URL, { 'sec-purpose': 'prefetch' }))).toBe(true);+ expect(isPrefetchRequest(reqUrl(ROUTE_URL, { 'sec-purpose': 'prefetch;prerender' }))).toBe(+ true,);+ expect(isPrefetchRequest(reqUrl(ROUTE_URL, { purpose: 'prefetch' }))).toBe(true);+ expect(isPrefetchRequest(reqUrl(ROUTE_URL, { 'next-router-prefetch': '1' }))).toBe(true);});- test('undefined when missing or unparseable', () => {- expect(referrerHostname(req())).toBeUndefined();- expect(referrerHostname(req({ referer: 'not a url' }))).toBeUndefined();+ test('false for ordinary requests', () => {+ expect(isPrefetchRequest(reqUrl(ROUTE_URL))).toBe(false);+ expect(isPrefetchRequest(reqUrl(ROUTE_URL, { 'sec-fetch-site': 'none' }))).toBe(false);});});diff --git a/docs/src/lib/track.ts b/docs/src/lib/track.tsindex 5853b511d..7606a8184 100644--- a/docs/src/lib/track.ts+++ b/docs/src/lib/track.ts@@ -130,15 +130,165 @@ function readPosthogDistinctId(request: Request, key: string): string | null {}/**- * Coarse referrer for the `referrer` property: hostname only, so a referring- * path is never sent to PostHog. Missing or unparseable referer → omitted.+ * The standard UTM campaign parameters, captured under their canonical names+ * so PostHog's built-in UTM property definitions apply. Internal CTAs set only+ * `utm_content` (the standard field for differentiating links/CTAs);+ * `utm_source`/`utm_medium`/`utm_campaign` describe the acquisition channel+ * and are reserved for genuinely external campaign links (newsletter, social)+ * — fabricating them for internal clicks would corrupt campaign reporting.*/-export function referrerHostname(request: Request): string | undefined {- const referer = request.headers.get('referer');- if (!referer) return undefined;+const UTM_PARAMS = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_content', 'utm_term'] as const;++/**+ * External campaign tools mint arbitrary UTM values, so no slug allowlist —+ * just drop control characters and bound the length.+ */+function sanitizeUtmValue(raw: string | null): string | undefined {+ if (!raw) return undefined;+ const cleaned = [...raw]+ .filter((ch) => ch.charCodeAt(0) >= 0x20 && ch.charCodeAt(0) !== 0x7f)+ .join('')+ .trim()+ .slice(0, 100);+ return cleaned.length > 0 ? cleaned : undefined;+}++const SEC_FETCH_SITE_VALUES = ['none', 'same-origin', 'same-site', 'cross-site'] as const;+type SecFetchSite = (typeof SEC_FETCH_SITE_VALUES)[number];++function isSecFetchSite(value: string): value is SecFetchSite {+ return (SEC_FETCH_SITE_VALUES as readonly string[]).includes(value);+}++export type UaClass = 'browser' | 'bot' | 'cli' | 'electron' | 'none' | 'other';++/**+ * Path detail is captured for our own referring pages only — external+ * referrers stay hostname-only.+ */+function isOwnSiteHostname(hostname: string): boolean {+ return hostname === 'openknowledge.ai' || hostname.endsWith('.openknowledge.ai');+}++export interface AttributionProperties {+ referrer?: string;+ referrer_path?: string;+ sec_fetch_site?: SecFetchSite;+ utm_source?: string;+ utm_medium?: string;+ utm_campaign?: string;+ utm_content?: string;+ utm_term?: string;+ $useragent?: string;+ ua_class?: UaClass;+}++/**+ * Attribution properties for a download event:+ *+ * - `utm_*` — standard campaign parameters, passed through under their+ * canonical names. Our own CTAs tag links with `?utm_content=<cta-slug>`+ * (immune to referrer stripping); external campaign links can use the full+ * set and attribute with no custom vocabulary.+ * - `referrer` / `referrer_path` — where the click came from. External sites+ * report hostname only; the path is added for our own pages so an untagged+ * link (e.g. pasted in docs prose) still attributes to the exact page.+ * - `sec_fetch_site` — browser-supplied fetch classification (`none` = address+ * bar / non-web entry, `same-origin`/`same-site` = our site, `cross-site` =+ * external link, absent = non-browser client such as curl or a bot). This is+ * what separates "pasted the URL from the README" from "clicked a link".+ */+export function attribution(request: Request): AttributionProperties {+ const out: AttributionProperties = {};+try {- return new URL(referer).hostname;+ const params = new URL(request.url).searchParams;+ for (const name of UTM_PARAMS) {+ const value = sanitizeUtmValue(params.get(name));+ if (value) out[name] = value;+ }} catch {- return undefined;+ // no UTM capture on an unparseable request URL+ }++ const referer = request.headers.get('referer');+ if (referer) {+ try {+ const refUrl = new URL(referer);+ // External referrers stay hostname-only; a referring path is only+ // captured for our own pages, and never its query string. `/d/<encoded>`+ // share routes are excluded outright — there the share payload (the+ // encoded GitHub URL) lives in the PATH itself.+ out.referrer = refUrl.hostname;+ if (isOwnSiteHostname(refUrl.hostname) && !refUrl.pathname.startsWith('/d/')) {+ out.referrer_path = refUrl.pathname.slice(0, 200);+ }+ } catch {+ // unparseable referer → no referrer properties+ }+ }++ const secFetchSite = request.headers.get('sec-fetch-site');+ if (secFetchSite && isSecFetchSite(secFetchSite)) {+ out.sec_fetch_site = secFetchSite;}++ Object.assign(out, userAgentProperties(request));++ return out;+}++/**+ * Client identity for downloads and updates. `$useragent` is the property+ * PostHog's "User Agent Populator" transformation reads on server-captured+ * events — with that transformation enabled on the project, ingestion derives+ * `$browser`/`$browser_version` from it. `ua_class` is our own coarse,+ * bounded bucket for dashboard grouping (browsers vs bots/unfurlers vs+ * curl-style clients vs the Electron auto-updater) and needs no PostHog+ * configuration. The UA is deliberately the only request-shape property we+ * send — IP and geo stay suppressed (see buildCapturePayload).+ */+export function userAgentProperties(request: Request): {+ $useragent?: string;+ ua_class?: UaClass;+} {+ const ua = request.headers.get('user-agent');+ if (!ua) return { ua_class: 'none' };+ return { $useragent: ua.slice(0, 300), ua_class: classifyUserAgent(ua) };+}++/**+ * Order matters: Electron and bot UAs both embed `Mozilla/5.0`, so the+ * browser check must come last.+ */+function classifyUserAgent(ua: string): UaClass {+ if (/electron-updater|electron-builder|\belectron\//i.test(ua)) return 'electron';+ if (+ /bot|crawler|spider|slurp|bingpreview|externalhit|embedly|whatsapp|telegram|slack|discord|pinterest|linkedin|vkshare/i.test(+ ua,+ )+ ) {+ return 'bot';+ }+ if (+ /^curl|^wget|^httpie|python-requests|python-urllib|node-fetch|undici|axios|go-http-client|okhttp|java\/|libwww/i.test(+ ua,+ )+ ) {+ return 'cli';+ }+ if (ua.startsWith('Mozilla/')) return 'browser';+ return 'other';+}++/**+ * Browser and framework prefetches hit the download routes without a real+ * click (Chrome sends `Sec-Purpose: prefetch`, Safari `Purpose: prefetch`,+ * next/link `Next-Router-Prefetch: 1`). Counting them would inflate download+ * numbers with phantom events — callers skip capture but still redirect.+ */+export function isPrefetchRequest(request: Request): boolean {+ const purpose = request.headers.get('sec-purpose') ?? request.headers.get('purpose') ?? '';+ if (/prefetch|prerender/i.test(purpose)) return true;+ return request.headers.get('next-router-prefetch') !== null;}