feat(analytics): record where paying customers actually came from

Adds first-party acquisition attribution and a sixteen-event funnel, written to
this deployment's own database and read back on /admin/growth. Nothing is sent
anywhere else, and the whole subsystem is off unless OPENFRAME_ENABLE_ANALYTICS
is set, so a self-hosted instance carries the tables empty and pays nothing.

The proxy gives a visitor an anonymous id and stores what brought them in two
first-party cookies; signup copies that onto the account and claims the events
the visitor produced before they had one, which is what joins the two halves of
the funnel. Recording happens where each step actually happens rather than in
the browser: an ad blocker cannot undercount landing views, and blocking rates
differ by channel, so an undercounted denominator would have made GitHub traffic
look like it converts better than it does.

Every event carries a dedupe key on a UNIQUE column, so "recorded exactly once"
is a property of the schema rather than of fifteen call sites. Subscription
events are derived by comparing the row being overwritten with the row being
written inside the existing Stripe sync, which makes them order-independent and
replay-safe.

The scoreboard reports step-to-step conversion with the denominator beside it,
and splits by source over a rolling 28-day window rather than a week: at this
volume a weekly per-source cell holds single digits, and a percentage computed
from three visits reads exactly as confidently as one computed from three
hundred.

"How did you hear about us?" is asked on the first onboarding screen, not on the
registration form. The number being measured is the signup conversion rate, and
a question added to that form would move it.

tests/api/analytics-events.test.ts

