@coursebuilder/analytics 1.1.0 → 1.1.1

package/src/components/omnibus-dashboard.tsx

@@ -17,6 +17,7 @@ import {
 	PlayIcon,
 	ShoppingCartIcon,
 	TrendingUpIcon,
+	RouteIcon,
 } from 'lucide-react'
 import { parseAsStringLiteral, useQueryState } from 'nuqs'
 
@@ -125,6 +126,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
@@ -661,6 +685,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 (
@@ -753,6 +778,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"
@@ -883,6 +916,136 @@ export function OmnibusDashboard({
 						</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>

package/src/engine.ts

@@ -27,9 +27,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]
 
@@ -86,22 +87,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 +182,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')
+	})
+})

package/src/providers/attribution-recovery.ts

@@ -0,0 +1,97 @@
+export const SHORTLINK_RECOVERY_LANE =
+	'recovered_from_shortlink_attribution_table' as const
+
+export type PurchaseAttributionClass =
+	| 'purchase_field'
+	| typeof SHORTLINK_RECOVERY_LANE
+	| 'dark'
+
+export interface ShortlinkAttributionEvidence {
+	type?: string | null
+	metadata?: unknown
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}
+
+function nonEmptyString(value: unknown) {
+	return typeof value === 'string' && value.trim().length > 0
+}
+
+function parseMetadata(value: unknown): Record<string, unknown> | null {
+	if (typeof value === 'string') {
+		try {
+			const parsed = JSON.parse(value) as unknown
+			return isRecord(parsed) ? parsed : null
+		} catch {
+			return null
+		}
+	}
+
+	return isRecord(value) ? value : null
+}
+
+/**
+ * Detects durable purchase-field attribution on a purchase fields object.
+ *
+ * @param fields Unknown purchase fields payload.
+ * @returns True when the purchase already has attribution, legacy UTM source, or legacy GA client ID evidence.
+ * @example
+ * hasPurchaseFieldAttribution({ attribution: { source: 'email' } })
+ */
+export function hasPurchaseFieldAttribution(fields: unknown) {
+	const record = isRecord(fields) ? fields : {}
+	const attribution = record.attribution
+
+	return Boolean(
+		(isRecord(attribution) && Object.keys(attribution).length > 0) ||
+		nonEmptyString(record.utmSource) ||
+		nonEmptyString(record.gaClientId),
+	)
+}
+
+/**
+ * Detects exact shortlink purchase evidence for one purchase.
+ *
+ * @param params.purchaseId Purchase ID that must match attribution metadata.purchaseId.
+ * @param params.attributions ShortlinkAttributionEvidence rows to inspect.
+ * @returns True only for purchase rows with valid JSON metadata and an exact purchase ID match.
+ */
+export function hasExactShortlinkPurchaseAttribution(params: {
+	purchaseId: string
+	attributions: readonly ShortlinkAttributionEvidence[]
+}) {
+	return params.attributions.some((attribution) => {
+		if (attribution.type !== 'purchase') return false
+		const metadata = parseMetadata(attribution.metadata)
+		return metadata?.purchaseId === params.purchaseId
+	})
+}
+
+/**
+ * Classifies purchase attribution with purchase fields taking precedence.
+ *
+ * @param params.purchaseId Purchase ID being classified.
+ * @param params.fields Purchase fields payload.
+ * @param params.shortlinkAttributions ShortlinkAttributionEvidence rows used as exact fallback evidence.
+ * @returns A PurchaseAttributionClass: 'purchase_field', SHORTLINK_RECOVERY_LANE, or 'dark'.
+ * @example
+ * classifyPurchaseAttribution({ purchaseId: 'p1', fields: {}, shortlinkAttributions: [] })
+ */
+export function classifyPurchaseAttribution(params: {
+	purchaseId: string
+	fields?: unknown
+	shortlinkAttributions?: readonly ShortlinkAttributionEvidence[]
+}): PurchaseAttributionClass {
+	if (hasPurchaseFieldAttribution(params.fields)) return 'purchase_field'
+	if (
+		hasExactShortlinkPurchaseAttribution({
+			purchaseId: params.purchaseId,
+			attributions: params.shortlinkAttributions ?? [],
+		})
+	) {
+		return SHORTLINK_RECOVERY_LANE
+	}
+	return 'dark'
+}