From 7ca5abd041add2e471837c779d01fb4d3d8ad6e7 Mon Sep 17 00:00:00 2001 From: yusufipk Date: Sat, 1 Aug 2026 20:00:27 +0300 Subject: [PATCH] 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. --- .env.example | 4 + README.md | 1 + app/(auth)/register/page.tsx | 9 + app/(marketing)/[slug]/page.tsx | 14 +- app/admin/growth/page.tsx | 358 +++++++++++++++++ app/admin/layout.tsx | 16 +- app/api/admin/growth/route.ts | 35 ++ .../approvals/[requestId]/decision/route.ts | 7 + app/api/auth/register/route.ts | 10 + app/api/billing/checkout/route.ts | 10 + app/api/events/route.ts | 36 ++ app/api/onboarding/source/route.ts | 40 ++ .../videos/[videoId]/share/route.ts | 15 +- app/api/projects/[projectId]/videos/route.ts | 7 + app/api/projects/route.ts | 10 + .../versions/[versionId]/comments/route.ts | 13 + app/api/workspaces/route.ts | 7 + app/onboarding/onboarding-wizard.tsx | 77 +++- app/onboarding/page.tsx | 2 + app/page.tsx | 13 +- components/LandingPage.tsx | 13 +- components/marketing/comparison-page.tsx | 9 +- components/marketing/cta-link.tsx | 30 ++ lib/analytics/billing-events.ts | 88 +++++ lib/analytics/bots.ts | 42 ++ lib/analytics/channel.ts | 212 ++++++++++ lib/analytics/cookies.ts | 113 ++++++ lib/analytics/record.ts | 183 +++++++++ lib/analytics/scoreboard.ts | 323 ++++++++++++++++ lib/analytics/signup.ts | 48 +++ lib/analytics/visitor.ts | 72 ++++ lib/auth.ts | 15 + lib/billing.ts | 58 ++- lib/client/track.ts | 31 ++ lib/email-verification.ts | 19 + lib/feature-flags.ts | 10 + lib/rate-limit.ts | 3 + .../migration.sql | 87 +++++ prisma/schema.prisma | 116 +++++- proxy.ts | 72 +++- tests/api/analytics-events.test.ts | 365 ++++++++++++++++++ tests/api/analytics-scoreboard.test.ts | 155 ++++++++ tests/api/auth-matrix.test.ts | 24 +- tests/setup/db-global.ts | 1 + tests/unit/lib/analytics-channel.test.ts | 130 +++++++ tests/unit/lib/analytics-cookies.test.ts | 137 +++++++ tests/unit/lib/analytics-scoreboard.test.ts | 36 ++ tests/unit/proxy.test.ts | 163 ++++++++ 48 files changed, 3214 insertions(+), 25 deletions(-) create mode 100644 app/admin/growth/page.tsx create mode 100644 app/api/admin/growth/route.ts create mode 100644 app/api/events/route.ts create mode 100644 app/api/onboarding/source/route.ts create mode 100644 components/marketing/cta-link.tsx create mode 100644 lib/analytics/billing-events.ts create mode 100644 lib/analytics/bots.ts create mode 100644 lib/analytics/channel.ts create mode 100644 lib/analytics/cookies.ts create mode 100644 lib/analytics/record.ts create mode 100644 lib/analytics/scoreboard.ts create mode 100644 lib/analytics/signup.ts create mode 100644 lib/analytics/visitor.ts create mode 100644 lib/client/track.ts create mode 100644 prisma/migrations/20260801120000_add_acquisition_analytics/migration.sql create mode 100644 tests/api/analytics-events.test.ts create mode 100644 tests/api/analytics-scoreboard.test.ts create mode 100644 tests/unit/lib/analytics-channel.test.ts create mode 100644 tests/unit/lib/analytics-cookies.test.ts create mode 100644 tests/unit/lib/analytics-scoreboard.test.ts create mode 100644 tests/unit/proxy.test.ts diff --git a/.env.example b/.env.example index fa63f41..5d0d2f2 100644 --- a/.env.example +++ b/.env.example @@ -34,6 +34,10 @@ OPENFRAME_R2_MULTIPART_PART_SIZE_BYTES="33554432" # Run once after creating the bucket: bun run r2:configure-cors # Or set CORS manually in Cloudflare R2 -> bucket -> Settings -> CORS policy. OPENFRAME_REQUIRE_INVITE_CODE="true" +# Acquisition attribution and funnel events, read back on /admin/growth. Off by +# default: the rows only pay for themselves if you are running a signup funnel. +# Everything is written to this instance's own database and sent nowhere. +OPENFRAME_ENABLE_ANALYTICS="false" SELF_HOSTED_AUTO_CREATE_BUCKET="false" # ============================================================================ diff --git a/README.md b/README.md index adc1b64..79f6dfd 100644 --- a/README.md +++ b/README.md @@ -180,6 +180,7 @@ Behavior when disabled: - `OPENFRAME_ENABLE_BUNNY_UPLOADS=false` hides Bunny direct-upload entry points. URL-based providers such as YouTube remain available. - `OPENFRAME_ENABLE_S3_VIDEO_UPLOADS=true` (with `R2_*` configured) enables presigned uploads to your own S3-compatible storage. Set `OPENFRAME_ENABLE_BUNNY_UPLOADS=false` — only one direct-upload backend can be active. The bucket must allow CORS `PUT` from your app origin (for example `http://localhost:3000` in dev and your production URL). For Docker + MinIO, keep `R2_ENDPOINT=http://minio:9000` (app-internal) and set `R2_PRESIGN_ENDPOINT` to the browser-reachable MinIO origin (for example `http://localhost:9000` locally, or `https://minio.example.com` when MinIO is behind a reverse proxy). Use the origin only — no path suffix. The app's Content-Security-Policy is generated from runtime env at request time, so published Docker images pick up custom `R2_PRESIGN_ENDPOINT` values without rebuilding or editing `next.config.ts`. - `OPENFRAME_REQUIRE_INVITE_CODE=false` allows open registration while keeping invitation-link registration intact. +- `OPENFRAME_ENABLE_ANALYTICS=true` records first-touch attribution and funnel events into your own database, readable on `/admin/growth`. Off by default, and nothing leaves the instance either way. For self-hosted MinIO behind a reverse proxy, choose one of these browser-facing layouts: diff --git a/app/(auth)/register/page.tsx b/app/(auth)/register/page.tsx index 43a012a..2610263 100644 --- a/app/(auth)/register/page.tsx +++ b/app/(auth)/register/page.tsx @@ -1,3 +1,6 @@ +import { cookies } from 'next/headers'; +import { after } from 'next/server'; +import { readVisitorContext, recordVisitorEvent } from '@/lib/analytics/visitor'; import { isInviteCodeRequired } from '@/lib/feature-flags'; import { getInvitationPreviewByToken } from '@/lib/invitations'; import { isInvitationPreviewAllowed } from '@/lib/invitation-preview-limit'; @@ -8,6 +11,12 @@ interface RegisterPageProps { } export default async function RegisterPage({ searchParams }: RegisterPageProps) { + // Reaching this page is the funnel step. Recording it here rather than from the + // browser also keeps it honest: a prefetch of this route is filtered in the + // proxy, so signup starts can never outnumber the landing views above them. + const visitor = readVisitorContext(await cookies()); + after(() => recordVisitorEvent('SIGNUP_STARTED', visitor)); + const googleEnabled = Boolean(process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET); const githubEnabled = Boolean(process.env.GITHUB_CLIENT_ID && process.env.GITHUB_CLIENT_SECRET); diff --git a/app/(marketing)/[slug]/page.tsx b/app/(marketing)/[slug]/page.tsx index 4e0c393..6a5b0b5 100644 --- a/app/(marketing)/[slug]/page.tsx +++ b/app/(marketing)/[slug]/page.tsx @@ -1,6 +1,9 @@ import type { Metadata } from 'next'; +import { cookies } from 'next/headers'; import { notFound } from 'next/navigation'; +import { after } from 'next/server'; import { ComparisonPage } from '@/components/marketing/comparison-page'; +import { readVisitorContext, recordVisitorEvent } from '@/lib/analytics/visitor'; import { auth } from '@/lib/auth'; import { comparisonPages, getComparisonPage } from '@/lib/marketing/comparison-pages'; import { buildComparisonJsonLd, buildComparisonMetadata } from '@/lib/marketing/metadata'; @@ -38,6 +41,15 @@ export default async function MarketingSlugPage({ params }: MarketingSlugPagePro } const session = await auth(); + const isLoggedIn = Boolean(session?.user); + + // A comparison page is a landing page: for most of these visitors it is the + // first thing they see, so it belongs in the same visitor count as `/`. + if (!isLoggedIn) { + const visitor = readVisitorContext(await cookies()); + after(() => recordVisitorEvent('LANDING_VIEW', visitor)); + } + const structuredData = buildComparisonJsonLd({ title: page.title, description: page.metaDescription, @@ -57,7 +69,7 @@ export default async function MarketingSlugPage({ params }: MarketingSlugPagePro }} /> ))} - + ); } diff --git a/app/admin/growth/page.tsx b/app/admin/growth/page.tsx new file mode 100644 index 0000000..58d34ab --- /dev/null +++ b/app/admin/growth/page.tsx @@ -0,0 +1,358 @@ +import { Metadata } from 'next'; +import { redirect } from 'next/navigation'; +import { auth } from '@/lib/auth'; +import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'; +import { + AT_RISK_SILENT_DAYS, + conversionRates, + getScoreboard, + type FunnelRates, +} from '@/lib/analytics/scoreboard'; +import { isProductAnalyticsEnabled } from '@/lib/feature-flags'; +import { AlertTriangle, CreditCard, TrendingUp, Users } from 'lucide-react'; + +export const metadata: Metadata = { + title: 'Growth | OpenFrame', + description: 'Acquisition funnel and retention scoreboard', +}; + +function formatMoney(cents: number | null, currency: string) { + if (cents === null) return '—'; + const safeCurrency = /^[a-zA-Z]{3}$/.test(currency) ? currency.toUpperCase() : 'USD'; + return new Intl.NumberFormat('en-US', { + style: 'currency', + currency: safeCurrency, + minimumFractionDigits: 0, + maximumFractionDigits: 0, + }).format(cents / 100); +} + +function formatWeek(date: Date) { + return date.toISOString().slice(0, 10); +} + +function formatDate(date: Date | null) { + return date ? date.toISOString().slice(0, 10) : 'never'; +} + +/** A percentage with the count it was computed from, because n matters here. */ +function Rate({ rate, of }: { rate: number | null; of: number }) { + if (rate === null) return —; + return ( + + {Math.round(rate * 100)}% /{of} + + ); +} + +const WEEK_COLUMNS: Array<{ key: string; label: string }> = [ + { key: 'visitors', label: 'Visitors' }, + { key: 'signups', label: 'Signup' }, + { key: 'firstVideo', label: 'Video' }, + { key: 'shareLinks', label: 'Share link' }, + { key: 'externalFeedback', label: 'Ext. feedback' }, + { key: 'trials', label: 'Trial' }, + { key: 'newPaid', label: 'New paid' }, + { key: 'canceled', label: 'Canceled' }, + { key: 'activePaid', label: 'Active paid' }, +]; + +export default async function AdminGrowthPage() { + const session = await auth(); + if (!session?.user?.isAdmin) { + redirect('/'); + } + + if (!isProductAnalyticsEnabled()) { + return ( +
+

Growth

