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.

app/api/admin/growth/route.ts

@@ -0,0 +1,35 @@
+import { NextRequest } from 'next/server';
+import { auth } from '@/lib/auth';
+import { apiErrors, successResponse, withCacheControl } from '@/lib/api-response';
+import { conversionRates, getScoreboard } from '@/lib/analytics/scoreboard';
+import { isProductAnalyticsEnabled } from '@/lib/feature-flags';
+import { logError } from '@/lib/logger';
+
+// The same numbers /admin/growth renders, as JSON, so the Monday digest can pull
+// the scoreboard instead of somebody retyping it into a table.
+export async function GET(request: NextRequest) {
+  try {
+    const session = await auth();
+    if (!session?.user?.isAdmin) {
+      return apiErrors.forbidden('Admin access required');
+    }
+
+    if (!isProductAnalyticsEnabled()) {
+      return apiErrors.badRequest('Analytics are disabled by this host');
+    }
+
+    const weeksParam = Number(request.nextUrl.searchParams.get('weeks'));
+    const scoreboard = await getScoreboard({
+      weeks: Number.isSafeInteger(weeksParam) && weeksParam > 0 ? weeksParam : undefined,
+    });
+
+    const response = successResponse({
+      ...scoreboard,
+      weeks: scoreboard.weeks.map((week) => ({ ...week, rates: conversionRates(week) })),
+    });
+    return withCacheControl(response, 'private, no-store');
+  } catch (error) {
+    logError('Error building the growth scoreboard:', error);
+    return apiErrors.internalError('Failed to build the scoreboard');
+  }
+}

app/api/approvals/[requestId]/decision/route.ts

@@ -6,6 +6,7 @@ import { notifyUsers } from '@/lib/notifications';
 import { rateLimit } from '@/lib/rate-limit';
 import { apiErrors, successResponse, withCacheControl } from '@/lib/api-response';
 import { logError } from '@/lib/logger';
+import { eventKey, recordEvent } from '@/lib/analytics/record';
 
 type RouteParams = { params: Promise<{ requestId: string }> };
 
