@btst/stack 5.1.0 → 5.2.0

package/src/plugins/school/db.ts

@@ -0,0 +1,76 @@
+import { createDbPlugin } from "@btst/db";
+/** School learning records; course content belongs to CMS contentItem. */
+export const schoolSchema = createDbPlugin("school", {
+	schoolSection: {
+		modelName: "schoolSection",
+		fields: {
+			courseId: { type: "string", required: true },
+			title: { type: "string", required: true },
+			order: { type: "number", required: true },
+		},
+	},
+	schoolLesson: {
+		modelName: "schoolLesson",
+		fields: {
+			courseId: { type: "string", required: true },
+			sectionId: { type: "string", required: false },
+			title: { type: "string", required: true },
+			type: { type: "string", required: true },
+			content: { type: "string", required: false },
+			videoUrl: { type: "string", required: false },
+			durationMins: { type: "number", defaultValue: 0 },
+			order: { type: "number", required: true },
+			isFreePreview: { type: "boolean", defaultValue: false },
+			resources: { type: "string", required: true },
+			quiz: { type: "string", required: false },
+		},
+	},
+	schoolEnrollment: {
+		modelName: "schoolEnrollment",
+		fields: {
+			courseId: { type: "string", required: true },
+			userId: { type: "string", required: true },
+			enrollmentKey: { type: "string", required: true, unique: true },
+			status: { type: "string", defaultValue: "enrolled" },
+			progressPct: { type: "number", defaultValue: 0 },
+			lastLessonId: { type: "string", required: false },
+			certificateId: { type: "string", required: false, unique: true },
+			paymentRef: { type: "string", required: false },
+			enrolledAt: { type: "date", defaultValue: () => new Date() },
+			completedAt: { type: "date", required: false },
+		},
+	},
+	schoolLessonProgress: {
+		modelName: "schoolLessonProgress",
+		fields: {
+			enrollmentId: { type: "string", required: true },
+			lessonId: { type: "string", required: true },
+			progressKey: { type: "string", required: true, unique: true },
+			completed: { type: "boolean", defaultValue: false },
+			completedAt: { type: "date", required: false },
+			positionSecs: { type: "number", defaultValue: 0 },
+		},
+	},
+	schoolQuizAttempt: {
+		modelName: "schoolQuizAttempt",
+		fields: {
+			lessonId: { type: "string", required: true },
+			userId: { type: "string", required: true },
+			answers: { type: "string", required: true },
+			score: { type: "number", required: true },
+			passed: { type: "boolean", required: true },
+			attemptedAt: { type: "date", defaultValue: () => new Date() },
+		},
+	},
+	schoolReview: {
+		modelName: "schoolReview",
+		fields: {
+			courseId: { type: "string", required: true },
+			userId: { type: "string", required: true },
+			reviewKey: { type: "string", required: true, unique: true },
+			rating: { type: "number", required: true },
+			body: { type: "string", required: true },
+			createdAt: { type: "date", defaultValue: () => new Date() },
+		},
+	},
+});

package/src/plugins/school/format-price.ts

@@ -0,0 +1,11 @@
+/** Format integer minor currency units using en-US currency formatting. */
+export function formatSchoolPrice(course: { price: number; currency: string }) {
+	if (course.price === 0) return "Free";
+	const formatter = new Intl.NumberFormat("en-US", {
+		style: "currency",
+		currency: course.currency,
+	});
+	return formatter.format(
+		course.price / 10 ** formatter.resolvedOptions().maximumFractionDigits!,
+	);
+}

package/src/plugins/school/permissions.ts