+ + + Acquisition tracking is off on this deployment. Set{' '} + OPENFRAME_ENABLE_ANALYTICS=true to start recording + the funnel. Nothing is collected until you do, and nothing is ever sent anywhere but + this instance's own database. + + +
+ ); + } + + const scoreboard = await getScoreboard(); + const latest = scoreboard.weeks[scoreboard.weeks.length - 1]; + const window = scoreboard.weeks.reduce( + (sum, week) => ({ + visitors: sum.visitors + week.visitors, + signups: sum.signups + week.signups, + firstVideo: sum.firstVideo + week.firstVideo, + shareLinks: sum.shareLinks + week.shareLinks, + externalFeedback: sum.externalFeedback + week.externalFeedback, + trials: sum.trials + week.trials, + newPaid: sum.newPaid + week.newPaid, + }), + { + visitors: 0, + signups: 0, + firstVideo: 0, + shareLinks: 0, + externalFeedback: 0, + trials: 0, + newPaid: 0, + } + ); + const overall: FunnelRates = conversionRates(window); + + return ( +
+
+

Growth

+
+ +
+ + + Active paid + + + +
{scoreboard.currentActivePaid ?? '—'}
+

from Stripe, right now

+ + + + + MRR + + + +
+ {formatMoney(scoreboard.currentMrrCents, scoreboard.currency)} +
+

from Stripe, right now

+ + + + + Visitors this week + + + +
{latest?.visitors ?? 0}
+

+ {latest ? `week of ${formatWeek(latest.weekStart)}` : 'no data yet'} +

+ + + + + At risk + + + +
{scoreboard.atRisk.length}
+

+ paid, silent for {AT_RISK_SILENT_DAYS}+ days +

+ + +
+ + + + Weekly funnel +

+ Weeks start Monday, UTC. Active paid is the running net of subscriptions started minus + canceled, so it can drift from the Stripe figure above; the difference is the drift. +

+ + + + + + + {WEEK_COLUMNS.map((column) => ( + + ))} + + + + + {scoreboard.weeks.map((week) => ( + + + {WEEK_COLUMNS.map((column) => ( + + ))} + + + ))} + +
Week + {column.label} + MRR
{formatWeek(week.weekStart)} + {week[column.key as keyof typeof week] as number} + + {formatMoney(week.mrrCents, scoreboard.currency)} +
+ + + + + + Where it narrows +

+ Every step over the whole {scoreboard.weeks.length}-week window, with the denominator + beside it. The lowest rate is the step to work on. +

+ + +
+
Visitor to signup
+
+ +
+
+
+
Signup to first video
+
+ +
+
+
+
Video to share link
+
+ +
+
+
+
Share to outside feedback
+
+ +
+
+
+
Trial to paid
+
+ +
+
+ + + + + + By source +

+ Rolling {scoreboard.channelWindowDays} days rather than one week: a weekly per-source + cell holds single digits at this volume, and a percentage computed from three visits + reads exactly as confidently as one computed from three hundred. +

+ + + + + + + + + + + + + + + {scoreboard.channels.length === 0 && ( + + + + )} + {scoreboard.channels.map((row) => ( + + + + + + + + + ))} + +
SourceVisitorsSignupTrialPaidVisitor to signup
+ Nothing recorded in this window yet. +
{row.channel.toLowerCase()}{row.visitors}{row.signups}{row.trials}{row.paid} + 0 ? row.signups / row.visitors : null} + of={row.visitors} + /> +
+ + + + + + Paid accounts +

+ Value events are videos, share links, outside feedback, approvals and projects. Rows + marked at risk have produced none for {AT_RISK_SILENT_DAYS} days. +

