@coursebuilder/analytics 1.1.0

package/src/providers/survey.ts

@@ -0,0 +1,487 @@
+import { and, count, eq, sql } from 'drizzle-orm'
+
+import type { AnalyticsRange } from '../types'
+
+// ─── Schema types ────────────────────────────────────────────────────────────
+
+/**
+ * Minimal column shape required from the contentResource table.
+ * We only reference the columns we actually query against.
+ */
+interface ContentResourceTable {
+	id: any
+	type: any
+	fields: any
+}
+
+/**
+ * Minimal column shape required from the contentResourceResource table.
+ */
+interface ContentResourceResourceTable {
+	resourceOfId: any
+	resourceId: any
+}
+
+/**
+ * Minimal column shape required from the questionResponse table.
+ */
+interface QuestionResponseTable {
+	id: any
+	surveyId: any
+	questionId: any
+	respondentKey: any
+	surveySessionId: any
+	userId: any
+	emailListSubscriberId: any
+	createdAt: any
+	updatedAt: any
+	fields: any
+}
+
+/**
+ * Minimal column shape required from the users table.
+ * Optional — only needed for getSurveyResponses to resolve user emails.
+ */
+interface UsersTable {
+	id: any
+	email: any
+}
+
+export interface SurveyAnalyticsSchema {
+	contentResource: ContentResourceTable
+	contentResourceResource: ContentResourceResourceTable
+	questionResponse: QuestionResponseTable
+	users?: UsersTable
+}
+
+type CanonicalSurveyRow = {
+	responseId: string
+	surveyId: string
+	surveyTitle: string | null
+	surveySlug: string | null
+	questionId: string
+	questionText: string | null
+	questionType: string | null
+	answer: string | null
+	respondentKey: string
+	surveySessionId: string | null
+	userId: string | null
+	userEmail: string | null
+	emailListSubscriberId: string | null
+	createdAt: Date | null
+	updatedAt: Date | null
+}
+
+// ─── Return type ─────────────────────────────────────────────────────────────
+
+export interface SurveyAnalyticsProvider {
+	getSurveySummary: (range?: AnalyticsRange) => Promise<{
+		totalSurveys: number
+		totalResponses: number
+		uniqueRespondents: number
+		avgResponsesPerSurvey: number
+	}>
+
+	getSurveyList: (range?: AnalyticsRange) => Promise<
+		Array<{
+			surveyId: string
+			surveyTitle: string
+			surveySlug: string
+			responses: number
+			uniqueRespondents: number
+			questionCount: number
+		}>
+	>
+
+	getSurveyResponsesByDay: (range?: AnalyticsRange) => Promise<
+		Array<{
+			date: string
+			responses: number
+		}>
+	>
+
+	getSurveyQuestionBreakdown: (
+		range?: AnalyticsRange,
+		limit?: number,
+	) => Promise<
+		Array<{
+			questionId: string
+			question: string
+			type: string | null
+			responses: number
+			uniqueRespondents: number
+			answerDistribution: Array<{ answer: string; count: number }>
+		}>
+	>
+
+	getSurveyResponses: (
+		range?: AnalyticsRange,
+		limit?: number,
+	) => Promise<
+		Array<{
+			responseId: string
+			surveyId: string
+			surveyTitle: string
+			surveySlug: string
+			questionId: string
+			questionText: string
+			questionType: string | null
+			answer: string
+			userId: string | null
+			userEmail: string | null
+			emailListSubscriberId: string | null
+			createdAt: string
+		}>
+	>
+}
+
+function normalizeRespondentKey(row: {
+	respondentKey: string | null
+	userId: string | null
+	emailListSubscriberId: string | null
+	surveySessionId: string | null
+}) {
+	if (row.respondentKey) return row.respondentKey
+	if (row.userId) return `user:${row.userId}`
+	if (row.emailListSubscriberId) {
+		return `subscriber:${row.emailListSubscriberId}`
+	}
+	if (row.surveySessionId) return `session:${row.surveySessionId}`
+	return null
+}
+
+function getRowTimestamp(row: {
+	updatedAt: Date | null
+	createdAt: Date | null
+}) {
+	const date = row.updatedAt ?? row.createdAt
+	return date instanceof Date ? date.getTime() : 0
+}
+
+function sortByNewest<
+	T extends { createdAt: Date | null; updatedAt: Date | null },
+>(rows: T[]) {
+	return [...rows].sort((a, b) => getRowTimestamp(b) - getRowTimestamp(a))
+}
+
+// ─── Factory ─────────────────────────────────────────────────────────────────
+
+/**
+ * Creates a survey analytics provider bound to the given Drizzle db instance
+ * and schema tables.
+ *
+ * @param db - Drizzle database instance
+ * @param schema - Object containing the required table references
+ */
+export function createSurveyProvider(
+	db: any,
+	schema: SurveyAnalyticsSchema,
+): SurveyAnalyticsProvider {
+	const { contentResource, contentResourceResource, questionResponse } = schema
+
+	// ─── Range helpers ───────────────────────────────────────────────────────
+
+	function rangeToInterval(range: AnalyticsRange): string {
+		switch (range) {
+			case '24h':
+				return '1 DAY'
+			case '7d':
+				return '7 DAY'
+			case '30d':
+				return '30 DAY'
+			case '90d':
+				return '90 DAY'
+			case 'all':
+				return '3650 DAY'
+		}
+	}
+
+	function rangeWhere(range: AnalyticsRange, column: any) {
+		return sql`${column} >= DATE_SUB(NOW(), INTERVAL ${sql.raw(rangeToInterval(range))})`
+	}
+
+	async function fetchCanonicalRows(range: AnalyticsRange) {
+		const { users } = schema
+
+		const rawRows = users
+			? await db
+					.select({
+						responseId: questionResponse.id,
+						surveyId: questionResponse.surveyId,
+						surveyTitle: sql<string>`JSON_UNQUOTE(JSON_EXTRACT(survey_cr.fields, '$.title'))`,
+						surveySlug: sql<string>`JSON_UNQUOTE(JSON_EXTRACT(survey_cr.fields, '$.slug'))`,
+						questionId: questionResponse.questionId,
+						questionText: sql<string>`JSON_UNQUOTE(JSON_EXTRACT(question_cr.fields, '$.question'))`,
+						questionType: sql<string>`JSON_UNQUOTE(JSON_EXTRACT(question_cr.fields, '$.type'))`,
+						answer: sql<string>`JSON_UNQUOTE(JSON_EXTRACT(${questionResponse.fields}, '$.answer'))`,
+						respondentKey: questionResponse.respondentKey,
+						surveySessionId: questionResponse.surveySessionId,
+						userId: questionResponse.userId,
+						userEmail: users.email,
+						emailListSubscriberId: questionResponse.emailListSubscriberId,
+						createdAt: questionResponse.createdAt,
+						updatedAt: questionResponse.updatedAt,
+					})
+					.from(questionResponse)
+					.leftJoin(
+						sql`${contentResource} AS survey_cr`,
+						sql`survey_cr.id = ${questionResponse.surveyId}`,
+					)
+					.leftJoin(
+						sql`${contentResource} AS question_cr`,
+						sql`question_cr.id = ${questionResponse.questionId}`,
+					)
+					.leftJoin(users, eq(questionResponse.userId, users.id))
+					.where(rangeWhere(range, questionResponse.createdAt))
+			: await db
+					.select({
+						responseId: questionResponse.id,
+						surveyId: questionResponse.surveyId,
+						surveyTitle: sql<string>`JSON_UNQUOTE(JSON_EXTRACT(survey_cr.fields, '$.title'))`,
+						surveySlug: sql<string>`JSON_UNQUOTE(JSON_EXTRACT(survey_cr.fields, '$.slug'))`,
+						questionId: questionResponse.questionId,
+						questionText: sql<string>`JSON_UNQUOTE(JSON_EXTRACT(question_cr.fields, '$.question'))`,
+						questionType: sql<string>`JSON_UNQUOTE(JSON_EXTRACT(question_cr.fields, '$.type'))`,
+						answer: sql<string>`JSON_UNQUOTE(JSON_EXTRACT(${questionResponse.fields}, '$.answer'))`,
+						respondentKey: questionResponse.respondentKey,
+						surveySessionId: questionResponse.surveySessionId,
+						userId: questionResponse.userId,
+						userEmail: sql<string | null>`NULL`,
+						emailListSubscriberId: questionResponse.emailListSubscriberId,
+						createdAt: questionResponse.createdAt,
+						updatedAt: questionResponse.updatedAt,
+					})
+					.from(questionResponse)
+					.leftJoin(
+						sql`${contentResource} AS survey_cr`,
+						sql`survey_cr.id = ${questionResponse.surveyId}`,
+					)
+					.leftJoin(
+						sql`${contentResource} AS question_cr`,
+						sql`question_cr.id = ${questionResponse.questionId}`,
+					)
+					.where(rangeWhere(range, questionResponse.createdAt))
+
+		const latestByAnswer = new Map<string, CanonicalSurveyRow>()
+
+		for (const row of rawRows) {
+			const respondentKey = normalizeRespondentKey(row)
+			if (!respondentKey) continue
+
+			const dedupeKey = `${row.surveyId}::${row.questionId}::${respondentKey}`
+			const current = latestByAnswer.get(dedupeKey)
+
+			if (!current || getRowTimestamp(row) >= getRowTimestamp(current)) {
+				latestByAnswer.set(dedupeKey, {
+					...row,
+					respondentKey,
+				})
+			}
+		}
+
+		return sortByNewest(Array.from(latestByAnswer.values()))
+	}
+
+	// ─── Survey Summary ──────────────────────────────────────────────────────
+
+	async function getSurveySummary(range: AnalyticsRange = '30d') {
+		const [surveyCount] = await db
+			.select({ total: count() })
+			.from(contentResource)
+			.where(eq(contentResource.type, 'survey'))
+
+		const canonicalRows = await fetchCanonicalRows(range)
+		const respondentKeys = new Set(
+			canonicalRows.map((row) => row.respondentKey),
+		)
+		const totalSurveys = surveyCount?.total ?? 0
+		const totalResponses = canonicalRows.length
+
+		return {
+			totalSurveys,
+			totalResponses,
+			uniqueRespondents: respondentKeys.size,
+			avgResponsesPerSurvey:
+				totalSurveys > 0 ? totalResponses / totalSurveys : 0,
+		}
+	}
+
+	// ─── Survey List ─────────────────────────────────────────────────────────
+
+	async function getSurveyList(range: AnalyticsRange = '30d') {
+		const canonicalRows = await fetchCanonicalRows(range)
+		const responsesBySurvey = new Map<
+			string,
+			{ responses: number; respondents: Set<string> }
+		>()
+
+		for (const row of canonicalRows) {
+			const current = responsesBySurvey.get(row.surveyId) ?? {
+				responses: 0,
+				respondents: new Set<string>(),
+			}
+			current.responses += 1
+			current.respondents.add(row.respondentKey)
+			responsesBySurvey.set(row.surveyId, current)
+		}
+
+		const surveys = await db
+			.select({
+				surveyId: contentResource.id,
+				surveyTitle: sql<string>`JSON_UNQUOTE(JSON_EXTRACT(${contentResource.fields}, '$.title'))`,
+				surveySlug: sql<string>`JSON_UNQUOTE(JSON_EXTRACT(${contentResource.fields}, '$.slug'))`,
+			})
+			.from(contentResource)
+			.where(eq(contentResource.type, 'survey'))
+
+		const questionCounts = await db
+			.select({
+				surveyId: contentResourceResource.resourceOfId,
+				questionCount: count(),
+			})
+			.from(contentResourceResource)
+			.innerJoin(
+				contentResource,
+				and(
+					eq(contentResourceResource.resourceId, contentResource.id),
+					eq(contentResource.type, 'question'),
+				),
+			)
+			.groupBy(contentResourceResource.resourceOfId)
+
+		const questionCountMap = new Map(
+			questionCounts.map((qc: { surveyId: string; questionCount: number }) => [
+				qc.surveyId,
+				qc.questionCount,
+			]),
+		)
+
+		return surveys
+			.map(
+				(s: {
+					surveyId: string
+					surveyTitle: string | null
+					surveySlug: string | null
+				}) => {
+					const counts = responsesBySurvey.get(s.surveyId)
+					return {
+						surveyId: s.surveyId,
+						surveyTitle: s.surveyTitle ?? '',
+						surveySlug: s.surveySlug ?? '',
+						responses: counts?.responses ?? 0,
+						uniqueRespondents: counts?.respondents.size ?? 0,
+						questionCount: questionCountMap.get(s.surveyId) ?? 0,
+					}
+				},
+			)
+			.sort(
+				(a: { responses: number }, b: { responses: number }) =>
+					b.responses - a.responses,
+			)
+	}
+
+	// ─── Daily Responses ─────────────────────────────────────────────────────
+
+	async function getSurveyResponsesByDay(range: AnalyticsRange = '30d') {
+		const canonicalRows = await fetchCanonicalRows(range)
+		const grouped = new Map<string, number>()
+
+		for (const row of canonicalRows) {
+			if (!(row.createdAt instanceof Date)) continue
+			const date = row.createdAt.toISOString().slice(0, 10)
+			grouped.set(date, (grouped.get(date) ?? 0) + 1)
+		}
+
+		return Array.from(grouped.entries())
+			.sort((entryA: [string, number], entryB: [string, number]) =>
+				entryA[0].localeCompare(entryB[0]),
+			)
+			.map(([date, responses]) => ({ date, responses }))
+	}
+
+	// ─── Question Breakdown ──────────────────────────────────────────────────
+
+	async function getSurveyQuestionBreakdown(
+		range: AnalyticsRange = '30d',
+		limit = 20,
+	) {
+		const canonicalRows = await fetchCanonicalRows(range)
+		const grouped = new Map<
+			string,
+			{
+				questionId: string
+				question: string
+				type: string | null
+				responses: number
+				respondents: Set<string>
+				answers: Map<string, number>
+			}
+		>()
+
+		for (const row of canonicalRows) {
+			const current = grouped.get(row.questionId) ?? {
+				questionId: row.questionId,
+				question: row.questionText ?? '',
+				type: row.questionType ?? null,
+				responses: 0,
+				respondents: new Set<string>(),
+				answers: new Map<string, number>(),
+			}
+
+			current.responses += 1
+			current.respondents.add(row.respondentKey)
+			const answer = row.answer ?? '(no answer)'
+			current.answers.set(answer, (current.answers.get(answer) ?? 0) + 1)
+			grouped.set(row.questionId, current)
+		}
+
+		return Array.from(grouped.values())
+			.sort(
+				(a: { responses: number }, b: { responses: number }) =>
+					b.responses - a.responses,
+			)
+			.slice(0, limit)
+			.map((entry) => ({
+				questionId: entry.questionId,
+				question: entry.question,
+				type: entry.type,
+				responses: entry.responses,
+				uniqueRespondents: entry.respondents.size,
+				answerDistribution: Array.from(entry.answers.entries())
+					.sort((a: [string, number], b: [string, number]) => b[1] - a[1])
+					.map(([answer, count]) => ({ answer, count })),
+			}))
+	}
+
+	// ─── Individual Response Rows ────────────────────────────────────────────
+
+	async function getSurveyResponses(
+		range: AnalyticsRange = '30d',
+		limit = 100,
+	) {
+		const canonicalRows = await fetchCanonicalRows(range)
+
+		return canonicalRows.slice(0, limit).map((row) => ({
+			responseId: row.responseId,
+			surveyId: row.surveyId,
+			surveyTitle: row.surveyTitle ?? '',
+			surveySlug: row.surveySlug ?? '',
+			questionId: row.questionId,
+			questionText: row.questionText ?? '',
+			questionType: row.questionType ?? null,
+			answer: row.answer ?? '',
+			userId: row.userId ?? null,
+			userEmail: row.userEmail ?? null,
+			emailListSubscriberId: row.emailListSubscriberId ?? null,
+			createdAt: row.createdAt ? String(row.createdAt) : '',
+		}))
+	}
+
+	return {
+		getSurveySummary,
+		getSurveyList,
+		getSurveyResponsesByDay,
+		getSurveyQuestionBreakdown,
+		getSurveyResponses,
+	}
+}