@@ -202,6 +203,12 @@ export async function POST(request: NextRequest, { params }: RouteParams) {
     });
 
     if (updated.status === 'APPROVED') {
+      await recordEvent({
+        name: 'APPROVAL_COMPLETED',
+        dedupeKey: eventKey('APPROVAL_COMPLETED', requestId),
+        userId: approvalRequest.version.video.project.ownerId,
+      });
+
       notifyUsers([updated.requestedById], {
         type: 'approval_completed',
         projectName: updated.version.video.project.name,

app/api/auth/register/route.ts

@@ -17,6 +17,8 @@ import {
   sendVerificationEmail,
 } from '@/lib/email-verification';
 import { isValidEmailAddress, normalizeEmail } from '@/lib/email-validation';
+import { recordSignupCompleted } from '@/lib/analytics/signup';
+import { readVisitorContext } from '@/lib/analytics/visitor';
 
 export async function POST(request: NextRequest) {
   try {
@@ -132,6 +134,14 @@ export async function POST(request: NextRequest) {
       }
     }
 
+    // Ties the account to the first touch stored in this browser's cookie and
+    // claims the visitor events that led here. Recorded after the invitation has
+    // been accepted, so an account that gets rolled back never leaves a signup.
+    await recordSignupCompleted({
+      userId: user.id,
+      visitor: readVisitorContext(request.cookies),
+    });
+
     // Send verification email if SMTP is configured
     if (emailVerificationRequired) {
       const verificationToken = await createVerificationToken(normalizedEmail);

app/api/billing/checkout/route.ts

@@ -11,6 +11,7 @@ import { isStripeFeatureEnabled } from '@/lib/feature-flags';
 import { getStripe, getStripePriceId, isStripeConfigured } from '@/lib/stripe';
 import { isTrustedSameOriginRequest } from '@/lib/request-origin';
 import { logError } from '@/lib/logger';
+import { eventKey, recordEvent } from '@/lib/analytics/record';
 
 function getAppOrigin(request: NextRequest) {
   if (isTrustedSameOriginRequest(request)) {
@@ -84,6 +85,15 @@ export async function POST(request: NextRequest) {
       throw new Error('Stripe did not return a checkout URL');
     }
 
+    // Keyed on the Stripe session, so an abandoned checkout followed by a second
+    // attempt counts twice. That is the intent: the gap between checkouts started
+    // and subscriptions started is the number worth watching.
+    await recordEvent({
+      name: 'CHECKOUT_STARTED',
+      dedupeKey: eventKey('CHECKOUT_STARTED', checkoutSession.id),
+      userId: session.user.id,
+    });
+
     const response = successResponse({ url: checkoutSession.url });
     return withCacheControl(response, 'private, no-store');
   } catch (error) {

app/api/events/route.ts

@@ -0,0 +1,36 @@
+import { NextRequest } from 'next/server';
+import { rateLimit } from '@/lib/rate-limit';
+import { isTrustedSameOriginRequest } from '@/lib/request-origin';
+import { readVisitorContext, recordVisitorEvent } from '@/lib/analytics/visitor';
+
+// The one funnel event that cannot be observed from the server: a click on a
+// call to action, which never reaches us as a request of its own.
+//
+// Everything else in the funnel is recorded where it actually happens, so this
+// endpoint accepts exactly one event name. An anonymous caller must not be able
+// to post `SUBSCRIPTION_STARTED` into the scoreboard, and the cheapest way to
+// guarantee that is to make the allowed set a single literal.
+const ALLOWED_EVENTS = new Set(['cta_clicked']);
+
+export async function POST(request: NextRequest) {
+  // Answers 204 whatever happens. This endpoint reports nothing back to the page
+  // that called it, so there is no reason to tell a caller which of their
+  // attempts landed.
+  const noContent = new Response(null, {
+    status: 204,
+    headers: { 'Cache-Control': 'private, no-store' },
+  });
+
+  const limited = await rateLimit(request, 'analytics-beacon');
+  if (limited) return limited;
+
+  if (!isTrustedSameOriginRequest(request)) return noContent;
+
+  const body = await request.json().catch(() => null);
+  const name = typeof body?.name === 'string' ? body.name : '';
+  if (!ALLOWED_EVENTS.has(name)) return noContent;
+
+  await recordVisitorEvent('CTA_CLICKED', readVisitorContext(request.cookies));
+
+  return noContent;
+}

app/api/onboarding/source/route.ts

@@ -0,0 +1,40 @@
+import { NextRequest } from 'next/server';
+import { auth } from '@/lib/auth';
+import { apiErrors, successResponse, withCacheControl } from '@/lib/api-response';
+import { rateLimit } from '@/lib/rate-limit';
+import { setSelfReportedSource } from '@/lib/analytics/record';
+import { isAcquisitionChannel } from '@/lib/analytics/cookies';
+import { isProductAnalyticsEnabled } from '@/lib/feature-flags';
+
+// "How did you hear about us?", answered on the first onboarding screen.
+//
+// It is stored beside the cookie-derived channel rather than instead of it. The
+// cookie is precise but loses cross-device visits and cleared browsers; the
+// answer survives both, and it is the only thing that can name a channel no UTM
+// tag ever carries, like being told about it by a friend.
+export async function POST(request: NextRequest) {
+  const session = await auth();
+  if (!session?.user?.id) {
+    return apiErrors.unauthorized();
+  }
+
+  const limited = await rateLimit(request, 'onboarding-complete');
+  if (limited) return limited;
+
+  if (!isProductAnalyticsEnabled()) {
+    return apiErrors.badRequest('Analytics are disabled by this host');
+  }
+
+  const body = await request.json().catch(() => null);
+  const source = body?.source;
+  if (!isAcquisitionChannel(source)) {
+    return apiErrors.badRequest('Unknown source');
+  }
+
+  const note = typeof body?.note === 'string' ? body.note : null;
+
+  await setSelfReportedSource({ userId: session.user.id, selfReported: source, note });
+
+  const response = successResponse({ recorded: true });
+  return withCacheControl(response, 'private, no-store');
+}

app/api/projects/[projectId]/videos/[videoId]/share/route.ts

@@ -8,6 +8,7 @@ import { db } from '@/lib/db';
 import { rateLimit } from '@/lib/rate-limit';
 import { MAX_SHARE_PASSWORD_LENGTH } from '@/lib/share-links';
 import { logError } from '@/lib/logger';
+import { eventKey, recordEvent } from '@/lib/analytics/record';
 
 type RouteParams = { params: Promise<{ projectId: string; videoId: string }> };
 
@@ -141,7 +142,11 @@ export async function POST(request: NextRequest, { params }: RouteParams) {
     }
 
     const { projectId, videoId } = await params;
-    const { error } = await requireShareManagementAccess(projectId, videoId, session.user.id);
+    const { error, video } = await requireShareManagementAccess(
+      projectId,
+      videoId,
+      session.user.id
+    );
     if (error) return error;
 
     const body = await request.json().catch(() => ({}));
@@ -244,6 +249,14 @@ export async function POST(request: NextRequest, { params }: RouteParams) {
       return apiErrors.internalError('Failed to create video share link');
     }
 
+    // Keyed on the link id, so re-issuing the token for a link that already
+    // exists updates the row and records nothing: the share was created once.
+    await recordEvent({
+      name: 'SHARE_LINK_CREATED',
+      dedupeKey: eventKey('SHARE_LINK_CREATED', link.id),
+      userId: video?.project.ownerId ?? null,
+    });
+
     const response = successResponse(serializeShareLink(request, videoId, link));
 
     return withCacheControl(response, 'private, no-store');

app/api/projects/[projectId]/videos/route.ts

@@ -8,6 +8,7 @@ import { apiErrors, successResponse, withCacheControl } from '@/lib/api-response
 import { verifyBunnyUploadToken } from '@/lib/bunny-upload-token';
 import { finalizeR2VideoUpload } from '@/lib/r2-video-finalize';
 import { logError } from '@/lib/logger';
+import { eventKey, recordEvent } from '@/lib/analytics/record';
 
 type RouteParams = { params: Promise<{ projectId: string }> };
 
@@ -268,6 +269,12 @@ export async function POST(request: NextRequest, { params }: RouteParams) {
       }).catch((err) => logError('Notification failed:', err));
     }
 
+    await recordEvent({
+      name: 'VIDEO_ADDED',
+      dedupeKey: eventKey('VIDEO_ADDED', video.id),
+      userId: project.ownerId,
+    });
+
     const response = successResponse(video, 201);
     return withCacheControl(response, 'private, no-store');
   } catch (error) {

app/api/projects/route.ts

@@ -7,6 +7,7 @@ import { buildBillingAccessWhereInput } from '@/lib/billing';
 import { apiErrors, successResponse, withCacheControl } from '@/lib/api-response';
 import { DEFAULT_COMMENT_TAGS } from '@/lib/comment-tags';
 import { logError } from '@/lib/logger';
+import { eventKey, recordEvent } from '@/lib/analytics/record';
 
 // GET /api/projects - List all projects for the authenticated user
 export async function GET(request: NextRequest) {
@@ -187,6 +188,15 @@ export async function POST(request: NextRequest) {
       return createdProject;
     });
 
+    // Attributed to the workspace owner rather than the caller: the funnel asks
+    // which account is progressing, and a team member creating a project moves
+    // the owner's account, not their own.
+    await recordEvent({
+      name: 'PROJECT_CREATED',
+      dedupeKey: eventKey('PROJECT_CREATED', project.id),
+      userId: workspace.ownerId,
+    });
+
     const response = successResponse(project, 201);
     return withCacheControl(response, 'private, no-store');
   } catch (error) {

app/api/versions/[versionId]/comments/route.ts

@@ -13,6 +13,7 @@ import {
   getGuestIdentityFromRequest,
   setGuestIdentityCookie,
 } from '@/lib/guest-identity';
+import { eventKey, recordEvent } from '@/lib/analytics/record';
 import {
   extractImageFileNameFromProxyUrl,
   extractAudioFileNameFromProxyUrl,
@@ -547,6 +548,18 @@ export async function POST(request: NextRequest, { params }: RouteParams) {
       }
     }
 
+    // Feedback arriving from outside the team is the moment this product
+    // becomes worth paying for, so it is the activation step of the funnel.
+    // Keyed on the account, not the comment: what matters is the first time an
+    // account ever received one.
+    if (isGuest) {
+      await recordEvent({
+        name: 'FIRST_GUEST_COMMENT',
+        dedupeKey: eventKey('FIRST_GUEST_COMMENT', project.workspace.ownerId),
+        userId: project.workspace.ownerId,
+      });
+    }
+
     const viewerUserId = session?.user?.id ?? null;
     const viewerGuestIdentityId = viewerUserId
       ? null

app/api/workspaces/route.ts

@@ -5,6 +5,7 @@ import { rateLimit } from '@/lib/rate-limit';
 import { buildBillingAccessWhereInput, getWorkspaceCreationEligibility } from '@/lib/billing';
 import { apiErrors, successResponse, withCacheControl } from '@/lib/api-response';
 import { logError } from '@/lib/logger';
+import { eventKey, recordEvent } from '@/lib/analytics/record';
 
 // GET /api/workspaces - List all workspaces for the authenticated user
 export async function GET(request: NextRequest) {
@@ -136,6 +137,12 @@ export async function POST(request: NextRequest) {
       },
     });
 
+    await recordEvent({
+      name: 'WORKSPACE_CREATED',
+      dedupeKey: eventKey('WORKSPACE_CREATED', workspace.id),
+      userId: workspace.ownerId,
+    });
+
     const response = successResponse(workspace, 201);
     return withCacheControl(response, 'private, no-store');
   } catch (error) {