+ + + + + + + + + + + + + + + {scoreboard.paidAccounts.length === 0 && ( + + + + )} + {scoreboard.paidAccounts.map((account) => { + const atRisk = scoreboard.atRisk.some((row) => row.userId === account.userId); + return ( + + + + + + + + + ); + })} + +
AccountStatusSource7d30dLast activity
+ No active or trialing accounts. +
+ {account.name || account.email || account.userId} + {atRisk && ( + + at risk + + )} + + {account.status.toLowerCase()} + + {account.channel?.toLowerCase() ?? '—'} + {account.selfReported && account.selfReported !== account.channel && ( + + {' '} + (said {account.selfReported.toLowerCase()}) + + )} + {account.valueEvents7}{account.valueEvents30} + {formatDate(account.lastValueEventAt)} +
+ + +
+ ); +} diff --git a/app/admin/layout.tsx b/app/admin/layout.tsx index 8ac9288..a57dcbe 100644 --- a/app/admin/layout.tsx +++ b/app/admin/layout.tsx @@ -2,7 +2,7 @@ import { redirect } from 'next/navigation'; import { auth } from '@/lib/auth'; import { Header } from '@/components/layout'; import Link from 'next/link'; -import { LayoutDashboard, MessageSquareQuote, Users } from 'lucide-react'; +import { LayoutDashboard, MessageSquareQuote, TrendingUp, Users } from 'lucide-react'; export default async function AdminLayout({ children }: { children: React.ReactNode }) { const session = await auth(); @@ -39,6 +39,13 @@ export default async function AdminLayout({ children }: { children: React.ReactN Feedback + + + Growth + {/* Desktop Nav */} @@ -66,6 +73,13 @@ export default async function AdminLayout({ children }: { children: React.ReactN Feedback + + + Growth + diff --git a/app/api/admin/growth/route.ts b/app/api/admin/growth/route.ts new file mode 100644 index 0000000..7a710dd --- /dev/null +++ b/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'); + } +} diff --git a/app/api/approvals/[requestId]/decision/route.ts b/app/api/approvals/[requestId]/decision/route.ts index f5ecf6a..71b141f 100644 --- a/app/api/approvals/[requestId]/decision/route.ts +++ b/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, diff --git a/app/api/auth/register/route.ts b/app/api/auth/register/route.ts index 7c28ba9..e7c671b 100644 --- a/app/api/auth/register/route.ts +++ b/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); diff --git a/app/api/billing/checkout/route.ts b/app/api/billing/checkout/route.ts index b28cb83..81c44dd 100644 --- a/app/api/billing/checkout/route.ts +++ b/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) { diff --git a/app/api/events/route.ts b/app/api/events/route.ts new file mode 100644 index 0000000..417680e --- /dev/null +++ b/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; +} diff --git a/app/api/onboarding/source/route.ts b/app/api/onboarding/source/route.ts new file mode 100644 index 0000000..c4cab9f --- /dev/null +++ b/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'); +} diff --git a/app/api/projects/[projectId]/videos/[videoId]/share/route.ts b/app/api/projects/[projectId]/videos/[videoId]/share/route.ts index 52d5fca..66d3971 100644 --- a/app/api/projects/[projectId]/videos/[videoId]/share/route.ts +++ b/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'); diff --git a/app/api/projects/[projectId]/videos/route.ts b/app/api/projects/[projectId]/videos/route.ts index a56fa73..cad3a12 100644 --- a/app/api/projects/[projectId]/videos/route.ts +++ b/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) { diff --git a/app/api/projects/route.ts b/app/api/projects/route.ts index 3c28ae0..f35ad8d 100644 --- a/app/api/projects/route.ts +++ b/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) { diff --git a/app/api/versions/[versionId]/comments/route.ts b/app/api/versions/[versionId]/comments/route.ts index cf889f7..b236f1b 100644 --- a/app/api/versions/[versionId]/comments/route.ts +++ b/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 diff --git a/app/api/workspaces/route.ts b/app/api/workspaces/route.ts index 83de26f..79ba35d 100644 --- a/app/api/workspaces/route.ts +++ b/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) { diff --git a/app/onboarding/onboarding-wizard.tsx b/app/onboarding/onboarding-wizard.tsx index c152b45..1c853e2 100644 --- a/app/onboarding/onboarding-wizard.tsx +++ b/app/onboarding/onboarding-wizard.tsx @@ -107,7 +107,45 @@ function ToggleButton({ // ─── Step 1: Welcome ─────────────────────────────────────────────────────────── -function StepWelcome({ userName, onNext }: { userName: string; onNext: () => void }) { +// Asked here rather than on the registration form. The whole point of measuring +// this funnel is the signup conversion rate, and a question added to the form +// would move the number being measured. +const SOURCE_OPTIONS: Array<{ value: string; label: string }> = [ + { value: 'GITHUB', label: 'GitHub' }, + { value: 'YOUTUBE', label: 'YouTube' }, + { value: 'GOOGLE', label: 'A search engine' }, + { value: 'REVIEW_LINK', label: 'A review or comparison site' }, + { value: 'REFERRAL', label: 'Someone recommended it' }, + { value: 'COMMUNITY', label: 'Reddit, X, Discord or a forum' }, + { value: 'OUTBOUND', label: 'An email from us' }, + { value: 'OTHER', label: 'Somewhere else' }, +]; + +function StepWelcome({ + userName, + askSource, + onNext, +}: { + userName: string; + askSource: boolean; + onNext: () => void; +}) { + const [source, setSource] = useState(''); + const [note, setNote] = useState(''); + + const handleNext = () => { + // Never blocks the wizard. An unanswered or failed question costs one row in + // a cross-check column; a broken Get Started button costs the account. + if (askSource && source) { + void fetch('/api/onboarding/source', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ source, note: source === 'OTHER' ? note : undefined }), + }).catch(() => undefined); + } + onNext(); + }; + return (
@@ -122,7 +160,36 @@ function StepWelcome({ userName, onNext }: { userName: string; onNext: () => voi manage versions, and streamline approvals — all in one place.

- @@ -691,10 +758,12 @@ export function OnboardingWizard({ userName, canCreateWorkspace, availableWorkspaces, + askAcquisitionSource, }: { userName: string; canCreateWorkspace: boolean; availableWorkspaces: Array<{ id: string; name: string; isOwner: boolean }>; + askAcquisitionSource: boolean; }) { const router = useRouter(); const [currentStep, setCurrentStep] = useState(1); @@ -761,7 +830,9 @@ export function OnboardingWizard({ {/* Step content */} - {currentStep === 1 && } + {currentStep === 1 && ( + + )} {currentStep === 2 && ( ({ id: workspace.id, name: workspace.name, diff --git a/app/page.tsx b/app/page.tsx index c8e9008..f7a2285 100644 --- a/app/page.tsx +++ b/app/page.tsx @@ -1,8 +1,19 @@ +import { cookies } from 'next/headers'; +import { after } from 'next/server'; import { LandingPage } from '@/components/LandingPage'; import { auth } from '@/lib/auth'; +import { readVisitorContext, recordVisitorEvent } from '@/lib/analytics/visitor'; export default async function HomePage() { const session = await auth(); + const isLoggedIn = Boolean(session?.user); - return ; + // Signed-in users land here too, and counting them would put existing + // customers at the top of the acquisition funnel. + if (!isLoggedIn) { + const visitor = readVisitorContext(await cookies()); + after(() => recordVisitorEvent('LANDING_VIEW', visitor)); + } + + return ; } diff --git a/components/LandingPage.tsx b/components/LandingPage.tsx index 1e9c7f0..213a409 100644 --- a/components/LandingPage.tsx +++ b/components/LandingPage.tsx @@ -2,6 +2,7 @@ import Image from 'next/image'; import Link from 'next/link'; +import { CtaLink } from '@/components/marketing/cta-link'; import { MarketingCompareLinks } from '@/components/marketing/marketing-compare-links'; import { useEffect, useRef } from 'react'; import { gsap } from 'gsap'; @@ -258,13 +259,13 @@ export function LandingPage({ isLoggedIn }: LandingPageProps) { data-hero-copy className="mx-auto flex max-w-md flex-col items-center justify-center gap-3" > - Start free trial - +

7-day free trial · Flat $10/mo — no per-seat fees · No client accounts @@ -717,12 +718,12 @@ export function LandingPage({ isLoggedIn }: LandingPageProps) { Need more storage? Add 100 GB for $5/mo.

- Start free trial - +
{/* Card 2: Fair Source (Self-hosted) */} @@ -901,12 +902,12 @@ export function LandingPage({ isLoggedIn }: LandingPageProps) { Your first review link takes minutes.

- Start free trial - + diff --git a/components/marketing/comparison-page.tsx b/components/marketing/comparison-page.tsx index 7c7a431..c99660a 100644 --- a/components/marketing/comparison-page.tsx +++ b/components/marketing/comparison-page.tsx @@ -1,5 +1,6 @@ import Link from 'next/link'; import { ArrowRight, Github, MoveRight } from 'lucide-react'; +import { CtaLink } from '@/components/marketing/cta-link'; import { FeatureComparisonTable } from '@/components/marketing/feature-comparison-table'; import { MarketingFooter } from '@/components/marketing/marketing-footer'; import { MarketingHeader } from '@/components/marketing/marketing-header'; @@ -41,13 +42,13 @@ export function ComparisonPage({ page, isLoggedIn }: ComparisonPageProps) { $10/month hosted plan covers your whole team and every client reviewer link.

- Start free trial - +
- Start free trial - + + {children} + + ); +} diff --git a/lib/analytics/billing-events.ts b/lib/analytics/billing-events.ts new file mode 100644 index 0000000..e7fc5f9 --- /dev/null +++ b/lib/analytics/billing-events.ts @@ -0,0 +1,88 @@ +// Turning Stripe state into funnel events. +// +// These four events are derived from a before/after comparison inside the sync +// that already re-reads every subscription a customer has, rather than from the +// webhook event types. That is deliberate: webhooks arrive out of order and get +// replayed, and `customer.subscription.updated` fires for changes that mean +// nothing here. Comparing the row we are about to overwrite with the row we are +// writing is order-independent, and the dedupe keys make a replay a no-op. + +import type { BillingSubscriptionStatus } from '@prisma/client'; +import { eventKey, recordEvent } from '@/lib/analytics/record'; +import { isProductAnalyticsEnabled } from '@/lib/feature-flags'; + +export interface SubscriptionStateBefore { + status: BillingSubscriptionStatus; + cancelAtPeriodEnd: boolean; + /** Whether this account had already consumed a trial before this sync. */ + hadTrial: boolean; +} + +export interface SubscriptionStateAfter { + status: BillingSubscriptionStatus; + cancelAtPeriodEnd: boolean; + trialEndsAt: Date | null; + currentPeriodEnd: Date | null; +} + +/** + * A cancellation and the reactivation that may follow it both belong to a + * billing cycle. Keying them on the period end lets a customer cancel, come + * back, and cancel again in a later cycle without the second one being + * swallowed as a duplicate, while the two Stripe writes that describe a single + * cancellation (the `cancel_at_period_end` flag now, the `canceled` status + * later) collapse into one event. + */ +function cycleMarker(currentPeriodEnd: Date | null): string { + return String(currentPeriodEnd ? currentPeriodEnd.getTime() : 0); +} + +export async function recordSubscriptionTransition(params: { + userId: string; + subscriptionId: string; + before: SubscriptionStateBefore; + after: SubscriptionStateAfter; +}): Promise { + if (!isProductAnalyticsEnabled()) return; + + const { userId, subscriptionId, before, after } = params; + const cycle = cycleMarker(after.currentPeriodEnd); + + // Once per account for its lifetime. A second trial is not a second start of + // the funnel, and Stripe will not grant one anyway. + if (after.trialEndsAt && !before.hadTrial) { + await recordEvent({ + name: 'TRIAL_STARTED', + dedupeKey: eventKey('TRIAL_STARTED', userId), + userId, + }); + } + + // The paying moment. With a trial the status goes trialing -> active, so this + // fires on conversion rather than on signup for the trial. + if (after.status === 'ACTIVE' && before.status !== 'ACTIVE') { + await recordEvent({ + name: 'SUBSCRIPTION_STARTED', + dedupeKey: eventKey('SUBSCRIPTION_STARTED', subscriptionId), + userId, + }); + } + + const startedCanceling = after.cancelAtPeriodEnd && !before.cancelAtPeriodEnd; + const becameCanceled = after.status === 'CANCELED' && before.status !== 'CANCELED'; + if (startedCanceling || becameCanceled) { + await recordEvent({ + name: 'SUBSCRIPTION_CANCELED', + dedupeKey: `SUBSCRIPTION_CANCELED:${subscriptionId}:${cycle}`, + userId, + }); + } + + if (!after.cancelAtPeriodEnd && before.cancelAtPeriodEnd && after.status !== 'CANCELED') { + await recordEvent({ + name: 'SUBSCRIPTION_REACTIVATED', + dedupeKey: `SUBSCRIPTION_REACTIVATED:${subscriptionId}:${cycle}`, + userId, + }); + } +} diff --git a/lib/analytics/bots.ts b/lib/analytics/bots.ts new file mode 100644 index 0000000..0bf06e3 --- /dev/null +++ b/lib/analytics/bots.ts @@ -0,0 +1,42 @@ +// Traffic that is not a person. +// +// This matters more than it looks. Visitors are the denominator of every +// conversion rate in the scoreboard, so counting a crawler as a visit does not +// add noise evenly: it quietly makes every channel look worse, and the channels +// that attract the most crawling (an indexed landing page, a GitHub README link) +// look worst of all. + +const BOT_PATTERN = + /bot\b|bots\b|crawler|spider|crawl|slurp|facebookexternalhit|embedly|quora link preview|whatsapp|telegram|discordbot|slackbot|preview|monitor|uptime|pingdom|curl\/|wget\/|python-requests|python-urllib|scrapy|axios\/|node-fetch|go-http-client|okhttp|java\/|headlesschrome|phantomjs|lighthouse|semrush|ahrefs|mj12|dotbot|petalbot|bytespider|gptbot|claudebot|ccbot/i; + +/** + * A missing user agent counts as a bot. Every real browser sends one, so the + * blank case is a script that did not bother. + */ +export function isLikelyBot(userAgent: string | null | undefined): boolean { + if (typeof userAgent !== 'string') return true; + const value = userAgent.trim(); + if (!value) return true; + return BOT_PATTERN.test(value); +} + +/** + * Whether a request is a real page load rather than a prefetch, an asset or a + * client-side navigation payload. + * + * Next prefetches the register page as soon as a CTA scrolls into view, so + * without this the funnel would show more signup starts than landing views. + */ +export function isCountableDocumentRequest(headers: Headers): boolean { + if (headers.get('sec-purpose')?.includes('prefetch')) return false; + if (headers.get('purpose') === 'prefetch') return false; + if (headers.get('next-router-prefetch')) return false; + // An RSC navigation is the same visitor moving inside the app, not a new view. + if (headers.get('rsc')) return false; + + const dest = headers.get('sec-fetch-dest'); + if (dest) return dest === 'document'; + + // Older browsers and anything behind a proxy that strips fetch metadata. + return headers.get('accept')?.includes('text/html') ?? false; +} diff --git a/lib/analytics/channel.ts b/lib/analytics/channel.ts new file mode 100644 index 0000000..342e4b1 --- /dev/null +++ b/lib/analytics/channel.ts @@ -0,0 +1,212 @@ +// Turns whatever the browser told us about a visit into one of nine buckets. +// +// Pure and dependency-free on purpose: this runs in the proxy (edge runtime), so +// the only Prisma reference here is a type-only import, which the compiler erases. +// +// Everything that reaches this file is already reduced to a host and a couple of +// UTM tags. Nothing here ever sees a full URL, so a query string carrying a share +// token or an email address cannot be classified into a stored column by mistake. + +import type { AcquisitionChannel } from '@prisma/client'; + +export interface ChannelInput { + utmSource?: string | null; + utmMedium?: string | null; + referrerHost?: string | null; +} + +const MAX_TAG_LENGTH = 64; +const MAX_PATH_LENGTH = 128; + +/** Lowercases, trims and caps a UTM tag. Returns null for anything empty. */ +export function sanitizeTag(value: string | null | undefined): string | null { + if (typeof value !== 'string') return null; + const cleaned = value.trim().toLowerCase().slice(0, MAX_TAG_LENGTH); + if (!cleaned) return null; + // Campaign names are ours, so anything outside this set is either a typo or + // somebody probing what the column accepts. Drop it rather than store it. + if (!/^[a-z0-9._%+\- ]+$/.test(cleaned)) return null; + return cleaned; +} + +/** + * Strips the `www.` prefix and the port, lowercases, and caps the length. + * + * A whole URL is not a host and comes back null. Splitting on the first colon + * would otherwise turn `https://github.com` into the host `https`, and every + * caller that passed one by mistake would file its traffic under a channel that + * does not exist. + */ +export function normalizeHost(value: string | null | undefined): string | null { + if (typeof value !== 'string') return null; + const trimmed = value.trim().toLowerCase(); + const withoutPort = trimmed.replace(/:\d+$/, ''); + const host = withoutPort.replace(/^www\./, ''); + if (!host || !/^[a-z0-9.\-]+$/.test(host)) return null; + return host.slice(0, MAX_TAG_LENGTH); +} + +/** + * The referring host, or null when there is no usable one. + * + * A referrer pointing at our own deployment is not a referrer: it is the visitor + * clicking through the site. Treating it as one would file most of the funnel + * under whatever page they happened to start on. + */ +export function extractReferrerHost( + referrer: string | null | undefined, + selfHost?: string | null +): string | null { + if (!referrer) return null; + let host: string | null; + try { + const url = new URL(referrer); + // Browsers only ever send an http(s) referrer. Anything else is a scheme we + // have no host for, such as `android-app://com.example`, and reading its + // opaque body as a domain would invent a referring site. + if (url.protocol !== 'http:' && url.protocol !== 'https:') return null; + host = normalizeHost(url.hostname); + } catch { + return null; + } + if (!host) return null; + const self = normalizeHost(selfHost); + if (self && host === self) return null; + return host; +} + +/** Path only, no query string and no fragment, capped. */ +export function sanitizeLandingPath(pathname: string | null | undefined): string { + if (typeof pathname !== 'string' || !pathname.startsWith('/')) return '/'; + const path = pathname.split('?')[0]?.split('#')[0] ?? '/'; + return path.slice(0, MAX_PATH_LENGTH) || '/'; +} + +function suffixMatch(host: string, domain: string): boolean { + return host === domain || host.endsWith(`.${domain}`); +} + +const GITHUB_HOSTS = ['github.com', 'github.blog']; +const YOUTUBE_HOSTS = ['youtube.com', 'youtu.be']; + +// The bucket the plan calls "google" is really organic search. Google is the +// overwhelming majority of it, and splitting Bing and DuckDuckGo into their own +// slivers would make every row in the scoreboard smaller without changing a +// single decision. +const SEARCH_HOSTS = ['google.com', 'bing.com', 'duckduckgo.com', 'ecosia.org', 'yandex.com']; + +const REVIEW_HOSTS = [ + 'producthunt.com', + 'g2.com', + 'capterra.com', + 'getapp.com', + 'alternativeto.net', + 'saashub.com', + 'slant.co', + 'trustpilot.com', + 'sourceforge.net', +]; + +const COMMUNITY_HOSTS = [ + 'reddit.com', + 'news.ycombinator.com', + 'lobste.rs', + 'discord.com', + 'discord.gg', + 'x.com', + 'twitter.com', + 't.co', + 'linkedin.com', + 'lnkd.in', + 'bsky.app', + 'mastodon.social', + 'dev.to', + 'indiehackers.com', + 'facebook.com', + 'instagram.com', + 't.me', +]; + +// utm_source values we set ourselves, plus the ones other people tend to use +// when they link us. Matched exactly after sanitizing. +const SOURCE_NAMES: ReadonlyMap = new Map([ + ['github', 'GITHUB'], + ['youtube', 'YOUTUBE'], + ['yt', 'YOUTUBE'], + ['google', 'GOOGLE'], + ['bing', 'GOOGLE'], + ['duckduckgo', 'GOOGLE'], + ['producthunt', 'REVIEW_LINK'], + ['product-hunt', 'REVIEW_LINK'], + ['g2', 'REVIEW_LINK'], + ['capterra', 'REVIEW_LINK'], + ['alternativeto', 'REVIEW_LINK'], + ['reddit', 'COMMUNITY'], + ['hackernews', 'COMMUNITY'], + ['hn', 'COMMUNITY'], + ['discord', 'COMMUNITY'], + ['twitter', 'COMMUNITY'], + ['x', 'COMMUNITY'], + ['linkedin', 'COMMUNITY'], + ['newsletter', 'OUTBOUND'], + ['coldmail', 'OUTBOUND'], + ['outreach', 'OUTBOUND'], +]); + +// A medium that names the motion beats the source that names the place: an +// outbound campaign sent from a LinkedIn account is outbound, not community. +const MEDIUM_NAMES: ReadonlyMap = new Map([ + ['outbound', 'OUTBOUND'], + ['email', 'OUTBOUND'], + ['cold-email', 'OUTBOUND'], + ['coldemail', 'OUTBOUND'], + ['dm', 'OUTBOUND'], + ['referral', 'REFERRAL'], + ['affiliate', 'REFERRAL'], +]); + +function classifyHost(host: string): AcquisitionChannel | null { + if (GITHUB_HOSTS.some((domain) => suffixMatch(host, domain))) return 'GITHUB'; + if (YOUTUBE_HOSTS.some((domain) => suffixMatch(host, domain))) return 'YOUTUBE'; + // google.co.uk, google.de and the rest: the country domains all sit under a + // `google.` label, so match the label rather than listing 190 domains. + if (/(^|\.)google\.[a-z.]{2,6}$/.test(host)) return 'GOOGLE'; + if (SEARCH_HOSTS.some((domain) => suffixMatch(host, domain))) return 'GOOGLE'; + if (REVIEW_HOSTS.some((domain) => suffixMatch(host, domain))) return 'REVIEW_LINK'; + if (COMMUNITY_HOSTS.some((domain) => suffixMatch(host, domain))) return 'COMMUNITY'; + return null; +} + +/** + * The bucket a visit belongs to. + * + * Precedence: an explicit medium that names the motion, then an explicit source, + * then the referring host, then direct. A tagged campaign we do not recognise is + * OTHER rather than DIRECT, because somebody deliberately tagged it. + * + * An unrecognised site that links to us counts as REFERRAL. The raw host is + * stored alongside, so a host that turns out to matter can be promoted into one + * of the lists above and re-read from history. + */ +export function classifyChannel(input: ChannelInput): AcquisitionChannel { + const source = sanitizeTag(input.utmSource); + const medium = sanitizeTag(input.utmMedium); + const host = normalizeHost(input.referrerHost); + + const byMedium = medium ? MEDIUM_NAMES.get(medium) : undefined; + if (byMedium) return byMedium; + + if (source) { + const bySource = SOURCE_NAMES.get(source); + if (bySource) return bySource; + // A source that looks like a domain (utm_source=github.com) is worth reading + // as one before giving up on it. + return classifyHost(source) ?? 'OTHER'; + } + + if (host) { + return classifyHost(host) ?? 'REFERRAL'; + } + + return 'DIRECT'; +} diff --git a/lib/analytics/cookies.ts b/lib/analytics/cookies.ts new file mode 100644 index 0000000..ee16352 --- /dev/null +++ b/lib/analytics/cookies.ts @@ -0,0 +1,113 @@ +// The two cookies the acquisition system sets, and how to read them back. +// +// Both are first party, both stay on this deployment's own domain, and neither +// is readable from JavaScript. They exist so that a visitor who arrives from a +// YouTube link on Tuesday and signs up on Friday is still counted against +// YouTube; there is no cross-site identifier and nothing is sent anywhere. +// +// Imported by the proxy, so this file must stay free of Prisma and of anything +// else that cannot run on the edge. + +import type { AcquisitionChannel } from '@prisma/client'; +import { sanitizeLandingPath, sanitizeTag, normalizeHost } from '@/lib/analytics/channel'; + +export const ANONYMOUS_ID_COOKIE = 'of_aid'; +export const FIRST_TOUCH_COOKIE = 'of_ft'; + +export const ANONYMOUS_ID_MAX_AGE_SECONDS = 60 * 60 * 24 * 365; + +/** cuid-ish length bound. Values outside it are treated as absent, not repaired. */ +const ANONYMOUS_ID_PATTERN = /^[a-z0-9]{16,64}$/; + +export interface FirstTouch { + channel: AcquisitionChannel; + utmSource: string | null; + utmMedium: string | null; + utmCampaign: string | null; + referrerHost: string | null; + landingPath: string; +} + +/** Short keys: this rides on every request, so the wire form stays compact. */ +interface EncodedFirstTouch { + c: string; + s?: string; + m?: string; + k?: string; + r?: string; + p: string; +} + +const CHANNELS: readonly AcquisitionChannel[] = [ + 'DIRECT', + 'GITHUB', + 'YOUTUBE', + 'GOOGLE', + 'REVIEW_LINK', + 'REFERRAL', + 'OUTBOUND', + 'COMMUNITY', + 'OTHER', +]; + +export function isAcquisitionChannel(value: unknown): value is AcquisitionChannel { + return typeof value === 'string' && (CHANNELS as readonly string[]).includes(value); +} + +export function isValidAnonymousId(value: string | null | undefined): value is string { + return typeof value === 'string' && ANONYMOUS_ID_PATTERN.test(value); +} + +/** 26 lowercase base36 characters from the Web Crypto API, which the edge has. */ +export function generateAnonymousId(): string { + const bytes = new Uint8Array(16); + crypto.getRandomValues(bytes); + let id = ''; + for (const byte of bytes) { + id += byte.toString(36).padStart(2, '0'); + } + return id; +} + +export function encodeFirstTouch(touch: FirstTouch): string { + const payload: EncodedFirstTouch = { c: touch.channel, p: touch.landingPath }; + if (touch.utmSource) payload.s = touch.utmSource; + if (touch.utmMedium) payload.m = touch.utmMedium; + if (touch.utmCampaign) payload.k = touch.utmCampaign; + if (touch.referrerHost) payload.r = touch.referrerHost; + return encodeURIComponent(JSON.stringify(payload)); +} + +/** + * Parses the cookie back, re-sanitizing every field. + * + * The cookie is httpOnly but it still came from the client, so a hand-edited one + * must not be able to put arbitrary text into a database column. Anything that + * fails validation makes the whole value null: a half-trusted first touch is + * worse than none. + */ +export function decodeFirstTouch(raw: string | null | undefined): FirstTouch | null { + if (!raw) return null; + + let parsed: unknown; + try { + parsed = JSON.parse(decodeURIComponent(raw)); + } catch { + return null; + } + + if (!parsed || typeof parsed !== 'object') return null; + const value = parsed as Record; + + if (!isAcquisitionChannel(value.c)) return null; + if (typeof value.p !== 'string') return null; + + return { + channel: value.c, + utmSource: sanitizeTag(typeof value.s === 'string' ? value.s : null), + utmMedium: sanitizeTag(typeof value.m === 'string' ? value.m : null), + utmCampaign: sanitizeTag(typeof value.k === 'string' ? value.k : null), + referrerHost: normalizeHost(typeof value.r === 'string' ? value.r : null), + landingPath: sanitizeLandingPath(value.p), + }; +} diff --git a/lib/analytics/record.ts b/lib/analytics/record.ts new file mode 100644 index 0000000..cc73239 --- /dev/null +++ b/lib/analytics/record.ts @@ -0,0 +1,183 @@ +// The only way anything in this repo writes an analytics row. +// +// Two things are centralised here so that no call site has to remember them: +// +// 1. The feature flag. Every function below returns without touching the +// database when OPENFRAME_ENABLE_ANALYTICS is off, which is why the ~15 call +// sites scattered through app/api are unconditional one-liners. +// 2. Failure. Measurement must never be able to fail a product request, so +// every write is caught and logged. An event that is not recorded is a hole +// in a chart; an event that throws is a user who cannot create a project. + +import type { AcquisitionChannel, AnalyticsEventName } from '@prisma/client'; +import { db } from '@/lib/db'; +import { isProductAnalyticsEnabled } from '@/lib/feature-flags'; +import { logError } from '@/lib/logger'; +import type { FirstTouch } from '@/lib/analytics/cookies'; + +export interface RecordEventInput { + name: AnalyticsEventName; + /** + * What makes this event unique. The column is UNIQUE, so a replayed webhook, a + * double-submitted form or a refreshed page collide here and the second write + * is dropped by the database rather than by a check somebody might forget. + */ + dedupeKey: string; + userId?: string | null; + anonymousId?: string | null; + /** + * Only set for events that happen before there is an account. Once a user + * exists their channel lives in user_acquisitions and the scoreboard reads it + * from there, so a later correction applies to their whole history. + */ + channel?: AcquisitionChannel | null; + occurredAt?: Date; +} + +/** `:`, for something that can only ever happen once per subject. */ +export function eventKey(name: AnalyticsEventName, subject: string): string { + return `${name}:${subject}`; +} + +/** + * `::`, for something repeatable that should still count + * once per visitor per day (a landing view, a CTA click). + */ +export function dailyEventKey( + name: AnalyticsEventName, + subject: string, + at: Date = new Date() +): string { + return `${name}:${subject}:${at.toISOString().slice(0, 10)}`; +} + +export async function recordEvent(input: RecordEventInput): Promise { + if (!isProductAnalyticsEnabled()) return; + + try { + await db.analyticsEvent.createMany({ + data: [ + { + name: input.name, + dedupeKey: input.dedupeKey, + userId: input.userId ?? null, + anonymousId: input.anonymousId ?? null, + channel: input.channel ?? null, + ...(input.occurredAt ? { occurredAt: input.occurredAt } : {}), + }, + ], + skipDuplicates: true, + }); + } catch (error) { + logError('Failed to record analytics event:', error); + } +} + +/** + * Stores the first touch for a visitor with no account yet. + * + * Never updated. A visitor who comes back a week later through a different link + * keeps the channel that brought them the first time, which is the question the + * scoreboard is asking. + */ +export async function recordFirstTouch(anonymousId: string, touch: FirstTouch): Promise { + if (!isProductAnalyticsEnabled()) return; + + try { + await db.acquisitionTouch.createMany({ + data: [ + { + anonymousId, + channel: touch.channel, + utmSource: touch.utmSource, + utmMedium: touch.utmMedium, + utmCampaign: touch.utmCampaign, + referrerHost: touch.referrerHost, + landingPath: touch.landingPath, + }, + ], + skipDuplicates: true, + }); + } catch (error) { + logError('Failed to record acquisition touch:', error); + } +} + +/** + * Copies the first touch onto a freshly created account and claims the events + * that visitor produced before they had one. + * + * The backfill is what joins the two halves of the funnel: without it a landing + * view and the signup it led to are two unrelated rows, and no query can tell + * you that GitHub traffic converts and Google traffic does not. + */ +export async function attachAcquisitionToUser(params: { + userId: string; + anonymousId: string | null; + touch: FirstTouch | null; +}): Promise { + if (!isProductAnalyticsEnabled()) return; + + const { userId, anonymousId, touch } = params; + + try { + await db.userAcquisition.createMany({ + data: [ + { + userId, + anonymousId, + channel: touch?.channel ?? 'DIRECT', + utmSource: touch?.utmSource ?? null, + utmMedium: touch?.utmMedium ?? null, + utmCampaign: touch?.utmCampaign ?? null, + referrerHost: touch?.referrerHost ?? null, + landingPath: touch?.landingPath ?? null, + }, + ], + skipDuplicates: true, + }); + + if (anonymousId) { + await db.analyticsEvent.updateMany({ + where: { anonymousId, userId: null }, + data: { userId }, + }); + } + } catch (error) { + logError('Failed to attach acquisition to user:', error); + } +} + +/** + * The answer to the onboarding question, which is a check on the cookie rather + * than a replacement for it: it survives a cleared cookie and a phone-to-laptop + * switch, and it is the only signal that can catch a channel the UTM tags miss + * entirely ("a friend told me"). + */ +export async function setSelfReportedSource(params: { + userId: string; + selfReported: AcquisitionChannel; + note?: string | null; +}): Promise { + if (!isProductAnalyticsEnabled()) return; + + const note = params.note?.trim().slice(0, 200) || null; + + try { + await db.userAcquisition.upsert({ + where: { userId: params.userId }, + create: { + userId: params.userId, + channel: 'DIRECT', + selfReported: params.selfReported, + selfReportedNote: note, + }, + update: { + selfReported: params.selfReported, + selfReportedNote: note, + }, + }); + } catch (error) { + logError('Failed to store self-reported acquisition source:', error); + } +} diff --git a/lib/analytics/scoreboard.ts b/lib/analytics/scoreboard.ts new file mode 100644 index 0000000..3ec846a --- /dev/null +++ b/lib/analytics/scoreboard.ts @@ -0,0 +1,323 @@ +// The Monday scoreboard, as queries. +// +// Two decisions here are worth stating, because they are what make the numbers +// readable rather than merely present: +// +// 1. Rates, not just counts. A funnel is a set of ratios; the step with the +// worst ratio is the thing to fix, and a column of absolute numbers hides it. +// 2. Every rate carries its denominator. At this volume a weekly per-channel +// cell holds single digits, and 1 out of 3 renders as "33%" exactly as +// confidently as 340 out of 1020. The channel view therefore runs on a +// rolling 28-day window rather than a week, and still reports `n`. + +import type { AcquisitionChannel } from '@prisma/client'; +import { db } from '@/lib/db'; +import { getCachedStripeStats } from '@/lib/admin-stats'; + +/** What "using the product" means for a paying account. */ +export const VALUE_EVENT_NAMES = [ + 'VIDEO_ADDED', + 'SHARE_LINK_CREATED', + 'FIRST_GUEST_COMMENT', + 'APPROVAL_COMPLETED', + 'PROJECT_CREATED', +] as const; + +/** A paid account that has produced nothing for this long is drifting away. */ +export const AT_RISK_SILENT_DAYS = 14; + +const DEFAULT_WEEKS = 12; +const CHANNEL_WINDOW_DAYS = 28; + +export interface WeeklyRow { + weekStart: Date; + visitors: number; + ctaClicks: number; + signupStarted: number; + signups: number; + emailVerified: number; + firstVideo: number; + shareLinks: number; + externalFeedback: number; + trials: number; + newPaid: number; + canceled: number; + /** Running net of started minus canceled. Derived, not a Stripe snapshot. */ + activePaid: number; + mrrCents: number; +} + +export interface ChannelRow { + channel: AcquisitionChannel; + visitors: number; + signups: number; + trials: number; + paid: number; +} + +export interface PaidAccountRow { + userId: string; + name: string | null; + email: string | null; + status: string; + valueEvents7: number; + valueEvents30: number; + lastValueEventAt: Date | null; + channel: AcquisitionChannel | null; + selfReported: AcquisitionChannel | null; +} + +export interface Scoreboard { + weeks: WeeklyRow[]; + channels: ChannelRow[]; + channelWindowDays: number; + paidAccounts: PaidAccountRow[]; + atRisk: PaidAccountRow[]; + currentActivePaid: number | null; + currentMrrCents: number | null; + currency: string; +} + +interface WeeklyQueryRow { + week: Date; + name: string; + subjects: number; +} + +interface ChannelQueryRow { + channel: AcquisitionChannel | null; + name: string; + subjects: number; +} + +interface PaidQueryRow { + user_id: string; + name: string | null; + email: string | null; + status: string; + channel: AcquisitionChannel | null; + self_reported: AcquisitionChannel | null; + value_events_7: number; + value_events_30: number; + last_value_event_at: Date | null; +} + +function startOfWeek(date: Date): Date { + const copy = new Date( + Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate(), 0, 0, 0, 0) + ); + // Postgres date_trunc('week') starts on Monday; match it so the two halves of + // the table line up. + const isoDayIndex = (copy.getUTCDay() + 6) % 7; + copy.setUTCDate(copy.getUTCDate() - isoDayIndex); + return copy; +} + +function emptyWeek(weekStart: Date): WeeklyRow { + return { + weekStart, + visitors: 0, + ctaClicks: 0, + signupStarted: 0, + signups: 0, + emailVerified: 0, + firstVideo: 0, + shareLinks: 0, + externalFeedback: 0, + trials: 0, + newPaid: 0, + canceled: 0, + activePaid: 0, + mrrCents: 0, + }; +} + +const WEEK_COLUMN_BY_EVENT: Record = { + LANDING_VIEW: 'visitors', + CTA_CLICKED: 'ctaClicks', + SIGNUP_STARTED: 'signupStarted', + SIGNUP_COMPLETED: 'signups', + EMAIL_VERIFIED: 'emailVerified', + VIDEO_ADDED: 'firstVideo', + SHARE_LINK_CREATED: 'shareLinks', + FIRST_GUEST_COMMENT: 'externalFeedback', + TRIAL_STARTED: 'trials', + SUBSCRIPTION_STARTED: 'newPaid', + SUBSCRIPTION_CANCELED: 'canceled', +}; + +export interface FunnelRates { + visitorToSignup: number | null; + signupToFirstVideo: number | null; + firstVideoToShare: number | null; + shareToFeedback: number | null; + trialToPaid: number | null; +} + +/** + * Step-to-step conversion, or null when the denominator is zero. + * + * Null rather than 0 on purpose: "no visitors, so no rate" and "visitors, none + * of whom converted" are different facts, and showing the first as 0% invents a + * problem that is not there. + */ +export function conversionRates(row: { + visitors: number; + signups: number; + firstVideo: number; + shareLinks: number; + externalFeedback: number; + trials: number; + newPaid: number; +}): FunnelRates { + const ratio = (numerator: number, denominator: number) => + denominator > 0 ? numerator / denominator : null; + + return { + visitorToSignup: ratio(row.signups, row.visitors), + signupToFirstVideo: ratio(row.firstVideo, row.signups), + firstVideoToShare: ratio(row.shareLinks, row.firstVideo), + shareToFeedback: ratio(row.externalFeedback, row.shareLinks), + trialToPaid: ratio(row.newPaid, row.trials), + }; +} + +export async function getScoreboard(options?: { weeks?: number }): Promise { + const weeks = Math.min(Math.max(options?.weeks ?? DEFAULT_WEEKS, 1), 52); + const now = new Date(); + const firstWeekStart = startOfWeek(now); + firstWeekStart.setUTCDate(firstWeekStart.getUTCDate() - (weeks - 1) * 7); + + const channelWindowStart = new Date(now); + channelWindowStart.setUTCDate(channelWindowStart.getUTCDate() - CHANNEL_WINDOW_DAYS); + + const [weekRows, channelRows, priorPaid, paidAccounts, stripeStats] = await Promise.all([ + // COUNT(DISTINCT COALESCE(anonymous_id, id)) rather than COUNT(*): a landing + // view is deduped per visitor per day, so a visitor who came back on three + // days would otherwise be three weekly visitors. Rows with no anonymous id + // fall back to their own primary key and stay distinct. + db.$queryRaw` + SELECT date_trunc('week', occurred_at) AS week, + name::text AS name, + COUNT(DISTINCT COALESCE(anonymous_id, id))::int AS subjects + FROM analytics_events + WHERE occurred_at >= ${firstWeekStart} + GROUP BY 1, 2 + `, + db.$queryRaw` + SELECT COALESCE(ua.channel, e.channel) AS channel, + e.name::text AS name, + COUNT(DISTINCT COALESCE(e.anonymous_id, e.id))::int AS subjects + FROM analytics_events e + LEFT JOIN user_acquisitions ua ON ua.user_id = e.user_id + WHERE e.occurred_at >= ${channelWindowStart} + GROUP BY 1, 2 + `, + db.$queryRaw>` + SELECT + COUNT(*) FILTER (WHERE name::text = 'SUBSCRIPTION_STARTED')::int AS started, + COUNT(*) FILTER (WHERE name::text = 'SUBSCRIPTION_CANCELED')::int AS canceled + FROM analytics_events + WHERE occurred_at < ${firstWeekStart} + `, + db.$queryRaw` + SELECT u.id AS user_id, + u.name, + u.email, + u."subscriptionStatus"::text AS status, + ua.channel, + ua.self_reported, + COUNT(e.id) FILTER (WHERE e.occurred_at >= NOW() - INTERVAL '7 days')::int + AS value_events_7, + COUNT(e.id) FILTER (WHERE e.occurred_at >= NOW() - INTERVAL '30 days')::int + AS value_events_30, + MAX(e.occurred_at) AS last_value_event_at + FROM users u + LEFT JOIN user_acquisitions ua ON ua.user_id = u.id + LEFT JOIN analytics_events e + ON e.user_id = u.id + AND e.name::text = ANY(${[...VALUE_EVENT_NAMES]}::text[]) + WHERE u."subscriptionStatus"::text IN ('ACTIVE', 'TRIALING') + GROUP BY u.id, u.name, u.email, u."subscriptionStatus", ua.channel, ua.self_reported + ORDER BY MAX(e.occurred_at) ASC NULLS FIRST + `, + getCachedStripeStats(), + ]); + + const byWeek = new Map(); + for (let index = 0; index < weeks; index += 1) { + const weekStart = new Date(firstWeekStart); + weekStart.setUTCDate(weekStart.getUTCDate() + index * 7); + byWeek.set(weekStart.getTime(), emptyWeek(weekStart)); + } + + for (const row of weekRows) { + const bucket = byWeek.get(startOfWeek(row.week).getTime()); + const column = WEEK_COLUMN_BY_EVENT[row.name]; + if (!bucket || !column) continue; + (bucket[column] as number) = row.subjects; + } + + // One flat plan, so a per-subscription price is enough to turn a subscriber + // count into MRR. Taken from Stripe rather than hardcoded, and zero when + // billing is not configured at all. + const unitAmountCents = + stripeStats && stripeStats.activeSubscribers > 0 + ? Math.round(stripeStats.mrrCents / stripeStats.activeSubscribers) + : 0; + + let running = (priorPaid[0]?.started ?? 0) - (priorPaid[0]?.canceled ?? 0); + const orderedWeeks = [...byWeek.values()].sort( + (a, b) => a.weekStart.getTime() - b.weekStart.getTime() + ); + for (const week of orderedWeeks) { + running += week.newPaid - week.canceled; + week.activePaid = Math.max(running, 0); + week.mrrCents = week.activePaid * unitAmountCents; + } + + const channelBuckets = new Map(); + for (const row of channelRows) { + const channel = row.channel ?? 'OTHER'; + const bucket = channelBuckets.get(channel) ?? { + channel, + visitors: 0, + signups: 0, + trials: 0, + paid: 0, + }; + if (row.name === 'LANDING_VIEW') bucket.visitors += row.subjects; + if (row.name === 'SIGNUP_COMPLETED') bucket.signups += row.subjects; + if (row.name === 'TRIAL_STARTED') bucket.trials += row.subjects; + if (row.name === 'SUBSCRIPTION_STARTED') bucket.paid += row.subjects; + channelBuckets.set(channel, bucket); + } + + const accounts: PaidAccountRow[] = paidAccounts.map((row) => ({ + userId: row.user_id, + name: row.name, + email: row.email, + status: row.status, + channel: row.channel, + selfReported: row.self_reported, + valueEvents7: row.value_events_7, + valueEvents30: row.value_events_30, + lastValueEventAt: row.last_value_event_at, + })); + + const silentBefore = new Date(now); + silentBefore.setUTCDate(silentBefore.getUTCDate() - AT_RISK_SILENT_DAYS); + + return { + weeks: orderedWeeks, + channels: [...channelBuckets.values()].sort((a, b) => b.visitors - a.visitors), + channelWindowDays: CHANNEL_WINDOW_DAYS, + paidAccounts: accounts, + atRisk: accounts.filter( + (account) => !account.lastValueEventAt || account.lastValueEventAt < silentBefore + ), + currentActivePaid: stripeStats?.activeSubscribers ?? null, + currentMrrCents: stripeStats?.mrrCents ?? null, + currency: stripeStats?.currency ?? 'usd', + }; +} diff --git a/lib/analytics/signup.ts b/lib/analytics/signup.ts new file mode 100644 index 0000000..142fd77 --- /dev/null +++ b/lib/analytics/signup.ts @@ -0,0 +1,48 @@ +// Signup is the seam where an anonymous visitor becomes an account, so it is the +// one place the two halves of the funnel are joined. Both ways of creating an +// account (the credentials form and an OAuth provider) go through here, because +// a channel that only shows up for one of them is worse than no channel at all. + +import { eventKey, recordEvent, attachAcquisitionToUser } from '@/lib/analytics/record'; +import { readVisitorContext, type VisitorContext } from '@/lib/analytics/visitor'; +import { isProductAnalyticsEnabled } from '@/lib/feature-flags'; + +const NO_VISITOR: VisitorContext = { anonymousId: null, firstTouch: null }; + +/** + * The visitor context of the request being handled. + * + * For the OAuth path there is no NextRequest to read: the account is created by + * the adapter, from inside a NextAuth event. `cookies()` still resolves there, + * and when it does not the signup is simply recorded without a channel rather + * than not recorded at all. + */ +export async function readVisitorContextFromHeaders(): Promise { + if (!isProductAnalyticsEnabled()) return NO_VISITOR; + try { + const { cookies } = await import('next/headers'); + return readVisitorContext(await cookies()); + } catch { + return NO_VISITOR; + } +} + +export async function recordSignupCompleted(params: { + userId: string; + visitor: VisitorContext; +}): Promise { + if (!isProductAnalyticsEnabled()) return; + + await attachAcquisitionToUser({ + userId: params.userId, + anonymousId: params.visitor.anonymousId, + touch: params.visitor.firstTouch, + }); + + await recordEvent({ + name: 'SIGNUP_COMPLETED', + dedupeKey: eventKey('SIGNUP_COMPLETED', params.userId), + userId: params.userId, + anonymousId: params.visitor.anonymousId, + }); +} diff --git a/lib/analytics/visitor.ts b/lib/analytics/visitor.ts new file mode 100644 index 0000000..734ec77 --- /dev/null +++ b/lib/analytics/visitor.ts @@ -0,0 +1,72 @@ +// Reading the acquisition cookies, and recording the events that happen before +// an account exists. +// +// The proxy sets the cookies but cannot write rows (it runs on the edge). These +// helpers close that gap from Node, and are the reason no visitor event depends +// on client-side JavaScript running: a landing view is recorded by the server +// rendering the landing page, so an ad blocker has nothing to block. That is not +// a purity argument. Blocking rates differ by channel, and an undercounted +// denominator would make GitHub and Hacker News traffic look like it converts +// better than it does. + +import type { AnalyticsEventName } from '@prisma/client'; +import { + ANONYMOUS_ID_COOKIE, + FIRST_TOUCH_COOKIE, + decodeFirstTouch, + isValidAnonymousId, + type FirstTouch, +} from '@/lib/analytics/cookies'; +import { dailyEventKey, recordEvent, recordFirstTouch } from '@/lib/analytics/record'; +import { isProductAnalyticsEnabled } from '@/lib/feature-flags'; + +/** Both `cookies()` from next/headers and `request.cookies` satisfy this. */ +export interface AnalyticsCookieReader { + get(name: string): { value: string } | undefined; +} + +export interface VisitorContext { + anonymousId: string | null; + firstTouch: FirstTouch | null; +} + +export function readVisitorContext(store: AnalyticsCookieReader): VisitorContext { + const rawId = store.get(ANONYMOUS_ID_COOKIE)?.value; + return { + anonymousId: isValidAnonymousId(rawId) ? rawId : null, + firstTouch: decodeFirstTouch(store.get(FIRST_TOUCH_COOKIE)?.value), + }; +} + +const DIRECT_TOUCH: FirstTouch = { + channel: 'DIRECT', + utmSource: null, + utmMedium: null, + utmCampaign: null, + referrerHost: null, + landingPath: '/', +}; + +/** + * Records an event for a visitor with no account, once per visitor per UTC day. + * + * The first touch row is written here rather than in the proxy because this is + * the first moment the visitor is known to be a browser that kept the cookie. + */ +export async function recordVisitorEvent( + name: AnalyticsEventName, + visitor: VisitorContext +): Promise { + if (!isProductAnalyticsEnabled()) return; + if (!visitor.anonymousId) return; + + const touch = visitor.firstTouch ?? DIRECT_TOUCH; + + await recordFirstTouch(visitor.anonymousId, touch); + await recordEvent({ + name, + dedupeKey: dailyEventKey(name, visitor.anonymousId), + anonymousId: visitor.anonymousId, + channel: touch.channel, + }); +} diff --git a/lib/auth.ts b/lib/auth.ts index 5f3880d..5d8dad5 100644 --- a/lib/auth.ts +++ b/lib/auth.ts @@ -150,6 +150,21 @@ export const { handlers, signIn, signOut, auth } = NextAuth({ return token; }, }, + events: { + // The OAuth half of signup. Accounts created by Google or GitHub are written + // by the Prisma adapter and never reach app/api/auth/register, so recording + // the event only there would have made every social signup invisible in the + // funnel while looking like it worked. + async createUser({ user }) { + if (!user.id) return; + const { recordSignupCompleted, readVisitorContextFromHeaders } = + await import('@/lib/analytics/signup'); + await recordSignupCompleted({ + userId: user.id, + visitor: await readVisitorContextFromHeaders(), + }); + }, + }, }); // --------------------------------------------------------------------------- diff --git a/lib/billing.ts b/lib/billing.ts index 082001e..3b67130 100644 --- a/lib/billing.ts +++ b/lib/billing.ts @@ -4,6 +4,7 @@ import { BillingSubscriptionStatus } from '@prisma/client'; import { db } from '@/lib/db'; import { getStripe, getStripePriceId } from '@/lib/stripe'; import { isStripeFeatureEnabled } from '@/lib/feature-flags'; +import { recordSubscriptionTransition } from '@/lib/analytics/billing-events'; const ACTIVE_SUBSCRIPTION_STATUSES = new Set([ BillingSubscriptionStatus.ACTIVE, @@ -394,6 +395,10 @@ export async function syncStripeSubscriptionToUser(subscription: Stripe.Subscrip select: { id: true, billingTrialConsumedAt: true, + // Read for the funnel: the transition is what gets recorded, so the state + // being overwritten has to be captured before the update below. + subscriptionStatus: true, + stripeCancelAtPeriodEnd: true, }, }); @@ -430,7 +435,7 @@ export async function syncStripeSubscriptionToUser(subscription: Stripe.Subscrip (hasActiveSubscription(mappedStatus) || Boolean(currentPeriodEnd && currentPeriodEnd * 1000 > Date.now())); - return db.user.update({ + const updated = await db.user.update({ where: { id: user.id }, data: { stripeSubscriptionId: subscription.id, @@ -449,6 +454,24 @@ export async function syncStripeSubscriptionToUser(subscription: Stripe.Subscrip : getInactiveBillingAccessEndedAt(subscription, hasEntitledPrice ? currentPeriodEnd : null), }, }); + + await recordSubscriptionTransition({ + userId: user.id, + subscriptionId: subscription.id, + before: { + status: user.subscriptionStatus, + cancelAtPeriodEnd: user.stripeCancelAtPeriodEnd, + hadTrial: user.billingTrialConsumedAt !== null, + }, + after: { + status: mappedStatus, + cancelAtPeriodEnd, + trialEndsAt: effectiveTrialEnd, + currentPeriodEnd: effectiveCurrentPeriodEnd, + }, + }); + + return updated; } // A single Stripe customer can own several subscriptions at once (e.g. after @@ -524,14 +547,21 @@ export async function markSubscriptionCanceledByCustomerId( ) { const user = await db.user.findUnique({ where: { stripeCustomerId: customerId }, - select: { id: true }, + select: { + id: true, + subscriptionStatus: true, + stripeSubscriptionId: true, + stripeCancelAtPeriodEnd: true, + stripeCurrentPeriodEnd: true, + billingTrialConsumedAt: true, + }, }); if (!user) { return null; } - return db.user.update({ + const updated = await db.user.update({ where: { id: user.id }, data: { subscriptionStatus: BillingSubscriptionStatus.CANCELED, @@ -544,4 +574,26 @@ export async function markSubscriptionCanceledByCustomerId( billingAccessEndedAt: options?.endedAt ?? options?.currentPeriodEnd ?? new Date(), }, }); + + // Reached when the customer has no subscriptions left at all. The cycle marker + // uses the period end being cleared here, which is the same one the earlier + // "cancel at period end" write carried, so a customer who cancelled through the + // portal and then reached the end of their term produces one cancellation, not two. + await recordSubscriptionTransition({ + userId: user.id, + subscriptionId: user.stripeSubscriptionId ?? user.id, + before: { + status: user.subscriptionStatus, + cancelAtPeriodEnd: user.stripeCancelAtPeriodEnd, + hadTrial: user.billingTrialConsumedAt !== null, + }, + after: { + status: BillingSubscriptionStatus.CANCELED, + cancelAtPeriodEnd: false, + trialEndsAt: null, + currentPeriodEnd: options?.currentPeriodEnd ?? user.stripeCurrentPeriodEnd ?? null, + }, + }); + + return updated; } diff --git a/lib/client/track.ts b/lib/client/track.ts new file mode 100644 index 0000000..88ae685 --- /dev/null +++ b/lib/client/track.ts @@ -0,0 +1,31 @@ +/** + * Reports a click on a call to action. + * + * `sendBeacon` rather than a plain fetch because a CTA click navigates away + * immediately, and a request still in flight when the page unloads is cancelled. + * + * Everything here is best effort. This is the only funnel event that depends on + * the browser cooperating, which is also why nothing downstream divides by it: + * the visitor and signup counts either side of it are recorded server-side. + */ +export function trackCtaClick(): void { + if (typeof navigator === 'undefined') return; + + const payload = JSON.stringify({ name: 'cta_clicked' }); + + try { + if (typeof navigator.sendBeacon === 'function') { + navigator.sendBeacon('/api/events', new Blob([payload], { type: 'application/json' })); + return; + } + + void fetch('/api/events', { + method: 'POST', + headers: { 'content-type': 'application/json' }, + body: payload, + keepalive: true, + }).catch(() => undefined); + } catch { + // A click must never fail because measurement did. + } +} diff --git a/lib/email-verification.ts b/lib/email-verification.ts index 875d6ff..a8c6b8c 100644 --- a/lib/email-verification.ts +++ b/lib/email-verification.ts @@ -9,6 +9,8 @@ import { EMAIL_COLORS, } from '@/lib/email-brand'; import { logError } from '@/lib/logger'; +import { eventKey, recordEvent } from '@/lib/analytics/record'; +import { isProductAnalyticsEnabled } from '@/lib/feature-flags'; // Reduce window to 2 hours — shorter exposure in access logs and backups. const TOKEN_EXPIRY_HOURS = 2; @@ -77,6 +79,23 @@ export async function consumeVerificationToken(token: string): Promise 0 above already means this is the one call + // that flipped the account, so a replayed link cannot reach here. + if (isProductAnalyticsEnabled()) { + const verified = await db.user.findUnique({ + where: { email: record.identifier }, + select: { id: true }, + }); + if (verified) { + await recordEvent({ + name: 'EMAIL_VERIFIED', + dedupeKey: eventKey('EMAIL_VERIFIED', verified.id), + userId: verified.id, + }); + } + } + return record.identifier; } diff --git a/lib/feature-flags.ts b/lib/feature-flags.ts index 00c1eb3..9bea836 100644 --- a/lib/feature-flags.ts +++ b/lib/feature-flags.ts @@ -98,6 +98,16 @@ export function isInviteCodeRequired() { return readBooleanEnv('OPENFRAME_REQUIRE_INVITE_CODE', true); } +// Acquisition attribution and funnel events. Defaults to OFF, unlike the other +// product flags here, because the cost of the two mistakes is not symmetric: a +// hosted instance that forgets to switch it on shows an empty growth page and is +// noticed the same day, while a self-hosted instance that gets it silently +// switched on accumulates rows nobody asked for. Nothing is ever sent off the +// instance either way, so this is about cost, not disclosure. +export function isProductAnalyticsEnabled() { + return readBooleanEnv('OPENFRAME_ENABLE_ANALYTICS', false); +} + function parseBigIntEnv(name: string, defaultValue: bigint, minValue?: bigint): bigint { const raw = process.env[name]?.trim(); if (!raw) return defaultValue; diff --git a/lib/rate-limit.ts b/lib/rate-limit.ts index 37017e6..011b767 100644 --- a/lib/rate-limit.ts +++ b/lib/rate-limit.ts @@ -105,6 +105,9 @@ export const RATE_LIMIT_CONFIGS: Record = { // Mutations (update/delete) — moderate mutate: { windowMs: 60 * 1000, maxRequests: 30 }, // 30 per minute + // Analytics beacon — anonymous and public, so bound it per IP + 'analytics-beacon': { windowMs: 60 * 60 * 1000, maxRequests: 30 }, // 30 per hour + // General reads — generous api: { windowMs: 60 * 1000, maxRequests: 100 }, // 100 per minute }; diff --git a/prisma/migrations/20260801120000_add_acquisition_analytics/migration.sql b/prisma/migrations/20260801120000_add_acquisition_analytics/migration.sql new file mode 100644 index 0000000..ebffb2d --- /dev/null +++ b/prisma/migrations/20260801120000_add_acquisition_analytics/migration.sql @@ -0,0 +1,87 @@ +-- CreateEnum +CREATE TYPE "AcquisitionChannel" AS ENUM ('DIRECT', 'GITHUB', 'YOUTUBE', 'GOOGLE', 'REVIEW_LINK', 'REFERRAL', 'OUTBOUND', 'COMMUNITY', 'OTHER'); + +-- CreateEnum +CREATE TYPE "AnalyticsEventName" AS ENUM ('LANDING_VIEW', 'CTA_CLICKED', 'SIGNUP_STARTED', 'SIGNUP_COMPLETED', 'EMAIL_VERIFIED', 'TRIAL_STARTED', 'WORKSPACE_CREATED', 'PROJECT_CREATED', 'VIDEO_ADDED', 'SHARE_LINK_CREATED', 'FIRST_GUEST_COMMENT', 'APPROVAL_COMPLETED', 'CHECKOUT_STARTED', 'SUBSCRIPTION_STARTED', 'SUBSCRIPTION_CANCELED', 'SUBSCRIPTION_REACTIVATED'); + +-- CreateTable +CREATE TABLE "acquisition_touches" ( + "id" TEXT NOT NULL, + "anonymous_id" TEXT NOT NULL, + "channel" "AcquisitionChannel" NOT NULL, + "utm_source" TEXT, + "utm_medium" TEXT, + "utm_campaign" TEXT, + "referrer_host" TEXT, + "landing_path" TEXT NOT NULL, + "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP, + + CONSTRAINT "acquisition_touches_pkey" PRIMARY KEY ("id") +); + +-- CreateTable +CREATE TABLE "user_acquisitions" ( + "user_id" TEXT NOT NULL, + "anonymous_id" TEXT, + "channel" "AcquisitionChannel" NOT NULL DEFAULT 'DIRECT', + "utm_source" TEXT, + "utm_medium" TEXT, + "utm_campaign" TEXT, + "referrer_host" TEXT, + "landing_path" TEXT, + "self_reported" "AcquisitionChannel", + "self_reported_note" TEXT, + "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP, + "updated_at" TIMESTAMP(3) NOT NULL, + + CONSTRAINT "user_acquisitions_pkey" PRIMARY KEY ("user_id") +); + +-- CreateTable +CREATE TABLE "analytics_events" ( + "id" TEXT NOT NULL, + "name" "AnalyticsEventName" NOT NULL, + "user_id" TEXT, + "anonymous_id" TEXT, + "channel" "AcquisitionChannel", + "dedupe_key" TEXT NOT NULL, + "occurred_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP, + + CONSTRAINT "analytics_events_pkey" PRIMARY KEY ("id") +); + +-- CreateIndex +CREATE UNIQUE INDEX "acquisition_touches_anonymous_id_key" ON "acquisition_touches"("anonymous_id"); + +-- CreateIndex +CREATE INDEX "acquisition_touches_channel_created_at_idx" ON "acquisition_touches"("channel", "created_at"); + +-- CreateIndex +CREATE INDEX "acquisition_touches_created_at_idx" ON "acquisition_touches"("created_at"); + +-- CreateIndex +CREATE INDEX "user_acquisitions_channel_created_at_idx" ON "user_acquisitions"("channel", "created_at"); + +-- CreateIndex +CREATE INDEX "user_acquisitions_anonymous_id_idx" ON "user_acquisitions"("anonymous_id"); + +-- CreateIndex +CREATE UNIQUE INDEX "analytics_events_dedupe_key_key" ON "analytics_events"("dedupe_key"); + +-- CreateIndex +CREATE INDEX "analytics_events_name_occurred_at_idx" ON "analytics_events"("name", "occurred_at"); + +-- CreateIndex +CREATE INDEX "analytics_events_user_id_occurred_at_idx" ON "analytics_events"("user_id", "occurred_at"); + +-- CreateIndex +CREATE INDEX "analytics_events_channel_name_occurred_at_idx" ON "analytics_events"("channel", "name", "occurred_at"); + +-- CreateIndex +CREATE INDEX "analytics_events_anonymous_id_idx" ON "analytics_events"("anonymous_id"); + +-- AddForeignKey +ALTER TABLE "user_acquisitions" ADD CONSTRAINT "user_acquisitions_user_id_fkey" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE; + +-- AddForeignKey +ALTER TABLE "analytics_events" ADD CONSTRAINT "analytics_events_user_id_fkey" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE SET NULL ON UPDATE CASCADE; diff --git a/prisma/schema.prisma b/prisma/schema.prisma index 8fc215b..0f6f42b 100644 --- a/prisma/schema.prisma +++ b/prisma/schema.prisma @@ -50,7 +50,9 @@ model User { canceledApprovalRequests ApprovalRequest[] @relation("ApprovalRequestsCanceledBy") approvalDecisions ApprovalDecision[] sentInvitations Invitation[] @relation("InvitationsSentBy") - + acquisition UserAcquisition? + analyticsEvents AnalyticsEvent[] + @@map("users") } @@ -738,6 +740,118 @@ model VideoUploadSession { @@map("video_upload_sessions") } +// ============================================ +// ACQUISITION + PRODUCT ANALYTICS +// ============================================ +// +// Everything here is first party. Rows are written to this deployment's own +// database and read back by this deployment's own admin panel; no part of the +// codebase ships them anywhere else. The whole subsystem is off unless +// OPENFRAME_ENABLE_ANALYTICS is set, so a self-hosted instance carries the +// tables empty and pays nothing for them. +// +// No free text from user content is stored. Referrers are reduced to a host and +// landing pages to a path, both without query strings, so a shared link with a +// name or token in it cannot leak in here. + +enum AcquisitionChannel { + DIRECT + GITHUB + YOUTUBE + GOOGLE + REVIEW_LINK + REFERRAL + OUTBOUND + COMMUNITY + OTHER +} + +enum AnalyticsEventName { + LANDING_VIEW + CTA_CLICKED + SIGNUP_STARTED + SIGNUP_COMPLETED + EMAIL_VERIFIED + TRIAL_STARTED + WORKSPACE_CREATED + PROJECT_CREATED + VIDEO_ADDED + SHARE_LINK_CREATED + FIRST_GUEST_COMMENT + APPROVAL_COMPLETED + CHECKOUT_STARTED + SUBSCRIPTION_STARTED + SUBSCRIPTION_CANCELED + SUBSCRIPTION_REACTIVATED +} + +// First touch for a visitor who does not have an account yet. Written once per +// anonymous id and never updated: the whole point is what brought them here the +// first time, so a later visit carrying different UTM tags must not overwrite it. +model AcquisitionTouch { + id String @id @default(cuid()) + anonymousId String @unique @map("anonymous_id") + channel AcquisitionChannel + utmSource String? @map("utm_source") + utmMedium String? @map("utm_medium") + utmCampaign String? @map("utm_campaign") + referrerHost String? @map("referrer_host") + landingPath String @map("landing_path") + createdAt DateTime @default(now()) @map("created_at") + + @@index([channel, createdAt]) + @@index([createdAt]) + @@map("acquisition_touches") +} + +// The first touch copied onto the account at signup, plus the answer to the +// onboarding question. Kept beside User rather than on it so the acquisition +// columns stay out of every session and billing query. +model UserAcquisition { + userId String @id @map("user_id") + user User @relation(fields: [userId], references: [id], onDelete: Cascade) + anonymousId String? @map("anonymous_id") + channel AcquisitionChannel @default(DIRECT) + utmSource String? @map("utm_source") + utmMedium String? @map("utm_medium") + utmCampaign String? @map("utm_campaign") + referrerHost String? @map("referrer_host") + landingPath String? @map("landing_path") + selfReported AcquisitionChannel? @map("self_reported") + selfReportedNote String? @map("self_reported_note") + createdAt DateTime @default(now()) @map("created_at") + updatedAt DateTime @updatedAt @map("updated_at") + + @@index([channel, createdAt]) + @@index([anonymousId]) + @@map("user_acquisitions") +} + +// One row per funnel step. `dedupeKey` is what makes "recorded exactly once" +// a property of the schema instead of a property of every call site: a replayed +// webhook, a double-submitted form or a refreshed page all collide on the unique +// index and the second write is dropped. +// +// The user relation is SetNull rather than Cascade on purpose. A deleted account +// still happened, and dropping its rows would silently rewrite past weeks of the +// funnel. +model AnalyticsEvent { + id String @id @default(cuid()) + name AnalyticsEventName + userId String? @map("user_id") + user User? @relation(fields: [userId], references: [id], onDelete: SetNull) + anonymousId String? @map("anonymous_id") + channel AcquisitionChannel? + dedupeKey String @unique @map("dedupe_key") + occurredAt DateTime @default(now()) @map("occurred_at") + + @@index([name, occurredAt]) + @@index([userId, occurredAt]) + @@index([channel, name, occurredAt]) + @@index([anonymousId]) + @@map("analytics_events") +} + // Rate limiting table (created as UNLOGGED via raw SQL migration) // Defined here so `prisma db push` doesn't drop it model RateLimit { diff --git a/proxy.ts b/proxy.ts index 52d5ac4..be1a726 100644 --- a/proxy.ts +++ b/proxy.ts @@ -1,9 +1,75 @@ -import { NextResponse } from 'next/server'; +import { NextRequest, NextResponse } from 'next/server'; import { buildContentSecurityPolicy } from '@/lib/content-security-policy'; +import { + classifyChannel, + extractReferrerHost, + sanitizeLandingPath, + sanitizeTag, +} from '@/lib/analytics/channel'; +import { + ANONYMOUS_ID_COOKIE, + ANONYMOUS_ID_MAX_AGE_SECONDS, + FIRST_TOUCH_COOKIE, + encodeFirstTouch, + generateAnonymousId, + isValidAnonymousId, +} from '@/lib/analytics/cookies'; +import { isCountableDocumentRequest, isLikelyBot } from '@/lib/analytics/bots'; +import { isProductAnalyticsEnabled } from '@/lib/feature-flags'; -export function proxy() { - const response = NextResponse.next(); +// Runs on the edge, so nothing here touches the database. It only decides who a +// visitor is and what brought them, then hands both downstream as cookies. The +// rows are written by the pages, which run in Node. +function applyAcquisitionCookies(request: NextRequest, response: NextResponse): void { + if (!isProductAnalyticsEnabled()) return; + if (!isCountableDocumentRequest(request.headers)) return; + if (isLikelyBot(request.headers.get('user-agent'))) return; + + const cookieOptions = { + httpOnly: true, + sameSite: 'lax' as const, + secure: request.nextUrl.protocol === 'https:', + path: '/', + maxAge: ANONYMOUS_ID_MAX_AGE_SECONDS, + }; + + const existingId = request.cookies.get(ANONYMOUS_ID_COOKIE)?.value; + if (!isValidAnonymousId(existingId)) { + const anonymousId = generateAnonymousId(); + // Set on the request as well as the response: without this the page rendering + // *this* request cannot see the id, and the first landing view of every new + // visitor, the one carrying the campaign tags, goes unrecorded. + request.cookies.set(ANONYMOUS_ID_COOKIE, anonymousId); + response.cookies.set(ANONYMOUS_ID_COOKIE, anonymousId, cookieOptions); + } + + if (request.cookies.get(FIRST_TOUCH_COOKIE)) return; + + const params = request.nextUrl.searchParams; + const referrerHost = extractReferrerHost( + request.headers.get('referer'), + request.nextUrl.hostname + ); + const utmSource = sanitizeTag(params.get('utm_source')); + const utmMedium = sanitizeTag(params.get('utm_medium')); + + const firstTouch = encodeFirstTouch({ + channel: classifyChannel({ utmSource, utmMedium, referrerHost }), + utmSource, + utmMedium, + utmCampaign: sanitizeTag(params.get('utm_campaign')), + referrerHost, + landingPath: sanitizeLandingPath(request.nextUrl.pathname), + }); + + request.cookies.set(FIRST_TOUCH_COOKIE, firstTouch); + response.cookies.set(FIRST_TOUCH_COOKIE, firstTouch, cookieOptions); +} + +export function proxy(request: NextRequest) { + const response = NextResponse.next({ request }); response.headers.set('Content-Security-Policy', buildContentSecurityPolicy()); + applyAcquisitionCookies(request, response); return response; } diff --git a/tests/api/analytics-events.test.ts b/tests/api/analytics-events.test.ts new file mode 100644 index 0000000..5cfced9 --- /dev/null +++ b/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; +}) { + const headers: Record = {}; + 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 { + 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('attributed@example.com'); + expect(response.status).toBe(201); + + const user = await db.user.findUniqueOrThrow({ where: { email: 'attributed@example.com' } }); + 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('backfilled@example.com'); + + const user = await db.user.findUniqueOrThrow({ where: { email: 'backfilled@example.com' } }); + 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('unmeasured@example.com'); + + 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); + }); +}); diff --git a/tests/api/analytics-scoreboard.test.ts b/tests/api/analytics-scoreboard.test.ts new file mode 100644 index 0000000..d128614 --- /dev/null +++ b/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); + }); +}); diff --git a/tests/api/auth-matrix.test.ts b/tests/api/auth-matrix.test.ts index 14fa3cd..6be06e2 100644 --- a/tests/api/auth-matrix.test.ts +++ b/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 = 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, diff --git a/tests/setup/db-global.ts b/tests/setup/db-global.ts index 3df05c5..ce68aed 100644 --- a/tests/setup/db-global.ts +++ b/tests/setup/db-global.ts @@ -66,6 +66,7 @@ const REVIEWED_MIGRATIONS = [ '20260613120000_add_r2_video_asset_provider', '20260614160000_add_project_allow_downloads', '20260627140000_add_video_upload_multipart_id', + '20260801120000_add_acquisition_analytics', ]; /** Objects POST_PUSH_SQL must have produced. Verified after it runs. */ diff --git a/tests/unit/lib/analytics-channel.test.ts b/tests/unit/lib/analytics-channel.test.ts new file mode 100644 index 0000000..3a197f3 --- /dev/null +++ b/tests/unit/lib/analytics-channel.test.ts @@ -0,0 +1,130 @@ +import { describe, it, expect } from 'vitest'; +import { + classifyChannel, + extractReferrerHost, + normalizeHost, + sanitizeLandingPath, + sanitizeTag, +} from '@/lib/analytics/channel'; + +// Every expected value below is written by hand. Deriving them from the lookup +// tables in the module would mean deleting an entry from a table also deletes +// its own test case. + +describe('sanitizeTag', () => { + it('lowercases and trims', () => { + expect(sanitizeTag(' GitHub ')).toBe('github'); + }); + + it('rejects a tag carrying markup or control characters', () => { + expect(sanitizeTag('', r: 'not a host' }) + ); + const decoded = decodeFirstTouch(forged); + expect(decoded?.utmSource).toBeNull(); + expect(decoded?.referrerHost).toBeNull(); + }); + + it('returns null for garbage and for an absent cookie', () => { + expect(decodeFirstTouch('%%%not-json%%%')).toBeNull(); + expect(decodeFirstTouch(null)).toBeNull(); + expect(decodeFirstTouch(encodeURIComponent(JSON.stringify(['DIRECT'])))).toBeNull(); + }); +}); + +describe('anonymous id', () => { + it('generates an id the validator accepts', () => { + expect(isValidAnonymousId(generateAnonymousId())).toBe(true); + }); + + it('generates a different id each time', () => { + expect(generateAnonymousId()).not.toBe(generateAnonymousId()); + }); + + it('rejects an id that is too short, too long or not base36', () => { + expect(isValidAnonymousId('abc')).toBe(false); + expect(isValidAnonymousId('a'.repeat(65))).toBe(false); + expect(isValidAnonymousId('ABCDEF0123456789ABCD')).toBe(false); + expect(isValidAnonymousId(undefined)).toBe(false); + }); +}); + +describe('isAcquisitionChannel', () => { + it('accepts the nine buckets and nothing else', () => { + expect(isAcquisitionChannel('REVIEW_LINK')).toBe(true); + expect(isAcquisitionChannel('direct')).toBe(false); + expect(isAcquisitionChannel(7)).toBe(false); + }); +}); + +describe('isLikelyBot', () => { + it('passes a real browser through', () => { + expect( + isLikelyBot( + 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126 Safari/537.36' + ) + ).toBe(false); + }); + + it('catches crawlers, link previewers and scripts', () => { + expect(isLikelyBot('Googlebot/2.1 (+http://www.google.com/bot.html)')).toBe(true); + expect(isLikelyBot('facebookexternalhit/1.1')).toBe(true); + expect(isLikelyBot('curl/8.4.0')).toBe(true); + expect(isLikelyBot('python-requests/2.31.0')).toBe(true); + expect(isLikelyBot('HeadlessChrome/120.0.0.0')).toBe(true); + }); + + it('treats a missing user agent as a bot', () => { + expect(isLikelyBot('')).toBe(true); + expect(isLikelyBot(null)).toBe(true); + }); +}); + +describe('isCountableDocumentRequest', () => { + it('counts a real page load', () => { + expect(isCountableDocumentRequest(new Headers({ 'sec-fetch-dest': 'document' }))).toBe(true); + }); + + it('does not count a prefetch of the register page', () => { + expect( + isCountableDocumentRequest( + new Headers({ 'sec-fetch-dest': 'document', 'sec-purpose': 'prefetch;prerender' }) + ) + ).toBe(false); + expect( + isCountableDocumentRequest( + new Headers({ 'sec-fetch-dest': 'document', 'next-router-prefetch': '1' }) + ) + ).toBe(false); + }); + + it('does not count an RSC navigation or a subresource', () => { + expect( + isCountableDocumentRequest(new Headers({ 'sec-fetch-dest': 'document', rsc: '1' })) + ).toBe(false); + expect(isCountableDocumentRequest(new Headers({ 'sec-fetch-dest': 'image' }))).toBe(false); + }); + + it('falls back to the accept header when fetch metadata is missing', () => { + expect(isCountableDocumentRequest(new Headers({ accept: 'text/html,*/*' }))).toBe(true); + expect(isCountableDocumentRequest(new Headers({ accept: 'application/json' }))).toBe(false); + expect(isCountableDocumentRequest(new Headers())).toBe(false); + }); +}); diff --git a/tests/unit/lib/analytics-scoreboard.test.ts b/tests/unit/lib/analytics-scoreboard.test.ts new file mode 100644 index 0000000..92c224e --- /dev/null +++ b/tests/unit/lib/analytics-scoreboard.test.ts @@ -0,0 +1,36 @@ +import { describe, it, expect } from 'vitest'; +import { conversionRates } from '@/lib/analytics/scoreboard'; + +const WEEK = { + visitors: 200, + signups: 20, + firstVideo: 10, + shareLinks: 5, + externalFeedback: 1, + trials: 4, + newPaid: 1, +}; + +describe('conversionRates', () => { + it('divides each step by the one above it', () => { + const rates = conversionRates(WEEK); + expect(rates.visitorToSignup).toBeCloseTo(0.1); + expect(rates.signupToFirstVideo).toBeCloseTo(0.5); + expect(rates.firstVideoToShare).toBeCloseTo(0.5); + expect(rates.shareToFeedback).toBeCloseTo(0.2); + expect(rates.trialToPaid).toBeCloseTo(0.25); + }); + + it('returns null rather than zero when the denominator is zero', () => { + const rates = conversionRates({ ...WEEK, visitors: 0, trials: 0 }); + expect(rates.visitorToSignup).toBeNull(); + expect(rates.trialToPaid).toBeNull(); + // "nobody arrived" and "nobody converted" are different facts, and the rest + // of the funnel still has to report normally. + expect(rates.signupToFirstVideo).toBeCloseTo(0.5); + }); + + it('reports a step where nobody converted as zero, not as missing', () => { + expect(conversionRates({ ...WEEK, newPaid: 0 }).trialToPaid).toBe(0); + }); +}); diff --git a/tests/unit/proxy.test.ts b/tests/unit/proxy.test.ts new file mode 100644 index 0000000..b0320ef --- /dev/null +++ b/tests/unit/proxy.test.ts @@ -0,0 +1,163 @@ +// The proxy is where a visitor gets an identity, and it is the only place that +// can: it runs on the edge, before the page, on every document request. +// +// The load-bearing detail below is that the id is written to the *request* as +// well as the response. A cookie set only on the response is invisible to the +// page rendering that same request, so the very first landing view, the one +// carrying the campaign tags that brought the visitor, would go unrecorded. + +import { describe, it, expect, afterEach, vi } from 'vitest'; +import { NextRequest } from 'next/server'; +import { proxy } from '@/proxy'; +import { ANONYMOUS_ID_COOKIE, FIRST_TOUCH_COOKIE, decodeFirstTouch } from '@/lib/analytics/cookies'; + +const BROWSER_UA = + 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126 Safari/537.36'; + +function documentRequest( + url: string, + init?: { headers?: Record; cookies?: Record } +) { + const headers = new Headers({ + 'user-agent': BROWSER_UA, + 'sec-fetch-dest': 'document', + ...init?.headers, + }); + const cookies = Object.entries(init?.cookies ?? {}); + if (cookies.length > 0) { + headers.set('cookie', cookies.map(([name, value]) => `${name}=${value}`).join('; ')); + } + return new NextRequest(new URL(url), { headers }); +} + +afterEach(() => { + vi.unstubAllEnvs(); +}); + +describe('proxy', () => { + it('always sets the content security policy', () => { + vi.stubEnv('OPENFRAME_ENABLE_ANALYTICS', 'false'); + + const response = proxy(documentRequest('https://open-frame.net/')); + + expect(response.headers.get('Content-Security-Policy')).toContain("default-src 'self'"); + }); + + it('sets no acquisition cookie at all when the flag is off', () => { + vi.stubEnv('OPENFRAME_ENABLE_ANALYTICS', 'false'); + + const response = proxy(documentRequest('https://open-frame.net/?utm_source=github')); + + expect(response.cookies.get(ANONYMOUS_ID_COOKIE)).toBeUndefined(); + expect(response.cookies.get(FIRST_TOUCH_COOKIE)).toBeUndefined(); + }); + + it('gives a new visitor an id and stores what brought them', () => { + vi.stubEnv('OPENFRAME_ENABLE_ANALYTICS', 'true'); + const request = documentRequest( + 'https://open-frame.net/?utm_source=youtube&utm_medium=video&utm_campaign=launch' + ); + + const response = proxy(request); + + const id = response.cookies.get(ANONYMOUS_ID_COOKIE); + expect(id?.value).toMatch(/^[a-z0-9]{32}$/); + expect(id?.httpOnly).toBe(true); + expect(id?.sameSite).toBe('lax'); + expect(id?.secure).toBe(true); + + const touch = decodeFirstTouch(response.cookies.get(FIRST_TOUCH_COOKIE)?.value); + expect(touch).toEqual({ + channel: 'YOUTUBE', + utmSource: 'youtube', + utmMedium: 'video', + utmCampaign: 'launch', + referrerHost: null, + landingPath: '/', + }); + + // The page rendering this same request has to be able to read both. + expect(request.cookies.get(ANONYMOUS_ID_COOKIE)?.value).toBe(id?.value); + expect(request.cookies.get(FIRST_TOUCH_COOKIE)?.value).toBeDefined(); + }); + + it('classifies a visit that only carries a referrer', () => { + vi.stubEnv('OPENFRAME_ENABLE_ANALYTICS', 'true'); + + const response = proxy( + documentRequest('https://open-frame.net/vs/frameio', { + headers: { referer: 'https://github.com/yusufipk/OpenFrame' }, + }) + ); + + expect(decodeFirstTouch(response.cookies.get(FIRST_TOUCH_COOKIE)?.value)).toMatchObject({ + channel: 'GITHUB', + referrerHost: 'github.com', + landingPath: '/vs/frameio', + }); + }); + + it('does not overwrite the first touch of a returning visitor', () => { + vi.stubEnv('OPENFRAME_ENABLE_ANALYTICS', 'true'); + const existingId = 'a1b2c3d4e5f60718293a4b5c6d7e8f90'; + + const response = proxy( + documentRequest('https://open-frame.net/?utm_source=google', { + cookies: { [ANONYMOUS_ID_COOKIE]: existingId, [FIRST_TOUCH_COOKIE]: 'anything' }, + }) + ); + + expect(response.cookies.get(ANONYMOUS_ID_COOKIE)).toBeUndefined(); + expect(response.cookies.get(FIRST_TOUCH_COOKIE)).toBeUndefined(); + }); + + it('replaces an id that does not look like one we issued', () => { + vi.stubEnv('OPENFRAME_ENABLE_ANALYTICS', 'true'); + + const response = proxy( + documentRequest('https://open-frame.net/', { + cookies: { [ANONYMOUS_ID_COOKIE]: 'nope' }, + }) + ); + + expect(response.cookies.get(ANONYMOUS_ID_COOKIE)?.value).toMatch(/^[a-z0-9]{32}$/); + }); + + it('ignores crawlers, so they never enter the visitor count', () => { + vi.stubEnv('OPENFRAME_ENABLE_ANALYTICS', 'true'); + + const response = proxy( + documentRequest('https://open-frame.net/', { + headers: { 'user-agent': 'Googlebot/2.1 (+http://www.google.com/bot.html)' }, + }) + ); + + expect(response.cookies.get(ANONYMOUS_ID_COOKIE)).toBeUndefined(); + }); + + it('ignores a prefetch and an API call', () => { + vi.stubEnv('OPENFRAME_ENABLE_ANALYTICS', 'true'); + + const prefetch = proxy( + documentRequest('https://open-frame.net/register', { + headers: { 'next-router-prefetch': '1' }, + }) + ); + const api = proxy( + documentRequest('https://open-frame.net/api/projects', { + headers: { 'sec-fetch-dest': 'empty' }, + }) + ); + + expect(prefetch.cookies.get(ANONYMOUS_ID_COOKIE)).toBeUndefined(); + expect(api.cookies.get(ANONYMOUS_ID_COOKIE)).toBeUndefined(); + }); + + it('leaves the cookie insecure on plain http, so local development works', () => { + vi.stubEnv('OPENFRAME_ENABLE_ANALYTICS', 'true'); + + const response = proxy(documentRequest('http://localhost:3000/')); + + expect(response.cookies.get(ANONYMOUS_ID_COOKIE)?.secure).toBe(false); + }); +});