@@ -0,0 +1,41 @@
+import { definePermissions, permission } from "@btst/stack/authorization";
+import { z } from "zod";
+const courseFacts = z.object({
+	courseId: z.string(),
+	instructorId: z.string(),
+	status: z.enum(["draft", "published", "archived"]),
+});
+/** School permission descriptors. Identity is resolved by the stack, never by request body. */
+export const schoolPermissions = definePermissions("school", {
+	course: {
+		read: permission(
+			z.object({
+				scope: z.enum(["catalog", "course", "instructor"]),
+				courseId: z.string().optional(),
+				instructorId: z.string().optional(),
+				status: z.string().optional(),
+			}),
+		),
+		create: permission(z.object({ instructorId: z.string() })),
+		manage: permission(courseFacts),
+	},
+	enrollment: {
+		read: permission(
+			z.object({
+				courseId: z.string().optional(),
+				instructorId: z.string().optional(),
+				userId: z.string().optional(),
+				scope: z.enum(["own", "students"]),
+			}),
+		),
+		enroll: permission(courseFacts),
+	},
+	lesson: {
+		read: permission(
+			courseFacts.extend({ lessonId: z.string(), isFreePreview: z.boolean() }),
+		),
+		complete: permission(courseFacts.extend({ lessonId: z.string() })),
+	},
+	quiz: { submit: permission(courseFacts.extend({ lessonId: z.string() })) },
+	certificate: { read: permission(z.object({ certificateId: z.string() })) },
+});

package/src/plugins/school/query-keys.ts