@@ -0,0 +1,365 @@
+// The property the whole acquisition system rests on: every funnel event is
+// recorded exactly once, against the right account, and nothing at all is
+// recorded when the feature flag is off.
+//
+// The dedupe key is a UNIQUE column, so these tests are checking that each call
+// site derives the right key. A key that varies when it should not shows up here
+// as a duplicated row, which is the failure that would quietly inflate the
+// scoreboard.
+
+import { describe, expect, it, beforeEach, afterEach, vi } from 'vitest';
+import { db } from '@/lib/db';
+import { POST as beacon } from '@/app/api/events/route';
+import { POST as register } from '@/app/api/auth/register/route';
+import { recordSubscriptionTransition } from '@/lib/analytics/billing-events';
+import { recordSignupCompleted } from '@/lib/analytics/signup';
+import { encodeFirstTouch, type FirstTouch } from '@/lib/analytics/cookies';
+import { apiRequest, callRoute } from '../helpers/request';
+import { signedOut } from '../helpers/session';
+import { createUser } from '../factories';
+
+const ANON_ID = 'a1b2c3d4e5f60718293a4b5c6d7e8f90';
+const INVITE_CODE = 'test-invite';
+const ORIGIN = 'http://localhost:3000';
+
+const GITHUB_TOUCH: FirstTouch = {
+  channel: 'GITHUB',
+  utmSource: 'github',
+  utmMedium: 'readme',
+  utmCampaign: null,
+  referrerHost: 'github.com',
+  landingPath: '/',
+};
+
+function visitorCookies(anonymousId = ANON_ID, touch: FirstTouch = GITHUB_TOUCH) {
+  return { of_aid: anonymousId, of_ft: encodeFirstTouch(touch) };
+}
+
+function beaconRequest(options?: {
+  name?: string;
+  origin?: string | null;
+  cookies?: Record<string, string>;
+}) {
+  const headers: Record<string, string> = {};
+  const origin = options?.origin === undefined ? ORIGIN : options.origin;
+  if (origin) headers.origin = origin;
+
+  return apiRequest('/api/events', {
+    body: { name: options?.name ?? 'cta_clicked' },
+    headers,
+    cookies: options?.cookies ?? visitorCookies(),
+  });
+}
+
+async function eventNames(): Promise<string[]> {
+  const rows = await db.analyticsEvent.findMany({ orderBy: { dedupeKey: 'asc' } });
+  return rows.map((row) => row.name);
+}
+
+beforeEach(() => {
+  signedOut();
+  vi.stubEnv('OPENFRAME_ENABLE_ANALYTICS', 'true');
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+describe('POST /api/events', () => {
+  it('records a CTA click and the first touch behind it', async () => {
+    const response = await callRoute(beacon, beaconRequest());
+
+    expect(response.status).toBe(204);
+
+    const events = await db.analyticsEvent.findMany();
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      name: 'CTA_CLICKED',
+      anonymousId: ANON_ID,
+      channel: 'GITHUB',
+      userId: null,
+    });
+
+    const touches = await db.acquisitionTouch.findMany();
+    expect(touches).toHaveLength(1);
+    expect(touches[0]).toMatchObject({
+      anonymousId: ANON_ID,
+      channel: 'GITHUB',
+      utmSource: 'github',
+      referrerHost: 'github.com',
+    });
+  });
+
+  it('records one event however many times the same visitor clicks', async () => {
+    await callRoute(beacon, beaconRequest());
+    await callRoute(beacon, beaconRequest());
+    await callRoute(beacon, beaconRequest());
+
+    expect(await db.analyticsEvent.count()).toBe(1);
+  });
+
+  it('counts two different visitors separately', async () => {
+    await callRoute(beacon, beaconRequest());
+    await callRoute(
+      beacon,
+      beaconRequest({ cookies: visitorCookies('f0e1d2c3b4a596877869504132231415') })
+    );
+
+    expect(await db.analyticsEvent.count()).toBe(2);
+  });
+
+  it('never keeps the first touch of a visitor who came back through another link', async () => {
+    await callRoute(beacon, beaconRequest());
+    await callRoute(
+      beacon,
+      beaconRequest({
+        cookies: visitorCookies(ANON_ID, { ...GITHUB_TOUCH, channel: 'GOOGLE', utmSource: null }),
+      })
+    );
+
+    const touches = await db.acquisitionTouch.findMany();
+    expect(touches).toHaveLength(1);
+    expect(touches[0]?.channel).toBe('GITHUB');
+  });
+
+  it('refuses to record an event name the beacon does not own', async () => {
+    // Without this the endpoint would let any anonymous caller write a payment
+    // into the funnel.
+    for (const name of ['subscription_started', 'signup_completed', 'SUBSCRIPTION_STARTED', '']) {
+      const response = await callRoute(beacon, beaconRequest({ name }));
+      expect(response.status, name).toBe(204);
+    }
+
+    expect(await db.analyticsEvent.count()).toBe(0);
+  });
+
+  it('ignores a cross-origin caller', async () => {
+    const response = await callRoute(beacon, beaconRequest({ origin: 'https://evil.example' }));
+
+    expect(response.status).toBe(204);
+    expect(await db.analyticsEvent.count()).toBe(0);
+  });
+
+  it('ignores a caller with no anonymous id cookie', async () => {
+    await callRoute(beacon, beaconRequest({ cookies: {} }));
+
+    expect(await db.analyticsEvent.count()).toBe(0);
+    expect(await db.acquisitionTouch.count()).toBe(0);
+  });
+
+  it('writes nothing at all when the flag is off', async () => {
+    vi.stubEnv('OPENFRAME_ENABLE_ANALYTICS', 'false');
+
+    const response = await callRoute(beacon, beaconRequest());
+
+    expect(response.status).toBe(204);
+    expect(await db.analyticsEvent.count()).toBe(0);
+    expect(await db.acquisitionTouch.count()).toBe(0);
+  });
+});
+
+describe('signup attribution', () => {
+  async function registerWithCookies(email: string) {
+    return callRoute(
+      register,
+      apiRequest('/api/auth/register', {
+        body: {
+          name: 'New User',
+          email,
+          password: 'correct horse battery',
+          inviteCode: INVITE_CODE,
+        },
+        cookies: visitorCookies(),
+      })
+    );
+  }
+
+  it('copies the first touch onto the account and records the signup once', async () => {
+    const response = await registerWithCookies('[email protected]');
+    expect(response.status).toBe(201);
+
+    const user = await db.user.findUniqueOrThrow({ where: { email: '[email protected]' } });
+    const acquisition = await db.userAcquisition.findUniqueOrThrow({
+      where: { userId: user.id },
+    });
+
+    expect(acquisition).toMatchObject({
+      channel: 'GITHUB',
+      utmSource: 'github',
+      utmMedium: 'readme',
+      referrerHost: 'github.com',
+      anonymousId: ANON_ID,
+    });
+
+    const signups = await db.analyticsEvent.findMany({ where: { name: 'SIGNUP_COMPLETED' } });
+    expect(signups).toHaveLength(1);
+    expect(signups[0]?.userId).toBe(user.id);
+  });
+
+  it('claims the events the visitor produced before they had an account', async () => {
+    await callRoute(beacon, beaconRequest());
+    await registerWithCookies('[email protected]');
+
+    const user = await db.user.findUniqueOrThrow({ where: { email: '[email protected]' } });
+    const click = await db.analyticsEvent.findFirstOrThrow({ where: { name: 'CTA_CLICKED' } });
+
+    // Without the backfill the click and the signup are two unrelated rows and
+    // no query can tell you which channel converted.
+    expect(click.userId).toBe(user.id);
+  });
+
+  it('records one signup even if the helper runs twice', async () => {
+    const user = await createUser();
+
+    await recordSignupCompleted({
+      userId: user.id,
+      visitor: { anonymousId: ANON_ID, firstTouch: GITHUB_TOUCH },
+    });
+    await recordSignupCompleted({
+      userId: user.id,
+      visitor: { anonymousId: ANON_ID, firstTouch: GITHUB_TOUCH },
+    });
+
+    expect(await db.analyticsEvent.count({ where: { name: 'SIGNUP_COMPLETED' } })).toBe(1);
+    expect(await db.userAcquisition.count({ where: { userId: user.id } })).toBe(1);
+  });
+
+  it('records no acquisition row when the flag is off', async () => {
+    vi.stubEnv('OPENFRAME_ENABLE_ANALYTICS', 'false');
+
+    const response = await registerWithCookies('[email protected]');
+
+    expect(response.status).toBe(201);
+    expect(await db.userAcquisition.count()).toBe(0);
+    expect(await db.analyticsEvent.count()).toBe(0);
+  });
+});
+
+describe('subscription transitions', () => {
+  const SUB = 'sub_test_1';
+  const periodEnd = new Date('2026-09-01T00:00:00.000Z');
+
+  async function transition(params: {
+    userId: string;
+    beforeStatus: 'FREE' | 'TRIALING' | 'ACTIVE' | 'CANCELED';
+    afterStatus: 'FREE' | 'TRIALING' | 'ACTIVE' | 'CANCELED';
+    beforeCancelAtPeriodEnd?: boolean;
+    afterCancelAtPeriodEnd?: boolean;
+    hadTrial?: boolean;
+    trialEndsAt?: Date | null;
+  }) {
+    await recordSubscriptionTransition({
+      userId: params.userId,
+      subscriptionId: SUB,
+      before: {
+        status: params.beforeStatus,
+        cancelAtPeriodEnd: params.beforeCancelAtPeriodEnd ?? false,
+        hadTrial: params.hadTrial ?? false,
+      },
+      after: {
+        status: params.afterStatus,
+        cancelAtPeriodEnd: params.afterCancelAtPeriodEnd ?? false,
+        trialEndsAt: params.trialEndsAt ?? null,
+        currentPeriodEnd: periodEnd,
+      },
+    });
+  }
+
+  it('records the trial once and the conversion to paid once', async () => {
+    const user = await createUser();
+
+    await transition({
+      userId: user.id,
+      beforeStatus: 'FREE',
+      afterStatus: 'TRIALING',
+      trialEndsAt: new Date('2026-08-15T00:00:00.000Z'),
+    });
+    // The same webhook arriving again, which Stripe does routinely.
+    await transition({
+      userId: user.id,
+      beforeStatus: 'FREE',
+      afterStatus: 'TRIALING',
+      trialEndsAt: new Date('2026-08-15T00:00:00.000Z'),
+    });
+    await transition({
+      userId: user.id,
+      beforeStatus: 'TRIALING',
+      afterStatus: 'ACTIVE',
+      hadTrial: true,
+    });
+
+    expect(await eventNames()).toEqual(['SUBSCRIPTION_STARTED', 'TRIAL_STARTED']);
+  });
+
+  it('does not record a second trial for an account that already had one', async () => {
+    const user = await createUser();
+
+    await transition({
+      userId: user.id,
+      beforeStatus: 'CANCELED',
+      afterStatus: 'TRIALING',
+      hadTrial: true,
+      trialEndsAt: new Date('2026-08-15T00:00:00.000Z'),
+    });
+
+    expect(await eventNames()).toEqual([]);
+  });
+
+  it('counts one cancellation for the flag and the status that follow each other', async () => {
+    const user = await createUser();
+
+    // The customer cancels in the portal: cancel_at_period_end flips on.
+    await transition({
+      userId: user.id,
+      beforeStatus: 'ACTIVE',
+      afterStatus: 'ACTIVE',
+      afterCancelAtPeriodEnd: true,
+    });
+    // The term ends weeks later and Stripe marks the subscription canceled.
+    await transition({
+      userId: user.id,
+      beforeStatus: 'ACTIVE',
+      afterStatus: 'CANCELED',
+      beforeCancelAtPeriodEnd: true,
+    });
+
+    expect(await db.analyticsEvent.count({ where: { name: 'SUBSCRIPTION_CANCELED' } })).toBe(1);
+  });
+
+  it('records a reactivation when the customer changes their mind', async () => {
+    const user = await createUser();
+
+    await transition({
+      userId: user.id,
+      beforeStatus: 'ACTIVE',
+      afterStatus: 'ACTIVE',
+      afterCancelAtPeriodEnd: true,
+    });
+    await transition({
+      userId: user.id,
+      beforeStatus: 'ACTIVE',
+      afterStatus: 'ACTIVE',
+      beforeCancelAtPeriodEnd: true,
+      afterCancelAtPeriodEnd: false,
+    });
+
+    expect(await eventNames()).toEqual(['SUBSCRIPTION_CANCELED', 'SUBSCRIPTION_REACTIVATED']);
+  });
+
+  it('records nothing when nothing changed', async () => {
+    const user = await createUser();
+
+    await transition({ userId: user.id, beforeStatus: 'ACTIVE', afterStatus: 'ACTIVE' });
+
+    expect(await eventNames()).toEqual([]);
+  });
+
+  it('writes nothing when the flag is off', async () => {
+    vi.stubEnv('OPENFRAME_ENABLE_ANALYTICS', 'false');
+    const user = await createUser();
+
+    await transition({ userId: user.id, beforeStatus: 'FREE', afterStatus: 'ACTIVE' });
+
+    expect(await db.analyticsEvent.count()).toBe(0);
+  });
+});

