@coursebuilder/analytics 1.1.0 → 1.1.2-canary.0.0c9beb2ae

package/src/components/omnibus-dashboard.tsx

@@ -17,6 +17,7 @@ import {
 	PlayIcon,
 	ShoppingCartIcon,
 	TrendingUpIcon,
+	RouteIcon,
 } from 'lucide-react'
 import { parseAsStringLiteral, useQueryState } from 'nuqs'
 
@@ -28,7 +29,7 @@ import {
 	CardTitle,
 } from '@coursebuilder/ui'
 
-import type { AnalyticsRange } from '../types'
+import type { AnalyticsRange, TrafficBreakdownRow } from '../types'
 import { CountryChart } from './country-chart'
 import { RevenueChart } from './revenue-chart'
 
@@ -106,6 +107,11 @@ export interface DashboardData {
 		totalUsers: number
 		newUsers: number
 		pageviews: number
+		deviceCategories?: Array<TrafficBreakdownRow & { deviceCategory: string }>
+		operatingSystems?: Array<TrafficBreakdownRow & { operatingSystem: string }>
+		screenResolutions?: Array<
+			TrafficBreakdownRow & { screenResolution: string }
+		>
 	} | null
 	attributionCoverage: {
 		totalRevenue: number
@@ -113,6 +119,16 @@ export interface DashboardData {
 		unattributedRevenue: number
 		attributionRate: number
 		totalPurchases: number
+		quality?: Record<
+			'strong' | 'medium' | 'weak' | 'unknown',
+			{
+				lane: 'strong' | 'medium' | 'weak' | 'unknown'
+				purchases: number
+				revenue: number
+				revenuePercent: number
+				notes: string[]
+			}
+		>
 	} | null
 	mux: VideoDashboardData | null
 	muxThumbnails: Record<string, string>
@@ -125,6 +141,29 @@ export interface DashboardData {
 				answerDistribution: { answer: string; count: number }[]
 		  }[]
 		| null
+	valuePaths?: {
+		contacts: number
+		events: number
+		intents: number
+		completedIntents: number
+		pendingIntents: number
+		blockedIntents: number
+		answerEvents: number
+		dripEvents: number
+		enteredEvents: number
+		participantsWithAnswerClicks: number
+		participantsWithNoAnswerClicks: number
+		terminalParticipants: number
+		answerOptions: {
+			key: string
+			step: string
+			optionValue: string
+			count: number
+		}[]
+		answerSteps: { step: string; count: number }[]
+		terminalSteps: { emailResourceId: string; count: number }[]
+		notes: string[]
+	} | null
 	surveyCorrelation: {
 		totalRespondents: number
 		respondentsWhoPurchased: number
@@ -594,6 +633,133 @@ function ShortlinksCard({
 	)
 }
 
+// ─── Traffic Breakdowns ──────────────────────────────────────────────────────
+
+function fmtPct(v: number): string {
+	return `${v.toFixed(1)}%`
+}
+
+function TrafficBreakdownTable<T extends TrafficBreakdownRow>({
+	title,
+	label,
+	rows,
+	getName,
+}: {
+	title: string
+	label: string
+	rows: T[]
+	getName: (row: T) => string
+}) {
+	if (!rows.length) return null
+
+	return (
+		<section className="min-w-0">
+			<div className="mb-2 flex items-baseline justify-between gap-2">
+				<h3 className="text-sm font-semibold">{title}</h3>
+				<span className="text-muted-foreground text-[11px]">
+					Top {rows.length}
+				</span>
+			</div>
+			<div className="overflow-x-auto rounded-xl border border-border/50">
+				<table className="w-full min-w-[440px] text-left text-sm">
+					<thead className="bg-muted/30 text-muted-foreground text-[11px] uppercase tracking-wide">
+						<tr>
+							<th className="px-3 py-2 font-medium">{label}</th>
+							<th className="px-3 py-2 text-right font-medium">Sessions</th>
+							<th className="px-3 py-2 text-right font-medium">Users</th>
+							<th className="px-3 py-2 text-right font-medium">In rows</th>
+							<th className="px-3 py-2 text-right font-medium">Of traffic</th>
+						</tr>
+					</thead>
+					<tbody>
+						{rows.map((row) => (
+							<tr
+								key={getName(row)}
+								className="border-t border-border/40 tabular-nums"
+							>
+								<td className="max-w-[220px] truncate px-3 py-2 font-medium">
+									{getName(row)}
+								</td>
+								<td className="px-3 py-2 text-right">
+									{row.sessions.toLocaleString()}
+								</td>
+								<td className="px-3 py-2 text-right">
+									{row.users.toLocaleString()}
+								</td>
+								<td className="px-3 py-2 text-right">
+									{fmtPct(row.sessionPercent)}
+								</td>
+								<td className="px-3 py-2 text-right">
+									{fmtPct(row.trafficSessionPercent)}
+								</td>
+							</tr>
+						))}
+					</tbody>
+				</table>
+			</div>
+		</section>
+	)
+}
+
+function TrafficBreakdownsCard({
+	traffic,
+}: {
+	traffic: NonNullable<DashboardData['traffic']>
+}) {
+	const deviceCategories = traffic.deviceCategories ?? []
+	const operatingSystems = traffic.operatingSystems ?? []
+	const screenResolutions = traffic.screenResolutions ?? []
+
+	if (
+		deviceCategories.length === 0 &&
+		operatingSystems.length === 0 &&
+		screenResolutions.length === 0
+	) {
+		return null
+	}
+
+	return (
+		<Card>
+			<CardHeader>
+				<div className="flex items-center gap-2.5">
+					<GlobeIcon className="text-muted-foreground h-4 w-4" />
+					<div>
+						<CardTitle className="text-sm font-semibold">
+							Traffic Details
+						</CardTitle>
+						<CardDescription className="text-[11px]">
+							Device, OS, and screen share. In rows is share inside the table.
+							Of traffic is share of total sessions.
+						</CardDescription>
+					</div>
+				</div>
+			</CardHeader>
+			<CardContent>
+				<div className="grid gap-4 xl:grid-cols-3">
+					<TrafficBreakdownTable
+						title="Device category"
+						label="Device"
+						rows={deviceCategories}
+						getName={(row) => row.deviceCategory}
+					/>
+					<TrafficBreakdownTable
+						title="Operating systems"
+						label="OS"
+						rows={operatingSystems.slice(0, 10)}
+						getName={(row) => row.operatingSystem}
+					/>
+					<TrafficBreakdownTable
+						title="Screen resolutions"
+						label="Resolution"
+						rows={screenResolutions.slice(0, 10)}
+						getName={(row) => row.screenResolution}
+					/>
+				</div>
+			</CardContent>
+		</Card>
+	)
+}
+
 // ─── Range Selector ───────────────────────────────────────────────────────────
 
 const RANGES: { value: AnalyticsRange; label: string }[] = [
@@ -661,6 +827,7 @@ export function OmnibusDashboard({
 	const hasSurveys =
 		data.surveySegments != null && data.surveySegments.length > 0
 	const hasSurveyCorrelation = data.surveyCorrelation != null
+	const hasValuePaths = data.valuePaths != null && data.valuePaths.contacts > 0
 	const hasShortlinks = data.shortlinks.length > 0
 
 	return (
@@ -672,7 +839,7 @@ export function OmnibusDashboard({
 						Analytics
 					</h1>
 					<p className="text-muted-foreground truncate text-[13px]">
-						Revenue · Attribution · Video · Traffic · Surveys — {rangeLabel}
+						Revenue · Attribution · Video · Traffic · Surveys, {rangeLabel}
 					</p>
 				</div>
 				<div className="flex shrink-0 items-center gap-2">
@@ -753,6 +920,14 @@ export function OmnibusDashboard({
 							icon={MousePointerClickIcon}
 						/>
 					)}
+					{hasValuePaths && (
+						<Stat
+							label="Value Paths"
+							value={`${data.valuePaths!.terminalParticipants}/${data.valuePaths!.contacts}`}
+							sub={`${data.valuePaths!.answerEvents} answers · ${data.valuePaths!.dripEvents} drips`}
+							icon={RouteIcon}
+						/>
+					)}
 					{hasSurveys && (
 						<Stat
 							label="Surveys"
@@ -763,6 +938,9 @@ export function OmnibusDashboard({
 					)}
 				</div>
 
+				{/* ── Traffic Details ──────────────────────────────────────── */}
+				{hasTraffic && <TrafficBreakdownsCard traffic={data.traffic!} />}
+
 				{/* ── Video Performance ────────────────────────────────────── */}
 				{hasMux && data.mux!.topVideos.length > 0 && (
 					<TopVideosCard
@@ -821,7 +999,7 @@ export function OmnibusDashboard({
 									<span className="text-foreground mt-1 block text-xl font-bold tabular-nums">
 										{signupCount > 0
 											? `${((purchaseAttrCount / signupCount) * 100).toFixed(1)}%`
-											: '—'}
+											: '-'}
 									</span>
 								</div>
 							</div>
@@ -879,10 +1057,166 @@ export function OmnibusDashboard({
 										</span>
 									</div>
 								</div>
+								{data.attributionCoverage!.quality && (
+									<div className="mt-4 grid gap-2 sm:grid-cols-4">
+										{(['strong', 'medium', 'weak', 'unknown'] as const).map(
+											(lane) => {
+												const item = data.attributionCoverage!.quality![lane]
+												return (
+													<div
+														key={lane}
+														className="rounded-lg border border-border/40 p-3"
+													>
+														<span className="text-muted-foreground block text-[11px] font-medium uppercase tracking-wider">
+															{lane}
+														</span>
+														<span className="text-foreground mt-1 block text-lg font-bold tabular-nums">
+															{fmt$(item.revenue)}
+														</span>
+														<span className="text-muted-foreground text-[11px]">
+															{item.purchases.toLocaleString()} purchases ·{' '}
+															{(item.revenuePercent * 100).toFixed(1)}%
+														</span>
+													</div>
+												)
+											},
+										)}
+									</div>
+								)}
 							</CardContent>
 						</Card>
 					)}
 
+				{/* ── Value Paths ──────────────────────────────────────────── */}
+				{hasValuePaths && (
+					<Card>
+						<CardHeader className="pb-3">
+							<div className="flex items-center gap-2.5">
+								<div className="flex h-7 w-7 items-center justify-center rounded-lg bg-sky-500/10 text-sky-500">
+									<RouteIcon className="h-3.5 w-3.5" />
+								</div>
+								<div>
+									<CardTitle className="text-sm font-semibold">
+										Value Paths
+									</CardTitle>
+									<CardDescription className="text-[11px]">
+										Progression, answer clicks, drip fallback, and terminal
+										completion
+									</CardDescription>
+								</div>
+							</div>
+						</CardHeader>
+						<CardContent className="space-y-5">
+							{(() => {
+								const vp = data.valuePaths!
+								const completionRate =
+									vp.contacts > 0
+										? (vp.terminalParticipants / vp.contacts) * 100
+										: 0
+								const clickRate =
+									vp.contacts > 0
+										? (vp.participantsWithAnswerClicks / vp.contacts) * 100
+										: 0
+								return (
+									<>
+										<div className="grid grid-cols-2 gap-2 sm:grid-cols-5">
+											<div className="bg-muted/20 rounded-lg p-3">
+												<span className="text-muted-foreground block text-[11px] font-medium uppercase tracking-wider">
+													Contacts
+												</span>
+												<span className="text-foreground mt-1 block text-lg font-bold tabular-nums">
+													{vp.contacts.toLocaleString()}
+												</span>
+											</div>
+											<div className="bg-muted/20 rounded-lg p-3">
+												<span className="text-muted-foreground block text-[11px] font-medium uppercase tracking-wider">
+													Terminal
+												</span>
+												<span className="text-foreground mt-1 block text-lg font-bold tabular-nums">
+													{vp.terminalParticipants.toLocaleString()}
+												</span>
+												<span className="text-muted-foreground/70 text-[10px]">
+													{completionRate.toFixed(0)}% completed
+												</span>
+											</div>
+											<div className="bg-muted/20 rounded-lg p-3">
+												<span className="text-muted-foreground block text-[11px] font-medium uppercase tracking-wider">
+													Answered
+												</span>
+												<span className="text-foreground mt-1 block text-lg font-bold tabular-nums">
+													{vp.participantsWithAnswerClicks.toLocaleString()}
+												</span>
+												<span className="text-muted-foreground/70 text-[10px]">
+													{clickRate.toFixed(0)}% clicked
+												</span>
+											</div>
+											<div className="bg-muted/20 rounded-lg p-3">
+												<span className="text-muted-foreground block text-[11px] font-medium uppercase tracking-wider">
+													Drips
+												</span>
+												<span className="text-foreground mt-1 block text-lg font-bold tabular-nums">
+													{vp.dripEvents.toLocaleString()}
+												</span>
+											</div>
+											<div className="bg-muted/20 rounded-lg p-3">
+												<span className="text-muted-foreground block text-[11px] font-medium uppercase tracking-wider">
+													Blocked
+												</span>
+												<span className="text-foreground mt-1 block text-lg font-bold tabular-nums">
+													{vp.blockedIntents.toLocaleString()}
+												</span>
+											</div>
+										</div>
+
+										{vp.answerOptions.length > 0 && (
+											<div className="space-y-2">
+												<p className="text-muted-foreground text-[11px]">
+													Top answer choices by captured answer event
+												</p>
+												<div className="space-y-1.5">
+													{vp.answerOptions.slice(0, 8).map((answer) => {
+														const pct =
+															vp.answerEvents > 0
+																? (answer.count / vp.answerEvents) * 100
+																: 0
+														return (
+															<div
+																key={answer.key}
+																className="flex items-center gap-2.5"
+															>
+																<span
+																	className="text-muted-foreground w-[140px] shrink-0 truncate text-right text-[12px]"
+																	title={answer.key}
+																>
+																	{answer.optionValue}
+																</span>
+																<div className="bg-muted/50 relative h-5 flex-1 overflow-hidden rounded">
+																	<div
+																		className="absolute inset-y-0 left-0 rounded bg-sky-500/20"
+																		style={{ width: `${Math.max(pct, 1)}%` }}
+																	/>
+																	<div className="relative flex h-full items-center px-2">
+																		<span className="text-foreground/70 text-[11px] font-medium tabular-nums">
+																			{pct.toFixed(0)}%
+																		</span>
+																	</div>
+																</div>
+																<span className="text-muted-foreground w-10 shrink-0 text-right text-[11px] tabular-nums">
+																	{answer.count.toLocaleString()}
+																</span>
+															</div>
+														)
+													})}
+												</div>
+											</div>
+										)}
+									</>
+								)
+							})()}
+						</CardContent>
+					</Card>
+				)}
+
 				{/* ── Survey Segments ──────────────────────────────────────── */}
 				{hasSurveys && (
 					<Card>
@@ -1430,18 +1764,18 @@ export function OmnibusDashboard({
 													{p.totalAmount > 0 ? fmt$(p.totalAmount) : 'Free'}
 												</td>
 												<td className="py-2.5 pr-4 text-right text-sm tabular-nums">
-													{p.seats ?? '—'}
+													{p.seats ?? '-'}
 												</td>
 												<td className="max-w-[200px] truncate py-2.5 pr-4 text-sm font-medium">
 													{p.productName}
 												</td>
 												<td className="text-muted-foreground hidden max-w-[150px] truncate py-2.5 pr-4 text-sm sm:table-cell">
-													{p.userName ?? p.userEmail ?? '—'}
+													{p.userName ?? p.userEmail ?? '-'}
 												</td>
 												<td className="text-muted-foreground hidden py-2.5 pr-4 text-sm sm:table-cell">
 													{p.country
 														? `${countryFlag(p.country)} ${p.country}`
-														: '—'}
+														: '-'}
 												</td>
 												<td className="text-muted-foreground whitespace-nowrap py-2.5 pr-4 text-sm">
 													{fmtAgo(p.createdAt)}

package/src/engine.ts

@@ -5,6 +5,7 @@ import type {
 	QueryResult,
 	SurfaceMap,
 	SurfaceName,
+	TrafficAnalyticsRange,
 } from './types'
 
 export type AnalyticsProvider = Record<
@@ -14,7 +15,7 @@ export type AnalyticsProvider = Record<
 
 export type ProviderMap = Record<string, AnalyticsProvider>
 
-function toGA4Range(range: AnalyticsRange): '24h' | '7d' | '30d' | '90d' {
+function toGA4Range(range: AnalyticsRange): TrafficAnalyticsRange {
 	if (range === 'all') return '90d'
 	return range
 }
@@ -27,9 +28,10 @@ function toYouTubeRange(range: AnalyticsRange): '24h' | '7d' | '30d' | '90d' {
 async function invokeSurface<S extends SurfaceName>(
 	providers: ProviderMap,
 	surface: S,
-	range: AnalyticsRange,
-	limit: number,
+	options: Required<Pick<QueryOptions, 'range' | 'limit' | 'offset'>> &
+		Omit<QueryOptions, 'range' | 'limit' | 'offset'>,
 ): Promise<SurfaceMap[S] | null> {
+	const { range, limit, offset } = options
 	const entry = catalog[surface]
 	const provider = providers[entry.provider]
 
@@ -70,7 +72,7 @@ async function invokeSurface<S extends SurfaceName>(
 		case 'traffic/pages':
 		case 'traffic/sources': {
 			const fn = provider[entry.fn] as (
-				range: '24h' | '7d' | '30d' | '90d',
+				range: TrafficAnalyticsRange,
 				limit?: number,
 			) => Promise<SurfaceMap[S]>
 			if (surface === 'traffic/pages' || surface === 'traffic/sources') {
@@ -86,22 +88,71 @@ async function invokeSurface<S extends SurfaceName>(
 			) => Promise<SurfaceMap[S]>
 			return fn(range)
 		}
-		case 'attribution/email-campaigns': {
+		case 'attribution/sources':
+		case 'attribution/coverage':
+		case 'attribution/commerce-lanes': {
+			const fn = provider[entry.fn] as (
+				range: AnalyticsRange,
+				filters?: Pick<QueryOptions, 'productId'>,
+			) => Promise<SurfaceMap[S]>
+			return fn(range, { productId: options.productId })
+		}
+		case 'attribution/email-campaigns':
+		case 'attribution/email-campaigns/strict': {
+			const fn = provider[entry.fn] as (
+				range: AnalyticsRange,
+				limit?: number,
+				filters?: Pick<QueryOptions, 'productId'>,
+			) => Promise<SurfaceMap[S]>
+			return fn(range, limit, { productId: options.productId })
+		}
+		case 'attribution/checkout-receipt': {
+			const fn = provider[entry.fn] as (
+				filters: Pick<QueryOptions, 'purchaseId'>,
+			) => Promise<SurfaceMap[S]>
+			return fn({ purchaseId: options.purchaseId })
+		}
+		case 'attribution/checkout-survey-fallback': {
 			const fn = provider[entry.fn] as (
 				range: AnalyticsRange,
 				limit?: number,
+				filters?: Pick<QueryOptions, 'productId'>,
+			) => Promise<SurfaceMap[S]>
+			return fn(range, limit, { productId: options.productId })
+		}
+		case 'surveys/questions': {
+			const fn = provider[entry.fn] as (
+				range: AnalyticsRange,
+				limit: number,
 			) => Promise<SurfaceMap[S]>
 			return fn(range, limit)
 		}
-		case 'surveys/questions':
 		case 'surveys/responses': {
 			const fn = provider[entry.fn] as (
 				range: AnalyticsRange,
 				limit: number,
+				offset: number,
 			) => Promise<SurfaceMap[S]>
-			return fn(range, limit)
+			return fn(range, limit, offset)
 		}
 		default: {
+			if (surface === 'correlation/survey-revenue/product') {
+				const productSurveyFn = provider[entry.fn] as (
+					range: AnalyticsRange,
+					limit?: number,
+					filters?: Pick<
+						QueryOptions,
+						'productId' | 'surveyId' | 'surveySlug' | 'questionId'
+					>,
+				) => Promise<SurfaceMap[S] | null>
+				return productSurveyFn(range, limit, {
+					productId: options.productId,
+					surveyId: options.surveyId,
+					surveySlug: options.surveySlug,
+					questionId: options.questionId,
+				})
+			}
+
 			const fn = provider[entry.fn] as (
 				range: AnalyticsRange,
 				limit?: number,
@@ -132,11 +183,21 @@ export function createAnalyticsEngine(providers: ProviderMap) {
 	): Promise<QueryResult<S>> {
 		const range = options?.range ?? '30d'
 		const limit = options?.limit ?? 20
+		const offset = options?.offset ?? 0
 		const entry = catalog[surface]
 		const startMs = Date.now()
 
 		try {
-			const data = await invokeSurface(providers, surface, range, limit)
+			const data = await invokeSurface(providers, surface, {
+				range,
+				limit,
+				offset,
+				productId: options?.productId,
+				purchaseId: options?.purchaseId,
+				surveyId: options?.surveyId,
+				surveySlug: options?.surveySlug,
+				questionId: options?.questionId,
+			})
 
 			if (data === null) {
 				return {

package/src/providers/attribution-recovery.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+	classifyPurchaseAttribution,
+	hasExactShortlinkPurchaseAttribution,
+	SHORTLINK_RECOVERY_LANE,
+} from './attribution-recovery'
+
+describe('attribution recovery classification', () => {
+	it('keeps purchase field attribution ahead of exact shortlink recovery', () => {
+		expect(
+			classifyPurchaseAttribution({
+				purchaseId: 'purch_1',
+				fields: { attribution: { source: 'email' } },
+				shortlinkAttributions: [
+					{
+						type: 'purchase',
+						metadata: JSON.stringify({ purchaseId: 'purch_1' }),
+					},
+				],
+			}),
+		).toBe('purchase_field')
+	})
+
+	it('recovers an otherwise dark purchase from exact shortlink metadata', () => {
+		expect(
+			classifyPurchaseAttribution({
+				purchaseId: 'purch_2',
+				fields: {},
+				shortlinkAttributions: [
+					{
+						type: 'purchase',
+						metadata: JSON.stringify({ purchaseId: 'purch_2' }),
+					},
+				],
+			}),
+		).toBe(SHORTLINK_RECOVERY_LANE)
+	})
+
+	it('ignores invalid shortlink attribution metadata', () => {
+		expect(
+			hasExactShortlinkPurchaseAttribution({
+				purchaseId: 'purch_3',
+				attributions: [{ type: 'purchase', metadata: '{not json' }],
+			}),
+		).toBe(false)
+	})
+
+	it('ignores non-matching shortlink attribution metadata', () => {
+		expect(
+			classifyPurchaseAttribution({
+				purchaseId: 'purch_4',
+				fields: {},
+				shortlinkAttributions: [
+					{
+						type: 'purchase',
+						metadata: JSON.stringify({ purchaseId: 'purch_other' }),
+					},
+				],
+			}),
+		).toBe('dark')
+	})
+})