@coursebuilder/analytics 1.1.0

package/src/components/revenue-chart.tsx

@@ -0,0 +1,251 @@
+'use client'
+
+import React, { useMemo } from 'react'
+import {
+	Area,
+	AreaChart,
+	CartesianGrid,
+	ResponsiveContainer,
+	Tooltip,
+	XAxis,
+	YAxis,
+} from 'recharts'
+
+import { useChartColors } from './use-chart-colors'
+
+interface DayData {
+	date: string
+	revenue: number
+	count: number
+}
+
+interface RevenueChartProps {
+	data: DayData[]
+	previousData?: DayData[]
+}
+
+function formatDate(dateStr: string) {
+	const d = new Date(dateStr + 'T00:00:00')
+	return d.toLocaleDateString('en-US', { month: 'short', day: 'numeric' })
+}
+
+function formatCurrency(value: number): string {
+	if (value >= 1000) return `$${(value / 1000).toFixed(1)}k`
+	return `$${value.toFixed(0)}`
+}
+
+function CustomTooltip({
+	active,
+	payload,
+	label,
+}: {
+	active?: boolean
+	payload?: { dataKey: string; value: number; payload: MergedDay }[]
+	label?: string
+}) {
+	if (!active || !payload?.length || !label) return null
+
+	const merged = payload[0]?.payload
+	if (!merged) return null
+
+	const current = merged.revenue ?? 0
+	const previous = merged.prevRevenue ?? 0
+	const hasPrev = previous > 0
+
+	let delta = ''
+	let deltaColor = ''
+	if (hasPrev && current > 0) {
+		const pct = ((current - previous) / previous) * 100
+		delta = pct >= 0 ? `+${pct.toFixed(0)}%` : `${pct.toFixed(0)}%`
+		deltaColor = pct >= 0 ? 'text-emerald-500' : 'text-red-400'
+	}
+
+	return (
+		<div className="border-border/50 bg-card rounded-lg border px-3 py-2 shadow-xl">
+			<p className="text-muted-foreground text-xs">{formatDate(label)}</p>
+			<div className="mt-1 flex items-baseline gap-2">
+				<p className="text-foreground text-lg font-bold tabular-nums">
+					$
+					{current.toLocaleString(undefined, {
+						minimumFractionDigits: 0,
+						maximumFractionDigits: 0,
+					})}
+				</p>
+				{delta && (
+					<span className={`text-xs font-semibold ${deltaColor}`}>{delta}</span>
+				)}
+			</div>
+			<p className="text-muted-foreground text-xs">
+				{merged.count ?? 0} purchases
+			</p>
+			{hasPrev && (
+				<p className="text-muted-foreground border-border/30 mt-1 border-t pt-1 text-[11px]">
+					prev: $
+					{previous.toLocaleString(undefined, {
+						minimumFractionDigits: 0,
+						maximumFractionDigits: 0,
+					})}{' '}
+					· {merged.prevCount ?? 0} purchases
+				</p>
+			)}
+		</div>
+	)
+}
+
+interface MergedDay {
+	date: string
+	revenue: number
+	count: number
+	prevRevenue: number | null
+	prevCount: number | null
+}
+
+export function RevenueChart({ data, previousData = [] }: RevenueChartProps) {
+	const colors = useChartColors()
+
+	const merged = useMemo<MergedDay[]>(() => {
+		if (previousData.length === 0) {
+			return data.map((d) => ({
+				...d,
+				prevRevenue: null,
+				prevCount: null,
+			}))
+		}
+
+		// Align previous period by day offset (day 0 = start of each period)
+		return data.map((d, i) => {
+			const prev = previousData[i]
+			return {
+				...d,
+				prevRevenue: prev?.revenue ?? null,
+				prevCount: prev?.count ?? null,
+			}
+		})
+	}, [data, previousData])
+
+	const maxRevenue = useMemo(
+		() =>
+			Math.max(
+				...merged.map((d) => d.revenue),
+				...merged.map((d) => d.prevRevenue ?? 0),
+				0,
+			),
+		[merged],
+	)
+
+	// Use log scale when the max is >10x the median — prevents spikes from crushing everything
+	const nonZeroVals = useMemo(
+		() =>
+			merged
+				.map((d) => d.revenue)
+				.filter((v) => v > 0)
+				.sort((a, b) => a - b),
+		[merged],
+	)
+	const useLog = useMemo(() => {
+		if (nonZeroVals.length < 3) return false
+		const median = nonZeroVals[Math.floor(nonZeroVals.length / 2)]!
+		return maxRevenue > median * 10
+	}, [nonZeroVals, maxRevenue])
+	const logFloor =
+		nonZeroVals.length > 0 ? Math.floor(nonZeroVals[0]! * 0.7) : 100
+
+	const hasPrev = previousData.length > 0
+
+	return (
+		<div className="h-[280px] w-full">
+			<ResponsiveContainer width="100%" height="100%">
+				<AreaChart
+					data={merged}
+					margin={{ top: 8, right: 8, left: -12, bottom: 0 }}
+				>
+					<defs>
+						<linearGradient id="revenueGradient" x1="0" y1="0" x2="0" y2="1">
+							<stop offset="0%" stopColor="#22c55e" stopOpacity={0.3} />
+							<stop offset="100%" stopColor="#22c55e" stopOpacity={0} />
+						</linearGradient>
+					</defs>
+					<CartesianGrid
+						strokeDasharray="3 3"
+						stroke={colors.gridLine}
+						vertical={false}
+					/>
+					<XAxis
+						dataKey="date"
+						tickFormatter={formatDate}
+						tick={{ fill: colors.mutedForeground, fontSize: 11 }}
+						axisLine={{ stroke: colors.gridLine }}
+						tickLine={false}
+						interval="preserveStartEnd"
+						minTickGap={40}
+					/>
+					<YAxis
+						tick={{ fill: colors.mutedForeground, fontSize: 11 }}
+						axisLine={false}
+						tickLine={false}
+						scale={useLog ? 'log' : 'auto'}
+						domain={
+							useLog ? [logFloor, 'auto'] : [0, Math.ceil(maxRevenue * 1.1)]
+						}
+						allowDataOverflow={useLog}
+						tickFormatter={formatCurrency}
+					/>
+					<Tooltip
+						content={<CustomTooltip />}
+						cursor={{
+							stroke: '#22c55e',
+							strokeWidth: 1,
+							strokeDasharray: '4 4',
+						}}
+					/>
+					{hasPrev && (
+						<Area
+							type="linear"
+							dataKey="prevRevenue"
+							stroke={colors.mutedForeground}
+							strokeWidth={1.5}
+							strokeDasharray="4 3"
+							fill="none"
+							dot={false}
+							activeDot={false}
+							connectNulls
+						/>
+					)}
+					<Area
+						type="linear"
+						dataKey="revenue"
+						stroke="#22c55e"
+						strokeWidth={2}
+						fill="url(#revenueGradient)"
+						dot={false}
+						activeDot={{
+							r: 5,
+							fill: '#22c55e',
+							stroke: colors.cardBg,
+							strokeWidth: 2,
+						}}
+					/>
+				</AreaChart>
+			</ResponsiveContainer>
+			{hasPrev && (
+				<div className="mt-2 flex items-center gap-4 text-[11px]">
+					<span className="flex items-center gap-1.5">
+						<span className="inline-block h-0.5 w-4 rounded bg-emerald-500" />
+						<span className="text-muted-foreground">Current period</span>
+					</span>
+					<span className="flex items-center gap-1.5">
+						<span
+							className="inline-block h-0.5 w-4 rounded"
+							style={{
+								background: colors.mutedForeground,
+								backgroundImage:
+									'repeating-linear-gradient(90deg, transparent, transparent 3px, currentColor 3px, currentColor 5px)',
+							}}
+						/>
+						<span className="text-muted-foreground">Previous period</span>
+					</span>
+				</div>
+			)}
+		</div>
+	)
+}

