@btst/stack 5.1.0 → 5.2.0

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

@@ -0,0 +1,254 @@
+import {
+	createEndpoint,
+	defineBackendPlugin,
+	OperationHttpError,
+} from "@btst/stack/plugins/api";
+import type { QueryClient } from "@tanstack/react-query";
+import { z } from "zod";
+import { schoolSchema } from "../db";
+import {
+	courseSchema,
+	courseUpdateSchema,
+	courseFiltersSchema,
+	lessonSchema,
+	lessonUpdateSchema,
+	sectionSchema,
+	sectionUpdateSchema,
+	progressSchema,
+	quizSubmissionSchema,
+	reviewSchema,
+} from "../schemas";
+import type { CourseFilters, SchoolBackendOptions } from "../types";
+import { getCourseBySlug, getCourseDetail, listCourses } from "./getters";
+import { createSchoolOperations } from "./operations";
+import { ensureSchoolCourseType } from "./mutations";
+import { SCHOOL_QUERY_KEYS } from "./query-key-defs";
+
+/** Public pages that support header-free static generation. */
+export type SchoolRouteKey = "catalog" | "course";
+interface SchoolPrefetchForRoute {
+	(
+		key: "catalog",
+		queryClient: QueryClient,
+		params?: CourseFilters,
+	): Promise<void>;
+	(
+		key: "course",
+		queryClient: QueryClient,
+		params: { slug: string },
+	): Promise<void>;
+}
+/** CMS-backed online school with authorized instructor and student operations. */
+export function schoolBackendPlugin(options: SchoolBackendOptions = {}) {
+	z.number()
+		.min(0)
+		.max(100)
+		.parse(options.quizPassMark ?? 70);
+	return defineBackendPlugin({
+		id: "school",
+		dbPlugin: schoolSchema,
+		operations: (adapter, context) => {
+			if (
+				!Object.values(context?.plugins ?? {}).some(
+					(plugin) => plugin.id === "cms",
+				)
+			)
+				throw new Error(
+					"School requires cmsBackendPlugin with SCHOOL_COURSE_CONTENT_TYPE registered",
+				);
+			return createSchoolOperations(adapter, options);
+		},
+		raw: (adapter) => ({
+			prefetchForRoute: (async (
+				key: SchoolRouteKey,
+				queryClient: QueryClient,
+				params?: CourseFilters & { slug?: string },
+			) => {
+				await ensureSchoolCourseType(adapter);
+				if (key === "catalog") {
+					queryClient.setQueryData(
+						SCHOOL_QUERY_KEYS.list(params),
+						await listCourses(adapter, params),
+					);
+					return;
+				}
+				const course = await getCourseBySlug(adapter, params?.slug ?? "");
+				if (!course)
+					throw new OperationHttpError(
+						404,
+						"Course not found",
+						"SCHOOL_COURSE_NOT_FOUND",
+					);
+				queryClient.setQueryData(
+					SCHOOL_QUERY_KEYS.detail(course.slug),
+					await getCourseDetail(adapter, course),
+				);
+			}) as SchoolPrefetchForRoute,
+		}),
+		routes: (_adapter, _context, ops) => ({
+			listCourses: createEndpoint(
+				"/school/courses",
+				{ method: "GET", query: courseFiltersSchema, requireRequest: true },
+				ops.listCourses.route((ctx) => ctx.query),
+			),
+			getCourse: createEndpoint(
+				"/school/catalog/:slug",
+				{ method: "GET", requireRequest: true },
+				ops.getCourse.route((ctx) => ({ slug: ctx.params.slug })),
+			),
+			getInstructorCourse: createEndpoint(
+				"/school/courses/:id",
+				{ method: "GET", requireRequest: true },
+				ops.getInstructorCourse.route((ctx) => ({ id: ctx.params.id })),
+			),
+			listInstructorCourses: createEndpoint(
+				"/school/instructor",
+				{ method: "GET", requireRequest: true },
+				ops.listInstructorCourses.route(() => ({})),
+			),
+			createCourse: createEndpoint(
+				"/school/courses",
+				{ method: "POST", body: courseSchema, requireRequest: true },
+				ops.createCourse.route((ctx) => ctx.body),
+			),
+			updateCourse: createEndpoint(
+				"/school/courses/:id",
+				{ method: "PATCH", body: courseUpdateSchema, requireRequest: true },
+				ops.updateCourse.route((ctx) => ({
+					id: ctx.params.id,
+					data: ctx.body,
+				})),
+			),
+			deleteCourse: createEndpoint(
+				"/school/courses/:id",
+				{ method: "DELETE", requireRequest: true },
+				ops.deleteCourse.route((ctx) => ({ id: ctx.params.id })),
+			),
+			createSection: createEndpoint(
+				"/school/courses/:id/sections",
+				{ method: "POST", body: sectionSchema, requireRequest: true },
+				ops.createSection.route((ctx) => ({
+					courseId: ctx.params.id,
+					data: ctx.body,
+				})),
+			),
+			updateSection: createEndpoint(
+				"/school/sections/:id",
+				{ method: "PATCH", body: sectionUpdateSchema, requireRequest: true },
+				ops.updateSection.route((ctx) => ({
+					id: ctx.params.id,
+					data: ctx.body,
+				})),
+			),
+			deleteSection: createEndpoint(
+				"/school/sections/:id",
+				{ method: "DELETE", requireRequest: true },
+				ops.deleteSection.route((ctx) => ({ id: ctx.params.id })),
+			),
+			createLesson: createEndpoint(
+				"/school/courses/:id/lessons",
+				{ method: "POST", body: lessonSchema, requireRequest: true },
+				ops.createLesson.route((ctx) => ({
+					courseId: ctx.params.id,
+					data: ctx.body,
+				})),
+			),
+			updateLesson: createEndpoint(
+				"/school/lessons/:id",
+				{ method: "PATCH", body: lessonUpdateSchema, requireRequest: true },
+				ops.updateLesson.route((ctx) => ({
+					id: ctx.params.id,
+					data: ctx.body,
+				})),
+			),
+			getEditableLesson: createEndpoint(
+				"/school/lessons/:id/edit",
+				{ method: "GET", requireRequest: true },
+				ops.getEditableLesson.route((ctx) => ({ id: ctx.params.id })),
+			),
+			deleteLesson: createEndpoint(
+				"/school/lessons/:id",
+				{ method: "DELETE", requireRequest: true },
+				ops.deleteLesson.route((ctx) => ({ id: ctx.params.id })),
+			),
+			reorderLessons: createEndpoint(
+				"/school/courses/:id/reorder",
+				{
+					method: "POST",
+					body: z.object({ lessonIds: z.array(z.string()) }),
+					requireRequest: true,
+				},
+				ops.reorderLessons.route((ctx) => ({ id: ctx.params.id, ...ctx.body })),
+			),
+			enroll: createEndpoint(
+				"/school/courses/:id/enroll",
+				{ method: "POST", requireRequest: true },
+				ops.enroll.route((ctx) => ({ id: ctx.params.id })),
+			),
+			cancelEnrollment: createEndpoint(
+				"/school/courses/:id/cancel",
+				{ method: "POST", requireRequest: true },
+				ops.cancelEnrollment.route((ctx) => ({ id: ctx.params.id })),
+			),
+			retryCertificate: createEndpoint(
+				"/school/courses/:id/certificate",
+				{ method: "POST", requireRequest: true },
+				ops.retryCertificate.route((ctx) => ({ id: ctx.params.id })),
+			),
+			getMyCourses: createEndpoint(
+				"/school/me",
+				{ method: "GET", requireRequest: true },
+				ops.getMyCourses.route(() => ({})),
+			),
+			getLesson: createEndpoint(
+				"/school/lessons/:id",
+				{ method: "GET", requireRequest: true },
+				ops.getLesson.route((ctx) => ({ id: ctx.params.id })),
+			),
+			saveProgress: createEndpoint(
+				"/school/lessons/:id/progress",
+				{ method: "POST", body: progressSchema, requireRequest: true },
+				ops.saveProgress.route((ctx) => ({
+					id: ctx.params.id,
+					data: ctx.body,
+				})),
+			),
+			submitQuiz: createEndpoint(
+				"/school/lessons/:id/quiz",
+				{ method: "POST", body: quizSubmissionSchema, requireRequest: true },
+				ops.submitQuiz.route((ctx) => ({ id: ctx.params.id, data: ctx.body })),
+			),
+			listQuizAttempts: createEndpoint(
+				"/school/lessons/:id/attempts",
+				{ method: "GET", requireRequest: true },
+				ops.listQuizAttempts.route((ctx) => ({ id: ctx.params.id })),
+			),
+			listStudents: createEndpoint(
+				"/school/courses/:id/students",
+				{ method: "GET", requireRequest: true },
+				ops.listStudents.route((ctx) => ({ id: ctx.params.id })),
+			),
+			verifyCertificate: createEndpoint(
+				"/school/certificates/:id",
+				{ method: "GET", requireRequest: true },
+				ops.verifyCertificate.route((ctx) => ({ id: ctx.params.id })),
+			),
+			createReview: createEndpoint(
+				"/school/courses/:id/reviews",
+				{ method: "POST", body: reviewSchema, requireRequest: true },
+				ops.createReview.route((ctx) => ({
+					id: ctx.params.id,
+					data: ctx.body,
+				})),
+			),
+			listReviews: createEndpoint(
+				"/school/courses/:id/reviews",
+				{ method: "GET", requireRequest: true },
+				ops.listReviews.route((ctx) => ({ id: ctx.params.id })),
+			),
+		}),
+	});
+}
+export type SchoolApiRouter = ReturnType<
+	ReturnType<typeof schoolBackendPlugin>["routes"]
+>;