@@ -0,0 +1,348 @@
+import {
+	createResourceQueryKeys,
+	type ResourcesDeclaration,
+	type ResourceClient,
+	type ResourceQueryKeys,
+} from "@btst/stack/plugins/client";
+export { formatSchoolPrice } from "./format-price";
+import { SCHOOL_QUERY_KEYS } from "./api/query-key-defs";
+import type { StackIdentity } from "@btst/stack/context";
+import type {
+	Course,
+	CourseDetail,
+	Enrollment,
+	Lesson,
+	QuizAttempt,
+	Section,
+	StudentCoursesResult,
+} from "./types";
+import type { z } from "zod";
+import type { courseSchema, lessonSchema } from "./schemas";
+
+/** Identity snapshot isolates enrollment, instructor, and lesson caches. */
+export type SchoolIdentityPartition =
+	| StackIdentity
+	| `pending:${number}`
+	| `error:${number}`;
+/** Public catalog filters. */
+export interface CatalogFilters {
+	category?: string;
+	difficulty?: "beginner" | "intermediate" | "advanced";
+	maxDurationMins?: number;
+	pricing?: "free" | "paid";
+	featured?: boolean;
+	query?: string;
+}
+export type CourseInput = z.input<typeof courseSchema>;
+export type LessonInput = z.input<typeof lessonSchema>;
+
+const recordKey = (id: string, identity?: SchoolIdentityPartition) => [
+	id,
+	{ identity },
+];
+const recordParams = (id: string, _identity?: SchoolIdentityPartition) => ({
+	id,
+});
+const courseInvalidations = ["schoolCourses", "schoolInstructor", "schoolMe"];
+const lessonInvalidations = [
+	...courseInvalidations,
+	"schoolLessons",
+	"schoolStudents",
+];
+
+export const schoolResources = {
+	schoolCourses: {
+		queries: {
+			list: {
+				path: "/school/courses",
+				query: (filters?: CatalogFilters) => ({ ...filters }),
+				key: (filters?: CatalogFilters) => [SCHOOL_QUERY_KEYS.list(filters)[2]],
+				select: (data: { items: Course[]; total: number }) => data,
+			},
+			detail: {
+				path: "/school/catalog/:slug",
+				params: (slug: string) => ({ slug }),
+				key: (slug: string) => [SCHOOL_QUERY_KEYS.detail(slug)[2]],
+				select: (data: CourseDetail) => data,
+			},
+			edit: {
+				path: "/school/courses/:id",
+				params: recordParams,
+				key: recordKey,
+				select: (data: CourseDetail) => data,
+			},
+		},
+		mutations: {
+			create: {
+				path: "@post/school/courses",
+				method: "POST",
+				input: (data: CourseInput) => ({ body: data }),
+				select: (data: Course) => data,
+				invalidates: courseInvalidations,
+				refresh: false,
+			},
+			update: {
+				path: "@patch/school/courses/:id",
+				method: "PATCH",
+				input: ({ id, data }: { id: string; data: Partial<CourseInput> }) => ({
+					params: { id },
+					body: data,
+				}),
+				select: (data: Course) => data,
+				invalidates: courseInvalidations,
+				refresh: false,
+			},
+			delete: {
+				path: "@delete/school/courses/:id",
+				method: "DELETE",
+				input: (id: string) => ({ params: { id } }),
+				invalidates: courseInvalidations,
+				refresh: false,
+			},
+			enroll: {
+				path: "@post/school/courses/:id/enroll",
+				method: "POST",
+				input: (id: string) => ({ params: { id }, body: {} }),
+				select: (data: Enrollment) => data,
+				invalidates: ["schoolMe", "schoolLessons", "schoolStudents"],
+				refresh: false,
+			},
+			cancel: {
+				path: "@post/school/courses/:id/cancel",
+				method: "POST",
+				input: (id: string) => ({ params: { id }, body: {} }),
+				select: (data: Enrollment) => data,
+				invalidates: ["schoolMe", "schoolLessons", "schoolStudents"],
+				refresh: false,
+			},
+			retryCertificate: {
+				path: "@post/school/courses/:id/certificate",
+				method: "POST",
+				input: (id: string) => ({ params: { id } }),
+				select: (data: Enrollment) => data,
+				invalidates: [
+					"schoolMe",
+					"schoolLessons",
+					"schoolStudents",
+					"schoolCertificates",
+				],
+				refresh: false,
+			},
+			reorder: {
+				path: "@post/school/courses/:id/reorder",
+				method: "POST",
+				input: ({ id, lessonIds }: { id: string; lessonIds: string[] }) => ({
+					params: { id },
+					body: { lessonIds },
+				}),
+				invalidates: lessonInvalidations,
+				refresh: false,
+			},
+			review: {
+				path: "@post/school/courses/:id/reviews",
+				method: "POST",
+				input: ({
+					id,
+					rating,
+					body,
+				}: {
+					id: string;
+					rating: number;
+					body: string;
+				}) => ({ params: { id }, body: { rating, body } }),
+				invalidates: ["schoolCourses"],
+				refresh: false,
+			},
+		},
+	},
+	schoolMe: {
+		queries: {
+			list: {
+				path: "/school/me",
+				key: (identity?: SchoolIdentityPartition) => [{ identity }],
+				select: (data: StudentCoursesResult) => data.items,
+			},
+		},
+	},
+	schoolInstructor: {
+		queries: {
+			list: {
+				path: "/school/instructor",
+				key: (identity?: SchoolIdentityPartition) => [{ identity }],
+				select: (data: { items: Course[] }) => data.items,
+			},
+		},
+	},
+	schoolStudents: {
+		queries: {
+			list: {
+				path: "/school/courses/:id/students",
+				params: recordParams,
+				key: recordKey,
+				select: (data: {
+					items: Enrollment[];
+					analytics: {
+						totalEnrolled: number;
+						totalCompleted: number;
+						completionRate: number;
+						enrollmentsOverTime: { date: string; count: number }[];
+					};
+				}) => data,
+			},
+		},
+	},
+	schoolLessons: {
+		queries: {
+			detail: {
+				path: "/school/lessons/:id",
+				params: recordParams,
+				key: recordKey,
+				select: (data: {
+					lesson: Lesson;
+					enrollment: Enrollment | null;
+					progress: { completed: boolean; positionSecs: number } | null;
+					attempts: QuizAttempt[];
+				}) => data,
+			},
+			edit: {
+				path: "/school/lessons/:id/edit",
+				params: recordParams,
+				key: recordKey,
+				select: (data: Lesson) => data,
+			},
+			attempts: {
+				path: "/school/lessons/:id/attempts",
+				params: recordParams,
+				key: recordKey,
+				select: (data: { items: QuizAttempt[] }) => data.items,
+			},
+		},
+		mutations: {
+			create: {
+				path: "@post/school/courses/:id/lessons",
+				method: "POST",
+				input: ({ id, data }: { id: string; data: LessonInput }) => ({
+					params: { id },
+					body: data,
+				}),
+				select: (data: Lesson) => data,
+				invalidates: lessonInvalidations,
+				refresh: false,
+			},
+			update: {
+				path: "@patch/school/lessons/:id",
+				method: "PATCH",
+				input: ({ id, data }: { id: string; data: Partial<LessonInput> }) => ({
+					params: { id },
+					body: data,
+				}),
+				select: (data: Lesson) => data,
+				invalidates: lessonInvalidations,
+				refresh: false,
+			},
+			delete: {
+				path: "@delete/school/lessons/:id",
+				method: "DELETE",
+				input: (id: string) => ({ params: { id } }),
+				invalidates: lessonInvalidations,
+				refresh: false,
+			},
+			progress: {
+				path: "@post/school/lessons/:id/progress",
+				method: "POST",
+				input: ({
+					id,
+					...data
+				}: {
+					id: string;
+					completed?: boolean;
+					positionSecs?: number;
+				}) => ({ params: { id }, body: data }),
+				select: (data: Enrollment) => data,
+				invalidates: ["schoolMe", "schoolLessons", "schoolStudents"],
+				refresh: false,
+			},
+			quiz: {
+				path: "@post/school/lessons/:id/quiz",
+				method: "POST",
+				input: ({
+					id,
+					answers,
+				}: {
+					id: string;
+					answers: { questionId: string; answer: number }[];
+				}) => ({ params: { id }, body: { answers } }),
+				select: (data: QuizAttempt) => data,
+				invalidates: ["schoolMe", "schoolLessons", "schoolStudents"],
+				refresh: false,
+			},
+		},
+	},
+	schoolSections: {
+		queries: {},
+		mutations: {
+			create: {
+				path: "@post/school/courses/:id/sections",
+				method: "POST",
+				input: ({
+					id,
+					title,
+					order,
+				}: {
+					id: string;
+					title: string;
+					order: number;
+				}) => ({ params: { id }, body: { title, order } }),
+				select: (data: Section) => data,
+				invalidates: courseInvalidations,
+				refresh: false,
+			},
+			update: {
+				path: "@patch/school/sections/:id",
+				method: "PATCH",
+				input: ({
+					id,
+					title,
+					order,
+				}: {
+					id: string;
+					title?: string;
+					order?: number;
+				}) => ({ params: { id }, body: { title, order } }),
+				invalidates: courseInvalidations,
+				refresh: false,
+			},
+			delete: {
+				path: "@delete/school/sections/:id",
+				method: "DELETE",
+				input: (id: string) => ({ params: { id } }),
+				invalidates: lessonInvalidations,
+				refresh: false,
+			},
+		},
+	},
+	schoolCertificates: {
+		queries: {
+			detail: {
+				path: "/school/certificates/:id",
+				params: (id: string) => ({ id }),
+				key: (id: string) => [id],
+				select: (data: {
+					certificateId: string;
+					courseTitle: string;
+					completedAt: string;
+				}) => data,
+			},
+		},
+	},
+} satisfies ResourcesDeclaration;
+
+/** Exact School resource inventory shared by generated hooks and query factories. */
+export type SchoolResources = typeof schoolResources;
+
+export function createSchoolQueryKeys(
+	client: ResourceClient,
+	headers?: HeadersInit,
+): ResourceQueryKeys<SchoolResources> {
+	return createResourceQueryKeys(client, schoolResources, headers);
+}