package/src/components/use-chart-colors.ts

@@ -0,0 +1,75 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+
+export interface ChartColors {
+	primary: string
+	primaryMuted: string
+	foreground: string
+	mutedForeground: string
+	gridLine: string
+	cardBg: string
+	hoverBg: string
+}
+
+const FALLBACK: ChartColors = {
+	primary: '#d4a053',
+	primaryMuted: 'rgba(212, 160, 83, 0.2)',
+	foreground: '#e5e5e5',
+	mutedForeground: '#999',
+	gridLine: '#333',
+	cardBg: '#1a1a1a',
+	hoverBg: '#222',
+}
+
+function getCSSVar(name: string): string {
+	return getComputedStyle(document.documentElement)
+		.getPropertyValue(name)
+		.trim()
+}
+
+function oklchToUsable(raw: string): string {
+	if (!raw) return ''
+	// raw is like "oklch(0.85 0.12 79.28)" — browsers handle it fine
+	return raw.startsWith('oklch') ? raw : raw
+}
+
+export function useChartColors(): ChartColors {
+	const [colors, setColors] = useState<ChartColors>(FALLBACK)
+
+	useEffect(() => {
+		function update() {
+			const primary = getCSSVar('--primary')
+			const muted = getCSSVar('--muted')
+			const mutedFg = getCSSVar('--muted-foreground')
+			const fg = getCSSVar('--foreground')
+			const border = getCSSVar('--border')
+			const card = getCSSVar('--card')
+
+			if (!primary) return
+
+			setColors({
+				primary: oklchToUsable(primary),
+				primaryMuted: oklchToUsable(primary).replace(')', ' / 0.2)'),
+				foreground: oklchToUsable(fg),
+				mutedForeground: oklchToUsable(mutedFg),
+				gridLine: oklchToUsable(border),
+				cardBg: oklchToUsable(card),
+				hoverBg: oklchToUsable(muted),
+			})
+		}
+
+		update()
+
+		// Re-read when theme changes (class mutation on <html>)
+		const observer = new MutationObserver(update)
+		observer.observe(document.documentElement, {
+			attributes: true,
+			attributeFilter: ['class'],
+		})
+
+		return () => observer.disconnect()
+	}, [])
+
+	return colors
+}