package/src/plugins/school/api/query-key-defs.ts

@@ -0,0 +1,8 @@
+import { courseFiltersSchema } from "../schemas";
+import type { CourseFilters } from "../types";
+/** Canonical public query keys shared by HTTP loaders and direct SSG. */
+export const SCHOOL_QUERY_KEYS = {
+	list: (filters: CourseFilters = {}) =>
+		["schoolCourses", "list", courseFiltersSchema.parse(filters)] as const,
+	detail: (slug: string) => ["schoolCourses", "detail", slug] as const,
+};

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

@@ -0,0 +1,22 @@
+import type { DBAdapter } from "@btst/db";
+
+type Adapter = Omit<DBAdapter, "transaction">;
+
+/** Read complete collections despite adapter defaults or smaller maximum pages. */
+export async function findAllSchoolRecords<T extends Record<string, unknown>>(
+	adapter: Adapter,
+	options: Pick<Parameters<Adapter["findMany"]>[0], "model" | "where">,
+): Promise<T[]> {
+	const records: T[] = [];
+	for (let offset = 0; ; ) {
+		const page = await adapter.findMany<T>({
+			...options,
+			limit: 100,
+			offset,
+			sortBy: { field: "id", direction: "asc" },
+		});
+		if (page.length === 0) return records;
+		records.push(...page);
+		offset += page.length;
+	}
+}

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

