Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
feat(open-knowledge): track downloads and updates per version (#2222)
Andrew Mikofalvyaed26f10f84c
diff --git a/README.md b/README.mdindex 5065a313f..19691b181 100644--- a/README.md+++ b/README.md@@ -13,7 +13,7 @@<div ><a href="https://openknowledge.ai">website</a><span> • </span>- <a href="https://github.com/inkeep/open-knowledge/releases/latest/download/OpenKnowledge-arm64.dmg">macOS app</a>+ <a href="https://openknowledge.ai/download/stable">macOS app</a><span> • </span><a href="https://openknowledge.ai/docs/get-started/quickstart#ok-install-web-app-linux-windows-intel-mac">web view + cli</a><span> • </span>diff --git a/docs/src/app/(home)/marketing-button.tsx b/docs/src/app/(home)/marketing-button.tsxindex b1b1038c7..ef5e0434a 100644--- a/docs/src/app/(home)/marketing-button.tsx+++ b/docs/src/app/(home)/marketing-button.tsx@@ -183,6 +183,9 @@ export function MarketingButton({const ArrowIcon = iconDirection === 'down' ? ArrowDown : ArrowRight;const ChevronsIcon = iconDirection === 'down' ? ChevronsDown : ChevronsRight;const isFileLink = typeof href === 'string' && href.split('?')[0]?.toLowerCase().endsWith('.pdf');+ const isRedirectRoute =+ typeof href === 'string' && (href.startsWith('/download/') || href.startsWith('/updates/'));+ const useRawAnchor = isFileLink || isRedirectRoute;const computedDownload = typeof download !== 'undefined' ? download : isFileLink ? '' : undefined;const buttonContent = (@@ -251,7 +254,7 @@ export function MarketingButton({const defaultRel = target === '_blank' ? 'noopener noreferrer' : undefined;const finalRel = rel || defaultRel;- if (isFileLink) {+ if (useRawAnchor) {return (<ahref={href}diff --git a/docs/src/app/(home)/sections/call-to-action.tsx b/docs/src/app/(home)/sections/call-to-action.tsxindex e5458f02c..6769cf775 100644--- a/docs/src/app/(home)/sections/call-to-action.tsx+++ b/docs/src/app/(home)/sections/call-to-action.tsx@@ -3,7 +3,7 @@import Image from 'next/image';import Link from 'next/link';import { useEffect, useState } from 'react';-import { DOWNLOAD_URL } from '@/lib/site';+import { DOWNLOAD_ROUTE } from '@/lib/site';import { useIsInView } from '@/lib/use-is-in-view';import { cn } from '@/lib/utils';import { DotTexture } from '../dot-texture';@@ -104,7 +104,7 @@ export function CallToAction() {<div className="mt-10 flex flex-wrap items-center justify-center gap-5"><MarketingButton- href={DOWNLOAD_URL}+ href={DOWNLOAD_ROUTE}target="_blank"size="lg"showIcondiff --git a/docs/src/app/(home)/sections/hero.tsx b/docs/src/app/(home)/sections/hero.tsxindex 268f499f6..a1a156bd9 100644--- a/docs/src/app/(home)/sections/hero.tsx+++ b/docs/src/app/(home)/sections/hero.tsx@@ -6,7 +6,7 @@ import { useState } from 'react';import { ClaudeIcon } from '@/components/icons/claude';import { CodexBrandIcon } from '@/components/icons/codex';import { CursorIcon } from '@/components/icons/cursor';-import { DOWNLOAD_URL, SITE_HEADLINE } from '@/lib/site';+import { DOWNLOAD_ROUTE, SITE_HEADLINE } from '@/lib/site';import { cn } from '@/lib/utils';import { DotTexture } from '../dot-texture';import { MarketingButton } from '../marketing-button';@@ -46,7 +46,7 @@ export function Hero() {<div className="mt-6 flex items-center justify-center gap-4"><MarketingButton- href={DOWNLOAD_URL}+ href={DOWNLOAD_ROUTE}target="_blank"size="md"showIcondiff --git a/docs/src/app/(home)/site-nav.tsx b/docs/src/app/(home)/site-nav.tsxindex e1c2b50fb..8c8230aa2 100644--- a/docs/src/app/(home)/site-nav.tsx+++ b/docs/src/app/(home)/site-nav.tsx@@ -8,7 +8,7 @@ import { DiscordIcon } from '@/components/icons/discord';import { GitHubIcon } from '@/components/icons/github';import { XIcon } from '@/components/icons/x';import { OkWordmark } from '@/components/ok-wordmark';-import { DOWNLOAD_URL } from '@/lib/site';+import { DOWNLOAD_ROUTE } from '@/lib/site';import { MarketingButton } from './marketing-button';type NavLink = {@@ -127,7 +127,7 @@ export function SiteNav() {</Link>);})}- <MarketingButton href={DOWNLOAD_URL} size="sm">+ <MarketingButton href={DOWNLOAD_ROUTE} size="sm">Download</MarketingButton></nav>@@ -186,7 +186,7 @@ export function SiteNav() {</Link>);})}- <MarketingButton href={DOWNLOAD_URL} size="md" className="text-base" showIcon>+ <MarketingButton href={DOWNLOAD_ROUTE} size="md" className="text-base" showIcon>Download</MarketingButton></nav>diff --git a/docs/src/app/continue/page.tsx b/docs/src/app/continue/page.tsxindex b4f54a0a7..687280c77 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 { SPLASH_DOWNLOAD_URL } from '@/lib/share-splash';+import { DOWNLOAD_ROUTE } from '@/lib/site';export const dynamic = 'force-dynamic';@@ -68,7 +68,7 @@ export default async function ContinuePage({ searchParams }: ContinuePageProps)<br />Don’t have the app yet?{' '}<a- href={SPLASH_DOWNLOAD_URL}+ href={DOWNLOAD_ROUTE}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.tsnew file mode 100644index 000000000..d8ecf95d8--- /dev/null+++ b/docs/src/app/d/[encoded]/download/route.test.ts@@ -0,0 +1,70 @@+import { describe, expect, mock, test } from 'bun:test';++const SPLASH_URL =+ 'https://github.com/inkeep/open-knowledge/releases/latest/download/OpenKnowledge-arm64.dmg';++type CaptureOpts = {+ event: string;+ distinctId: string;+ properties?: Record<string, string | undefined>;+};+let _lastCapture: CaptureOpts | null = null;+mock.module('../../../../lib/track.ts', () => ({+ captureServerEvent: (opts: CaptureOpts) => {+ _lastCapture = opts;+ },+ resolveDistinctId: () => 'splash-1',+}));++let _viewKind: 'ok' | 'invalid' | 'unsupported-version' = 'ok';+mock.module('../../../../lib/share-splash.ts', () => ({+ buildSplashViewModel: () => ({ kind: _viewKind }),+ SPLASH_DOWNLOAD_URL: SPLASH_URL,+}));++mock.module('../../../../lib/deferred-share.ts', () => ({+ buildPendingShareCookie: (encoded: string) => ({ name: 'ok-pending-share', value: encoded }),+}));++const { GET } = await import('./route.ts');++function call(encoded: string): Promise<Response> {+ return GET(new Request(`https://openknowledge.ai/d/${encoded}/download`), {+ params: Promise.resolve({ encoded }),+ });+}++describe('GET /d/[encoded]/download', () => {+ test('valid share: 302 to the DMG, sets the pairing cookie, counts share-splash', async () => {+ _viewKind = 'ok';+ _lastCapture = null;+ const res = await call('valid-share');+ expect(res.status).toBe(302);+ expect(res.headers.get('location')).toBe(SPLASH_URL);+ 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');+ expect(_lastCapture?.distinctId).toBe('splash-1');+ });++ test('invalid share: 302 with NO cookie but still counts the download', async () => {+ _viewKind = 'invalid';+ _lastCapture = null;+ const res = await call('bad-share');+ expect(res.status).toBe(302);+ 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');+ });++ test('unsupported-version share: no cookie, still counts', async () => {+ _viewKind = 'unsupported-version';+ _lastCapture = null;+ const res = await call('old-share');+ expect(res.status).toBe(302);+ expect(res.headers.get('set-cookie')).toBeNull();+ expect(_lastCapture?.event).toBe('dmg_downloaded');+ });+});diff --git a/docs/src/app/d/[encoded]/download/route.ts b/docs/src/app/d/[encoded]/download/route.tsindex 671482f1e..2bb4fcc25 100644--- a/docs/src/app/d/[encoded]/download/route.ts+++ b/docs/src/app/d/[encoded]/download/route.ts@@ -1,9 +1,10 @@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';export async function GET(- _request: Request,+ request: Request,{ params }: { params: Promise<{ encoded: string }> },): Promise<NextResponse> {const { encoded } = await params;@@ -14,5 +15,11 @@ export async function GET(response.cookies.set(buildPendingShareCookie(encoded));}+ captureServerEvent({+ event: 'dmg_downloaded',+ distinctId: resolveDistinctId(request),+ properties: { channel: 'stable', source: '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 2ca01aa1a..bb5be8013 100644--- a/docs/src/app/d/[encoded]/splash-share-view.tsx+++ b/docs/src/app/d/[encoded]/splash-share-view.tsx@@ -1,12 +1,8 @@import { DotIcon, GitBranchIcon } from 'lucide-react';import Link from 'next/link';import { OkWordmark } from '@/components/ok-wordmark';-import {- buildCloneCommand,- SPLASH_DOWNLOAD_URL,- SPLASH_INSTALL_COMMAND,- type SplashView,-} from '@/lib/share-splash';+import { buildCloneCommand, SPLASH_INSTALL_COMMAND, type SplashView } from '@/lib/share-splash';+import { DOWNLOAD_ROUTE } from '@/lib/site';import { DotTexture } from '../../(home)/dot-texture';import { SiteFooter } from '../../(home)/footer';import { SplashButtonLabel, splashPrimaryButton } from './splash-buttons';@@ -133,7 +129,7 @@ export function SplashFallback({ heading }: { heading: string }) {</h1><div className="mt-10 flex flex-wrap items-center gap-4">- <a href={SPLASH_DOWNLOAD_URL} className={splashPrimaryButton}>+ <a href={DOWNLOAD_ROUTE} 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 fc1b2bda7..8f357f7a8 100644--- a/docs/src/app/download/beta/route.test.ts+++ b/docs/src/app/download/beta/route.test.ts@@ -23,30 +23,56 @@ mock.module('../../../lib/download-links.ts', () => ({}),}));+type CaptureOpts = {+ event: string;+ distinctId: string;+ properties?: Record<string, string | undefined>;+};+let _lastCapture: CaptureOpts | null = null;+mock.module('../../../lib/track.ts', () => ({+ captureServerEvent: (opts: CaptureOpts) => {+ _lastCapture = opts;+ },+ resolveDistinctId: () => 'visitor-9',+ referrerHostname: () => undefined,+}));+const { GET } = await import('./route.ts');+function call(): Promise<Response> {+ return GET(new Request('https://openknowledge.ai/download/beta'));+}+describe('GET /download/beta', () => {- test('302 to the fresh beta URL with CDN-cacheable headers', async () => {+ test('302 to the fresh beta URL and fires dmg_downloaded (beta)', async () => {_redirect = { kind: 'fresh', url: TEST_DMG_URL };- const res = await GET();+ _lastCapture = null;+ const res = await call();expect(res.status).toBe(302);expect(res.headers.get('location')).toBe(TEST_DMG_URL);expect(res.headers.get('cache-control')).toBe(SUCCESS_CACHE_CONTROL);+ expect(_lastCapture?.event).toBe('dmg_downloaded');+ expect(_lastCapture?.distinctId).toBe('visitor-9');+ expect(_lastCapture?.properties?.channel).toBe('beta');});- test('302 to the stale LKG URL with CDN-cacheable headers', async () => {+ test('302 to the stale LKG URL and still counts', async () => {_redirect = { kind: 'stale-lkg', url: TEST_DMG_URL, refreshError: 'network down' };- const res = await GET();+ _lastCapture = null;+ const res = await call();expect(res.status).toBe(302);expect(res.headers.get('location')).toBe(TEST_DMG_URL);expect(res.headers.get('cache-control')).toBe(SUCCESS_CACHE_CONTROL);+ expect(_lastCapture?.properties?.channel).toBe('beta');});- test('302 to the releases page uncached on fallback', async () => {+ test('302 to the releases page on fallback is NOT counted as a download', async () => {_redirect = { kind: 'fallback', url: RELEASES_PAGE_URL, cause: 'API error' };- const res = await GET();+ _lastCapture = null;+ const res = await call();expect(res.status).toBe(302);expect(res.headers.get('location')).toBe(RELEASES_PAGE_URL);expect(res.headers.get('cache-control')).toBe(FALLBACK_CACHE_CONTROL);+ expect(_lastCapture).toBeNull();});});diff --git a/docs/src/app/download/beta/route.ts b/docs/src/app/download/beta/route.tsindex 7d5b67819..79fd8a530 100644--- a/docs/src/app/download/beta/route.ts+++ b/docs/src/app/download/beta/route.ts@@ -1,10 +1,11 @@import { createBetaResolver, toRedirectResponse } from '@/lib/download-links';+import { captureServerEvent, referrerHostname, resolveDistinctId } from '@/lib/track';export const dynamic = 'force-dynamic';const resolveBetaRedirect = createBetaResolver();-export async function GET(): Promise<Response> {+export async function GET(request: Request): Promise<Response> {const redirect = await resolveBetaRedirect();if (redirect.kind === 'stale-lkg') {console.warn(@@ -14,5 +15,12 @@ export async function GET(): Promise<Response> {if (redirect.kind === 'fallback') {console.error(`[download/beta] falling back to releases page: ${redirect.cause}`);}+ if (redirect.kind !== 'fallback') {+ captureServerEvent({+ event: 'dmg_downloaded',+ distinctId: resolveDistinctId(request),+ properties: { channel: 'beta', referrer: referrerHostname(request) },+ });+ }return toRedirectResponse(redirect);}diff --git a/docs/src/app/download/stable/route.test.ts b/docs/src/app/download/stable/route.test.tsindex d286c801a..d4f49a6ae 100644--- a/docs/src/app/download/stable/route.test.ts+++ b/docs/src/app/download/stable/route.test.ts@@ -1,12 +1,33 @@-import { describe, expect, test } from 'bun:test';-import { STABLE_CACHE_CONTROL, STABLE_DMG_URL } from '../../../lib/download-links.ts';-import { GET } from './route.ts';+import { describe, expect, mock, test } from 'bun:test';+import { STABLE_DMG_URL } from '../../../lib/download-links.ts';++type CaptureOpts = {+ event: string;+ distinctId: string;+ properties?: Record<string, string | undefined>;+};++let _lastCapture: CaptureOpts | null = null;+mock.module('../../../lib/track.ts', () => ({+ captureServerEvent: (opts: CaptureOpts) => {+ _lastCapture = opts;+ },+ resolveDistinctId: () => 'visitor-1',+ referrerHostname: () => 'news.ycombinator.com',+}));++const { GET } = await import('./route.ts');describe('GET /download/stable', () => {- test('302 to the stable DMG URL with CDN-cacheable headers', () => {- const res = GET();+ test('302 to the stable DMG URL, uncached, and fires dmg_downloaded', () => {+ _lastCapture = null;+ const res = GET(new Request('https://openknowledge.ai/download/stable'));expect(res.status).toBe(302);expect(res.headers.get('location')).toBe(STABLE_DMG_URL);- expect(res.headers.get('cache-control')).toBe(STABLE_CACHE_CONTROL);+ expect(res.headers.get('cache-control')).toBe('no-store');+ expect(_lastCapture?.event).toBe('dmg_downloaded');+ expect(_lastCapture?.distinctId).toBe('visitor-1');+ expect(_lastCapture?.properties?.channel).toBe('stable');+ expect(_lastCapture?.properties?.referrer).toBe('news.ycombinator.com');});});diff --git a/docs/src/app/download/stable/route.ts b/docs/src/app/download/stable/route.tsindex 1a31829fd..5fd6ed0ab 100644--- a/docs/src/app/download/stable/route.ts+++ b/docs/src/app/download/stable/route.ts@@ -1,13 +1,19 @@-import { STABLE_CACHE_CONTROL, STABLE_DMG_URL } from '@/lib/download-links';+import { STABLE_DMG_URL } from '@/lib/download-links';+import { captureServerEvent, referrerHostname, resolveDistinctId } from '@/lib/track';export const dynamic = 'force-dynamic';-export function GET(): Response {+export function GET(request: Request): Response {+ captureServerEvent({+ event: 'dmg_downloaded',+ distinctId: resolveDistinctId(request),+ properties: { channel: 'stable', referrer: referrerHostname(request) },+ });return new Response(null, {status: 302,headers: {location: STABLE_DMG_URL,- 'cache-control': STABLE_CACHE_CONTROL,+ 'cache-control': 'no-store',},});}diff --git a/docs/src/app/updates/[channel]/[...path]/route.test.ts b/docs/src/app/updates/[channel]/[...path]/route.test.tsnew file mode 100644index 000000000..4d76af538--- /dev/null+++ b/docs/src/app/updates/[channel]/[...path]/route.test.ts@@ -0,0 +1,139 @@+import { describe, expect, mock, test } from 'bun:test';++type CaptureOpts = {+ event: string;+ distinctId: string;+ properties?: Record<string, string | undefined>;+};+let _lastCapture: CaptureOpts | null = null;++mock.module('../../../../lib/track.ts', () => ({+ captureServerEvent: (opts: CaptureOpts) => {+ _lastCapture = opts;+ },+ resolveDistinctId: () => 'updater-1',+}));++const BETA_DMG_URL =+ 'https://github.com/inkeep/open-knowledge/releases/download/v0.20.0-beta.4/OpenKnowledge-arm64.dmg';+type BetaRedirect = { kind: string; url: string; cause?: string };+let _betaRedirect: BetaRedirect = { kind: 'fresh', url: BETA_DMG_URL };+mock.module('../../../../lib/download-links.ts', () => ({+ createBetaResolver: () => () => Promise.resolve(_betaRedirect),+}));++const { GET } = await import('./route.ts');+const REL = 'https://github.com/inkeep/open-knowledge/releases';++function call(+ channel: string,+ path: string[],+ headers: Record<string, string> = {},+): Promise<Response> {+ return GET(+ new Request(`https://openknowledge.ai/updates/${channel}/${path.join('/')}`, { headers }),+ {+ params: Promise.resolve({ channel, path }),+ },+ );+}++describe('GET /updates/[channel]/[...path]', () => {+ test('stable manifest 302s to the latest alias and is NOT counted', async () => {+ _lastCapture = null;+ const res = await call('stable', ['latest-mac.yml']);+ expect(res.status).toBe(302);+ expect(res.headers.get('location')).toBe(`${REL}/latest/download/latest-mac.yml`);+ expect(_lastCapture).toBeNull();+ });++ test('beta manifest 302s to the resolved beta tag and is NOT counted', async () => {+ _betaRedirect = { kind: 'fresh', url: BETA_DMG_URL };+ _lastCapture = null;+ const res = await call('beta', ['beta-mac.yml']);+ expect(res.status).toBe(302);+ expect(res.headers.get('location')).toBe(`${REL}/download/v0.20.0-beta.4/beta-mac.yml`);+ expect(_lastCapture).toBeNull();+ });++ test('stable zip 302s to the tagged release and counts app_update_downloaded', async () => {+ _lastCapture = null;+ const file = 'OpenKnowledge-0.20.0-arm64-mac.zip';+ const res = await call('stable', [file], { 'x-ok-from-version': '0.19.1' });+ expect(res.status).toBe(302);+ expect(res.headers.get('location')).toBe(`${REL}/download/v0.20.0/${file}`);+ expect(res.headers.get('cache-control')).toBe('no-store');+ expect(_lastCapture?.event).toBe('app_update_downloaded');+ expect(_lastCapture?.properties?.channel).toBe('stable');+ 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');+ });++ test('beta zip parses the prerelease version and counts (no from_version header)', async () => {+ _lastCapture = null;+ const file = 'OpenKnowledge-0.20.0-beta.4-arm64-mac.zip';+ const res = await call('beta', [file]);+ expect(res.status).toBe(302);+ expect(res.headers.get('location')).toBe(`${REL}/download/v0.20.0-beta.4/${file}`);+ expect(_lastCapture?.properties?.to_version).toBe('0.20.0-beta.4');+ 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';+ const res = await call('stable', [file]);+ expect(res.status).toBe(302);+ expect(res.headers.get('location')).toBe(`${REL}/download/v0.20.0/${file}`);+ expect(_lastCapture).toBeNull();+ });++ test('human dmg 302s (latest alias) but is NOT counted', async () => {+ _lastCapture = null;+ const res = await call('stable', ['OpenKnowledge-arm64.dmg']);+ expect(res.status).toBe(302);+ expect(res.headers.get('location')).toBe(`${REL}/latest/download/OpenKnowledge-arm64.dmg`);+ expect(_lastCapture).toBeNull();+ });++ test('dmg blockmap 302s (latest alias) but is NOT counted', async () => {+ _lastCapture = null;+ const file = 'OpenKnowledge-arm64.dmg.blockmap';+ const res = await call('stable', [file]);+ expect(res.status).toBe(302);+ expect(res.headers.get('location')).toBe(`${REL}/latest/download/${file}`);+ expect(_lastCapture).toBeNull();+ });++ test('invalid channel → 404', async () => {+ expect((await call('canary', ['latest-mac.yml'])).status).toBe(404);+ });++ test('path traversal / multi-segment → 404', async () => {+ expect((await call('stable', ['..', 'secret'])).status).toBe(404);+ });++ test('unknown artifact type → 404', async () => {+ expect((await call('stable', ['random.txt'])).status).toBe(404);+ });++ test('x64 zip parses the version and counts', async () => {+ _lastCapture = null;+ const file = 'OpenKnowledge-0.20.0-x64-mac.zip';+ const res = await call('stable', [file]);+ expect(res.status).toBe(302);+ expect(res.headers.get('location')).toBe(`${REL}/download/v0.20.0/${file}`);+ expect(_lastCapture?.properties?.to_version).toBe('0.20.0');+ });++ test('beta manifest 503s (no-store) on resolver fallback, not counted', async () => {+ _betaRedirect = { kind: 'fallback', url: REL, cause: 'API error' };+ _lastCapture = null;+ const res = await call('beta', ['beta-mac.yml']);+ expect(res.status).toBe(503);+ expect(res.headers.get('cache-control')).toBe('no-store');+ expect(_lastCapture).toBeNull();+ _betaRedirect = { kind: 'fresh', url: BETA_DMG_URL };+ });+});diff --git a/docs/src/app/updates/[channel]/[...path]/route.ts b/docs/src/app/updates/[channel]/[...path]/route.tsnew file mode 100644index 000000000..d9758046a--- /dev/null+++ b/docs/src/app/updates/[channel]/[...path]/route.ts@@ -0,0 +1,88 @@+import { createBetaResolver } from '@/lib/download-links';+import { captureServerEvent, resolveDistinctId } from '@/lib/track';++export const dynamic = 'force-dynamic';++const RELEASES_BASE = 'https://github.com/inkeep/open-knowledge/releases';+const VALID_CHANNELS = new Set(['stable', 'beta']);+const SAFE_FILENAME = /^[A-Za-z0-9._-]+$/;+const ARTIFACT_VERSION =+ /-(\d+\.\d+\.\d+(?:-[0-9A-Za-z.]+)?)-(?:arm64|x64|universal)-mac\.zip(?:\.blockmap)?$/;+const BETA_TAG_FROM_URL = /\/releases\/download\/([^/]+)\//;+const FROM_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.]+)?$/;++const resolveBeta = createBetaResolver();++type ArtifactType = 'manifest' | 'zip' | 'blockmap' | 'dmg' | 'other';++function classify(filename: string): ArtifactType {+ if (filename.endsWith('-mac.yml')) return 'manifest';+ if (filename.endsWith('.blockmap')) return 'blockmap';+ if (filename.endsWith('.zip')) return 'zip';+ if (filename.endsWith('.dmg')) return 'dmg';+ return 'other';+}++function redirect302(location: string): Response {+ return new Response(null, { status: 302, headers: { location, 'cache-control': 'no-store' } });+}++function errorResponse(status: number): Response {+ return new Response(null, { status, headers: { 'cache-control': 'no-store' } });+}++async function latestBetaTag(): Promise<string | null> {+ const redirect = await resolveBeta();+ if (redirect.kind === 'stale-lkg') {+ console.warn(+ `[updates/beta] serving stale LKG tag after refresh failure: ${redirect.refreshError}`,+ );+ }+ if (redirect.kind === 'fallback') return null;+ return BETA_TAG_FROM_URL.exec(redirect.url)?.[1] ?? null;+}++export async function GET(+ request: Request,+ { params }: { params: Promise<{ channel: string; path: string[] }> },+): Promise<Response> {+ const { channel, path } = await params;+ if (!VALID_CHANNELS.has(channel)) return errorResponse(404);++ const filename = path.join('/');+ if (!SAFE_FILENAME.test(filename)) return errorResponse(404);++ const type = classify(filename);+ if (type === 'other') return errorResponse(404);++ const version = ARTIFACT_VERSION.exec(filename)?.[1];++ let target: string;+ if (version) {+ target = `${RELEASES_BASE}/download/v${version}/${filename}`;+ } else if (channel === 'stable') {+ target = `${RELEASES_BASE}/latest/download/${filename}`;+ } else {+ const tag = await latestBetaTag();+ if (!tag) {+ return errorResponse(503);+ }+ target = `${RELEASES_BASE}/download/${tag}/${filename}`;+ }++ if (type === 'zip' && version) {+ const rawFrom = request.headers.get('x-ok-from-version');+ captureServerEvent({+ event: 'app_update_downloaded',+ distinctId: resolveDistinctId(request),+ properties: {+ channel,+ artifact_type: 'zip',+ to_version: version,+ from_version: rawFrom && FROM_VERSION.test(rawFrom) ? rawFrom : undefined,+ },+ });+ }++ return redirect302(target);+}diff --git a/docs/src/components/download-button.tsx b/docs/src/components/download-button.tsxindex ee5c0272a..d45b1d5f2 100644--- a/docs/src/components/download-button.tsx+++ b/docs/src/components/download-button.tsx@@ -1,6 +1,5 @@import { DownloadIcon } from 'lucide-react';-import Link from 'next/link';-import { STABLE_DMG_URL } from '@/lib/download-links';+import { DOWNLOAD_ROUTE } from '@/lib/site';type DownloadButtonProps = {href?: string;@@ -8,11 +7,11 @@ type DownloadButtonProps = {};export function DownloadButton({- href = STABLE_DMG_URL,+ href = DOWNLOAD_ROUTE,label = 'DOWNLOAD FOR MAC',}: DownloadButtonProps) {return (- <Link+ <ahref={href}target="_blank"rel="noopener noreferrer"@@ -20,6 +19,6 @@ export function DownloadButton({>{label}<DownloadIcon className="size-4" aria-hidden="true" />- </Link>+ </a>);}diff --git a/docs/src/lib/download-links.ts b/docs/src/lib/download-links.tsindex d20cf97d0..b597c20b2 100644--- a/docs/src/lib/download-links.ts+++ b/docs/src/lib/download-links.ts@@ -113,8 +113,6 @@ export const SUCCESS_CACHE_CONTROL = 'public, max-age=0, s-maxage=300, stale-whiexport const FALLBACK_CACHE_CONTROL = 'no-store';-export const STABLE_CACHE_CONTROL = 'public, max-age=0, s-maxage=3600';-export function toRedirectResponse(redirect: BetaRedirect): Response {return new Response(null, {status: 302,diff --git a/docs/src/lib/site.ts b/docs/src/lib/site.tsindex 6fb31f1f9..74caf7136 100644--- a/docs/src/lib/site.ts+++ b/docs/src/lib/site.ts@@ -25,5 +25,7 @@ export function metaDescription(export const DOWNLOAD_URL = STABLE_DMG_URL;+export const DOWNLOAD_ROUTE = '/download/stable';+export const EXAMPLE_KB_SHARE_URL ='https://openknowledge.ai/d/AWh0dHBzOi8vZ2l0aHViLmNvbS9pbmtlZXAvdGVjaC1pcG9zL2Jsb2IvbWFpbi9SRUFETUUubWQ';diff --git a/docs/src/lib/track.test.ts b/docs/src/lib/track.test.tsnew file mode 100644index 000000000..204e07aed--- /dev/null+++ b/docs/src/lib/track.test.ts@@ -0,0 +1,114 @@+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';+import {+ buildCapturePayload,+ captureServerEvent,+ referrerHostname,+ resolveDistinctId,+} from './track.ts';++const KEY = 'phc_test_key';+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;++const prevKey = process.env.NEXT_PUBLIC_POSTHOG_KEY;+afterEach(() => {+ if (prevKey === undefined) delete process.env.NEXT_PUBLIC_POSTHOG_KEY;+ else process.env.NEXT_PUBLIC_POSTHOG_KEY = prevKey;+});++function req(headers: Record<string, string> = {}): Request {+ return new Request('https://openknowledge.ai/download/stable', { headers });+}++describe('buildCapturePayload', () => {+ test('forces the privacy guards and strips undefined props', () => {+ const p = buildCapturePayload(+ {+ event: 'dmg_downloaded',+ distinctId: 'd1',+ properties: { channel: 'stable', from_version: undefined },+ },+ KEY,+ );+ expect(p.api_key).toBe(KEY);+ expect(p.event).toBe('dmg_downloaded');+ expect(p.distinct_id).toBe('d1');+ expect(typeof p.timestamp).toBe('string');+ expect(p.properties.channel).toBe('stable');+ expect('from_version' in p.properties).toBe(false);+ expect(p.properties.$ip).toBeNull();+ expect(p.properties.$geoip_disable).toBe(true);+ expect('$useragent' in p.properties).toBe(false);+ });+});++describe('resolveDistinctId', () => {+ beforeEach(() => {+ process.env.NEXT_PUBLIC_POSTHOG_KEY = KEY;+ });++ test('reuses the posthog cookie distinct_id when present', () => {+ const cookie = `ph_${KEY}_posthog=${encodeURIComponent(JSON.stringify({ distinct_id: 'abc-123' }))}`;+ expect(resolveDistinctId(req({ cookie }))).toBe('abc-123');+ });++ test('falls back to a random UUID when no cookie', () => {+ expect(resolveDistinctId(req())).toMatch(UUID_RE);+ });++ test('falls back to a random UUID on a malformed cookie (no throw)', () => {+ const cookie = `ph_${KEY}_posthog=not-json`;+ expect(resolveDistinctId(req({ cookie }))).toMatch(UUID_RE);+ });++ test('falls back to a random UUID on an empty distinct_id', () => {+ const cookie = `ph_${KEY}_posthog=${encodeURIComponent(JSON.stringify({ distinct_id: '' }))}`;+ expect(resolveDistinctId(req({ cookie }))).toMatch(UUID_RE);+ });++ test('finds the posthog cookie among multiple cookies', () => {+ const ph = encodeURIComponent(JSON.stringify({ distinct_id: 'abc-456' }));+ const cookie = `_ga=GA1.1; ph_${KEY}_posthog=${ph}; session=xyz`;+ expect(resolveDistinctId(req({ cookie }))).toBe('abc-456');+ });++ test('ignores cookies and returns a UUID when the key is unset', () => {+ delete process.env.NEXT_PUBLIC_POSTHOG_KEY;+ const cookie = `ph_${KEY}_posthog=${encodeURIComponent(JSON.stringify({ distinct_id: 'abc-123' }))}`;+ expect(resolveDistinctId(req({ cookie }))).toMatch(UUID_RE);+ });+});++describe('referrerHostname', () => {+ test('returns hostname only (never the path)', () => {+ expect(referrerHostname(req({ referer: 'https://news.ycombinator.com/item?id=1' }))).toBe(+ 'news.ycombinator.com',+ );+ });+ test('undefined when missing or unparseable', () => {+ expect(referrerHostname(req())).toBeUndefined();+ expect(referrerHostname(req({ referer: 'not a url' }))).toBeUndefined();+ });+});++describe('captureServerEvent', () => {+ test('no-ops (no fetch) when the key is unset', () => {+ delete process.env.NEXT_PUBLIC_POSTHOG_KEY;+ let called = false;+ const orig = globalThis.fetch;+ globalThis.fetch = (async () => {+ called = true;+ return new Response(null);+ }) as typeof fetch;+ try {+ captureServerEvent({ event: 'dmg_downloaded', distinctId: 'd1' });+ } finally {+ globalThis.fetch = orig;+ }+ expect(called).toBe(false);+ });++ test('never throws even when scheduling fails (key set, no request scope)', () => {+ process.env.NEXT_PUBLIC_POSTHOG_KEY = KEY;+ expect(() => captureServerEvent({ event: 'dmg_downloaded', distinctId: 'd1' })).not.toThrow();+ });+});diff --git a/docs/src/lib/track.ts b/docs/src/lib/track.tsnew file mode 100644index 000000000..f541e2cff--- /dev/null+++ b/docs/src/lib/track.ts@@ -0,0 +1,106 @@+import { after } from 'next/server';++const POSTHOG_CAPTURE_URL = 'https://us.i.posthog.com/capture/';+const CAPTURE_TIMEOUT_MS = 3_000;++export interface TrackOptions {+ event: string;+ distinctId: string;+ properties?: Record<string, string | undefined>;+}++export interface CapturePayload {+ api_key: string;+ event: string;+ distinct_id: string;+ timestamp: string;+ properties: Record<string, unknown>;+}++export function buildCapturePayload(opts: TrackOptions, key: string): CapturePayload {+ const properties: Record<string, unknown> = {};+ if (opts.properties) {+ for (const [k, v] of Object.entries(opts.properties)) {+ if (v !== undefined) properties[k] = v;+ }+ }+ properties.$ip = null;+ properties.$geoip_disable = true;+ return {+ api_key: key,+ event: opts.event,+ distinct_id: opts.distinctId,+ timestamp: new Date().toISOString(),+ properties,+ };+}++export function captureServerEvent(opts: TrackOptions): void {+ try {+ const key = process.env.NEXT_PUBLIC_POSTHOG_KEY;+ if (!key) return;+ const payload = buildCapturePayload(opts, key);+ after(async () => {+ try {+ const res = await fetch(POSTHOG_CAPTURE_URL, {+ method: 'POST',+ headers: { 'content-type': 'application/json' },+ body: JSON.stringify(payload),+ signal: AbortSignal.timeout(CAPTURE_TIMEOUT_MS),+ });+ if (!res.ok) {+ console.warn(`[track] capture HTTP ${res.status} for ${opts.event}`);+ }+ } catch (err) {+ console.warn(+ `[track] capture failed for ${opts.event}: ${err instanceof Error ? err.message : String(err)}`,+ );+ }+ });+ } catch (err) {+ console.warn(+ `[track] capture skipped for ${opts.event}: ${err instanceof Error ? err.message : String(err)}`,+ );+ }+}++export function resolveDistinctId(request: Request): string {+ const key = process.env.NEXT_PUBLIC_POSTHOG_KEY;+ if (key) {+ const fromCookie = readPosthogDistinctId(request, key);+ if (fromCookie) return fromCookie;+ }+ return crypto.randomUUID();+}++function readPosthogDistinctId(request: Request, key: string): string | null {+ const cookieHeader = request.headers.get('cookie');+ if (!cookieHeader) return null;+ const cookieName = `ph_${key}_posthog`;+ for (const part of cookieHeader.split(';')) {+ const eq = part.indexOf('=');+ if (eq === -1) continue;+ if (part.slice(0, eq).trim() !== cookieName) continue;+ try {+ const parsed = JSON.parse(decodeURIComponent(part.slice(eq + 1).trim())) as {+ distinct_id?: unknown;+ };+ return typeof parsed.distinct_id === 'string' && parsed.distinct_id.length > 0+ ? parsed.distinct_id+ : null;+ } catch {+ return null;+ }+ }+ return null;+}++export function referrerHostname(request: Request): string | undefined {+ const referer = request.headers.get('referer');+ if (!referer) return undefined;+ try {+ return new URL(referer).hostname;+ } catch {+ return undefined;+ }+}