package/src/engine.ts

@@ -0,0 +1,201 @@
+import { catalog, type SurfaceEntry } from './catalog'
+import type {
+	AnalyticsRange,
+	QueryOptions,
+	QueryResult,
+	SurfaceMap,
+	SurfaceName,
+} from './types'
+
+export type AnalyticsProvider = Record<
+	string,
+	((...args: any[]) => Promise<any>) | unknown
+>
+
+export type ProviderMap = Record<string, AnalyticsProvider>
+
+function toGA4Range(range: AnalyticsRange): '24h' | '7d' | '30d' | '90d' {
+	if (range === 'all') return '90d'
+	return range
+}
+
+function toYouTubeRange(range: AnalyticsRange): '24h' | '7d' | '30d' | '90d' {
+	if (range === 'all') return '90d'
+	return range
+}
+
+async function invokeSurface<S extends SurfaceName>(
+	providers: ProviderMap,
+	surface: S,
+	range: AnalyticsRange,
+	limit: number,
+): Promise<SurfaceMap[S] | null> {
+	const entry = catalog[surface]
+	const provider = providers[entry.provider]
+
+	if (!provider) {
+		return null
+	}
+
+	// Check that the provider actually exposes the expected function.
+	// A provider may exist but not support every surface in the catalog
+	// (e.g. CWA's derived provider omits YouTube correlation).
+	if (typeof provider[entry.fn] !== 'function') {
+		return null
+	}
+
+	switch (surface) {
+		case 'purchases/recent': {
+			const fn = provider[entry.fn] as (limit: number) => Promise<SurfaceMap[S]>
+			return fn(limit)
+		}
+		case 'youtube': {
+			const fn = provider[entry.fn] as () => Promise<SurfaceMap[S] | null>
+			return fn()
+		}
+		case 'youtube/videos':
+		case 'youtube/daily':
+		case 'youtube/sources': {
+			const fn = provider[entry.fn] as (
+				range: '24h' | '7d' | '30d' | '90d',
+				limit?: number,
+			) => Promise<SurfaceMap[S] | null>
+			if (surface === 'youtube/videos') {
+				return fn(toYouTubeRange(range), limit)
+			}
+			return fn(toYouTubeRange(range))
+		}
+		case 'traffic':
+		case 'traffic/daily':
+		case 'traffic/pages':
+		case 'traffic/sources': {
+			const fn = provider[entry.fn] as (
+				range: '24h' | '7d' | '30d' | '90d',
+				limit?: number,
+			) => Promise<SurfaceMap[S]>
+			if (surface === 'traffic/pages' || surface === 'traffic/sources') {
+				return fn(toGA4Range(range), limit)
+			}
+			return fn(toGA4Range(range))
+		}
+		case 'surveys':
+		case 'surveys/list':
+		case 'surveys/daily': {
+			const fn = provider[entry.fn] as (
+				range: AnalyticsRange,
+			) => Promise<SurfaceMap[S]>
+			return fn(range)
+		}
+		case 'attribution/email-campaigns': {
+			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,
+			) => Promise<SurfaceMap[S]>
+			return fn(range, limit)
+		}
+		default: {
+			const fn = provider[entry.fn] as (
+				range: AnalyticsRange,
+				limit?: number,
+			) => Promise<SurfaceMap[S] | null>
+			if (
+				surface === 'attribution/content' ||
+				surface === 'correlation/survey-revenue'
+			) {
+				return fn(range, limit)
+			}
+			return fn(range)
+		}
+	}
+}
+
+/**
+ * Creates an analytics engine bound to the given provider map.
+ *
+ * @param providers - A map of provider name → provider implementation. Keys
+ *   must match the `provider` field values used in the catalog
+ *   ('database', 'ga4', 'youtube', 'derived', 'newsletter', 'survey').
+ * @returns An object with `query`, `queryMany`, and `getCatalog` methods.
+ */
+export function createAnalyticsEngine(providers: ProviderMap) {
+	async function query<S extends SurfaceName>(
+		surface: S,
+		options?: QueryOptions,
+	): Promise<QueryResult<S>> {
+		const range = options?.range ?? '30d'
+		const limit = options?.limit ?? 20
+		const entry = catalog[surface]
+		const startMs = Date.now()
+
+		try {
+			const data = await invokeSurface(providers, surface, range, limit)
+
+			if (data === null) {
+				return {
+					ok: false,
+					surface,
+					error: {
+						message: `${entry.provider} is not available`,
+						code: `${entry.provider.toUpperCase()}_UNAVAILABLE`,
+					},
+					fix: entry.unavailableFix ?? 'Check provider configuration',
+				}
+			}
+
+			return {
+				ok: true,
+				surface,
+				range,
+				data,
+				meta: {
+					queryTimeMs: Date.now() - startMs,
+					truncated: Array.isArray(data) && data.length >= limit,
+				},
+			}
+		} catch (error) {
+			return {
+				ok: false,
+				surface,
+				error: {
+					message: error instanceof Error ? error.message : String(error),
+					code: 'QUERY_FAILED',
+				},
+				fix: `The ${surface} query failed. Try a different range or check server logs.`,
+			}
+		}
+	}
+
+	async function queryMany<S extends SurfaceName>(
+		surfaces: S[],
+		options?: QueryOptions,
+	): Promise<{ [K in S]: QueryResult<K> }> {
+		const results = await Promise.all(
+			surfaces.map(
+				async (surface) => [surface, await query(surface, options)] as const,
+			),
+		)
+
+		return Object.fromEntries(results) as { [K in S]: QueryResult<K> }
+	}
+
+	/**
+	 * Returns catalog entries filtered to only surfaces that this engine
+	 * can actually serve (provider present and function exported).
+	 */
+	function getCatalog(): SurfaceEntry[] {
+		return Object.values(catalog).filter((entry) => {
+			const provider = providers[entry.provider]
+			return provider && typeof provider[entry.fn] === 'function'
+		})
+	}
+
+	return { query, queryMany, getCatalog }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './types'
+export { ANALYTICS_CATALOG, catalog, type SurfaceEntry } from './catalog'
+export {
+	createAnalyticsEngine,
+	type ProviderMap,
+	type AnalyticsProvider,
+} from './engine'