@btst/stack 5.1.0 → 5.2.0

package/src/plugins/school/api/getters.ts

@@ -0,0 +1,293 @@
+import type { DBAdapter } from "@btst/db";
+type Adapter = Omit<DBAdapter, "transaction">;
+import type { ContentItem, ContentType } from "../../cms/types";
+import { courseSchema } from "../schemas";
+import type {
+	Course,
+	CourseDetail,
+	CourseFilters,
+	Enrollment,
+	Lesson,
+	LessonProgress,
+	LessonSummary,
+	QuizAttempt,
+	Review,
+	Section,
+} from "../types";
+import { findAllSchoolRecords } from "./records";
+import { serializeSchoolRecord } from "./serializers";
+
+export const whereId = (id: string) => [
+	{ field: "id", value: id, operator: "eq" as const },
+];
+export const whereField = (field: string, value: string) => [
+	{ field, value, operator: "eq" as const },
+];
+/** Lower-level model reads bypass authorization. Call operations for request work. */
+export async function listSections(
+	adapter: Adapter,
+	courseId: string,
+): Promise<Section[]> {
+	return (
+		await findAllSchoolRecords<Section>(adapter, {
+			model: "schoolSection",
+			where: whereField("courseId", courseId),
+		})
+	).sort((left, right) => left.order - right.order);
+}
+type StoredLesson = Omit<Lesson, "resources" | "quiz"> & {
+	resources: string;
+	quiz?: string | null;
+};
+export function parseLesson(lesson: StoredLesson): Lesson {
+	return {
+		...lesson,
+		resources: JSON.parse(lesson.resources),
+		quiz: lesson.quiz ? JSON.parse(lesson.quiz) : null,
+	};
+}
+export async function listLessons(
+	adapter: Adapter,
+	courseId: string,
+): Promise<Lesson[]> {
+	const lessons = await findAllSchoolRecords<StoredLesson>(adapter, {
+		model: "schoolLesson",
+		where: whereField("courseId", courseId),
+	});
+	const sections = await listSections(adapter, courseId);
+	const sectionRanks = new Map(
+		sections.map((section, index) => [section.id, index]),
+	);
+	lessons.sort(
+		(left, right) =>
+			(sectionRanks.get(left.sectionId ?? "") ?? sections.length) -
+				(sectionRanks.get(right.sectionId ?? "") ?? sections.length) ||
+			left.order - right.order,
+	);
+	return lessons.map(parseLesson);
+}
+export async function getLesson(
+	adapter: Adapter,
+	id: string,
+): Promise<Lesson | null> {
+	const lesson = await adapter.findOne<StoredLesson>({
+		model: "schoolLesson",
+		where: whereId(id),
+	});
+	return lesson ? parseLesson(lesson) : null;
+}
+export function lessonSummary(lesson: Lesson): LessonSummary {
+	const {
+		id,
+		courseId,
+		title,
+		sectionId,
+		type,
+		durationMins,
+		order,
+		isFreePreview,
+	} = lesson;
+	return {
+		id,
+		courseId,
+		title,
+		sectionId,
+		type,
+		durationMins,
+		order,
+		isFreePreview,
+	};
+}
+/** Return safe student content without the quiz answer key. */
+export function publicLesson(lesson: Lesson): Lesson {
+	return {
+		...lesson,
+		quiz: lesson.quiz
+			? {
+					...lesson.quiz,
+					questions: lesson.quiz.questions.map((q) => {
+						const { correctAnswer: _answer, ...publicQuestion } = q as {
+							id: string;
+							question: string;
+							options: string[];
+							correctAnswer?: number;
+						};
+						return publicQuestion;
+					}),
+				}
+			: null,
+	};
+}
+export async function getStoredCourses(adapter: Adapter): Promise<Course[]> {
+	const type = await adapter.findOne<ContentType>({
+		model: "contentType",
+		where: whereField("slug", "school-course"),
+	});
+	if (!type) return [];
+	const records = await findAllSchoolRecords<ContentItem>(adapter, {
+		model: "contentItem",
+		where: whereField("contentTypeId", type.id),
+	});
+	const result: Course[] = [];
+	for (const record of records) {
+		const course = await courseFromRecord(adapter, record);
+		if (course) result.push(course);
+	}
+
+	return result;
+}
+export async function listCourses(
+	adapter: Adapter,
+	filters: CourseFilters = {},
+): Promise<{ items: Course[]; total: number }> {
+	const items = (await getStoredCourses(adapter)).filter(
+		(course) =>
+			course.status === "published" &&
+			(!filters.category || course.category === filters.category) &&
+			(!filters.difficulty || course.difficulty === filters.difficulty) &&
+			(filters.maxDurationMins === undefined ||
+				course.durationMins <= Number(filters.maxDurationMins)) &&
+			(!filters.pricing ||
+				(filters.pricing === "free" ? course.price === 0 : course.price > 0)) &&
+			(filters.featured === undefined ||
+				course.featured ===
+					(filters.featured === true || filters.featured === "true")) &&
+			(!filters.query ||
+				`${course.title} ${course.description} ${course.tags.join(" ")}`
+					.toLowerCase()
+					.includes(filters.query.toLowerCase())),
+	);
+	return { items, total: items.length };
+}
+async function courseFromRecord(
+	adapter: Adapter,
+	record: ContentItem,
+): Promise<Course | null> {
+	const parsed = courseSchema.safeParse(JSON.parse(record.data));
+	if (!parsed.success) return null;
+	return {
+		...parsed.data,
+		id: record.id,
+		createdAt: new Date(record.createdAt).toISOString(),
+		updatedAt: new Date(record.updatedAt).toISOString(),
+		lessonCount: (await listLessons(adapter, record.id)).length,
+	};
+}
+export async function getCourse(
+	adapter: Adapter,
+	id: string,
+): Promise<Course | null> {
+	const type = await adapter.findOne<ContentType>({
+		model: "contentType",
+		where: whereField("slug", "school-course"),
+	});
+	if (!type) return null;
+	const record = await adapter.findOne<ContentItem>({
+		model: "contentItem",
+		where: whereId(id),
+	});
+	if (!record || record.contentTypeId !== type.id) return null;
+	return courseFromRecord(adapter, record);
+}
+
+export async function getCourseBySlug(
+	adapter: Adapter,
+	slug: string,
+): Promise<Course | null> {
+	return (
+		(await getStoredCourses(adapter)).find(
+			(course) => course.slug === slug && course.status === "published",
+		) ?? null
+	);
+}
+export async function listReviews(
+	adapter: Adapter,
+	courseId: string,
+): Promise<Review[]> {
+	return serializeSchoolRecord(
+		await findAllSchoolRecords<Review>(adapter, {
+			model: "schoolReview",
+			where: whereField("courseId", courseId),
+		}),
+	);
+}
+export async function getCourseDetail(
+	adapter: Adapter,
+	course: Course,
+): Promise<CourseDetail> {
+	return {
+		...course,
+		sections: await listSections(adapter, course.id),
+		lessons: (await listLessons(adapter, course.id)).map(lessonSummary),
+		reviews: await listReviews(adapter, course.id),
+		enrollment: null,
+	};
+}
+export async function getEnrollment(
+	adapter: Adapter,
+	courseId: string,
+	userId: string,
+): Promise<Enrollment | null> {
+	return serializeSchoolRecord(
+		await adapter.findOne<Enrollment>({
+			model: "schoolEnrollment",
+			where: [
+				...whereField("courseId", courseId),
+				...whereField("userId", userId),
+			],
+		}),
+	);
+}
+export async function getProgress(
+	adapter: Adapter,
+	enrollmentId: string,
+	lessonId: string,
+): Promise<LessonProgress | null> {
+	return serializeSchoolRecord(
+		await adapter.findOne<LessonProgress>({
+			model: "schoolLessonProgress",
+			where: [
+				...whereField("enrollmentId", enrollmentId),
+				...whereField("lessonId", lessonId),
+			],
+		}),
+	);
+}
+export async function getQuizAttempts(
+	adapter: Adapter,
+	lessonId: string,
+	userId: string,
+): Promise<QuizAttempt[]> {
+	const records = await findAllSchoolRecords<
+		Omit<QuizAttempt, "answers"> & { answers: string }
+	>(adapter, {
+		model: "schoolQuizAttempt",
+		where: [
+			...whereField("lessonId", lessonId),
+			...whereField("userId", userId),
+		],
+	});
+	records.sort(
+		(left, right) =>
+			new Date(right.attemptedAt).getTime() -
+			new Date(left.attemptedAt).getTime(),
+	);
+	return serializeSchoolRecord(
+		records.map((record) => ({
+			...record,
+			answers: JSON.parse(record.answers),
+		})),
+	);
+}
+export async function getEnrollments(
+	adapter: Adapter,
+	field: "userId" | "courseId",
+	id: string,
+): Promise<Enrollment[]> {
+	return serializeSchoolRecord(
+		await findAllSchoolRecords<Enrollment>(adapter, {
+			model: "schoolEnrollment",
+			where: whereField(field, id),
+		}),
+	);
+}

