@coursebuilder/analytics 1.1.0

package/src/api/catalog-handler.ts

@@ -0,0 +1,321 @@
+import { NextRequest, NextResponse } from 'next/server'
+
+import type { SurfaceEntry } from '../catalog'
+import type { QueryOptions, QueryResult, SurfaceName } from '../types'
+
+type AnalyticsRange = '24h' | '7d' | '30d' | '90d' | 'all'
+
+interface CatalogHandlerDeps {
+	engine: {
+		query: (
+			surface: string,
+			options?: QueryOptions,
+		) => Promise<QueryResult<SurfaceName>>
+		getCatalog: () => SurfaceEntry[]
+	}
+	checkAccess: (request: Request) => Promise<{
+		authorized: boolean
+		user?: Record<string, unknown> | null
+		authMethod?: string
+	}>
+	logger?: {
+		info: (message: string, data?: Record<string, unknown>) => unknown
+		warn: (message: string, data?: Record<string, unknown>) => unknown
+		error: (message: string, data?: Record<string, unknown>) => unknown
+	}
+	appName?: string
+	baseUrl?: string
+}
+
+export type { CatalogHandlerDeps }
+
+const VALID_RANGES = new Set<AnalyticsRange>(['24h', '7d', '30d', '90d', 'all'])
+const RANGE_OPTIONS: AnalyticsRange[] = ['24h', '7d', '30d', '90d', 'all']
+
+const CATEGORY_SUGGESTIONS: Record<string, string[]> = {
+	revenue: [
+		'revenue/daily',
+		'revenue/products',
+		'attribution/sources',
+		'correlation/traffic-revenue',
+	],
+	attribution: [
+		'attribution/funnel',
+		'attribution/sources',
+		'attribution/coverage',
+		'correlation/traffic-revenue',
+	],
+	traffic: [
+		'traffic/daily',
+		'traffic/sources',
+		'correlation/traffic-revenue',
+		'correlation/youtube-revenue',
+	],
+	youtube: [
+		'youtube/videos',
+		'youtube/daily',
+		'youtube/sources',
+		'correlation/youtube-revenue',
+	],
+	correlation: [
+		'summary',
+		'attribution/funnel',
+		'youtube',
+		'correlation/survey-revenue',
+	],
+	survey: [
+		'surveys',
+		'surveys/list',
+		'surveys/daily',
+		'surveys/questions',
+		'surveys/responses',
+	],
+}
+
+const corsHeaders = {
+	'Access-Control-Allow-Origin': '*',
+	'Access-Control-Allow-Methods': 'GET, OPTIONS',
+	'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+}
+
+function parseRange(raw?: string | null): AnalyticsRange {
+	if (raw && VALID_RANGES.has(raw as AnalyticsRange)) {
+		return raw as AnalyticsRange
+	}
+
+	return '30d'
+}
+
+function getMeta(data: unknown, queryTimeMs: number, truncated: boolean) {
+	return {
+		totalRows: Array.isArray(data) ? data.length : 1,
+		truncated,
+		queryTimeMs,
+	}
+}
+
+/**
+ * Creates a Next.js App Router GET handler that serves a HATEOAS-style
+ * analytics catalog and surface query API.
+ *
+ * @param deps - Handler dependencies including engine, access check, and
+ *   optional logger and app metadata
+ * @returns An object with `GET` and `OPTIONS` Next.js route handlers
+ */
+export function createAnalyticsCatalogHandler(deps: CatalogHandlerDeps) {
+	const { engine, checkAccess, logger, appName, baseUrl } = deps
+
+	const catalog = engine.getCatalog()
+	const catalogByName = Object.fromEntries(
+		catalog.map((entry) => [entry.name, entry]),
+	) as Record<string, SurfaceEntry>
+
+	function buildContextualNextActions(
+		surface: string,
+		range: AnalyticsRange,
+		endpointPath: string,
+	) {
+		const entry = catalogByName[surface]
+		if (!entry) return []
+		const suggestions = CATEGORY_SUGGESTIONS[entry.category] ?? []
+
+		return suggestions
+			.filter((name) => name !== surface)
+			.slice(0, 4)
+			.map((name) => ({
+				command: `GET ${endpointPath}?surface=${name}&range=<range>`,
+				description: catalogByName[name]?.description ?? name,
+				params: {
+					range: {
+						value: range,
+						enum: RANGE_OPTIONS,
+					},
+				},
+			}))
+	}
+
+	const OPTIONS = () => NextResponse.json({}, { headers: corsHeaders })
+
+	const GET = async (request: NextRequest) => {
+		const requestUrl = new URL(request.url)
+		const resolvedBase = baseUrl ?? `${requestUrl.protocol}//${requestUrl.host}`
+		const endpointPath = `${requestUrl.pathname}`
+		const appLabel = appName ?? 'Analytics'
+
+		const access = await checkAccess(request)
+
+		if (!access.authorized) {
+			if (logger) {
+				void logger.warn('api.analytics.access-denied', {
+					userId: access.user?.id ?? null,
+					email: access.user?.email ?? null,
+					authMethod: access.authMethod ?? 'unknown',
+					hasAuthorization: false,
+				})
+			}
+
+			return NextResponse.json(
+				{
+					ok: false,
+					endpoint: endpointPath,
+					error: {
+						message: 'Unauthorized',
+						code: 'AUTH_REQUIRED',
+					},
+					fix: 'Authenticate with an admin device token or an admin session cookie.',
+					next_actions: [
+						{
+							command: 'GET /api/coursebuilder/devices',
+							description:
+								'Start device verification flow to obtain a Bearer token',
+						},
+						{
+							command: 'GET /login',
+							description: 'Log in as an admin to use session-based auth',
+						},
+					],
+				},
+				{ status: 401, headers: corsHeaders },
+			)
+		}
+
+		const { searchParams } = requestUrl
+		const rawSurface = searchParams.get('surface')
+
+		if (!rawSurface) {
+			return NextResponse.json(
+				{
+					ok: true,
+					endpoint: endpointPath,
+					description: `${appLabel} analytics — revenue, attribution, traffic, YouTube, and content correlation`,
+					notes: [
+						'YouTube surfaces are useful for correlation/content analysis but lag by about 48 hours.',
+					],
+					surfaces: catalog,
+					_links: {
+						self: { href: `${resolvedBase}${endpointPath}` },
+					},
+					next_actions: [
+						{
+							command: `GET ${endpointPath}?surface=<surface>&range=<range>&limit=<limit>`,
+							description: 'Query a specific analytics surface',
+							params: {
+								surface: {
+									required: true,
+									enum: catalog.map((entry) => entry.name),
+									description: 'Analytics surface to query',
+								},
+								range: {
+									default: '30d',
+									enum: RANGE_OPTIONS,
+									description: 'Time range',
+								},
+								limit: {
+									default: '20',
+									description:
+										'Max rows for surfaces that support it (max 100)',
+								},
+							},
+						},
+					],
+				},
+				{ headers: corsHeaders },
+			)
+		}
+
+		if (!(rawSurface in catalogByName)) {
+			return NextResponse.json(
+				{
+					ok: false,
+					endpoint: endpointPath,
+					error: {
+						message: `Unknown surface: ${rawSurface}`,
+						code: 'INVALID_SURFACE',
+					},
+					fix: `Hit GET ${endpointPath} with no params for the full surface catalog.`,
+					next_actions: [
+						{
+							command: `GET ${endpointPath}`,
+							description: 'Browse the full analytics surface catalog',
+						},
+					],
+				},
+				{ status: 400, headers: corsHeaders },
+			)
+		}
+
+		const surface = rawSurface
+		const range = parseRange(searchParams.get('range'))
+		const limit = Math.min(Number(searchParams.get('limit') ?? 20), 100)
+
+		if (logger) {
+			logger.info('api.analytics.query', {
+				userId: access.user?.id ?? null,
+				email: access.user?.email ?? null,
+				authMethod: access.authMethod ?? 'unknown',
+				surface,
+				range,
+				limit,
+			})
+		}
+
+		const result = await engine.query(surface, { range, limit })
+
+		if (!result.ok) {
+			if (logger) {
+				logger.error('api.analytics.error', {
+					userId: access.user?.id ?? null,
+					surface,
+					range,
+					code: result.error.code,
+					error: result.error.message,
+				})
+			}
+
+			return NextResponse.json(
+				{
+					ok: false,
+					endpoint: endpointPath,
+					surface,
+					error: result.error,
+					fix: result.fix,
+					next_actions: buildContextualNextActions(
+						surface,
+						range,
+						endpointPath,
+					),
+				},
+				{
+					status: result.error.code.endsWith('_UNAVAILABLE') ? 503 : 500,
+					headers: corsHeaders,
+				},
+			)
+		}
+
+		return NextResponse.json(
+			{
+				ok: true,
+				endpoint: endpointPath,
+				surface,
+				range: result.range,
+				description: catalogByName[surface]?.description,
+				data: result.data,
+				meta: getMeta(
+					result.data,
+					result.meta.queryTimeMs,
+					result.meta.truncated,
+				),
+				_links: {
+					self: {
+						href: `${resolvedBase}${endpointPath}?surface=${surface}&range=${range}`,
+					},
+					catalog: { href: `${resolvedBase}${endpointPath}` },
+				},
+				next_actions: buildContextualNextActions(surface, range, endpointPath),
+			},
+			{ headers: corsHeaders },
+		)
+	}
+
+	return { GET, OPTIONS }
+}

package/src/api/index.ts

@@ -0,0 +1,4 @@
+export { createAnalyticsCatalogHandler } from './catalog-handler'
+export type { CatalogHandlerDeps } from './catalog-handler'
+export { createTokenHandler } from './token-handler'
+export type { TokenHandlerDeps } from './token-handler'

package/src/api/token-handler.ts

@@ -0,0 +1,71 @@
+import { NextRequest, NextResponse } from 'next/server'
+
+interface TokenHandlerDeps {
+	db: { insert: (table: any) => { values: (data: any) => Promise<any> } }
+	deviceAccessToken: unknown
+	checkAccess: (request: Request) => Promise<{
+		authorized: boolean
+		userId?: string
+		user?: { email?: string; [key: string]: unknown } | null
+	}>
+	ttlHours?: number
+	logger?: {
+		info: (message: string, data?: Record<string, unknown>) => unknown
+		warn: (message: string, data?: Record<string, unknown>) => unknown
+		error: (message: string, data?: Record<string, unknown>) => unknown
+	}
+}
+
+export type { TokenHandlerDeps }
+
+/**
+ * Creates a Next.js App Router POST handler that generates short-lived
+ * device access tokens for analytics API authentication.
+ *
+ * Tokens are stored with only `token` and `userId`. Expiry is **not**
+ * stored in the database — it is enforced at lookup time by comparing
+ * the row's `createdAt` timestamp against the configured TTL. Each
+ * app's `getUserAbilityForRequest` must enforce this check.
+ *
+ * @param deps - Handler dependencies including db, deviceAccessToken schema
+ *   table, an access-check function, and optional TTL and logger overrides
+ * @returns An object with a `POST` Next.js route handler
+ */
+export function createTokenHandler(deps: TokenHandlerDeps) {
+	const { db, deviceAccessToken, checkAccess, logger } = deps
+	const ttlHours = deps.ttlHours ?? 24
+	const ttlLabel = `${ttlHours} hours`
+
+	const POST = async (request: NextRequest) => {
+		const access = await checkAccess(request)
+
+		if (!access.authorized || !access.userId) {
+			return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+		}
+
+		const userId = access.userId
+		const token = crypto.randomUUID()
+
+		await db.insert(deviceAccessToken).values({
+			token,
+			userId,
+		})
+
+		if (logger) {
+			void logger.info('api.analytics.token-generated', {
+				userId,
+				email: access.user?.email ?? null,
+				ttlHours,
+			})
+		}
+
+		return NextResponse.json({
+			token,
+			ttl: `${ttlHours}h`,
+			ttlLabel,
+			expiresAt: new Date(Date.now() + ttlHours * 60 * 60 * 1000).toISOString(),
+		})
+	}
+
+	return { POST }
+}

package/src/catalog.ts

@@ -0,0 +1,223 @@
+import type { SurfaceName } from './types'
+
+export interface SurfaceEntry {
+	name: SurfaceName
+	description: string
+	category:
+		| 'revenue'
+		| 'attribution'
+		| 'traffic'
+		| 'youtube'
+		| 'correlation'
+		| 'survey'
+	provider: 'database' | 'ga4' | 'youtube' | 'derived' | 'newsletter' | 'survey'
+	fn: string
+	unavailableFix?: string
+}
+
+export const catalog: Record<SurfaceName, SurfaceEntry> = {
+	summary: {
+		name: 'summary',
+		description: 'Revenue overview: total, purchase count, AOV',
+		category: 'revenue',
+		provider: 'database',
+		fn: 'getRevenueSummary',
+	},
+	'revenue/daily': {
+		name: 'revenue/daily',
+		description: 'Revenue and purchase count per day',
+		category: 'revenue',
+		provider: 'database',
+		fn: 'getRevenueByDay',
+	},
+	'revenue/products': {
+		name: 'revenue/products',
+		description: 'Revenue grouped by product',
+		category: 'revenue',
+		provider: 'database',
+		fn: 'getRevenueByProduct',
+	},
+	'revenue/countries': {
+		name: 'revenue/countries',
+		description: 'Revenue grouped by country',
+		category: 'revenue',
+		provider: 'database',
+		fn: 'getRevenueByCountry',
+	},
+	'purchases/recent': {
+		name: 'purchases/recent',
+		description: 'Last N purchases',
+		category: 'revenue',
+		provider: 'database',
+		fn: 'getRecentPurchases',
+	},
+	attribution: {
+		name: 'attribution',
+		description: 'Attribution event counts by type',
+		category: 'attribution',
+		provider: 'database',
+		fn: 'getAttributionSummary',
+	},
+	'attribution/shortlinks': {
+		name: 'attribution/shortlinks',
+		description: 'Per-shortlink click performance',
+		category: 'attribution',
+		provider: 'database',
+		fn: 'getShortlinkPerformance',
+	},
+	'attribution/sources': {
+		name: 'attribution/sources',
+		description: 'Revenue by first-touch source/medium/campaign',
+		category: 'attribution',
+		provider: 'database',
+		fn: 'getRevenueBySource',
+	},
+	'attribution/funnel': {
+		name: 'attribution/funnel',
+		description: 'Signup → purchase conversion funnel',
+		category: 'attribution',
+		provider: 'database',
+		fn: 'getConversionFunnel',
+	},
+	'attribution/content': {
+		name: 'attribution/content',
+		description: 'Content consumed by purchasers',
+		category: 'attribution',
+		provider: 'database',
+		fn: 'getContentPurchaseCorrelation',
+	},
+	'attribution/coverage': {
+		name: 'attribution/coverage',
+		description: 'Attributed vs dark revenue',
+		category: 'attribution',
+		provider: 'database',
+		fn: 'getAttributedRevenueSummary',
+	},
+	traffic: {
+		name: 'traffic',
+		description: 'GA4 traffic overview',
+		category: 'traffic',
+		provider: 'ga4',
+		fn: 'getTrafficOverview',
+	},
+	'traffic/daily': {
+		name: 'traffic/daily',
+		description: 'GA4 daily sessions',
+		category: 'traffic',
+		provider: 'ga4',
+		fn: 'getSessionsByDay',
+	},
+	'traffic/pages': {
+		name: 'traffic/pages',
+		description: 'Top pages by pageviews',
+		category: 'traffic',
+		provider: 'ga4',
+		fn: 'getTopPages',
+	},
+	'traffic/sources': {
+		name: 'traffic/sources',
+		description: 'Traffic sources',
+		category: 'traffic',
+		provider: 'ga4',
+		fn: 'getTrafficSources',
+	},
+	youtube: {
+		name: 'youtube',
+		description: 'Channel overview (≈48h lag)',
+		category: 'youtube',
+		provider: 'youtube',
+		fn: 'getChannelOverview',
+		unavailableFix: 'Complete OAuth at /api/analytics/youtube-auth',
+	},
+	'youtube/videos': {
+		name: 'youtube/videos',
+		description: 'Per-video performance (≈48h lag)',
+		category: 'youtube',
+		provider: 'youtube',
+		fn: 'getVideoPerformance',
+		unavailableFix: 'Complete OAuth at /api/analytics/youtube-auth',
+	},
+	'youtube/daily': {
+		name: 'youtube/daily',
+		description: 'Daily views + watch minutes (≈48h lag)',
+		category: 'youtube',
+		provider: 'youtube',
+		fn: 'getChannelTimeseries',
+		unavailableFix: 'Complete OAuth at /api/analytics/youtube-auth',
+	},
+	'youtube/sources': {
+		name: 'youtube/sources',
+		description: 'YouTube traffic sources (≈48h lag)',
+		category: 'youtube',
+		provider: 'youtube',
+		fn: 'getYouTubeTrafficSources',
+		unavailableFix: 'Complete OAuth at /api/analytics/youtube-auth',
+	},
+	'correlation/traffic-revenue': {
+		name: 'correlation/traffic-revenue',
+		description: 'GA4 sessions + revenue by day',
+		category: 'correlation',
+		provider: 'derived',
+		fn: 'getTrafficRevenueCorrelation',
+	},
+	'correlation/youtube-revenue': {
+		name: 'correlation/youtube-revenue',
+		description: 'YouTube (≈48h lag) + GA4 + revenue overlay',
+		category: 'correlation',
+		provider: 'derived',
+		fn: 'getYouTubeRevenueCorrelation',
+	},
+	surveys: {
+		name: 'surveys',
+		description: 'Survey overview: total surveys, responses, respondents',
+		category: 'survey',
+		provider: 'survey',
+		fn: 'getSurveySummary',
+	},
+	'surveys/list': {
+		name: 'surveys/list',
+		description: 'All surveys with response counts',
+		category: 'survey',
+		provider: 'survey',
+		fn: 'getSurveyList',
+	},
+	'surveys/daily': {
+		name: 'surveys/daily',
+		description: 'Daily survey response volume',
+		category: 'survey',
+		provider: 'survey',
+		fn: 'getSurveyResponsesByDay',
+	},
+	'surveys/questions': {
+		name: 'surveys/questions',
+		description: 'Top questions by response count with answer distribution',
+		category: 'survey',
+		provider: 'survey',
+		fn: 'getSurveyQuestionBreakdown',
+	},
+	'surveys/responses': {
+		name: 'surveys/responses',
+		description:
+			'Individual survey responses as flat rows (multi-choice and open-ended)',
+		category: 'survey',
+		provider: 'survey',
+		fn: 'getSurveyResponses',
+	},
+	'attribution/email-campaigns': {
+		name: 'attribution/email-campaigns',
+		description:
+			'Kit email broadcasts → shortlink clicks → signups → purchases → revenue per campaign',
+		category: 'attribution',
+		provider: 'newsletter',
+		fn: 'getEmailCampaignAttribution',
+	},
+	'correlation/survey-revenue': {
+		name: 'correlation/survey-revenue',
+		description: 'Survey respondents → purchase conversion by question/answer',
+		category: 'correlation',
+		provider: 'derived',
+		fn: 'getSurveyRevenueCorrelation',
+	},
+} as const satisfies Record<SurfaceName, SurfaceEntry>
+
+export const ANALYTICS_CATALOG = catalog