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

package/dist/types.d.ts

@@ -8,6 +8,7 @@ type Percentage = Brand<number, 'Percentage'>;
 type Minutes = Brand<number, 'Minutes'>;
 type Seconds = Brand<number, 'Seconds'>;
 type AnalyticsRange = '24h' | '7d' | '30d' | '90d' | 'all';
+type TrafficAnalyticsRange = AnalyticsRange | '180d';
 interface RevenueSummary {
     totalRevenue: USD;
     purchaseCount: Count;
@@ -39,6 +40,8 @@ interface RecentPurchase {
     couponId: string | null;
     userName: string | null;
     userEmail: string | null;
+    isTeam?: boolean;
+    seats?: number | null;
 }
 interface AttributionCount {
     type: string;
@@ -49,6 +52,8 @@ interface ShortlinkPerformance {
     slug: string;
     url: string;
     clicks: Count;
+    signups?: Count;
+    purchases?: Count;
 }
 type CommerceRecordKind = 'paid_conversion' | 'access_grant' | 'synthetic' | 'unknown';
 interface RevenueBySource {
@@ -90,6 +95,20 @@ interface AttributionSignalSummary {
     recoveredFromShortlinkAttributionTable?: Count;
     internalFreeUpgrade: Count;
 }
+type AttributionQualityLaneName = 'strong' | 'medium' | 'weak' | 'unknown';
+interface AttributionQualityLane {
+    lane: AttributionQualityLaneName;
+    purchases: Count;
+    revenue: USD;
+    revenuePercent: Percentage;
+    notes: string[];
+}
+interface AttributionQualitySummary {
+    strong: AttributionQualityLane;
+    medium: AttributionQualityLane;
+    weak: AttributionQualityLane;
+    unknown: AttributionQualityLane;
+}
 interface AttributionCoverage {
     totalRevenue: USD;
     attributedRevenue: USD;
@@ -107,6 +126,22 @@ interface AttributionCoverage {
     syntheticPurchases?: Count;
     commerce?: CommerceLaneSummary;
     signals?: AttributionSignalSummary;
+    quality?: AttributionQualitySummary;
+}
+interface TrafficBreakdownRow {
+    sessions: Count;
+    users: Count;
+    sessionPercent: Percentage;
+    trafficSessionPercent: Percentage;
+}
+interface DeviceCategoryBreakdown extends TrafficBreakdownRow {
+    deviceCategory: string;
+}
+interface OperatingSystemBreakdown extends TrafficBreakdownRow {
+    operatingSystem: string;
+}
+interface ScreenResolutionBreakdown extends TrafficBreakdownRow {
+    screenResolution: string;
 }
 interface TrafficOverview {
     sessions: Count;
@@ -115,6 +150,9 @@ interface TrafficOverview {
     pageviews: Count;
     avgSessionDuration: Seconds;
     bounceRate: Percentage;
+    deviceCategories?: DeviceCategoryBreakdown[];
+    operatingSystems?: OperatingSystemBreakdown[];
+    screenResolutions?: ScreenResolutionBreakdown[];
 }
 interface TrafficDaily {
     date: string;
@@ -448,4 +486,4 @@ type QueryResult<S extends SurfaceName> = {
     fix: string;
 };
 
-export type { AnalyticsRange, AttributionCount, AttributionCoverage, AttributionSignalSummary, CheckoutAttributionReceipt, CheckoutSurveyFallbackAnswer, CheckoutSurveyFallbackReport, CommerceLaneSummary, CommerceRecordKind, ContentCorrelation, ConversionFunnel, Count, EmailCampaignFunnel, EmailCampaignKitLink, EmailCampaignShortlink, EmailRevenueOverview, Minutes, Percentage, ProductSurveyRevenueAnswer, ProductSurveyRevenueCorrelation, QueryOptions, QueryResult, RecentPurchase, RevenueByCountry, RevenueByProduct, RevenueBySource, RevenueDaily, RevenueSummary, Seconds, ShortlinkPerformance, SurfaceMap, SurfaceName, SurveyConversionByQuestion, SurveyListItem, SurveyQuestionBreakdown, SurveyResponseRow, SurveyResponsesDaily, SurveyRevenueCorrelation, SurveySummary, TopPage, TrafficDaily, TrafficOverview, TrafficRevenueCorrelation, TrafficSource, USD, ValuePathAnswerBucket, ValuePathStepBucket, ValuePathSummary, ValuePathTerminalBucket, YouTubeChannelOverview, YouTubeDaily, YouTubeRevenueCorrelation, YouTubeTrafficSource, YouTubeVideoPerformance };
+export type { AnalyticsRange, AttributionCount, AttributionCoverage, AttributionQualityLane, AttributionQualityLaneName, AttributionQualitySummary, AttributionSignalSummary, CheckoutAttributionReceipt, CheckoutSurveyFallbackAnswer, CheckoutSurveyFallbackReport, CommerceLaneSummary, CommerceRecordKind, ContentCorrelation, ConversionFunnel, Count, DeviceCategoryBreakdown, EmailCampaignFunnel, EmailCampaignKitLink, EmailCampaignShortlink, EmailRevenueOverview, Minutes, OperatingSystemBreakdown, Percentage, ProductSurveyRevenueAnswer, ProductSurveyRevenueCorrelation, QueryOptions, QueryResult, RecentPurchase, RevenueByCountry, RevenueByProduct, RevenueBySource, RevenueDaily, RevenueSummary, ScreenResolutionBreakdown, Seconds, ShortlinkPerformance, SurfaceMap, SurfaceName, SurveyConversionByQuestion, SurveyListItem, SurveyQuestionBreakdown, SurveyResponseRow, SurveyResponsesDaily, SurveyRevenueCorrelation, SurveySummary, TopPage, TrafficAnalyticsRange, TrafficBreakdownRow, TrafficDaily, TrafficOverview, TrafficRevenueCorrelation, TrafficSource, USD, ValuePathAnswerBucket, ValuePathStepBucket, ValuePathSummary, ValuePathTerminalBucket, YouTubeChannelOverview, YouTubeDaily, YouTubeRevenueCorrelation, YouTubeTrafficSource, YouTubeVideoPerformance };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coursebuilder/analytics",
-  "version": "1.1.1",
+  "version": "1.1.2-canary.0.0c9beb2ae",
   "files": [
     "dist",
     "src"
@@ -70,7 +70,7 @@
   },
   "dependencies": {
     "@google-analytics/data": "^4.0.0",
-    "zod": "^3.22.4"
+    "zod": "^4.1.12"
   },
   "devDependencies": {
     "@types/react": "19.2.7",
@@ -83,10 +83,10 @@
     "tsup": "8.0.2",
     "typescript": "5.4.5",
     "vitest": "1.6.0",
-    "@coursebuilder/ui": "2.0.12"
+    "@coursebuilder/ui": "2.4.1-canary.0.0c9beb2ae"
   },
   "peerDependencies": {
-    "@coursebuilder/ui": "*",
+    "@coursebuilder/ui": "2.4.1-canary.0",
     "drizzle-orm": "*",
     "lucide-react": "*",
     "next": "*",

package/src/components/omnibus-dashboard.tsx

@@ -29,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'
 
@@ -107,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
@@ -114,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>
@@ -618,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 }[] = [
@@ -697,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">
@@ -796,6 +938,9 @@ export function OmnibusDashboard({
 					)}
 				</div>
 
+				{/* ── Traffic Details ──────────────────────────────────────── */}
+				{hasTraffic && <TrafficBreakdownsCard traffic={data.traffic!} />}
+
 				{/* ── Video Performance ────────────────────────────────────── */}
 				{hasMux && data.mux!.topVideos.length > 0 && (
 					<TopVideosCard
@@ -854,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>
@@ -912,6 +1057,32 @@ 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>
 					)}
@@ -1593,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
 }
@@ -71,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') {

package/src/providers/database.ts

@@ -143,6 +143,35 @@ export function createDatabaseProvider(
 		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()
@@ -690,6 +719,24 @@ export function createDatabaseProvider(
 				.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,
@@ -736,6 +783,21 @@ export function createDatabaseProvider(
 		)
 		const unattributedRevenue = totalRevenue - attributedRevenue
 		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,
@@ -764,6 +826,12 @@ export function createDatabaseProvider(
 					recoveredFromShortlinkAttributionTableCount,
 				internalFreeUpgrade: commerce.freeUpgrades,
 			},
+			quality: {
+				strong: strongQuality,
+				medium: mediumQuality,
+				weak: weakQuality,
+				unknown: unknownQuality,
+			},
 		}
 	}
 

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,6 +60,8 @@ export interface ShortlinkPerformance {
 	slug: string
 	url: string
 	clicks: Count
+	signups?: Count
+	purchases?: Count
 }
 
 export type CommerceRecordKind =
@@ -109,6 +114,27 @@ export interface AttributionSignalSummary {
 	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
@@ -126,6 +152,26 @@ export interface AttributionCoverage {
 	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 {
@@ -135,6 +181,9 @@ export interface TrafficOverview {
 	pageviews: Count
 	avgSessionDuration: Seconds
 	bounceRate: Percentage
+	deviceCategories?: DeviceCategoryBreakdown[]
+	operatingSystems?: OperatingSystemBreakdown[]
+	screenResolutions?: ScreenResolutionBreakdown[]
 }
 
 export interface TrafficDaily {