@@ -0,0 +1,4 @@
+/** Match JSON transport timestamps before populating the React Query cache. */
+export function serializeSchoolRecord<T>(record: T): T {
+	return JSON.parse(JSON.stringify(record)) as T;
+}

package/src/plugins/school/client/components/index.tsx

@@ -0,0 +1,9 @@
+export { CourseListPageComponent } from "./pages/course-list-page";
+export { CourseDetailPageComponent } from "./pages/course-detail-page";
+export { LessonPlayerPageComponent } from "./pages/lesson-player-page";
+export { QuizPageComponent } from "./pages/quiz-page";
+export { CertificatePageComponent } from "./pages/certificate-page";
+export { MyCoursesPageComponent } from "./pages/my-courses-page";
+export { InstructorDashboardPageComponent } from "./pages/instructor-dashboard-page";
+export { CourseEditorPageComponent } from "./pages/course-editor-page";
+export { LessonEditorPageComponent } from "./pages/lesson-editor-page";

package/src/plugins/school/client/components/pages/certificate-page.internal.tsx

@@ -0,0 +1,32 @@
+"use client";
+import { Award } from "lucide-react";
+import { useCertificate } from "../../hooks";
+import { SchoolShell } from "./school-shared";
+
+export function CertificatePage({ certificateId }: { certificateId: string }) {
+	const { data } = useCertificate(certificateId);
+	return (
+		<SchoolShell title="Certificate verification">
+			<article className="school-certificate">
+				<Award size={40} aria-hidden="true" />
+				<p>Verified completion</p>
+				<h2>{data.courseTitle}</h2>
+				<p>All lessons in this course have been completed.</p>
+				<dl>
+					<div>
+						<dt>Completed</dt>
+						<dd>
+							{new Date(data.completedAt).toLocaleDateString("en-US", {
+								timeZone: "UTC",
+							})}
+						</dd>
+					</div>
+					<div>
+						<dt>Certificate ID</dt>
+						<dd>{data.certificateId}</dd>
+					</div>
+				</dl>
+			</article>
+		</SchoolShell>
+	);
+}

