@coursebuilder/analytics 1.1.0

package/src/providers/derived.ts

@@ -0,0 +1,79 @@
+import type { GA4TimeRange } from './ga4'
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type AnalyticsRange = '24h' | '7d' | '30d' | '90d' | 'all'
+
+export interface TrafficRevenueCorrelation {
+	traffic: {
+		date: string
+		sessions: number
+		users: number
+		pageviews: number
+	}[]
+	revenue: {
+		date: string
+		revenue: number
+		count: number
+	}[]
+}
+
+export interface DerivedProviderDeps {
+	database: {
+		getRevenueByDay: (range: AnalyticsRange) => Promise<
+			{
+				date: string
+				revenue: number
+				count: number
+			}[]
+		>
+	}
+	ga4: {
+		getSessionsByDay: (range: GA4TimeRange) => Promise<
+			{
+				date: string
+				sessions: number
+				users: number
+				pageviews: number
+			}[]
+		>
+	}
+}
+
+// ─── Factory ─────────────────────────────────────────────────────────────────
+
+/**
+ * Creates a derived analytics provider that combines data from multiple
+ * sources (database + GA4) to compute correlation metrics.
+ *
+ * @param deps - Provider dependencies (database and ga4 providers)
+ */
+export function createDerivedProvider(deps: DerivedProviderDeps) {
+	const { database, ga4 } = deps
+
+	function toGA4Range(range: AnalyticsRange): GA4TimeRange {
+		if (range === 'all') return '90d'
+		return range
+	}
+
+	/**
+	 * Correlates GA4 traffic sessions by day with revenue by day,
+	 * enabling side-by-side analysis of traffic and revenue trends.
+	 */
+	async function getTrafficRevenueCorrelation(
+		range: AnalyticsRange,
+	): Promise<TrafficRevenueCorrelation> {
+		const [traffic, revenue] = await Promise.all([
+			ga4.getSessionsByDay(toGA4Range(range)),
+			database.getRevenueByDay(range),
+		])
+
+		return { traffic, revenue }
+	}
+
+	return {
+		getTrafficRevenueCorrelation,
+	}
+}
+
+export type DerivedAnalyticsProvider = ReturnType<typeof createDerivedProvider>

package/src/providers/ga4.ts

