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

package/src/providers/database.ts

@@ -11,6 +11,8 @@ import {
 	sum,
 } from 'drizzle-orm'
 
+import { SHORTLINK_RECOVERY_LANE } from './attribution-recovery'
+
 // ─── Types ────────────────────────────────────────────────────────────────────
 
 export type AnalyticsTimeRange = '24h' | '7d' | '30d' | '90d' | 'all'
@@ -52,6 +54,9 @@ export interface DatabaseAnalyticsSchema {
 	shortlink: any
 	shortlinkAttribution: any
 	shortlinkClick: any
+	questionResponse?: any
+	contactEvent?: any
+	sideEffectIntent?: any
 }
 
 // ─── Factory ─────────────────────────────────────────────────────────────────
@@ -76,16 +81,97 @@ export function createDatabaseProvider(
 		shortlink,
 		shortlinkAttribution,
 		shortlinkClick,
+		questionResponse,
+		contactEvent,
+		sideEffectIntent,
 	} = schema
 
 	// ─── Internal helpers ───────────────────────────────────────────────────
 
 	const PAID_STATUSES = ['Valid', 'Restricted'] as const
 
-	function paidPurchase() {
+	function commerceRecord() {
 		return inArray(purchases.status, [...PAID_STATUSES])
 	}
 
+	function paidPurchase() {
+		return and(commerceRecord(), gt(purchases.totalAmount, 0))
+	}
+
+	function accessGrant() {
+		return and(commerceRecord(), sql`${purchases.totalAmount} = 0`)
+	}
+
+	function backfillFreeUpgrade() {
+		return and(
+			accessGrant(),
+			sql`JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.backfill')) = 'true'`,
+		)
+	}
+
+	const syntheticSignalSql = sql`(
+		JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.attribution.synthetic')) = 'true'
+		OR JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.synthetic')) = 'true'
+		OR JSON_SEARCH(JSON_EXTRACT(${purchases.fields}, '$.attribution.clickIds'), 'one', 'TEST_%') IS NOT NULL
+	)`
+
+	function syntheticPurchase() {
+		return and(commerceRecord(), syntheticSignalSql)
+	}
+
+	const purchaseFieldAttributionSignalSql = sql`(
+		JSON_EXTRACT(${purchases.fields}, '$.attribution') IS NOT NULL
+		OR JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.utmSource')) IS NOT NULL
+		OR JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.gaClientId')) IS NOT NULL
+	)`
+
+	const exactShortlinkPurchaseAttributionSignalSql = sql`EXISTS (
+		SELECT 1
+		FROM ${shortlinkAttribution}
+		WHERE ${shortlinkAttribution.type} = 'purchase'
+			AND JSON_VALID(${shortlinkAttribution.metadata})
+			AND JSON_UNQUOTE(JSON_EXTRACT(${shortlinkAttribution.metadata}, '$.purchaseId')) = ${purchases.id}
+	)`
+
+	const shortlinkRecoveredAttributionSignalSql = sql`(
+		NOT ${purchaseFieldAttributionSignalSql}
+		AND ${exactShortlinkPurchaseAttributionSignalSql}
+	)`
+
+	const attributionSignalSql = sql`(
+		${purchaseFieldAttributionSignalSql}
+		OR ${exactShortlinkPurchaseAttributionSignalSql}
+	)`
+
+	const strongAttributionQualitySql = sql`(
+		JSON_EXTRACT(${purchases.fields}, '$.attribution.clickIds') IS NOT NULL
+		OR JSON_EXTRACT(${purchases.fields}, '$.attribution.utm') IS NOT NULL
+		OR JSON_EXTRACT(${purchases.fields}, '$.attribution.shortlink') IS NOT NULL
+		OR JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.utmSource')) IS NOT NULL
+		OR JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.shortlinkRef')) IS NOT NULL
+	)`
+
+	const mediumAttributionQualitySql = sql`(
+		NOT ${strongAttributionQualitySql}
+		AND ${exactShortlinkPurchaseAttributionSignalSql}
+	)`
+
+	const weakAttributionQualitySql = sql`(
+		NOT ${strongAttributionQualitySql}
+		AND NOT ${exactShortlinkPurchaseAttributionSignalSql}
+		AND (
+			JSON_EXTRACT(${purchases.fields}, '$.attribution.ga.clientId') IS NOT NULL
+			OR JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.gaClientId')) IS NOT NULL
+			OR JSON_EXTRACT(${purchases.fields}, '$.attribution.selfReportedSource') IS NOT NULL
+		)
+	)`
+
+	const unknownAttributionQualitySql = sql`(
+		NOT ${strongAttributionQualitySql}
+		AND NOT ${mediumAttributionQualitySql}
+		AND NOT ${weakAttributionQualitySql}
+	)`
+
 	function rangeToDate(range: AnalyticsTimeRange): Date | null {
 		if (range === 'all') return null
 		const now = new Date()
@@ -403,38 +489,88 @@ export function createDatabaseProvider(
 
 	// ─── Revenue Attribution ─────────────────────────────────────────────────
 
-	async function getRevenueBySource(range: AnalyticsTimeRange = '30d') {
+	async function getRevenueBySource(
+		range: AnalyticsTimeRange = '30d',
+		filters: { productId?: string } = {},
+	) {
 		const since = rangeToDate(range)
-		const conditions = [paidPurchase()]
+		const conditions = [commerceRecord()]
 		if (since) conditions.push(gte(purchases.createdAt, since))
+		if (filters.productId)
+			conditions.push(eq(purchases.productId, filters.productId))
+
+		const kindExpr = sql<string>`CASE
+			WHEN ${syntheticSignalSql} THEN 'synthetic'
+			WHEN ${purchases.totalAmount} = 0 THEN 'access_grant'
+			WHEN ${purchases.totalAmount} > 0 THEN 'paid_conversion'
+			ELSE 'unknown'
+		END`
+		const sourceExpr = sql<string>`CASE
+			WHEN JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.backfill')) = 'true'
+				THEN 'internal'
+			WHEN ${shortlinkRecoveredAttributionSignalSql} THEN ${SHORTLINK_RECOVERY_LANE}
+			ELSE COALESCE(
+				NULLIF(JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.attribution.source')), 'null'),
+				NULLIF(JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.attribution.utm.source')), 'null'),
+				NULLIF(JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.utmSource')), 'null'),
+				CASE
+					WHEN JSON_EXTRACT(${purchases.fields}, '$.attribution.shortlink.slug') IS NOT NULL THEN 'shortlink'
+					WHEN JSON_EXTRACT(${purchases.fields}, '$.attribution.selfReportedSource') IS NOT NULL THEN 'self_reported'
+					WHEN JSON_EXTRACT(${purchases.fields}, '$.attribution.ga.clientId') IS NOT NULL THEN 'ga4'
+					WHEN JSON_EXTRACT(${purchases.fields}, '$.gaClientId') IS NOT NULL THEN 'ga4'
+					ELSE NULL
+				END
+			)
+		END`
+		const mediumExpr = sql<string>`CASE
+			WHEN JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.backfill')) = 'true'
+				THEN 'free_upgrade'
+			WHEN ${shortlinkRecoveredAttributionSignalSql} THEN 'shortlink'
+			ELSE COALESCE(
+				NULLIF(JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.attribution.medium')), 'null'),
+				NULLIF(JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.attribution.utm.medium')), 'null'),
+				NULLIF(JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.utmMedium')), 'null'),
+				CASE
+					WHEN JSON_EXTRACT(${purchases.fields}, '$.attribution.shortlink.slug') IS NOT NULL THEN 'shortlink'
+					WHEN JSON_EXTRACT(${purchases.fields}, '$.attribution.selfReportedSource') IS NOT NULL THEN 'checkout_survey'
+					WHEN JSON_EXTRACT(${purchases.fields}, '$.attribution.ga.clientId') IS NOT NULL THEN 'client_id'
+					WHEN JSON_EXTRACT(${purchases.fields}, '$.gaClientId') IS NOT NULL THEN 'client_id'
+					ELSE NULL
+				END
+			)
+		END`
+		const campaignExpr = sql<string>`CASE
+			WHEN JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.backfill')) = 'true'
+				THEN COALESCE(
+					NULLIF(JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.migrationBatchId')), 'null'),
+					'free_upgrade'
+				)
+			WHEN ${shortlinkRecoveredAttributionSignalSql} THEN NULL
+			ELSE COALESCE(
+				NULLIF(JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.attribution.campaign')), 'null'),
+				NULLIF(JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.attribution.utm.campaign')), 'null'),
+				NULLIF(JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.utmCampaign')), 'null'),
+				NULLIF(JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.attribution.shortlink.slug')), 'null'),
+				NULLIF(JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.attribution.selfReportedSource')), 'null')
+			)
+		END`
 
 		const rows = await db
 			.select({
-				source:
-					sql<string>`JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.utmSource'))`.as(
-						'source',
-					),
-				medium:
-					sql<string>`JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.utmMedium'))`.as(
-						'medium',
-					),
-				campaign:
-					sql<string>`JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.utmCampaign'))`.as(
-						'campaign',
-					),
+				kind: kindExpr.as('kind'),
+				source: sourceExpr.as('source'),
+				medium: mediumExpr.as('medium'),
+				campaign: campaignExpr.as('campaign'),
 				revenue: sum(purchases.totalAmount),
 				count: count(),
 			})
 			.from(purchases)
 			.where(and(...conditions))
-			.groupBy(
-				sql`JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.utmSource'))`,
-				sql`JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.utmMedium'))`,
-				sql`JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.utmCampaign'))`,
-			)
-			.orderBy(desc(sum(purchases.totalAmount)))
+			.groupBy(sql`1`, sql`2`, sql`3`, sql`4`)
+			.orderBy(desc(sum(purchases.totalAmount)), desc(count()))
 
 		return rows.map((r: any) => ({
+			kind: r.kind ?? 'unknown',
 			source: r.source ?? null,
 			medium: r.medium ?? null,
 			campaign: r.campaign ?? null,
@@ -463,15 +599,7 @@ export function createDatabaseProvider(
 		const [attributedCount] = await db
 			.select({ total: count() })
 			.from(purchases)
-			.where(
-				and(
-					...purchaseConditions,
-					sql`(
-            JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.utmSource')) IS NOT NULL
-            OR JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.gaClientId')) IS NOT NULL
-          )`,
-				),
-			)
+			.where(and(...purchaseConditions, attributionSignalSql))
 
 		const totalSignups = userCount?.total ?? 0
 		const totalPurchases = purchaseCount?.total ?? 0
@@ -487,12 +615,76 @@ export function createDatabaseProvider(
 		}
 	}
 
+	async function getCommerceLaneSummary(
+		range: AnalyticsTimeRange = '30d',
+		filters: { productId?: string } = {},
+	) {
+		const since = rangeToDate(range)
+		const conditions = [commerceRecord()]
+		if (since) conditions.push(gte(purchases.createdAt, since))
+		if (filters.productId)
+			conditions.push(eq(purchases.productId, filters.productId))
+
+		const [commerce] = await db
+			.select({ count: count() })
+			.from(purchases)
+			.where(and(...conditions))
+		const [paid] = await db
+			.select({ count: count(), revenue: sum(purchases.totalAmount) })
+			.from(purchases)
+			.where(and(...conditions, paidPurchase()))
+		const [grants] = await db
+			.select({ count: count(), revenue: sum(purchases.totalAmount) })
+			.from(purchases)
+			.where(and(...conditions, accessGrant()))
+		const [freeUpgrades] = await db
+			.select({ count: count() })
+			.from(purchases)
+			.where(and(...conditions, backfillFreeUpgrade()))
+		const [synthetic] = await db
+			.select({ count: count() })
+			.from(purchases)
+			.where(and(...conditions, syntheticPurchase()))
+		const reasonRows = await db
+			.select({
+				reason: sql<string>`COALESCE(
+					NULLIF(JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.backfillReason')), 'null'),
+					'access_grant'
+				)`.as('reason'),
+				count: count(),
+			})
+			.from(purchases)
+			.where(and(...conditions, accessGrant()))
+			.groupBy(
+				sql`COALESCE(
+					NULLIF(JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.backfillReason')), 'null'),
+					'access_grant'
+				)`,
+			)
+
+		return {
+			commerceRecords: commerce?.count ?? 0,
+			paidPurchases: paid?.count ?? 0,
+			paidRevenue: Number(paid?.revenue ?? 0),
+			accessGrants: grants?.count ?? 0,
+			accessGrantRevenue: Number(grants?.revenue ?? 0),
+			freeUpgrades: freeUpgrades?.count ?? 0,
+			syntheticPurchases: synthetic?.count ?? 0,
+			byAccessGrantReason: Object.fromEntries(
+				reasonRows.map((row: any) => [row.reason, row.count]),
+			),
+		}
+	}
+
 	async function getAttributedRevenueSummary(
 		range: AnalyticsTimeRange = '30d',
+		filters: { productId?: string } = {},
 	) {
 		const since = rangeToDate(range)
 		const conditions = [paidPurchase()]
 		if (since) conditions.push(gte(purchases.createdAt, since))
+		if (filters.productId)
+			conditions.push(eq(purchases.productId, filters.productId))
 
 		const [totals] = await db
 			.select({ total: sum(purchases.totalAmount), count: count() })
@@ -500,29 +692,146 @@ export function createDatabaseProvider(
 			.where(and(...conditions))
 
 		const [attributed] = await db
-			.select({ total: sum(purchases.totalAmount) })
+			.select({ total: sum(purchases.totalAmount), count: count() })
 			.from(purchases)
-			.where(
-				and(
-					...conditions,
-					sql`(
-            JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.utmSource')) IS NOT NULL
-            OR JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.gaClientId')) IS NOT NULL
-          )`,
-				),
-			)
+			.where(and(...conditions, attributionSignalSql))
+
+		const [purchaseFieldAttributed] = await db
+			.select({ total: sum(purchases.totalAmount), count: count() })
+			.from(purchases)
+			.where(and(...conditions, purchaseFieldAttributionSignalSql))
+
+		const [recoveredFromShortlinkAttributionTable] = await db
+			.select({ total: sum(purchases.totalAmount), count: count() })
+			.from(purchases)
+			.where(and(...conditions, shortlinkRecoveredAttributionSignalSql))
 
+		const signalConditions = since
+			? [commerceRecord(), gte(purchases.createdAt, since)]
+			: [commerceRecord()]
+		if (filters.productId) {
+			signalConditions.push(eq(purchases.productId, filters.productId))
+		}
+		const signalCount = async (condition: any) => {
+			const [row] = await db
+				.select({ count: count() })
+				.from(purchases)
+				.where(and(...signalConditions, condition))
+			return row?.count ?? 0
+		}
+		const qualityLane = async (
+			lane: 'strong' | 'medium' | 'weak' | 'unknown',
+			condition: any,
+			notes: string[],
+		) => {
+			const [row] = await db
+				.select({ total: sum(purchases.totalAmount), count: count() })
+				.from(purchases)
+				.where(and(...conditions, condition))
+			const revenue = Number(row?.total ?? 0)
+			return {
+				lane,
+				purchases: row?.count ?? 0,
+				revenue,
+				revenuePercent: totalRevenue > 0 ? revenue / totalRevenue : 0,
+				notes,
+			}
+		}
+		const [
+			shortlinkCount,
+			utmCount,
+			clickIdCount,
+			gaClientIdCount,
+			selfReportedSourceCount,
+			recoveredFromShortlinkAttributionTableCount,
+		] = await Promise.all([
+			signalCount(
+				sql`(
+						JSON_EXTRACT(${purchases.fields}, '$.attribution.shortlink.slug') IS NOT NULL
+						OR JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.shortlinkRef')) IS NOT NULL
+					)`,
+			),
+			signalCount(
+				sql`(
+						JSON_EXTRACT(${purchases.fields}, '$.attribution.utm') IS NOT NULL
+						OR JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.utmSource')) IS NOT NULL
+					)`,
+			),
+			signalCount(
+				sql`JSON_EXTRACT(${purchases.fields}, '$.attribution.clickIds') IS NOT NULL`,
+			),
+			signalCount(
+				sql`(
+						JSON_EXTRACT(${purchases.fields}, '$.attribution.ga.clientId') IS NOT NULL
+						OR JSON_UNQUOTE(JSON_EXTRACT(${purchases.fields}, '$.gaClientId')) IS NOT NULL
+					)`,
+			),
+			signalCount(
+				sql`JSON_EXTRACT(${purchases.fields}, '$.attribution.selfReportedSource') IS NOT NULL`,
+			),
+			signalCount(shortlinkRecoveredAttributionSignalSql),
+		])
+
+		const commerce = await getCommerceLaneSummary(range, filters)
 		const totalRevenue = Number(totals?.total ?? 0)
 		const attributedRevenue = Number(attributed?.total ?? 0)
+		const purchaseFieldAttributedRevenue = Number(
+			purchaseFieldAttributed?.total ?? 0,
+		)
+		const recoveredFromShortlinkAttributionTableRevenue = Number(
+			recoveredFromShortlinkAttributionTable?.total ?? 0,
+		)
 		const unattributedRevenue = totalRevenue - attributedRevenue
-		const totalPurchases = totals?.count ?? 0
+		const paidPurchases = totals?.count ?? 0
+		const [strongQuality, mediumQuality, weakQuality, unknownQuality] =
+			await Promise.all([
+				qualityLane('strong', strongAttributionQualitySql, [
+					'Purchase-field UTM, shortlink, or paid click evidence.',
+				]),
+				qualityLane('medium', mediumAttributionQualitySql, [
+					'Recovered from exact shortlink attribution table purchase match.',
+				]),
+				qualityLane('weak', weakAttributionQualitySql, [
+					'GA client ID or self-reported source without stronger campaign evidence.',
+				]),
+				qualityLane('unknown', unknownAttributionQualitySql, [
+					'No usable attribution evidence for paid revenue.',
+				]),
+			])
 
 		return {
 			totalRevenue,
 			attributedRevenue,
 			unattributedRevenue,
 			attributionRate: totalRevenue > 0 ? attributedRevenue / totalRevenue : 0,
-			totalPurchases,
+			totalPurchases: commerce.commerceRecords,
+			paidPurchases,
+			purchaseFieldAttributedPurchases: purchaseFieldAttributed?.count ?? 0,
+			purchaseFieldAttributedRevenue,
+			recoveredFromShortlinkAttributionTablePurchases:
+				recoveredFromShortlinkAttributionTable?.count ?? 0,
+			recoveredFromShortlinkAttributionTableRevenue,
+			commerceRecords: commerce.commerceRecords,
+			accessGrants: commerce.accessGrants,
+			freeUpgrades: commerce.freeUpgrades,
+			syntheticPurchases: commerce.syntheticPurchases,
+			commerce,
+			signals: {
+				shortlink: shortlinkCount,
+				utm: utmCount,
+				paidClickId: clickIdCount,
+				gaClientId: gaClientIdCount,
+				selfReportedSource: selfReportedSourceCount,
+				recoveredFromShortlinkAttributionTable:
+					recoveredFromShortlinkAttributionTableCount,
+				internalFreeUpgrade: commerce.freeUpgrades,
+			},
+			quality: {
+				strong: strongQuality,
+				medium: mediumQuality,
+				weak: weakQuality,
+				unknown: unknownQuality,
+			},
 		}
 	}
 
@@ -567,6 +876,363 @@ export function createDatabaseProvider(
 		}))
 	}
 
+	/**
+	 * Parses an unknown JSON-like value into a plain record.
+	 *
+	 * @param value Unknown input value from a JSON database column.
+	 * @returns A Record<string, any> when the value is a record, otherwise an empty object.
+	 */
+	function parseJsonRecord(value: unknown): Record<string, any> {
+		return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+			? (value as Record<string, any>)
+			: {}
+	}
+
+	/**
+	 * Checks whether a record contains at least one non-empty string value.
+	 *
+	 * @param value Unknown input value to inspect.
+	 * @returns True when at least one record value is a non-empty string.
+	 */
+	function hasRecordValue(value: unknown) {
+		return (
+			Boolean(value) &&
+			typeof value === 'object' &&
+			!Array.isArray(value) &&
+			Object.values(value as Record<string, unknown>).some(
+				(entry) => typeof entry === 'string' && entry.length > 0,
+			)
+		)
+	}
+
+	/**
+	 * Checks whether a click ID record contains a synthetic TEST_ value.
+	 *
+	 * @param value Unknown input value to inspect.
+	 * @returns True when any record value is a string starting with TEST_.
+	 */
+	function hasSyntheticClickId(value: unknown) {
+		return (
+			Boolean(value) &&
+			typeof value === 'object' &&
+			!Array.isArray(value) &&
+			Object.values(value as Record<string, unknown>).some(
+				(entry) => typeof entry === 'string' && entry.startsWith('TEST_'),
+			)
+		)
+	}
+
+	async function getCheckoutAttributionReceipt(opts: { purchaseId?: string }) {
+		if (!opts.purchaseId) {
+			return {
+				purchase: null,
+				checks: {
+					purchaseFound: false,
+					attributionSnapshot: false,
+					utm: false,
+					actualUtm: false,
+					clickId: false,
+					synthetic: false,
+					shortlink: false,
+					selfReportedSource: false,
+					gaClientId: false,
+				},
+				attribution: null,
+				legacy: {},
+				fieldKeys: [],
+			}
+		}
+
+		const [row] = await db
+			.select({
+				id: purchases.id,
+				createdAt: purchases.createdAt,
+				productId: purchases.productId,
+				productName: products.name,
+				totalAmount: purchases.totalAmount,
+				status: purchases.status,
+				country: purchases.country,
+				fields: purchases.fields,
+			})
+			.from(purchases)
+			.leftJoin(products, eq(purchases.productId, products.id))
+			.where(eq(purchases.id, opts.purchaseId))
+			.limit(1)
+
+		if (!row) {
+			return {
+				purchase: null,
+				checks: {
+					purchaseFound: false,
+					attributionSnapshot: false,
+					utm: false,
+					actualUtm: false,
+					clickId: false,
+					synthetic: false,
+					shortlink: false,
+					selfReportedSource: false,
+					gaClientId: false,
+				},
+				attribution: null,
+				legacy: {},
+				fieldKeys: [],
+			}
+		}
+
+		const fields = parseJsonRecord(row.fields)
+		const attribution = parseJsonRecord(fields.attribution)
+		const utm = parseJsonRecord(attribution.utm)
+		const clickIds = parseJsonRecord(attribution.clickIds)
+		const shortlinkSnapshot = parseJsonRecord(attribution.shortlink)
+		const ga = parseJsonRecord(attribution.ga)
+		const legacy = Object.fromEntries(
+			[
+				'utmSource',
+				'utmMedium',
+				'utmCampaign',
+				'gaClientId',
+				'shortlinkRef',
+				'landingPath',
+				'referrer',
+				'ltUtmSource',
+				'ltUtmMedium',
+				'ltUtmCampaign',
+			]
+				.map((key) => [key, fields[key]])
+				.filter(([, value]) => value !== undefined && value !== null),
+		)
+		const hasActualUtm = Boolean(
+			utm.source || utm.medium || utm.campaign || fields.utmSource,
+		)
+		const synthetic = Boolean(
+			attribution.synthetic ||
+			fields.synthetic ||
+			hasSyntheticClickId(clickIds),
+		)
+
+		return {
+			purchase: {
+				id: row.id,
+				createdAt: row.createdAt,
+				productId: row.productId,
+				productName: row.productName ?? null,
+				totalAmount: Number(row.totalAmount ?? 0),
+				status: row.status,
+				country: row.country,
+			},
+			checks: {
+				purchaseFound: true,
+				attributionSnapshot: Object.keys(attribution).length > 0,
+				utm: hasActualUtm,
+				actualUtm: hasActualUtm,
+				clickId: hasRecordValue(clickIds),
+				synthetic,
+				shortlink: Boolean(shortlinkSnapshot.slug || fields.shortlinkRef),
+				selfReportedSource: Boolean(attribution.selfReportedSource),
+				gaClientId: Boolean(ga.clientId || fields.gaClientId),
+			},
+			attribution: Object.keys(attribution).length > 0 ? attribution : null,
+			legacy,
+			fieldKeys: Object.keys(fields).sort(),
+		}
+	}
+
+	async function getCheckoutSurveyFallbackReport(
+		range: AnalyticsTimeRange = '30d',
+		limit: number = 20,
+		filters: { productId?: string } = {},
+	) {
+		const label = 'recovered_from_checkout_survey_response'
+		if (!questionResponse) {
+			return {
+				label,
+				productId: filters.productId ?? null,
+				totalDarkPurchases: 0,
+				totalDarkRevenue: 0,
+				exactPurchaseLinkedPurchases: 0,
+				exactPurchaseLinkedRevenue: 0,
+				userLinkedPurchases: 0,
+				userLinkedRevenue: 0,
+				byAnswer: [],
+				notes: ['questionResponse table was not provided to this provider'],
+			}
+		}
+
+		const since = rangeToDate(range)
+		const purchaseConditions = [
+			paidPurchase(),
+			sql`NOT ${attributionSignalSql}`,
+		]
+		if (since) purchaseConditions.push(gte(purchases.createdAt, since))
+		if (filters.productId) {
+			purchaseConditions.push(eq(purchases.productId, filters.productId))
+		}
+
+		const darkRows = await db
+			.select({
+				id: purchases.id,
+				userId: purchases.userId,
+				revenue: purchases.totalAmount,
+			})
+			.from(purchases)
+			.where(and(...purchaseConditions))
+
+		const totalDarkRevenue = darkRows.reduce(
+			(total: number, row: any) => total + Number(row.revenue ?? 0),
+			0,
+		)
+
+		if (darkRows.length === 0) {
+			return {
+				label,
+				productId: filters.productId ?? null,
+				totalDarkPurchases: 0,
+				totalDarkRevenue: 0,
+				exactPurchaseLinkedPurchases: 0,
+				exactPurchaseLinkedRevenue: 0,
+				userLinkedPurchases: 0,
+				userLinkedRevenue: 0,
+				byAnswer: [],
+				notes: ['No dark paid purchases matched the filters'],
+			}
+		}
+
+		const darkById = new Map<string, (typeof darkRows)[number]>(
+			darkRows.map((row: (typeof darkRows)[number]) => [row.id, row]),
+		)
+		const darkByUserId = new Map<string, any[]>()
+		for (const row of darkRows) {
+			if (!row.userId) continue
+			const bucket = darkByUserId.get(row.userId) ?? []
+			bucket.push(row)
+			darkByUserId.set(row.userId, bucket)
+		}
+
+		const responseConditions: any[] = []
+		if (since) responseConditions.push(gte(questionResponse.createdAt, since))
+		const darkIds = [...darkById.keys()]
+		const darkUserIds = [...darkByUserId.keys()]
+		const exactPurchaseCondition = sql`JSON_UNQUOTE(JSON_EXTRACT(${questionResponse.fields}, '$.purchaseId')) IN (${sql.join(
+			darkIds.map((id) => sql`${id}`),
+			sql`, `,
+		)})`
+		const userCondition =
+			darkUserIds.length > 0
+				? sql`${questionResponse.userId} IN (${sql.join(
+						darkUserIds.map((id) => sql`${id}`),
+						sql`, `,
+					)})`
+				: sql`FALSE`
+		responseConditions.push(
+			sql`(${exactPurchaseCondition} OR ${userCondition})`,
+		)
+
+		const responseRows = await db
+			.select({
+				purchaseId: sql<string>`JSON_UNQUOTE(JSON_EXTRACT(${questionResponse.fields}, '$.purchaseId'))`,
+				answer: sql<string>`JSON_UNQUOTE(JSON_EXTRACT(${questionResponse.fields}, '$.answer'))`,
+				userId: questionResponse.userId,
+				createdAt: questionResponse.createdAt,
+			})
+			.from(questionResponse)
+			.where(and(...responseConditions))
+
+		const exactByPurchase = new Map<string, any>()
+		const latestByUser = new Map<string, any>()
+		for (const row of responseRows) {
+			if (row.purchaseId && darkById.has(row.purchaseId)) {
+				exactByPurchase.set(row.purchaseId, row)
+				continue
+			}
+			if (!row.userId) continue
+			const current = latestByUser.get(row.userId)
+			const rowTime = new Date(row.createdAt ?? 0).getTime()
+			const currentTime = current
+				? new Date(current.createdAt ?? 0).getTime()
+				: -1
+			if (!current || rowTime >= currentTime) latestByUser.set(row.userId, row)
+		}
+
+		const classified = new Map<
+			string,
+			{
+				confidence: 'exact_purchase_link' | 'user_linked'
+				answer: string
+				revenue: number
+			}
+		>()
+		for (const [purchaseId, response] of exactByPurchase) {
+			const purchase = darkById.get(purchaseId)
+			classified.set(purchaseId, {
+				confidence: 'exact_purchase_link',
+				answer: response.answer || '(no answer)',
+				revenue: Number(purchase?.revenue ?? 0),
+			})
+		}
+		for (const row of darkRows) {
+			if (classified.has(row.id) || !row.userId) continue
+			const response = latestByUser.get(row.userId)
+			if (!response) continue
+			classified.set(row.id, {
+				confidence: 'user_linked',
+				answer: response.answer || '(no answer)',
+				revenue: Number(row.revenue ?? 0),
+			})
+		}
+
+		const byAnswer = new Map<
+			string,
+			{
+				answer: string
+				confidence: 'exact_purchase_link' | 'user_linked'
+				purchases: number
+				revenue: number
+			}
+		>()
+		let exactPurchaseLinkedPurchases = 0
+		let exactPurchaseLinkedRevenue = 0
+		let userLinkedPurchases = 0
+		let userLinkedRevenue = 0
+		for (const entry of classified.values()) {
+			if (entry.confidence === 'exact_purchase_link') {
+				exactPurchaseLinkedPurchases += 1
+				exactPurchaseLinkedRevenue += entry.revenue
+			} else {
+				userLinkedPurchases += 1
+				userLinkedRevenue += entry.revenue
+			}
+			const key = `${entry.confidence}:${entry.answer}`
+			const current = byAnswer.get(key) ?? {
+				answer: entry.answer,
+				confidence: entry.confidence,
+				purchases: 0,
+				revenue: 0,
+			}
+			current.purchases += 1
+			current.revenue += entry.revenue
+			byAnswer.set(key, current)
+		}
+
+		return {
+			label,
+			productId: filters.productId ?? null,
+			totalDarkPurchases: darkRows.length,
+			totalDarkRevenue,
+			exactPurchaseLinkedPurchases,
+			exactPurchaseLinkedRevenue,
+			userLinkedPurchases,
+			userLinkedRevenue,
+			byAnswer: [...byAnswer.values()]
+				.sort((a, b) => b.revenue - a.revenue || b.purchases - a.purchases)
+				.slice(0, limit),
+			notes: [
+				'Report-only fallback. No purchase fields are mutated.',
+				'Exact purchase-linked responses use QuestionResponse.fields.purchaseId when present.',
+				'User-linked responses are lower-confidence and remain report-only.',
+			],
+		}
+	}
+
 	// ─── Attribution Trail ───────────────────────────────────────────────────
 
 	/**
@@ -574,6 +1240,174 @@ export function createDatabaseProvider(
 	 * Walks: ShortlinkClick → ShortlinkAttribution (signup) →
 	 *        ResourceProgress → Purchase
 	 */
+
+	async function getValuePathSummary(range: AnalyticsTimeRange = '30d') {
+		if (!contactEvent || !sideEffectIntent) {
+			return {
+				contacts: 0,
+				events: 0,
+				intents: 0,
+				completedIntents: 0,
+				pendingIntents: 0,
+				blockedIntents: 0,
+				answerEvents: 0,
+				dripEvents: 0,
+				enteredEvents: 0,
+				participantsWithAnswerClicks: 0,
+				participantsWithNoAnswerClicks: 0,
+				terminalParticipants: 0,
+				answerOptions: [],
+				answerSteps: [],
+				terminalSteps: [],
+				notes: ['Contact Event and SideEffectIntent tables are unavailable.'],
+			}
+		}
+
+		const since = rangeToDate(range)
+		const eventConditions = [sql`${contactEvent.eventType} LIKE 'value-path.%'`]
+		const intentConditions = [
+			eq(sideEffectIntent.type, 'send-value-path-email'),
+		]
+		if (since) {
+			eventConditions.push(gte(contactEvent.occurredAt, since))
+			intentConditions.push(gte(sideEffectIntent.createdAt, since))
+		}
+
+		const [events, intents] = await Promise.all([
+			db
+				.select({
+					contactId: contactEvent.contactId,
+					eventType: contactEvent.eventType,
+					providerEventId: contactEvent.providerEventId,
+					occurredAt: contactEvent.occurredAt,
+				})
+				.from(contactEvent)
+				.where(and(...eventConditions)),
+			db
+				.select({
+					contactId: sideEffectIntent.contactId,
+					status: sideEffectIntent.status,
+					metadata: sideEffectIntent.metadata,
+					createdAt: sideEffectIntent.createdAt,
+				})
+				.from(sideEffectIntent)
+				.where(and(...intentConditions)),
+		])
+
+		const contactIds = new Set<string>()
+		for (const event of events) contactIds.add(event.contactId)
+		for (const intent of intents) contactIds.add(intent.contactId)
+
+		const answerEvents = events.filter(
+			(event: any) => event.eventType === 'value-path.answer-selected',
+		)
+		const dripEvents = events.filter(
+			(event: any) => event.eventType === 'value-path.drip-progressed',
+		)
+		const enteredEvents = events.filter(
+			(event: any) => event.eventType === 'value-path.entered',
+		)
+
+		const answersByContact = new Map<string, number>()
+		for (const event of answerEvents) {
+			answersByContact.set(
+				event.contactId,
+				(answersByContact.get(event.contactId) ?? 0) + 1,
+			)
+		}
+
+		const answerKeyCounts = new Map<string, number>()
+		const answerStepCounts = new Map<string, number>()
+		for (const event of answerEvents) {
+			const key = parseValuePathAnswerKey(event.providerEventId)
+			answerKeyCounts.set(key, (answerKeyCounts.get(key) ?? 0) + 1)
+			const step = answerStepFromKey(key)
+			answerStepCounts.set(step, (answerStepCounts.get(step) ?? 0) + 1)
+		}
+
+		const latestIntentByContact = new Map<string, any>()
+		for (const intent of [...intents].sort(
+			(a: any, b: any) =>
+				new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime(),
+		)) {
+			latestIntentByContact.set(intent.contactId, intent)
+		}
+
+		const terminalCounts = new Map<string, number>()
+		for (const intent of latestIntentByContact.values()) {
+			const emailResourceId = String(intent.metadata?.emailResourceId ?? '')
+			if (!isTerminalValuePathEmail(emailResourceId)) continue
+			terminalCounts.set(
+				emailResourceId,
+				(terminalCounts.get(emailResourceId) ?? 0) + 1,
+			)
+		}
+
+		return {
+			contacts: contactIds.size,
+			events: events.length,
+			intents: intents.length,
+			completedIntents: intents.filter(
+				(intent: any) => intent.status === 'completed',
+			).length,
+			pendingIntents: intents.filter(
+				(intent: any) => intent.status === 'pending',
+			).length,
+			blockedIntents: intents.filter(
+				(intent: any) => intent.status === 'blocked',
+			).length,
+			answerEvents: answerEvents.length,
+			dripEvents: dripEvents.length,
+			enteredEvents: enteredEvents.length,
+			participantsWithAnswerClicks: answersByContact.size,
+			participantsWithNoAnswerClicks: Math.max(
+				0,
+				contactIds.size - answersByContact.size,
+			),
+			terminalParticipants: [...terminalCounts.values()].reduce(
+				(total, count) => total + count,
+				0,
+			),
+			answerOptions: [...answerKeyCounts.entries()]
+				.map(([key, count]) => ({
+					key,
+					step: answerStepFromKey(key),
+					optionValue: answerOptionFromKey(key),
+					count,
+				}))
+				.sort((a, b) => b.count - a.count),
+			answerSteps: [...answerStepCounts.entries()]
+				.map(([step, count]) => ({ step, count }))
+				.sort((a, b) => b.count - a.count),
+			terminalSteps: [...terminalCounts.entries()]
+				.map(([emailResourceId, count]) => ({ emailResourceId, count }))
+				.sort((a, b) => b.count - a.count),
+			notes: [
+				'Counts are based on Contact Events and SideEffectIntents.',
+				'Kit-native opens, unsubscribes, complaints, and raw Kit link clicks are not included.',
+			],
+		}
+	}
+
+	function parseValuePathAnswerKey(providerEventId: string | null | undefined) {
+		const match = String(providerEventId ?? '').match(/:answer:(.+)$/)
+		return match?.[1] ?? 'unknown'
+	}
+
+	function answerStepFromKey(key: string) {
+		const index = key.lastIndexOf('.')
+		return index > -1 ? key.slice(0, index) : key
+	}
+
+	function answerOptionFromKey(key: string) {
+		const index = key.lastIndexOf('.')
+		return index > -1 ? key.slice(index + 1) : 'unknown'
+	}
+
+	function isTerminalValuePathEmail(emailResourceId: string) {
+		return /(?:^|\.)(?:email-6|team-email-6)$/.test(emailResourceId)
+	}
+
 	async function traceAttribution(opts: {
 		email?: string
 		purchaseId?: string
@@ -784,8 +1618,12 @@ export function createDatabaseProvider(
 		getShortlinkPerformance,
 		getRevenueBySource,
 		getConversionFunnel,
+		getCommerceLaneSummary,
 		getAttributedRevenueSummary,
 		getContentPurchaseCorrelation,
+		getCheckoutAttributionReceipt,
+		getCheckoutSurveyFallbackReport,
+		getValuePathSummary,
 		traceAttribution,
 	}
 }