package/src/plugins/school/api/index.ts

@@ -0,0 +1,25 @@
+export {
+	schoolBackendPlugin,
+	type SchoolApiRouter,
+	type SchoolRouteKey,
+} from "./plugin";
+export * from "./getters";
+export {
+	createCourse,
+	updateCourse,
+	createSection,
+	createLesson,
+	updateLesson,
+	createEnrollment,
+	createQuizAttempt,
+	createReview,
+} from "./mutations";
+export { SCHOOL_QUERY_KEYS } from "./query-key-defs";
+export { serializeSchoolRecord } from "./serializers";
+export {
+	SCHOOL_COURSE_CONTENT_TYPE,
+	courseSchema,
+	lessonSchema,
+	quizSchema,
+} from "../schemas";
+export type * from "../types";

package/src/plugins/school/api/mutations.ts

@@ -0,0 +1,187 @@
+import type { DBAdapter } from "@btst/db";
+type Adapter = Omit<DBAdapter, "transaction">;
+import type { z } from "zod";
+import { zodToFormSchema } from "@workspace/ui/lib/schema-converter";
+import type { ContentItem, ContentType } from "../../cms/types";
+import { courseSchema, type lessonSchema } from "../schemas";
+import { getCourse, parseLesson, whereField, whereId } from "./getters";
+import type {
+	Enrollment,
+	Lesson,
+	QuizAttempt,
+	Review,
+	Section,
+} from "../types";
+import { serializeSchoolRecord } from "./serializers";
+
+/** Synchronize the known course content type without requiring a prior CMS HTTP request. */
+export async function ensureSchoolCourseType(
+	adapter: Adapter,
+): Promise<ContentType> {
+	const existing = await adapter.findOne<ContentType>({
+		model: "contentType",
+		where: whereField("slug", "school-course"),
+	});
+	if (existing) return existing;
+	try {
+		return await adapter.create<ContentType>({
+			model: "contentType",
+			data: {
+				name: "Course",
+				slug: "school-course",
+				jsonSchema: JSON.stringify(zodToFormSchema(courseSchema)),
+				autoFormVersion: 2,
+				createdAt: new Date(),
+				updatedAt: new Date(),
+			},
+		});
+	} catch (error) {
+		const concurrent = await adapter.findOne<ContentType>({
+			model: "contentType",
+			where: whereField("slug", "school-course"),
+		});
+		if (concurrent) return concurrent;
+		throw error;
+	}
+}
+/** Lower-level write primitives. Callers own input validation, authorization, and lifecycle. */
+export async function createCourse(
+	adapter: Adapter,
+	data: z.output<typeof courseSchema>,
+) {
+	const type = await ensureSchoolCourseType(adapter);
+	const record = await adapter.create<ContentItem>({
+		model: "contentItem",
+		data: {
+			contentTypeId: type.id,
+			slug: data.slug,
+			data: JSON.stringify(data),
+			authorId: data.instructorId,
+			createdAt: new Date(),
+			updatedAt: new Date(),
+		},
+	});
+	return (await getCourse(adapter, record.id))!;
+}
+export async function updateCourse(
+	adapter: Adapter,
+	id: string,
+	data: z.output<typeof courseSchema>,
+) {
+	await adapter.update({
+		model: "contentItem",
+		where: whereId(id),
+		update: {
+			slug: data.slug,
+			data: JSON.stringify(data),
+			updatedAt: new Date(),
+		},
+	});
+	return (await getCourse(adapter, id))!;
+}
+export async function createSection(
+	adapter: Adapter,
+	courseId: string,
+	data: { title: string; order: number },
+): Promise<Section> {
+	return adapter.create<Section>({
+		model: "schoolSection",
+		data: { courseId, ...data },
+	});
+}
+export async function createLesson(
+	adapter: Adapter,
+	courseId: string,
+	data: z.output<typeof lessonSchema>,
+): Promise<Lesson> {
+	const record = await adapter.create<Parameters<typeof parseLesson>[0]>({
+		model: "schoolLesson",
+		data: {
+			...data,
+			courseId,
+			sectionId: data.sectionId ?? null,
+			resources: JSON.stringify(data.resources),
+			quiz: data.quiz ? JSON.stringify(data.quiz) : null,
+		},
+	});
+	return parseLesson(record);
+}
+export async function updateLesson(
+	adapter: Adapter,
+	id: string,
+	data: z.output<typeof lessonSchema>,
+): Promise<Lesson> {
+	const record = await adapter.update<Parameters<typeof parseLesson>[0]>({
+		model: "schoolLesson",
+		where: whereId(id),
+		update: {
+			...data,
+			sectionId: data.sectionId ?? null,
+			resources: JSON.stringify(data.resources),
+			quiz: data.quiz ? JSON.stringify(data.quiz) : null,
+		},
+	});
+	return parseLesson(record!);
+}
+export async function createEnrollment(
+	adapter: Adapter,
+	courseId: string,
+	userId: string,
+	paymentRef?: string,
+): Promise<Enrollment> {
+	return serializeSchoolRecord(
+		await adapter.create<Enrollment & { enrollmentKey: string }>({
+			model: "schoolEnrollment",
+			data: {
+				courseId,
+				userId,
+				enrollmentKey: JSON.stringify([courseId, userId]),
+				status: "enrolled",
+				progressPct: 0,
+				paymentRef: paymentRef ?? null,
+				enrolledAt: new Date().toISOString(),
+			},
+		}),
+	);
+}
+export async function createQuizAttempt(
+	adapter: Adapter,
+	input: {
+		lessonId: string;
+		userId: string;
+		answers: { questionId: string; answer: number }[];
+		score: number;
+		passed: boolean;
+	},
+): Promise<QuizAttempt> {
+	const record = await adapter.create<
+		Omit<QuizAttempt, "answers"> & { answers: string }
+	>({
+		model: "schoolQuizAttempt",
+		data: {
+			...input,
+			answers: JSON.stringify(input.answers),
+			attemptedAt: new Date().toISOString(),
+		},
+	});
+	return serializeSchoolRecord({ ...record, answers: input.answers });
+}
+export async function createReview(
+	adapter: Adapter,
+	courseId: string,
+	userId: string,
+	input: { rating: number; body: string },
+): Promise<Review> {
+	return serializeSchoolRecord(
+		await adapter.create<Review & { reviewKey: string }>({
+			model: "schoolReview",
+			data: {
+				...input,
+				courseId,
+				userId,
+				reviewKey: JSON.stringify([courseId, userId]),
+				createdAt: new Date().toISOString(),
+			},
+		}),
+	);
+}