@@ -0,0 +1,173 @@
+import { BetaAnalyticsDataClient } from '@google-analytics/data'
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type GA4TimeRange = '24h' | '7d' | '30d' | '90d'
+
+export interface GA4ProviderConfig {
+	propertyId: string
+	clientEmail: string
+	privateKey: string
+}
+
+// ─── Factory ─────────────────────────────────────────────────────────────────
+
+/**
+ * Creates a GA4 analytics provider with injected credentials.
+ * Lazily initializes the BetaAnalyticsDataClient on first use.
+ *
+ * @param config - GA4 credentials and property configuration
+ */
+export function createGA4Provider(config: GA4ProviderConfig) {
+	const { propertyId, clientEmail, privateKey } = config
+
+	let _client: BetaAnalyticsDataClient | null = null
+
+	function getClient(): BetaAnalyticsDataClient {
+		if (!_client) {
+			_client = new BetaAnalyticsDataClient({
+				credentials: {
+					client_email: clientEmail,
+					private_key: privateKey.replace(/\\n/g, '\n'),
+				},
+			})
+		}
+		return _client
+	}
+
+	function rangeToDateRange(range: GA4TimeRange) {
+		const map: Record<GA4TimeRange, string> = {
+			'24h': '1daysAgo',
+			'7d': '7daysAgo',
+			'30d': '30daysAgo',
+			'90d': '90daysAgo',
+		}
+		return { startDate: map[range], endDate: 'today' }
+	}
+
+	// ─── Reports ──────────────────────────────────────────────────────────────
+
+	async function getTrafficOverview(range: GA4TimeRange = '30d') {
+		const client = getClient()
+
+		const [response] = await client.runReport({
+			property: `properties/${propertyId}`,
+			dateRanges: [rangeToDateRange(range)],
+			metrics: [
+				{ name: 'sessions' },
+				{ name: 'totalUsers' },
+				{ name: 'newUsers' },
+				{ name: 'screenPageViews' },
+				{ name: 'averageSessionDuration' },
+				{ name: 'bounceRate' },
+			],
+		})
+
+		const row = response?.rows?.[0]
+		if (!row) {
+			return {
+				sessions: 0,
+				totalUsers: 0,
+				newUsers: 0,
+				pageviews: 0,
+				avgSessionDuration: 0,
+				bounceRate: 0,
+			}
+		}
+
+		return {
+			sessions: Number(row.metricValues?.[0]?.value ?? 0),
+			totalUsers: Number(row.metricValues?.[1]?.value ?? 0),
+			newUsers: Number(row.metricValues?.[2]?.value ?? 0),
+			pageviews: Number(row.metricValues?.[3]?.value ?? 0),
+			avgSessionDuration: Number(row.metricValues?.[4]?.value ?? 0),
+			bounceRate: Number(row.metricValues?.[5]?.value ?? 0),
+		}
+	}
+
+	async function getTopPages(range: GA4TimeRange = '30d', limit = 20) {
+		const client = getClient()
+
+		const [response] = await client.runReport({
+			property: `properties/${propertyId}`,
+			dateRanges: [rangeToDateRange(range)],
+			dimensions: [{ name: 'pagePath' }],
+			metrics: [
+				{ name: 'screenPageViews' },
+				{ name: 'totalUsers' },
+				{ name: 'averageSessionDuration' },
+			],
+			orderBys: [{ metric: { metricName: 'screenPageViews' }, desc: true }],
+			limit,
+		})
+
+		return (
+			response?.rows?.map((row) => ({
+				path: row.dimensionValues?.[0]?.value ?? '',
+				pageviews: Number(row.metricValues?.[0]?.value ?? 0),
+				users: Number(row.metricValues?.[1]?.value ?? 0),
+				avgDuration: Number(row.metricValues?.[2]?.value ?? 0),
+			})) ?? []
+		)
+	}
+
+	async function getTrafficSources(range: GA4TimeRange = '30d', limit = 15) {
+		const client = getClient()
+
+		const [response] = await client.runReport({
+			property: `properties/${propertyId}`,
+			dateRanges: [rangeToDateRange(range)],
+			dimensions: [{ name: 'sessionSource' }, { name: 'sessionMedium' }],
+			metrics: [{ name: 'sessions' }, { name: 'totalUsers' }],
+			orderBys: [{ metric: { metricName: 'sessions' }, desc: true }],
+			limit,
+		})
+
+		return (
+			response?.rows?.map((row) => ({
+				source: row.dimensionValues?.[0]?.value ?? '(direct)',
+				medium: row.dimensionValues?.[1]?.value ?? '(none)',
+				sessions: Number(row.metricValues?.[0]?.value ?? 0),
+				users: Number(row.metricValues?.[1]?.value ?? 0),
+			})) ?? []
+		)
+	}
+
+	async function getSessionsByDay(range: GA4TimeRange = '30d') {
+		const client = getClient()
+
+		const [response] = await client.runReport({
+			property: `properties/${propertyId}`,
+			dateRanges: [rangeToDateRange(range)],
+			dimensions: [{ name: 'date' }],
+			metrics: [
+				{ name: 'sessions' },
+				{ name: 'totalUsers' },
+				{ name: 'screenPageViews' },
+			],
+			orderBys: [{ dimension: { dimensionName: 'date' }, desc: false }],
+		})
+
+		return (
+			response?.rows?.map((row) => {
+				const raw = row.dimensionValues?.[0]?.value ?? ''
+				const date = `${raw.slice(0, 4)}-${raw.slice(4, 6)}-${raw.slice(6, 8)}`
+				return {
+					date,
+					sessions: Number(row.metricValues?.[0]?.value ?? 0),
+					users: Number(row.metricValues?.[1]?.value ?? 0),
+					pageviews: Number(row.metricValues?.[2]?.value ?? 0),
+				}
+			}) ?? []
+		)
+	}
+
+	return {
+		getTrafficOverview,
+		getTopPages,
+		getTrafficSources,
+		getSessionsByDay,
+	}
+}
+
+export type GA4AnalyticsProvider = ReturnType<typeof createGA4Provider>

package/src/providers/index.ts

@@ -0,0 +1,44 @@
+// Provider implementations are exported from their individual sub-paths:
+//   @coursebuilder/analytics/providers/database
+//   @coursebuilder/analytics/providers/ga4
+//   @coursebuilder/analytics/providers/derived
+//   @coursebuilder/analytics/providers/mux
+//
+// This barrel re-exports the provider interface types and all factories.
+export type { AnalyticsProvider, ProviderMap } from '../engine'
+export {
+	createDatabaseProvider,
+	type DatabaseAnalyticsProvider,
+	type DatabaseAnalyticsSchema,
+	type AnalyticsTimeRange,
+	type AttributionTrail,
+	type AttributionTrailEvent,
+} from './database'
+export {
+	createGA4Provider,
+	type GA4AnalyticsProvider,
+	type GA4ProviderConfig,
+	type GA4TimeRange,
+} from './ga4'
+export {
+	createDerivedProvider,
+	type DerivedAnalyticsProvider,
+	type DerivedProviderDeps,
+	type AnalyticsRange,
+	type TrafficRevenueCorrelation,
+} from './derived'
+export {
+	createMuxProvider,
+	type MuxAnalyticsProvider,
+	type MuxProviderConfig,
+	type MuxDbDeps,
+	type VideoDashboardData,
+	type VideoDetailBreakdowns,
+	type TimeRange,
+	type VideoTableRange,
+	type MuxOverallResponse,
+	type MuxTimeseriesResponse,
+	type MuxBreakdownItem,
+	type MuxBreakdownResponse,
+} from './mux'
+export { createSurveyProvider, type SurveyAnalyticsProvider } from './survey'