@coursebuilder/analytics 1.1.0

package/src/providers/mux.ts

@@ -0,0 +1,438 @@
+import { sql } from 'drizzle-orm'
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type TimeRange = '7:days' | '30:days' | '90:days'
+
+/** Ranges available on the Top Videos table (independent from page-level range) */
+export type VideoTableRange = '24:hours' | '7:days' | '30:days' | '90:days'
+
+export interface MuxOverallResponse {
+	data: {
+		value: number
+		total_watch_time: number
+		total_playing_time: number
+		total_views: number
+		global_value: number | null
+	}
+	timeframe: [number, number]
+}
+
+export interface MuxTimeseriesResponse {
+	data: [string, number | null, number | null][]
+	timeframe: [number, number]
+	total_row_count: number
+}
+
+export interface MuxBreakdownItem {
+	views: number
+	value: number
+	total_watch_time: number
+	total_playing_time: number
+	negative_impact: number | null
+	field: string
+}
+
+export interface MuxBreakdownResponse {
+	data: MuxBreakdownItem[]
+	timeframe: [number, number]
+	total_row_count: number
+}
+
+export interface VideoDashboardData {
+	overview: {
+		totalViews: number
+		uniqueViewers: number
+		totalWatchTimeMs: number
+		totalPlayingTimeMs: number
+		viewerExperienceScore: number
+		globalExperienceScore: number | null
+	}
+	watchTimeSeries: {
+		date: string
+		watchTimeMs: number
+	}[]
+	topVideos: {
+		title: string
+		views: number
+		watchTimeMs: number
+		playingTimeMs: number
+	}[]
+	countries: {
+		country: string
+		views: number
+		watchTimeMs: number
+	}[]
+}
+
+export type VideoDetailBreakdowns = {
+	countries: {
+		country: string
+		views: number
+		watchTimeMs: number
+	}[]
+	timeseries: {
+		date: string
+		views: number
+	}[]
+}
+
+export interface MuxProviderConfig {
+	tokenId: string
+	tokenSecret: string
+}
+
+export interface MuxDbDeps {
+	db: any
+	contentResource: any
+}
+
+// ─── Factory ─────────────────────────────────────────────────────────────────
+
+/**
+ * Creates a Mux analytics provider with injected credentials.
+ * Optionally accepts db dependencies for thumbnail lookups that
+ * require querying ContentResource records.
+ *
+ * @param config - Mux Data API token configuration
+ * @param dbDeps - Optional drizzle db + contentResource table for thumbnail queries
+ */
+export function createMuxProvider(
+	config: MuxProviderConfig,
+	dbDeps?: MuxDbDeps,
+) {
+	const MUX_DATA_BASE = 'https://api.mux.com/data/v1'
+
+	function getAuthHeader(): string {
+		return `Basic ${Buffer.from(
+			`${config.tokenId}:${config.tokenSecret}`,
+		).toString('base64')}`
+	}
+
+	async function muxDataFetch<T>(
+		path: string,
+		params?: Record<string, string | string[]>,
+	): Promise<T> {
+		const url = new URL(`${MUX_DATA_BASE}${path}`)
+		if (params) {
+			for (const [key, value] of Object.entries(params)) {
+				if (Array.isArray(value)) {
+					for (const v of value) {
+						url.searchParams.append(key, v)
+					}
+				} else {
+					url.searchParams.set(key, value)
+				}
+			}
+		}
+
+		const response = await fetch(url.toString(), {
+			headers: {
+				Authorization: getAuthHeader(),
+				'Content-Type': 'application/json',
+			},
+			next: { revalidate: 300 }, // cache 5 minutes
+		} as RequestInit)
+
+		if (!response.ok) {
+			throw new Error(
+				`Mux Data API error: ${response.status} ${response.statusText}`,
+			)
+		}
+
+		return response.json() as Promise<T>
+	}
+
+	// ─── Comparison (unique viewers) ─────────────────────────────────────────
+
+	interface MuxComparisonItem {
+		name: string
+		watch_time?: number
+		view_count?: number
+		unique_viewers?: number
+		started_views?: number
+		ended_views?: number
+		[key: string]: unknown
+	}
+
+	interface MuxComparisonResponse {
+		data: MuxComparisonItem[]
+		timeframe: [number, number]
+		total_row_count: number | null
+	}
+
+	async function getComparisonTotals(timeRange: TimeRange = '30:days') {
+		const resp = await muxDataFetch<MuxComparisonResponse>(
+			'/metrics/comparison',
+			{ 'timeframe[]': timeRange },
+		)
+		const totals = resp.data.find((d) => d.name === 'totals')
+		return {
+			uniqueViewers: totals?.unique_viewers ?? 0,
+			viewCount: totals?.view_count ?? 0,
+			watchTimeMs: totals?.watch_time ?? 0,
+		}
+	}
+
+	// ─── API Functions ────────────────────────────────────────────────────────
+
+	async function getViewsOverall(timeRange: TimeRange = '30:days') {
+		return muxDataFetch<MuxOverallResponse>('/metrics/views/overall', {
+			'timeframe[]': timeRange,
+		})
+	}
+
+	async function getViewerExperienceScore(timeRange: TimeRange = '30:days') {
+		return muxDataFetch<MuxOverallResponse>(
+			'/metrics/viewer_experience_score/overall',
+			{ 'timeframe[]': timeRange },
+		)
+	}
+
+	async function getViewsTimeseries(timeRange: TimeRange = '30:days') {
+		return muxDataFetch<MuxTimeseriesResponse>('/metrics/views/timeseries', {
+			'timeframe[]': timeRange,
+			group_by: 'day',
+		})
+	}
+
+	/**
+	 * Fetch watch time (playing_time) timeseries grouped by day.
+	 * Mux returns [date, totalPlayingTimeMs, viewCount] tuples.
+	 * The value IS the total playing time in ms (not the average).
+	 */
+	async function getWatchTimeTimeseries(timeRange: TimeRange = '30:days') {
+		return muxDataFetch<MuxTimeseriesResponse>(
+			'/metrics/playing_time/timeseries',
+			{
+				'timeframe[]': timeRange,
+				group_by: 'day',
+			},
+		)
+	}
+
+	async function getVideoBreakdown(
+		timeRange: TimeRange = '30:days',
+		limit: number = 25,
+	) {
+		return muxDataFetch<MuxBreakdownResponse>('/metrics/views/breakdown', {
+			'timeframe[]': timeRange,
+			group_by: 'video_title',
+			order_by: 'views',
+			order_direction: 'desc',
+			limit: String(limit),
+		})
+	}
+
+	/**
+	 * Standalone video breakdown fetcher for the Top Videos table's
+	 * independent time-range tabs. Accepts VideoTableRange.
+	 */
+	async function getVideoBreakdownForRange(
+		timeRange: VideoTableRange,
+		limit: number = 50,
+	) {
+		return muxDataFetch<MuxBreakdownResponse>('/metrics/views/breakdown', {
+			'timeframe[]': timeRange,
+			group_by: 'video_title',
+			order_by: 'views',
+			order_direction: 'desc',
+			limit: String(limit),
+		})
+	}
+
+	async function getCountryBreakdown(
+		timeRange: TimeRange = '30:days',
+		limit: number = 10,
+	) {
+		return muxDataFetch<MuxBreakdownResponse>('/metrics/views/breakdown', {
+			'timeframe[]': timeRange,
+			group_by: 'country',
+			order_by: 'views',
+			order_direction: 'desc',
+			limit: String(limit),
+		})
+	}
+
+	async function getVideoDetailBreakdowns(
+		videoTitle: string,
+		timeRange: TimeRange = '30:days',
+	): Promise<VideoDetailBreakdowns> {
+		const filter = `video_title:${videoTitle}`
+		const [countries, timeseries] = await Promise.all([
+			muxDataFetch<MuxBreakdownResponse>('/metrics/views/breakdown', {
+				'timeframe[]': timeRange,
+				group_by: 'country',
+				order_by: 'views',
+				order_direction: 'desc',
+				limit: '8',
+				'filters[]': filter,
+			}),
+			muxDataFetch<MuxTimeseriesResponse>('/metrics/views/timeseries', {
+				'timeframe[]': timeRange,
+				group_by: 'day',
+				'filters[]': filter,
+			}),
+		])
+
+		return {
+			countries: countries.data.map((c) => ({
+				country: c.field,
+				views: c.views,
+				watchTimeMs: c.total_watch_time,
+			})),
+			timeseries: timeseries.data.map(([date, value]) => ({
+				date,
+				views: value ?? 0,
+			})),
+		}
+	}
+
+	// ─── Aggregate fetcher ────────────────────────────────────────────────────
+
+	async function getVideoDashboardData(
+		timeRange: TimeRange = '30:days',
+	): Promise<VideoDashboardData> {
+		const [views, experience, comparison, watchTime, videos, countries] =
+			await Promise.all([
+				getViewsOverall(timeRange),
+				getViewerExperienceScore(timeRange),
+				getComparisonTotals(timeRange),
+				getWatchTimeTimeseries(timeRange),
+				getVideoBreakdown(timeRange, 50),
+				getCountryBreakdown(timeRange, 15),
+			])
+
+		return {
+			overview: {
+				totalViews: views.data.total_views,
+				uniqueViewers: comparison.uniqueViewers,
+				totalWatchTimeMs: views.data.total_watch_time,
+				totalPlayingTimeMs: views.data.total_playing_time,
+				viewerExperienceScore: experience.data.value,
+				globalExperienceScore: experience.data.global_value,
+			},
+			watchTimeSeries: watchTime.data.map(([date, totalMs]) => ({
+				date,
+				// Mux playing_time timeseries: value is total playing time in ms
+				watchTimeMs: totalMs ?? 0,
+			})),
+			topVideos: videos.data
+				.filter((v) => v.field !== '')
+				.map((v) => ({
+					title: v.field,
+					views: v.views,
+					watchTimeMs: v.total_watch_time,
+					playingTimeMs: v.total_playing_time,
+				})),
+			countries: countries.data.map((c) => ({
+				country: c.field,
+				views: c.views,
+				watchTimeMs: c.total_watch_time,
+			})),
+		}
+	}
+
+	/**
+	 * Resolve video titles to Mux thumbnail URLs.
+	 * 1. Break down by video_id to get ContentResource IDs for top videos
+	 * 2. Look up playback IDs from ContentResource.fields.muxPlaybackId
+	 * 3. Build image.mux.com thumbnail URLs
+	 * Returns Record<title, thumbnailUrl>.
+	 * Requires dbDeps to be provided at factory construction time.
+	 */
+	async function getVideoThumbnails(
+		timeRange: TimeRange = '30:days',
+		limit: number = 10,
+	): Promise<Record<string, string>> {
+		if (!dbDeps) {
+			throw new Error(
+				'getVideoThumbnails requires dbDeps (db + contentResource) ' +
+					'to be provided to createMuxProvider',
+			)
+		}
+
+		const { db, contentResource } = dbDeps
+
+		// Get breakdown by both video_id and video_title
+		const [byId, byTitle] = await Promise.all([
+			muxDataFetch<MuxBreakdownResponse>('/metrics/views/breakdown', {
+				'timeframe[]': timeRange,
+				group_by: 'video_id',
+				order_by: 'views',
+				order_direction: 'desc',
+				limit: String(limit),
+			}),
+			muxDataFetch<MuxBreakdownResponse>('/metrics/views/breakdown', {
+				'timeframe[]': timeRange,
+				group_by: 'video_title',
+				order_by: 'views',
+				order_direction: 'desc',
+				limit: String(limit),
+			}),
+		])
+
+		// video_id breakdown gives ContentResource IDs — look up playback IDs
+		const videoIds = byId.data
+			.filter((v) => v.field && v.field !== '')
+			.map((v) => v.field)
+
+		if (videoIds.length === 0) return {}
+
+		const rows = await db
+			.select({
+				id: contentResource.id,
+				playbackId:
+					sql<string>`JSON_UNQUOTE(JSON_EXTRACT(${contentResource.fields}, '$.muxPlaybackId'))`.as(
+						'playbackId',
+					),
+			})
+			.from(contentResource)
+			.where(
+				sql`${contentResource.id} IN (${sql.join(
+					videoIds.map((id: string) => sql`${id}`),
+					sql`, `,
+				)})`,
+			)
+
+		// Map video_id → playbackId
+		const idToPlayback = new Map<string, string>()
+		for (const r of rows) {
+			if (r.playbackId && r.playbackId !== 'null') {
+				idToPlayback.set(r.id, r.playbackId)
+			}
+		}
+
+		// Match by position: byId and byTitle are both sorted by views desc,
+		// so position i in byId corresponds to position i in byTitle
+		const result: Record<string, string> = {}
+		for (let i = 0; i < Math.min(byId.data.length, byTitle.data.length); i++) {
+			const videoId = byId.data[i]?.field
+			const title = byTitle.data[i]?.field
+			if (!videoId || !title) continue
+			const playbackId = idToPlayback.get(videoId)
+			if (playbackId) {
+				result[title] =
+					`https://image.mux.com/${playbackId}/thumbnail.jpg?width=240&height=135&fit_mode=smartcrop`
+			}
+		}
+
+		return result
+	}
+
+	return {
+		getComparisonTotals,
+		getViewsOverall,
+		getViewerExperienceScore,
+		getViewsTimeseries,
+		getWatchTimeTimeseries,
+		getVideoBreakdown,
+		getVideoBreakdownForRange,
+		getCountryBreakdown,
+		getVideoDetailBreakdowns,
+		getVideoDashboardData,
+		getVideoThumbnails,
+	}
+}
+
+export type MuxAnalyticsProvider = ReturnType<typeof createMuxProvider>