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

package/src/providers/survey.ts

@@ -117,6 +117,7 @@ export interface SurveyAnalyticsProvider {
 	getSurveyResponses: (
 		range?: AnalyticsRange,
 		limit?: number,
+		offset?: number,
 	) => Promise<
 		Array<{
 			responseId: string
@@ -458,10 +459,11 @@ export function createSurveyProvider(
 	async function getSurveyResponses(
 		range: AnalyticsRange = '30d',
 		limit = 100,
+		offset = 0,
 	) {
 		const canonicalRows = await fetchCanonicalRows(range)
 
-		return canonicalRows.slice(0, limit).map((row) => ({
+		return canonicalRows.slice(offset, offset + limit).map((row) => ({
 			responseId: row.responseId,
 			surveyId: row.surveyId,
 			surveyTitle: row.surveyTitle ?? '',

package/src/types.ts

@@ -9,6 +9,7 @@ export type Minutes = Brand<number, 'Minutes'>
 export type Seconds = Brand<number, 'Seconds'>
 
 export type AnalyticsRange = '24h' | '7d' | '30d' | '90d' | 'all'
+export type TrafficAnalyticsRange = AnalyticsRange | '180d'
 
 export interface RevenueSummary {
 	totalRevenue: USD
@@ -45,6 +46,8 @@ export interface RecentPurchase {
 	couponId: string | null
 	userName: string | null
 	userEmail: string | null
+	isTeam?: boolean
+	seats?: number | null
 }
 
 export interface AttributionCount {
@@ -57,11 +60,20 @@ export interface ShortlinkPerformance {
 	slug: string
 	url: string
 	clicks: Count
+	signups?: Count
+	purchases?: Count
 }
 
+export type CommerceRecordKind =
+	| 'paid_conversion'
+	| 'access_grant'
+	| 'synthetic'
+	| 'unknown'
+
 export interface RevenueBySource {
-	source: string
-	medium: string
+	kind?: CommerceRecordKind
+	source: string | null
+	medium: string | null
 	campaign: string | null
 	revenue: USD
 	count: Count
@@ -81,12 +93,85 @@ export interface ContentCorrelation {
 	purchaserCount: Count
 }
 
+export interface CommerceLaneSummary {
+	commerceRecords: Count
+	paidPurchases: Count
+	paidRevenue: USD
+	accessGrants: Count
+	accessGrantRevenue: USD
+	freeUpgrades: Count
+	syntheticPurchases: Count
+	byAccessGrantReason: Record<string, Count>
+}
+
+export interface AttributionSignalSummary {
+	shortlink: Count
+	utm: Count
+	paidClickId: Count
+	gaClientId: Count
+	selfReportedSource: Count
+	recoveredFromShortlinkAttributionTable?: Count
+	internalFreeUpgrade: Count
+}
+
+export type AttributionQualityLaneName =
+	| 'strong'
+	| 'medium'
+	| 'weak'
+	| 'unknown'
+
+export interface AttributionQualityLane {
+	lane: AttributionQualityLaneName
+	purchases: Count
+	revenue: USD
+	revenuePercent: Percentage
+	notes: string[]
+}
+
+export interface AttributionQualitySummary {
+	strong: AttributionQualityLane
+	medium: AttributionQualityLane
+	weak: AttributionQualityLane
+	unknown: AttributionQualityLane
+}
+
 export interface AttributionCoverage {
 	totalRevenue: USD
 	attributedRevenue: USD
 	unattributedRevenue: USD
 	attributionRate: Percentage
 	totalPurchases: Count
+	paidPurchases?: Count
+	purchaseFieldAttributedPurchases?: Count
+	purchaseFieldAttributedRevenue?: USD
+	recoveredFromShortlinkAttributionTablePurchases?: Count
+	recoveredFromShortlinkAttributionTableRevenue?: USD
+	commerceRecords?: Count
+	accessGrants?: Count
+	freeUpgrades?: Count
+	syntheticPurchases?: Count
+	commerce?: CommerceLaneSummary
+	signals?: AttributionSignalSummary
+	quality?: AttributionQualitySummary
+}
+
+export interface TrafficBreakdownRow {
+	sessions: Count
+	users: Count
+	sessionPercent: Percentage
+	trafficSessionPercent: Percentage
+}
+
+export interface DeviceCategoryBreakdown extends TrafficBreakdownRow {
+	deviceCategory: string
+}
+
+export interface OperatingSystemBreakdown extends TrafficBreakdownRow {
+	operatingSystem: string
+}
+
+export interface ScreenResolutionBreakdown extends TrafficBreakdownRow {
+	screenResolution: string
 }
 
 export interface TrafficOverview {
@@ -96,6 +181,9 @@ export interface TrafficOverview {
 	pageviews: Count
 	avgSessionDuration: Seconds
 	bounceRate: Percentage
+	deviceCategories?: DeviceCategoryBreakdown[]
+	operatingSystems?: OperatingSystemBreakdown[]
+	screenResolutions?: ScreenResolutionBreakdown[]
 }
 
 export interface TrafficDaily {
@@ -279,6 +367,119 @@ export interface SurveyRevenueCorrelation {
 	byQuestion: SurveyConversionByQuestion[]
 }
 
+/** One survey answer bucket correlated to paid product revenue. */
+export interface ProductSurveyRevenueAnswer {
+	surveyId: string
+	surveyTitle: string | null
+	surveySlug: string | null
+	questionId: string
+	question: string | null
+	answer: string
+	responses: Count
+	uniqueRespondents: Count
+	paidPurchasers: Count
+	paidRevenue: USD
+	conversionRate: Percentage
+}
+
+/** Product-filtered survey revenue report with aggregate counts and answer buckets. */
+export interface ProductSurveyRevenueCorrelation {
+	productId: string | null
+	surveyId: string | null
+	surveySlug: string | null
+	totalResponses: Count
+	uniqueRespondents: Count
+	respondentsWithUserId: Count
+	paidPurchasers: Count
+	paidRevenue: USD
+	byAnswer: ProductSurveyRevenueAnswer[]
+}
+
+/** Single-purchase attribution receipt used by operator audits and checkout debugging. */
+export interface CheckoutAttributionReceipt {
+	purchase: {
+		id: string
+		createdAt: Date | string | null
+		productId: string | null
+		productName: string | null
+		totalAmount: USD
+		status: string | null
+		country: string | null
+	} | null
+	checks: {
+		purchaseFound: boolean
+		attributionSnapshot: boolean
+		utm: boolean
+		actualUtm: boolean
+		clickId: boolean
+		synthetic: boolean
+		shortlink: boolean
+		selfReportedSource: boolean
+		gaClientId: boolean
+	}
+	attribution: Record<string, unknown> | null
+	legacy: Record<string, unknown>
+	fieldKeys: string[]
+}
+
+/** Checkout survey answer bucket for otherwise dark purchase recovery analysis. */
+export interface CheckoutSurveyFallbackAnswer {
+	answer: string
+	confidence: 'exact_purchase_link' | 'user_linked'
+	purchases: Count
+	revenue: USD
+}
+
+/** Report-only fallback from checkout survey responses to dark purchase revenue. */
+export interface CheckoutSurveyFallbackReport {
+	label: 'recovered_from_checkout_survey_response'
+	productId: string | null
+	totalDarkPurchases: Count
+	totalDarkRevenue: USD
+	exactPurchaseLinkedPurchases: Count
+	exactPurchaseLinkedRevenue: USD
+	userLinkedPurchases: Count
+	userLinkedRevenue: USD
+	byAnswer: CheckoutSurveyFallbackAnswer[]
+	notes: string[]
+}
+
+export interface ValuePathAnswerBucket {
+	key: string
+	step: string
+	optionValue: string
+	count: Count
+}
+
+export interface ValuePathStepBucket {
+	step: string
+	count: Count
+}
+
+export interface ValuePathTerminalBucket {
+	emailResourceId: string
+	count: Count
+}
+
+export interface ValuePathSummary {
+	contacts: Count
+	events: Count
+	intents: Count
+	completedIntents: Count
+	pendingIntents: Count
+	blockedIntents: Count
+	answerEvents: Count
+	dripEvents: Count
+	enteredEvents: Count
+	participantsWithAnswerClicks: Count
+	participantsWithNoAnswerClicks: Count
+	terminalParticipants: Count
+	answerOptions: ValuePathAnswerBucket[]
+	answerSteps: ValuePathStepBucket[]
+	terminalSteps: ValuePathTerminalBucket[]
+	notes: string[]
+}
+
 export interface SurfaceMap {
 	summary: RevenueSummary
 	'revenue/daily': RevenueDaily[]
@@ -291,6 +492,7 @@ export interface SurfaceMap {
 	'attribution/funnel': ConversionFunnel
 	'attribution/content': ContentCorrelation[]
 	'attribution/coverage': AttributionCoverage
+	'attribution/commerce-lanes': CommerceLaneSummary
 	traffic: TrafficOverview
 	'traffic/daily': TrafficDaily[]
 	'traffic/pages': TopPage[]
@@ -307,7 +509,12 @@ export interface SurfaceMap {
 	'surveys/questions': SurveyQuestionBreakdown[]
 	'surveys/responses': SurveyResponseRow[]
 	'correlation/survey-revenue': SurveyRevenueCorrelation
+	'correlation/survey-revenue/product': ProductSurveyRevenueCorrelation
 	'attribution/email-campaigns': EmailRevenueOverview
+	'attribution/email-campaigns/strict': EmailRevenueOverview
+	'attribution/checkout-receipt': CheckoutAttributionReceipt
+	'attribution/checkout-survey-fallback': CheckoutSurveyFallbackReport
+	'value-paths/summary': ValuePathSummary
 }
 
 export type SurfaceName = keyof SurfaceMap
@@ -315,6 +522,12 @@ export type SurfaceName = keyof SurfaceMap
 export interface QueryOptions {
 	range?: AnalyticsRange
 	limit?: number
+	offset?: number
+	productId?: string
+	purchaseId?: string
+	surveyId?: string
+	surveySlug?: string
+	questionId?: string
 }
 
 export type QueryResult<S extends SurfaceName> =