package/src/plugins/school/schemas.ts

@@ -0,0 +1,176 @@
+import { z } from "zod";
+import type { ContentTypeConfig } from "@btst/stack/plugins/cms/api";
+
+const safeUrl = z
+	.string()
+	.url()
+	.refine((value) => /^https?:\/\//i.test(value), "Use an HTTP or HTTPS URL");
+const optionalUrl = z.union([safeUrl, z.literal("")]).optional();
+/** Course content stored by the CMS plugin. Prices are integer minor currency units. */
+export const courseSchema = z.object({
+	title: z.string().trim().min(1).max(200),
+	slug: z
+		.string()
+		.regex(
+			/^(?!(?:me|instructor)$)[a-z0-9]+(?:-[a-z0-9]+)*$/,
+			"Use a lowercase course address; me and instructor are reserved",
+		)
+		.max(200),
+	description: z.string().max(100000).default(""),
+	coverImage: optionalUrl,
+	instructorId: z.string().min(1).max(200),
+	instructorName: z.string().max(200).default(""),
+	instructorBio: z.string().max(10000).default(""),
+	category: z.string().max(100).default(""),
+	tags: z.array(z.string().max(100)).max(30).default([]),
+	difficulty: z
+		.enum(["beginner", "intermediate", "advanced"])
+		.default("beginner"),
+	durationMins: z.number().int().nonnegative().default(0),
+	price: z.number().int().nonnegative().default(0),
+	currency: z
+		.string()
+		.regex(/^[A-Z]{3}$/)
+		.default("USD"),
+	status: z.enum(["draft", "published", "archived"]).default("draft"),
+	featured: z.boolean().default(false),
+});
+/** Partial edits preserve omitted values instead of applying creation defaults. */
+export const courseUpdateSchema = courseSchema.partial().extend({
+	description: courseSchema.shape.description.removeDefault().optional(),
+	instructorName: courseSchema.shape.instructorName.removeDefault().optional(),
+	instructorBio: courseSchema.shape.instructorBio.removeDefault().optional(),
+	category: courseSchema.shape.category.removeDefault().optional(),
+	tags: courseSchema.shape.tags.removeDefault().optional(),
+	difficulty: courseSchema.shape.difficulty.removeDefault().optional(),
+	durationMins: courseSchema.shape.durationMins.removeDefault().optional(),
+	price: courseSchema.shape.price.removeDefault().optional(),
+	currency: courseSchema.shape.currency.removeDefault().optional(),
+	status: courseSchema.shape.status.removeDefault().optional(),
+	featured: courseSchema.shape.featured.removeDefault().optional(),
+});
+/** Register alongside the School backend in cmsBackendPlugin({ contentTypes }). */
+export const SCHOOL_COURSE_CONTENT_TYPE: ContentTypeConfig = {
+	name: "Course",
+	slug: "school-course",
+	schema: courseSchema,
+};
+/** Public course list filtering. Draft/publication controls are deliberately absent. */
+export const courseFiltersSchema = z.object({
+	category: z.string().max(100).optional(),
+	difficulty: z.enum(["beginner", "intermediate", "advanced"]).optional(),
+	maxDurationMins: z.coerce.number().int().nonnegative().optional(),
+	pricing: z.enum(["free", "paid"]).optional(),
+	featured: z
+		.enum(["true", "false"])
+		.transform((v) => v === "true")
+		.or(z.boolean())
+		.optional(),
+	query: z.string().max(200).optional(),
+});
+/** Multiple choice quiz definition. Correct answer indexes are only returned to instructors. */
+export const quizSchema = z
+	.object({
+		questions: z
+			.array(
+				z.object({
+					id: z.string().min(1).max(100),
+					question: z.string().min(1).max(2000),
+					options: z.array(z.string().min(1).max(1000)).min(2).max(10),
+					correctAnswer: z.number().int().nonnegative(),
+				}),
+			)
+			.min(1)
+			.max(100),
+		passMark: z.number().min(0).max(100).optional(),
+		maxAttempts: z.number().int().min(1).max(100).optional(),
+	})
+	.superRefine((quiz, ctx) => {
+		const ids = new Set<string>();
+		for (const [index, q] of quiz.questions.entries()) {
+			if (q.correctAnswer >= q.options.length)
+				ctx.addIssue({
+					code: "custom",
+					path: ["questions", index, "correctAnswer"],
+					message: "Correct answer must match an option",
+				});
+			if (ids.has(q.id))
+				ctx.addIssue({
+					code: "custom",
+					path: ["questions", index, "id"],
+					message: "Question IDs must be unique",
+				});
+			ids.add(q.id);
+		}
+	});
+/** Lesson content, resource links, and optional server-scored quiz. */
+export const lessonSchema = z
+	.object({
+		title: z.string().trim().min(1).max(200),
+		sectionId: z.string().min(1).nullable().optional(),
+		type: z.enum(["video", "text", "quiz"]),
+		content: z.string().max(100000).default(""),
+		videoUrl: optionalUrl,
+		durationMins: z.number().int().nonnegative().default(0),
+		order: z.number().int().nonnegative().default(0),
+		isFreePreview: z.boolean().default(false),
+		resources: z
+			.array(z.object({ label: z.string().min(1).max(200), url: safeUrl }))
+			.max(30)
+			.default([]),
+		quiz: quizSchema.nullable().optional(),
+	})
+	.superRefine((lesson, ctx) => {
+		if (lesson.type === "quiz" && !lesson.quiz)
+			ctx.addIssue({
+				code: "custom",
+				path: ["quiz"],
+				message: "Quiz lessons require questions",
+			});
+		if (lesson.type === "video" && !lesson.videoUrl)
+			ctx.addIssue({
+				code: "custom",
+				path: ["videoUrl"],
+				message: "Video lessons require a video URL",
+			});
+	});
+/** Lesson patches preserve omitted metadata and are validated after merging stored content. */
+export const lessonUpdateSchema = z.object({
+	title: lessonSchema.shape.title.optional(),
+	sectionId: lessonSchema.shape.sectionId,
+	type: lessonSchema.shape.type.optional(),
+	content: lessonSchema.shape.content.removeDefault().optional(),
+	videoUrl: lessonSchema.shape.videoUrl,
+	durationMins: lessonSchema.shape.durationMins.removeDefault().optional(),
+	order: lessonSchema.shape.order.removeDefault().optional(),
+	isFreePreview: lessonSchema.shape.isFreePreview.removeDefault().optional(),
+	resources: lessonSchema.shape.resources.removeDefault().optional(),
+	quiz: lessonSchema.shape.quiz,
+});
+export const sectionSchema = z.object({
+	title: z.string().trim().min(1).max(200),
+	order: z.number().int().nonnegative().default(0),
+});
+/** Partial section edits do not reset omitted chapter ordering. */
+export const sectionUpdateSchema = sectionSchema.partial().extend({
+	order: sectionSchema.shape.order.removeDefault().optional(),
+});
+export const progressSchema = z.object({
+	completed: z.boolean().optional(),
+	positionSecs: z.number().finite().nonnegative().max(31536000).optional(),
+});
+export const quizSubmissionSchema = z.object({
+	answers: z
+		.array(
+			z.object({
+				questionId: z.string().min(1),
+				answer: z.number().int().nonnegative(),
+			}),
+		)
+		.min(1)
+		.max(100),
+});
+export const reviewSchema = z.object({
+	rating: z.number().int().min(1).max(5),
+	body: z.string().trim().min(1).max(5000),
+});

package/src/plugins/school/style.css

@@ -0,0 +1,2 @@
+@import "./client.css";
+@source "../../../src/plugins/school/client/**/*.{ts,tsx}";