tests/api/analytics-scoreboard.test.ts

@@ -0,0 +1,155 @@
+// Exercises the scoreboard queries against a real database.
+//
+// These are raw SQL: a date_trunc grouping, a COALESCE across two tables and a
+// filtered left join. None of that is checked by the type system, so a seeded
+// week with known counts is the only thing standing between a renamed column and
+// a growth page that renders zeros forever.
+
+import { describe, expect, it, beforeEach, afterEach, vi } from 'vitest';
+import type { AcquisitionChannel, AnalyticsEventName } from '@prisma/client';
+import { db } from '@/lib/db';
+import { AT_RISK_SILENT_DAYS, getScoreboard } from '@/lib/analytics/scoreboard';
+import { createUser } from '../factories';
+
+function daysAgo(days: number): Date {
+  const date = new Date();
+  date.setUTCDate(date.getUTCDate() - days);
+  return date;
+}
+
+let sequence = 0;
+
+async function seedEvent(params: {
+  name: AnalyticsEventName;
+  occurredAt: Date;
+  userId?: string;
+  anonymousId?: string;
+  channel?: AcquisitionChannel;
+}) {
+  sequence += 1;
+  await db.analyticsEvent.create({
+    data: {
+      name: params.name,
+      dedupeKey: `${params.name}:seed-${sequence}`,
+      occurredAt: params.occurredAt,
+      userId: params.userId ?? null,
+      anonymousId: params.anonymousId ?? null,
+      channel: params.channel ?? null,
+    },
+  });
+}
+
+beforeEach(() => {
+  sequence = 0;
+  vi.stubEnv('OPENFRAME_ENABLE_ANALYTICS', 'true');
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+describe('getScoreboard', () => {
+  it('returns an empty week for every week in the window when nothing happened', async () => {
+    const scoreboard = await getScoreboard({ weeks: 4 });
+
+    expect(scoreboard.weeks).toHaveLength(4);
+    expect(scoreboard.weeks.every((week) => week.visitors === 0)).toBe(true);
+    expect(scoreboard.channels).toEqual([]);
+    expect(scoreboard.paidAccounts).toEqual([]);
+  });
+
+  it('counts a returning visitor once per week, not once per visit', async () => {
+    // Landing views are deduped per visitor per day, so the same person on three
+    // days is three rows. Weekly visitors is a distinct count over the id.
+    for (const days of [1, 2, 3]) {
+      await seedEvent({
+        name: 'LANDING_VIEW',
+        occurredAt: daysAgo(days),
+        anonymousId: 'visitor-one',
+        channel: 'GITHUB',
+      });
+    }
+    await seedEvent({
+      name: 'LANDING_VIEW',
+      occurredAt: daysAgo(1),
+      anonymousId: 'visitor-two',
+      channel: 'GOOGLE',
+    });
+
+    const scoreboard = await getScoreboard({ weeks: 2 });
+    const total = scoreboard.weeks.reduce((sum, week) => sum + week.visitors, 0);
+
+    expect(total).toBe(2);
+  });
+
+  it('reads a signed-up visitor through the channel on their account', async () => {
+    const user = await createUser();
+    await db.userAcquisition.create({
+      data: { userId: user.id, channel: 'YOUTUBE', anonymousId: 'visitor-three' },
+    });
+
+    // The visitor event carries GITHUB from the cookie, but the account says
+    // YouTube. The account wins, so correcting a channel corrects its history.
+    await seedEvent({
+      name: 'LANDING_VIEW',
+      occurredAt: daysAgo(2),
+      anonymousId: 'visitor-three',
+      channel: 'GITHUB',
+      userId: user.id,
+    });
+    await seedEvent({
+      name: 'SIGNUP_COMPLETED',
+      occurredAt: daysAgo(2),
+      userId: user.id,
+      anonymousId: 'visitor-three',
+    });
+
+    const scoreboard = await getScoreboard({ weeks: 2 });
+    const youtube = scoreboard.channels.find((row) => row.channel === 'YOUTUBE');
+
+    expect(youtube).toMatchObject({ visitors: 1, signups: 1 });
+    expect(scoreboard.channels.find((row) => row.channel === 'GITHUB')).toBeUndefined();
+  });
+
+  it('carries subscriptions started before the window into the running total', async () => {
+    await seedEvent({ name: 'SUBSCRIPTION_STARTED', occurredAt: daysAgo(120) });
+    await seedEvent({ name: 'SUBSCRIPTION_STARTED', occurredAt: daysAgo(3) });
+    await seedEvent({ name: 'SUBSCRIPTION_CANCELED', occurredAt: daysAgo(3) });
+
+    const scoreboard = await getScoreboard({ weeks: 2 });
+    const last = scoreboard.weeks[scoreboard.weeks.length - 1];
+
+    // One from before the window, plus one started and one canceled inside it.
+    expect(last?.activePaid).toBe(1);
+    expect(last?.newPaid).toBe(1);
+    expect(last?.canceled).toBe(1);
+  });
+
+  it('flags a paid account that has produced nothing recently', async () => {
+    const busy = await createUser({ subscriptionStatus: 'ACTIVE' });
+    const silent = await createUser({ subscriptionStatus: 'ACTIVE' });
+    const trialing = await createUser({ subscriptionStatus: 'TRIALING' });
+    await createUser({ subscriptionStatus: 'FREE' });
+
+    await seedEvent({ name: 'VIDEO_ADDED', occurredAt: daysAgo(2), userId: busy.id });
+    await seedEvent({ name: 'SHARE_LINK_CREATED', occurredAt: daysAgo(20), userId: busy.id });
+    await seedEvent({
+      name: 'VIDEO_ADDED',
+      occurredAt: daysAgo(AT_RISK_SILENT_DAYS + 5),
+      userId: silent.id,
+    });
+    // A signup is not a value event, so it must not clear the risk flag.
+    await seedEvent({ name: 'SIGNUP_COMPLETED', occurredAt: daysAgo(1), userId: trialing.id });
+
+    const scoreboard = await getScoreboard({ weeks: 4 });
+    const ids = scoreboard.paidAccounts.map((row) => row.userId).sort();
+    const atRisk = scoreboard.atRisk.map((row) => row.userId).sort();
+
+    expect(ids).toEqual([busy.id, silent.id, trialing.id].sort());
+    expect(atRisk).toEqual([silent.id, trialing.id].sort());
+
+    const busyRow = scoreboard.paidAccounts.find((row) => row.userId === busy.id);
+    expect(busyRow?.valueEvents7).toBe(1);
+    expect(busyRow?.valueEvents30).toBe(2);
+  });
+});

tests/api/auth-matrix.test.ts

@@ -44,6 +44,7 @@ import {
 } from '../factories';
 
 import * as adminFeedbackRoute from '@/app/api/admin/feedback/[feedbackId]/route';
+import * as adminGrowthRoute from '@/app/api/admin/growth/route';
 import * as adminRefreshR2Route from '@/app/api/admin/stats/refresh-r2/route';
 import * as approvalCancelRoute from '@/app/api/approvals/[requestId]/cancel/route';
 import * as approvalDecisionRoute from '@/app/api/approvals/[requestId]/decision/route';
@@ -54,6 +55,7 @@ import * as commentRoute from '@/app/api/comments/[commentId]/route';
 import * as feedbackRoute from '@/app/api/feedback/route';
 import * as feedbackUploadRoute from '@/app/api/feedback/upload/route';
 import * as onboardingCompleteRoute from '@/app/api/onboarding/complete/route';
+import * as onboardingSourceRoute from '@/app/api/onboarding/source/route';
 import * as approvalCandidatesRoute from '@/app/api/projects/[projectId]/approval-candidates/route';
 import * as projectDownloadRoute from '@/app/api/projects/[projectId]/download/route';
 import * as projectInvitationRoute from '@/app/api/projects/[projectId]/members/invitations/[invitationId]/route';
@@ -143,7 +145,7 @@ vi.mock('@/lib/r2', async (importOriginal) => {
 // The count guard
 // ---------------------------------------------------------------------------
 // Bump this only together with a new entry in ROUTE_CASES or in PUBLIC_ROUTES.
-const EXPECTED_ROUTE_MODULE_COUNT = 60;
+const EXPECTED_ROUTE_MODULE_COUNT = 63;
 
 /**
  * Routes that are public by design, and why. Everything else must reject an
@@ -176,6 +178,15 @@ const PUBLIC_ROUTES: ReadonlyMap<string, string> = new Map([
     // so it cannot be used to enumerate accounts.
     'resend of the verification email, for users who cannot sign in yet',
   ],
+  [
+    'events/route.ts',
+    // The CTA-click beacon. Its whole job is to hear from visitors who have no
+    // account yet, so a session cannot be the guard. It is bounded three ways
+    // instead: same-origin only, IP rate limited, and it accepts exactly one
+    // event name, so nothing a caller sends can forge a signup or a payment.
+    // Covered in tests/api/analytics-events.test.ts.
+    'anonymous CTA beacon, restricted to one event name and to same-origin callers',
+  ],
   [
     'stripe/webhook/route.ts',
     // Called by Stripe, not by a browser. Authenticated by the HMAC signature
@@ -350,6 +361,11 @@ const ROUTE_CASES: readonly RouteCase[] = [
     url: (f) => `/api/admin/feedback/${f.feedbackId}`,
     params: (f) => ({ feedbackId: f.feedbackId }),
   },
+  {
+    file: 'admin/growth/route.ts',
+    module: adminGrowthRoute,
+    url: () => '/api/admin/growth',
+  },
   {
     file: 'admin/stats/refresh-r2/route.ts',
     module: adminRefreshR2Route,
@@ -405,6 +421,12 @@ const ROUTE_CASES: readonly RouteCase[] = [
     module: onboardingCompleteRoute,
     url: () => '/api/onboarding/complete',
   },
+  {
+    file: 'onboarding/source/route.ts',
+    module: onboardingSourceRoute,
+    url: () => '/api/onboarding/source',
+    body: { source: 'GITHUB' },
+  },
   {
     file: 'projects/[projectId]/approval-candidates/route.ts',
     module: approvalCandidatesRoute,