package/src/plugins/school/client/components/pages/certificate-page.tsx

@@ -0,0 +1,26 @@
+"use client";
+import { lazy } from "react";
+import { ComposedRoute } from "@btst/stack/client/components";
+import { SchoolLoading, SchoolNotFound, SchoolError } from "./route-state";
+const Page = lazy(() =>
+	import("./certificate-page.internal").then((m) => ({
+		default: m.CertificatePage,
+	})),
+);
+export function CertificatePageComponent({
+	certificateId,
+}: {
+	certificateId: string;
+}) {
+	return (
+		<ComposedRoute
+			path={`/learn/certificates/${certificateId}`}
+			PageComponent={Page}
+			LoadingComponent={SchoolLoading}
+			ErrorComponent={SchoolError}
+			NotFoundComponent={SchoolNotFound}
+			props={{ certificateId }}
+			onError={(error) => console.error("[btst/school]", error)}
+		/>
+	);
+}

package/src/plugins/school/client/components/pages/course-detail-page.internal.tsx

@@ -0,0 +1,195 @@
+"use client";
+import { useState, type FormEvent } from "react";
+import { Button } from "@workspace/ui/components/button";
+import { useIdentity, usePluginSiteNavigation } from "@btst/stack/context";
+import {
+	useSuspenseCourse,
+	useMyCourses,
+	useEnroll,
+	school,
+} from "../../hooks";
+import { SCHOOL_PLUGIN_ID } from "../../constants";
+import {
+	SchoolShell,
+	ErrorMessage,
+	Curriculum,
+	priceLabel,
+	Progress,
+} from "./school-shared";
+
+export function CourseDetailPage({ slug }: { slug: string }) {
+	const { data: course } = useSuspenseCourse(slug);
+	const { identity } = useIdentity();
+	const mine = useMyCourses(!!identity);
+	const ownEnrollment = mine.data?.find((item) => item.courseId === course.id);
+	const cancelled = ownEnrollment?.status === "cancelled";
+	const enrollment = cancelled ? undefined : ownEnrollment;
+	const enroll = useEnroll();
+	const review = school.schoolCourses.review.use();
+	const { Link, navigate, resolve } = usePluginSiteNavigation(SCHOOL_PLUGIN_ID);
+	const [body, setBody] = useState("");
+	const [rating, setRating] = useState(5);
+	const firstLesson = enrollment?.lastLessonId ?? course.lessons[0]?.id;
+	const start = async () => {
+		try {
+			await enroll.mutateAsync(course.id);
+			if (firstLesson) await navigate("learn", slug, "lessons", firstLesson);
+		} catch {
+			/* Mutation error is displayed below. */
+		}
+	};
+	const submitReview = async (event: FormEvent) => {
+		event.preventDefault();
+		try {
+			await review.mutateAsync({ id: course.id, rating, body });
+			setBody("");
+		} catch {
+			/* Mutation error is displayed below. */
+		}
+	};
+	return (
+		<SchoolShell title={course.title} description={course.description}>
+			<div className="school-detail-grid">
+				<div>
+					{course.coverImage && (
+						<img
+							src={course.coverImage}
+							alt=""
+							className="school-detail-cover"
+						/>
+					)}
+					<h2>What you’ll learn</h2>
+					<Curriculum course={course} enrollment={enrollment} />
+					<section className="school-section">
+						<h2>Your instructor</h2>
+						<h3>{course.instructorName || "Course instructor"}</h3>
+						<p className="school-text">
+							{course.instructorBio ||
+								"Learn through the lessons and resources in this course."}
+						</p>
+					</section>
+					{course.tags.length > 0 && (
+						<ul className="school-tags" aria-label="Course topics">
+							{course.tags.map((tag) => (
+								<li key={tag}>{tag}</li>
+							))}
+						</ul>
+					)}
+				</div>
+				<aside className="school-enrollment-panel">
+					<strong className="school-price">{priceLabel(course)}</strong>
+					<dl className="school-course-facts">
+						<div>
+							<dt>Level</dt>
+							<dd>{course.difficulty}</dd>
+						</div>
+						<div>
+							<dt>Lessons</dt>
+							<dd>{course.lessonCount}</dd>
+						</div>
+						<div>
+							<dt>Duration</dt>
+							<dd>{course.durationMins} min</dd>
+						</div>
+					</dl>
+					{enrollment ? (
+						<>
+							<Progress value={enrollment.progressPct} />
+							{firstLesson && (
+								<Button asChild>
+									<Link
+										href={resolve("learn", slug, "lessons", firstLesson).href}
+									>
+										Continue learning
+									</Link>
+								</Button>
+							)}
+							{enrollment.certificateId && (
+								<Link
+									href={
+										resolve("learn", "certificates", enrollment.certificateId)
+											.href
+									}
+								>
+									View certificate
+								</Link>
+							)}
+						</>
+					) : cancelled ? (
+						<p role="status">
+							Enrollment cancelled. This enrollment cannot be restarted.
+						</p>
+					) : (
+						<Button onClick={() => void start()} disabled={enroll.isPending}>
+							{enroll.isPending
+								? "Enrolling…"
+								: course.price
+									? "Enroll in course"
+									: "Enroll for free"}
+						</Button>
+					)}
+					<ErrorMessage error={enroll.error} />
+					{!enrollment && !cancelled && (
+						<p className="school-muted">
+							{course.price
+								? "Enrollment continues after payment is confirmed."
+								: "Sign in to save your progress."}
+						</p>
+					)}
+				</aside>
+			</div>
+			<section className="school-section">
+				<h2>Student reviews</h2>
+				{course.reviews.length ? (
+					<div className="school-reviews">
+						{course.reviews.map((item) => (
+							<blockquote key={item.id}>
+								<span aria-label={`${item.rating} out of 5 stars`}>
+									{"★".repeat(item.rating)}
+									{"☆".repeat(5 - item.rating)}
+								</span>
+								<p>{item.body}</p>
+							</blockquote>
+						))}
+					</div>
+				) : (
+					<p className="school-muted">No reviews yet.</p>
+				)}
+				{enrollment && (
+					<form
+						onSubmit={(event) => void submitReview(event)}
+						className="school-form school-review-form"
+					>
+						<h3>Share your experience</h3>
+						<label>
+							Rating
+							<select
+								value={rating}
+								onChange={(e) => setRating(Number(e.target.value))}
+							>
+								{[5, 4, 3, 2, 1].map((value) => (
+									<option key={value} value={value}>
+										{value} out of 5
+									</option>
+								))}
+							</select>
+						</label>
+						<label>
+							Your review
+							<textarea
+								value={body}
+								onChange={(e) => setBody(e.target.value)}
+								required
+								maxLength={5000}
+							/>
+						</label>
+						<ErrorMessage error={review.error} />
+						<Button type="submit" disabled={review.isPending}>
+							{review.isPending ? "Saving…" : "Save review"}
+						</Button>
+					</form>
+				)}
+			</section>
+		</SchoolShell>
+	);
+}

package/src/plugins/school/client/components/pages/course-detail-page.tsx

@@ -0,0 +1,22 @@
+"use client";
+import { lazy } from "react";
+import { ComposedRoute } from "@btst/stack/client/components";
+import { SchoolLoading, SchoolNotFound, SchoolError } from "./route-state";
+const Page = lazy(() =>
+	import("./course-detail-page.internal").then((m) => ({
+		default: m.CourseDetailPage,
+	})),
+);
+export function CourseDetailPageComponent({ slug }: { slug: string }) {
+	return (
+		<ComposedRoute
+			path={`/learn/${slug}`}
+			PageComponent={Page}
+			LoadingComponent={SchoolLoading}
+			ErrorComponent={SchoolError}
+			NotFoundComponent={SchoolNotFound}
+			props={{ slug }}
+			onError={(error) => console.error("[btst/school]", error)}
+		/>
+	);
+}