@headless-lms/server 0.1.0 → 0.3.0

package/dist/http/routes/courses.js

@@ -1,9 +1,9 @@
+import { refusals } from "../schemas/shared.js";
 import { resolveScope } from "../scope.js";
-import { ErrorBody } from "../schemas/shared.js";
 import { Course, CourseIdParam, CourseSettings, CoursesPage, CoursesQuery, CreateCourse, PatchCourseSettings, UpdateCourse } from "../schemas/content.js";
 import "../schemas/index.js";
-import { NotFoundError } from "@headless-lms/core/shared/errors";
 import { z } from "zod";
+import { NotFoundError } from "@headless-lms/core/shared/errors";
 //#region src/http/routes/courses.ts
 async function coursesRoutes(app, container) {
 	const r = app.withTypeProvider();
@@ -14,14 +14,18 @@ async function coursesRoutes(app, container) {
 		preHandler: app.requireOrgSession,
 		schema: {
 			operationId: "listCourses",
-			tags: ["Courses"],
-			summary: "List courses",
+			tags: ["Content"],
+			summary: "List courses (staff)",
+			description: "Staff only (owner, admin, instructor). Every course in the organization, drafts included, filtered by status and category and searched by title.",
 			querystring: CoursesQuery,
-			response: { 200: CoursesPage }
+			response: {
+				200: CoursesPage,
+				...refusals(403)
+			}
 		},
 		handler: async (req) => {
 			const scope = await resolveScope(container, req);
-			return courses.list(scope.orgId, req.query);
+			return courses.listCourses(scope.orgId, req.query);
 		}
 	});
 	r.route({
@@ -30,12 +34,13 @@ async function coursesRoutes(app, container) {
 		preHandler: app.requireOrgSession,
 		schema: {
 			operationId: "getCourse",
-			tags: ["Courses"],
-			summary: "Get a course by id",
+			tags: ["Content"],
+			summary: "Get a course (staff)",
+			description: "Staff only (owner, admin, instructor).",
 			params: CourseIdParam,
 			response: {
 				200: Course,
-				404: ErrorBody
+				...refusals(403, 404)
 			}
 		},
 		handler: async (req) => {
@@ -51,10 +56,14 @@ async function coursesRoutes(app, container) {
 		preHandler: app.requireOrgSession,
 		schema: {
 			operationId: "createCourse",
-			tags: ["Courses"],
-			summary: "Create a course",
+			tags: ["Content"],
+			summary: "Create a course (staff)",
+			description: "Staff only (owner, admin, instructor). The course starts as a draft. 409 when its slug is taken.",
 			body: CreateCourse,
-			response: { 201: Course }
+			response: {
+				201: Course,
+				...refusals(403, 409)
+			}
 		},
 		handler: async (req, reply) => {
 			const scope = await resolveScope(container, req);
@@ -68,13 +77,14 @@ async function coursesRoutes(app, container) {
 		preHandler: app.requireOrgSession,
 		schema: {
 			operationId: "updateCourse",
-			tags: ["Courses"],
-			summary: "Update a course",
+			tags: ["Content"],
+			summary: "Update a course (staff)",
+			description: "Staff only (owner, admin, instructor). Changes only the fields sent. `thumbnailAssetId` must be a ready library image (409 otherwise); null clears it.",
 			params: CourseIdParam,
 			body: UpdateCourse,
 			response: {
 				200: Course,
-				404: ErrorBody
+				...refusals(403, 404, 409)
 			}
 		},
 		handler: async (req) => {
@@ -88,19 +98,20 @@ async function coursesRoutes(app, container) {
 		preHandler: app.requireOrgSession,
 		schema: {
 			operationId: "updateCourseSettings",
-			tags: ["Courses"],
-			summary: "Update a course settings",
+			tags: ["Content"],
+			summary: "Update a course's settings (staff)",
+			description: "Staff only (owner, admin, instructor). Merges the settings sent into the current ones.",
 			params: CourseIdParam,
 			body: PatchCourseSettings,
 			response: {
 				200: CourseSettings,
-				404: ErrorBody
+				...refusals(403, 404)
 			}
 		},
 		handler: async (req) => {
 			const scope = await resolveScope(container, req);
 			req.log.info({ body: req.body }, "update course settings");
-			return courses.patchSettings(scope.orgId, req.params.id, req.body);
+			return courses.patchCourseSettings(scope.orgId, req.params.id, req.body);
 		}
 	});
 	r.route({
@@ -109,17 +120,21 @@ async function coursesRoutes(app, container) {
 		preHandler: app.requireOrgSession,
 		schema: {
 			operationId: "deleteCourse",
-			tags: ["Courses"],
-			summary: "Delete a course",
+			tags: ["Content"],
+			summary: "Delete a course (staff)",
+			description: "Staff only (owner, admin, instructor).",
 			params: CourseIdParam,
 			response: {
 				204: z.void(),
-				404: ErrorBody
+				...refusals(403, 404)
 			}
 		},
 		handler: async (req, reply) => {
 			const scope = await resolveScope(container, req);
-			await courses.deleteCourse(scope.orgId, req.params.id);
+			await courses.deleteCourse(scope.orgId, req.params.id, {
+				id: scope.orgUserId,
+				role: scope.role
+			});
 			return reply.code(204).send();
 		}
 	});

package/dist/http/routes/courses.js.map

@@ -1 +1 @@
-{"version":3,"file":"courses.js","names":[],"sources":["../../../src/http/routes/courses.ts"],"sourcesContent":["// HTTP routes for the courses context. Request + response are validated against\n// the shared contract schemas by the Zod type provider, and @fastify/swagger\n// reads the same schemas to build the OpenAPI spec the SDK is generated from.\nimport type { FastifyInstance } from 'fastify';\nimport type { ZodTypeProvider } from 'fastify-type-provider-zod';\nimport {\n  Course,\n  CourseIdParam,\n  CourseSettings,\n  CoursesPage,\n  CoursesQuery,\n  CreateCourse,\n  ErrorBody,\n  PatchCourseSettings,\n  UpdateCourse,\n} from '../schemas/index.js';\nimport { z } from 'zod';\nimport type { Container } from '../../app/container.js';\nimport { NotFoundError } from '@headless-lms/core/shared/errors';\nimport { resolveScope } from '../scope.js';\n\nexport async function coursesRoutes(app: FastifyInstance, container: Container): Promise<void> {\n  const r = app.withTypeProvider<ZodTypeProvider>();\n  const courses = container.content;\n\n  r.route({\n    method: 'GET',\n    url: '/api/courses',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'listCourses',\n      tags: ['Courses'],\n      summary: 'List courses',\n      querystring: CoursesQuery,\n      response: { 200: CoursesPage },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      return courses.list(scope.orgId, req.query);\n    },\n  });\n\n  r.route({\n    method: 'GET',\n    url: '/api/courses/:id',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'getCourse',\n      tags: ['Courses'],\n      summary: 'Get a course by id',\n      params: CourseIdParam,\n      response: { 200: Course, 404: ErrorBody },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      const course = await courses.getCourse(scope.orgId, req.params.id);\n      if (!course) {\n        throw new NotFoundError('Course', req.params.id);\n      }\n      return course;\n    },\n  });\n\n  r.route({\n    method: 'POST',\n    url: '/api/courses',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'createCourse',\n      tags: ['Courses'],\n      summary: 'Create a course',\n      body: CreateCourse,\n      response: { 201: Course },\n    },\n    handler: async (req, reply) => {\n      const scope = await resolveScope(container, req);\n      const course = await courses.createCourse(scope.orgId, req.body);\n      return reply.code(201).send(course);\n    },\n  });\n\n  r.route({\n    method: 'PATCH',\n    url: '/api/courses/:id',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'updateCourse',\n      tags: ['Courses'],\n      summary: 'Update a course',\n      params: CourseIdParam,\n      body: UpdateCourse,\n      response: { 200: Course, 404: ErrorBody },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      return courses.updateCourse(scope.orgId, req.params.id, req.body);\n    },\n  });\n\n  r.route({\n    method: 'PATCH',\n    url: '/api/courses/:id/settings',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'updateCourseSettings',\n      tags: ['Courses'],\n      summary: 'Update a course settings',\n      params: CourseIdParam,\n      body: PatchCourseSettings,\n      response: { 200: CourseSettings, 404: ErrorBody },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      req.log.info( { body: req.body },'update course settings',);\n      return courses.patchSettings(scope.orgId, req.params.id, req.body);\n    },\n  });\n\n  r.route({\n    method: 'DELETE',\n    url: '/api/courses/:id',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'deleteCourse',\n      tags: ['Courses'],\n      summary: 'Delete a course',\n      params: CourseIdParam,\n      response: { 204: z.void(), 404: ErrorBody },\n    },\n    handler: async (req, reply) => {\n      const scope = await resolveScope(container, req);\n      await courses.deleteCourse(scope.orgId, req.params.id);\n      return reply.code(204).send();\n    },\n  });\n}\n"],"mappings":";;;;;;;AAqBA,eAAsB,cAAc,KAAsB,WAAqC;CAC7F,MAAM,IAAI,IAAI,iBAAkC;CAChD,MAAM,UAAU,UAAU;CAE1B,EAAE,MAAM;EACN,QAAQ;EACR,KAAK;EACL,YAAY,IAAI;EAChB,QAAQ;GACN,aAAa;GACb,MAAM,CAAC,SAAS;GAChB,SAAS;GACT,aAAa;GACb,UAAU,EAAE,KAAK,YAAY;EAC/B;EACA,SAAS,OAAO,QAAQ;GACtB,MAAM,QAAQ,MAAM,aAAa,WAAW,GAAG;GAC/C,OAAO,QAAQ,KAAK,MAAM,OAAO,IAAI,KAAK;EAC5C;CACF,CAAC;CAED,EAAE,MAAM;EACN,QAAQ;EACR,KAAK;EACL,YAAY,IAAI;EAChB,QAAQ;GACN,aAAa;GACb,MAAM,CAAC,SAAS;GAChB,SAAS;GACT,QAAQ;GACR,UAAU;IAAE,KAAK;IAAQ,KAAK;GAAU;EAC1C;EACA,SAAS,OAAO,QAAQ;GACtB,MAAM,QAAQ,MAAM,aAAa,WAAW,GAAG;GAC/C,MAAM,SAAS,MAAM,QAAQ,UAAU,MAAM,OAAO,IAAI,OAAO,EAAE;GACjE,IAAI,CAAC,QACH,MAAM,IAAI,cAAc,UAAU,IAAI,OAAO,EAAE;GAEjD,OAAO;EACT;CACF,CAAC;CAED,EAAE,MAAM;EACN,QAAQ;EACR,KAAK;EACL,YAAY,IAAI;EAChB,QAAQ;GACN,aAAa;GACb,MAAM,CAAC,SAAS;GAChB,SAAS;GACT,MAAM;GACN,UAAU,EAAE,KAAK,OAAO;EAC1B;EACA,SAAS,OAAO,KAAK,UAAU;GAC7B,MAAM,QAAQ,MAAM,aAAa,WAAW,GAAG;GAC/C,MAAM,SAAS,MAAM,QAAQ,aAAa,MAAM,OAAO,IAAI,IAAI;GAC/D,OAAO,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,MAAM;EACpC;CACF,CAAC;CAED,EAAE,MAAM;EACN,QAAQ;EACR,KAAK;EACL,YAAY,IAAI;EAChB,QAAQ;GACN,aAAa;GACb,MAAM,CAAC,SAAS;GAChB,SAAS;GACT,QAAQ;GACR,MAAM;GACN,UAAU;IAAE,KAAK;IAAQ,KAAK;GAAU;EAC1C;EACA,SAAS,OAAO,QAAQ;GACtB,MAAM,QAAQ,MAAM,aAAa,WAAW,GAAG;GAC/C,OAAO,QAAQ,aAAa,MAAM,OAAO,IAAI,OAAO,IAAI,IAAI,IAAI;EAClE;CACF,CAAC;CAED,EAAE,MAAM;EACN,QAAQ;EACR,KAAK;EACL,YAAY,IAAI;EAChB,QAAQ;GACN,aAAa;GACb,MAAM,CAAC,SAAS;GAChB,SAAS;GACT,QAAQ;GACR,MAAM;GACN,UAAU;IAAE,KAAK;IAAgB,KAAK;GAAU;EAClD;EACA,SAAS,OAAO,QAAQ;GACtB,MAAM,QAAQ,MAAM,aAAa,WAAW,GAAG;GAC/C,IAAI,IAAI,KAAM,EAAE,MAAM,IAAI,KAAK,GAAE,wBAAyB;GAC1D,OAAO,QAAQ,cAAc,MAAM,OAAO,IAAI,OAAO,IAAI,IAAI,IAAI;EACnE;CACF,CAAC;CAED,EAAE,MAAM;EACN,QAAQ;EACR,KAAK;EACL,YAAY,IAAI;EAChB,QAAQ;GACN,aAAa;GACb,MAAM,CAAC,SAAS;GAChB,SAAS;GACT,QAAQ;GACR,UAAU;IAAE,KAAK,EAAE,KAAK;IAAG,KAAK;GAAU;EAC5C;EACA,SAAS,OAAO,KAAK,UAAU;GAC7B,MAAM,QAAQ,MAAM,aAAa,WAAW,GAAG;GAC/C,MAAM,QAAQ,aAAa,MAAM,OAAO,IAAI,OAAO,EAAE;GACrD,OAAO,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK;EAC9B;CACF,CAAC;AACH"}
+{"version":3,"file":"courses.js","names":[],"sources":["../../../src/http/routes/courses.ts"],"sourcesContent":["// HTTP routes for the courses context. Request + response are validated against\n// the shared contract schemas by the Zod type provider, and @fastify/swagger\n// reads the same schemas to build the OpenAPI spec the SDK is generated from.\nimport type { FastifyInstance } from 'fastify';\nimport type { ZodTypeProvider } from 'fastify-type-provider-zod';\nimport {\n  Course,\n  CourseIdParam,\n  CourseSettings,\n  CoursesPage,\n  CoursesQuery,\n  CreateCourse,\n  PatchCourseSettings,\n  UpdateCourse,\n  refusals,\n} from '../schemas/index.js';\nimport { z } from 'zod';\nimport type { Container } from '../../app/container.js';\nimport { NotFoundError } from '@headless-lms/core/shared/errors';\nimport { resolveScope } from '../scope.js';\n\nexport async function coursesRoutes(app: FastifyInstance, container: Container): Promise<void> {\n  const r = app.withTypeProvider<ZodTypeProvider>();\n  const courses = container.content;\n\n  r.route({\n    method: 'GET',\n    url: '/api/courses',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'listCourses',\n      tags: ['Content'],\n      summary: 'List courses (staff)',\n      description:\n        'Staff only (owner, admin, instructor). Every course in the organization, drafts included, filtered by status and category and searched by title.',\n      querystring: CoursesQuery,\n      response: { 200: CoursesPage, ...refusals(403) },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      return courses.listCourses(scope.orgId, req.query);\n    },\n  });\n\n  r.route({\n    method: 'GET',\n    url: '/api/courses/:id',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'getCourse',\n      tags: ['Content'],\n      summary: 'Get a course (staff)',\n      description: 'Staff only (owner, admin, instructor).',\n      params: CourseIdParam,\n      response: { 200: Course, ...refusals(403, 404) },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      const course = await courses.getCourse(scope.orgId, req.params.id);\n      if (!course) {\n        throw new NotFoundError('Course', req.params.id);\n      }\n      return course;\n    },\n  });\n\n  r.route({\n    method: 'POST',\n    url: '/api/courses',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'createCourse',\n      tags: ['Content'],\n      summary: 'Create a course (staff)',\n      description:\n        'Staff only (owner, admin, instructor). The course starts as a draft. 409 when its slug is taken.',\n      body: CreateCourse,\n      response: { 201: Course, ...refusals(403, 409) },\n    },\n    handler: async (req, reply) => {\n      const scope = await resolveScope(container, req);\n      const course = await courses.createCourse(scope.orgId, req.body);\n      return reply.code(201).send(course);\n    },\n  });\n\n  r.route({\n    method: 'PATCH',\n    url: '/api/courses/:id',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'updateCourse',\n      tags: ['Content'],\n      summary: 'Update a course (staff)',\n      description:\n        'Staff only (owner, admin, instructor). Changes only the fields sent. `thumbnailAssetId` must be a ready library image (409 otherwise); null clears it.',\n      params: CourseIdParam,\n      body: UpdateCourse,\n      response: { 200: Course, ...refusals(403, 404, 409) },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      return courses.updateCourse(scope.orgId, req.params.id, req.body);\n    },\n  });\n\n  r.route({\n    method: 'PATCH',\n    url: '/api/courses/:id/settings',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'updateCourseSettings',\n      tags: ['Content'],\n      summary: \"Update a course's settings (staff)\",\n      description:\n        'Staff only (owner, admin, instructor). Merges the settings sent into the current ones.',\n      params: CourseIdParam,\n      body: PatchCourseSettings,\n      response: { 200: CourseSettings, ...refusals(403, 404) },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      req.log.info({ body: req.body }, 'update course settings');\n      return courses.patchCourseSettings(scope.orgId, req.params.id, req.body);\n    },\n  });\n\n  r.route({\n    method: 'DELETE',\n    url: '/api/courses/:id',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'deleteCourse',\n      tags: ['Content'],\n      summary: 'Delete a course (staff)',\n      description: 'Staff only (owner, admin, instructor).',\n      params: CourseIdParam,\n      response: { 204: z.void(), ...refusals(403, 404) },\n    },\n    handler: async (req, reply) => {\n      const scope = await resolveScope(container, req);\n      await courses.deleteCourse(scope.orgId, req.params.id, {\n        id: scope.orgUserId,\n        role: scope.role,\n      });\n      return reply.code(204).send();\n    },\n  });\n}\n"],"mappings":"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"}

package/dist/http/routes/dashboard.js

@@ -1,3 +1,4 @@
+import { refusals } from "../schemas/shared.js";
 import { resolveScope } from "../scope.js";
 import { EnrollmentSeries, EnrollmentSeriesQuery, OverviewStats } from "../schemas/dashboard.js";
 import "../schemas/index.js";
@@ -10,13 +11,17 @@ async function dashboardRoutes(app, container) {
 		preHandler: app.requireOrgSession,
 		schema: {
 			operationId: "getOverview",
-			tags: ["Dashboard"],
-			summary: "Back-office overview stats",
-			response: { 200: OverviewStats }
+			tags: ["Reporting"],
+			summary: "Back-office overview stats (staff)",
+			description: "Staff only (owner, admin, instructor).",
+			response: {
+				200: OverviewStats,
+				...refusals(403)
+			}
 		},
 		handler: async (req) => {
 			const scope = await resolveScope(container, req);
-			return container.reporting.dashboard.overview(scope.orgId);
+			return container.reporting.admin.overview(scope.orgId);
 		}
 	});
 	r.route({
@@ -25,14 +30,18 @@ async function dashboardRoutes(app, container) {
 		preHandler: app.requireOrgSession,
 		schema: {
 			operationId: "getEnrollmentSeries",
-			tags: ["Dashboard"],
-			summary: "Enrollments granted per day over a trailing window",
+			tags: ["Reporting"],
+			summary: "Enrollments granted per day over a trailing window (staff)",
+			description: "Staff only (owner, admin, instructor).",
 			querystring: EnrollmentSeriesQuery,
-			response: { 200: EnrollmentSeries }
+			response: {
+				200: EnrollmentSeries,
+				...refusals(403)
+			}
 		},
 		handler: async (req) => {
 			const scope = await resolveScope(container, req);
-			return container.reporting.dashboard.enrollments(scope.orgId, req.query.days);
+			return container.reporting.admin.enrollments(scope.orgId, req.query.days);
 		}
 	});
 }

package/dist/http/routes/dashboard.js.map

@@ -1 +1 @@
-{"version":3,"file":"dashboard.js","names":[],"sources":["../../../src/http/routes/dashboard.ts"],"sourcesContent":["// HTTP routes for the dashboard (overview) context.\nimport type { FastifyInstance } from 'fastify';\nimport type { ZodTypeProvider } from 'fastify-type-provider-zod';\nimport { EnrollmentSeries, EnrollmentSeriesQuery, OverviewStats } from '../schemas/index.js';\nimport type { Container } from '../../app/container.js';\nimport { resolveScope } from '../scope.js';\n\nexport async function dashboardRoutes(app: FastifyInstance, container: Container): Promise<void> {\n  const r = app.withTypeProvider<ZodTypeProvider>();\n\n  r.route({\n    method: 'GET',\n    url: '/api/overview',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'getOverview',\n      tags: ['Dashboard'],\n      summary: 'Back-office overview stats',\n      response: { 200: OverviewStats },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      return container.reporting.dashboard.overview(scope.orgId);\n    },\n  });\n\n  r.route({\n    method: 'GET',\n    url: '/api/overview/enrollments',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'getEnrollmentSeries',\n      tags: ['Dashboard'],\n      summary: 'Enrollments granted per day over a trailing window',\n      querystring: EnrollmentSeriesQuery,\n      response: { 200: EnrollmentSeries },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      return container.reporting.dashboard.enrollments(scope.orgId, req.query.days);\n    },\n  });\n}\n"],"mappings":";;;;AAOA,eAAsB,gBAAgB,KAAsB,WAAqC;CAC/F,MAAM,IAAI,IAAI,iBAAkC;CAEhD,EAAE,MAAM;EACN,QAAQ;EACR,KAAK;EACL,YAAY,IAAI;EAChB,QAAQ;GACN,aAAa;GACb,MAAM,CAAC,WAAW;GAClB,SAAS;GACT,UAAU,EAAE,KAAK,cAAc;EACjC;EACA,SAAS,OAAO,QAAQ;GACtB,MAAM,QAAQ,MAAM,aAAa,WAAW,GAAG;GAC/C,OAAO,UAAU,UAAU,UAAU,SAAS,MAAM,KAAK;EAC3D;CACF,CAAC;CAED,EAAE,MAAM;EACN,QAAQ;EACR,KAAK;EACL,YAAY,IAAI;EAChB,QAAQ;GACN,aAAa;GACb,MAAM,CAAC,WAAW;GAClB,SAAS;GACT,aAAa;GACb,UAAU,EAAE,KAAK,iBAAiB;EACpC;EACA,SAAS,OAAO,QAAQ;GACtB,MAAM,QAAQ,MAAM,aAAa,WAAW,GAAG;GAC/C,OAAO,UAAU,UAAU,UAAU,YAAY,MAAM,OAAO,IAAI,MAAM,IAAI;EAC9E;CACF,CAAC;AACH"}
+{"version":3,"file":"dashboard.js","names":[],"sources":["../../../src/http/routes/dashboard.ts"],"sourcesContent":["// HTTP routes for the dashboard (overview) context.\nimport type { FastifyInstance } from 'fastify';\nimport type { ZodTypeProvider } from 'fastify-type-provider-zod';\nimport {\n  EnrollmentSeries,\n  EnrollmentSeriesQuery,\n  OverviewStats,\n  refusals,\n} from '../schemas/index.js';\nimport type { Container } from '../../app/container.js';\nimport { resolveScope } from '../scope.js';\n\nexport async function dashboardRoutes(app: FastifyInstance, container: Container): Promise<void> {\n  const r = app.withTypeProvider<ZodTypeProvider>();\n\n  r.route({\n    method: 'GET',\n    url: '/api/overview',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'getOverview',\n      tags: ['Reporting'],\n      summary: 'Back-office overview stats (staff)',\n      description: 'Staff only (owner, admin, instructor).',\n      response: { 200: OverviewStats, ...refusals(403) },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      return container.reporting.admin.overview(scope.orgId);\n    },\n  });\n\n  r.route({\n    method: 'GET',\n    url: '/api/overview/enrollments',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'getEnrollmentSeries',\n      tags: ['Reporting'],\n      summary: 'Enrollments granted per day over a trailing window (staff)',\n      description: 'Staff only (owner, admin, instructor).',\n      querystring: EnrollmentSeriesQuery,\n      response: { 200: EnrollmentSeries, ...refusals(403) },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      return container.reporting.admin.enrollments(scope.orgId, req.query.days);\n    },\n  });\n}\n"],"mappings":";;;;;AAYA,eAAsB,gBAAgB,KAAsB,WAAqC;CAC/F,MAAM,IAAI,IAAI,iBAAkC;CAEhD,EAAE,MAAM;EACN,QAAQ;EACR,KAAK;EACL,YAAY,IAAI;EAChB,QAAQ;GACN,aAAa;GACb,MAAM,CAAC,WAAW;GAClB,SAAS;GACT,aAAa;GACb,UAAU;IAAE,KAAK;IAAe,GAAG,SAAS,GAAG;GAAE;EACnD;EACA,SAAS,OAAO,QAAQ;GACtB,MAAM,QAAQ,MAAM,aAAa,WAAW,GAAG;GAC/C,OAAO,UAAU,UAAU,MAAM,SAAS,MAAM,KAAK;EACvD;CACF,CAAC;CAED,EAAE,MAAM;EACN,QAAQ;EACR,KAAK;EACL,YAAY,IAAI;EAChB,QAAQ;GACN,aAAa;GACb,MAAM,CAAC,WAAW;GAClB,SAAS;GACT,aAAa;GACb,aAAa;GACb,UAAU;IAAE,KAAK;IAAkB,GAAG,SAAS,GAAG;GAAE;EACtD;EACA,SAAS,OAAO,QAAQ;GACtB,MAAM,QAAQ,MAAM,aAAa,WAAW,GAAG;GAC/C,OAAO,UAAU,UAAU,MAAM,YAAY,MAAM,OAAO,IAAI,MAAM,IAAI;EAC1E;CACF,CAAC;AACH"}

package/dist/http/routes/discussion.js

@@ -1,22 +1,30 @@
-import { ErrorBody } from "../schemas/shared.js";
+import { refusals } from "../schemas/shared.js";
+import { resolveScope } from "../scope.js";
 import { Comment, CommentIdParam, CommentView, CommentsPage, CommentsQuery, PatchComment, ReplyToComment } from "../schemas/discussion.js";
 import "../schemas/index.js";
-import { NotFoundError } from "@headless-lms/core/shared/errors";
 import { z } from "zod";
+import { NotFoundError } from "@headless-lms/core/shared/errors";
 //#region src/http/routes/discussion.ts
 async function discussionRoutes(app, container) {
 	const r = app.withTypeProvider();
 	const discussion = container.discussion;
+	const staff = async (req) => {
+		await resolveScope(container, req);
+	};
 	r.route({
 		method: "GET",
 		url: "/api/comments",
-		preHandler: app.requireOrgSession,
+		preHandler: staff,
 		schema: {
 			operationId: "listComments",
 			tags: ["Discussion"],
-			summary: "List comments, filtered by course, activity, author, status or reports",
+			summary: "List course comments for moderation (staff)",
+			description: "Staff only (owner, admin, instructor). Comments on course activities, filtered by course, activity, author, status or open reports; each row carries the author's email and the open reports.",
 			querystring: CommentsQuery,
-			response: { 200: CommentsPage }
+			response: {
+				200: CommentsPage,
+				...refusals(403)
+			}
 		},
 		handler: async (req) => {
 			return discussion.listComments(req.orgId, req.query);
@@ -25,88 +33,88 @@ async function discussionRoutes(app, container) {
 	r.route({
 		method: "DELETE",
 		url: "/api/comments/:commentId",
-		preHandler: app.requireOrgSession,
+		preHandler: staff,
 		schema: {
 			operationId: "moderateRemoveComment",
 			tags: ["Discussion"],
-			summary: "Remove a comment as a moderator",
+			summary: "Remove a course comment (staff)",
+			description: "Staff only (owner, admin, instructor). Hides the comment and resolves its open reports as `removed`. Removing a removed comment returns it unchanged.",
 			params: CommentIdParam,
 			response: {
-				200: Comment,
-				403: ErrorBody,
-				404: ErrorBody
+				200: CommentView,
+				...refusals(403, 404)
 			}
 		},
 		handler: async (req) => {
 			const orgUser = await container.organizations.getOrgUser(req.orgId, req.userId);
-			return discussion.remove(req.orgId, req.params.commentId, orgUser);
+			return discussion.remove(req.orgId, req.params.commentId, orgUser, null);
 		}
 	});
 	r.route({
 		method: "PATCH",
 		url: "/api/comments/:commentId",
-		preHandler: app.requireOrgSession,
+		preHandler: staff,
 		schema: {
-			operationId: "editComment",
+			operationId: "publishComment",
 			tags: ["Discussion"],
-			summary: "Publish a comment: approves a pending one, restores a removed one",
+			summary: "Publish a course comment (staff)",
+			description: "Staff only (owner, admin, instructor). Approves a pending comment or restores a removed one; a published comment is returned unchanged.",
 			params: CommentIdParam,
 			body: PatchComment,
 			response: {
 				200: Comment,
-				403: ErrorBody,
-				404: ErrorBody
+				...refusals(403, 404)
 			}
 		},
 		handler: async (req) => {
 			const orgUser = await container.organizations.getOrgUser(req.orgId, req.userId);
 			if (!orgUser) throw new NotFoundError("OrgUser", req.userId);
-			return discussion.publish(req.orgId, req.params.commentId, orgUser);
+			return discussion.publish(req.orgId, req.params.commentId, orgUser, null);
 		}
 	});
 	r.route({
 		method: "DELETE",
 		url: "/api/comments/:commentId/reports",
-		preHandler: app.requireOrgSession,
+		preHandler: staff,
 		schema: {
 			operationId: "dismissCommentReports",
 			tags: ["Discussion"],
-			summary: "Dismiss every open report on a comment",
+			summary: "Dismiss every open report on a course comment (staff)",
+			description: "Staff only (owner, admin, instructor). The comment stays up.",
 			params: CommentIdParam,
 			response: {
 				204: z.void(),
-				403: ErrorBody,
-				404: ErrorBody
+				...refusals(403, 404)
 			}
 		},
 		handler: async (req, reply) => {
 			const orgUser = await container.organizations.getOrgUser(req.orgId, req.userId);
 			if (!orgUser) throw new NotFoundError("OrgUser", req.userId);
-			await discussion.resolveReports(req.orgId, req.params.commentId, orgUser);
+			await discussion.resolveReports(req.orgId, req.params.commentId, orgUser, null);
 			return reply.code(204).send();
 		}
 	});
 	r.route({
 		method: "POST",
 		url: "/api/comments/:commentId/replies",
-		preHandler: app.requireOrgSession,
+		preHandler: staff,
 		schema: {
 			operationId: "replyToComment",
 			tags: ["Discussion"],
-			summary: "Reply to a comment from the moderation queue",
+			summary: "Reply to a course comment from the moderation queue (staff)",
+			description: "Staff only (owner, admin, instructor). Replies nest one level: answering a reply attaches to its root comment.",
 			params: CommentIdParam,
 			body: ReplyToComment,
 			response: {
 				200: CommentView,
-				403: ErrorBody,
-				404: ErrorBody
+				...refusals(403, 404)
 			}
 		},
 		handler: async (req) => {
 			const orgUser = await container.organizations.getOrgUser(req.orgId, req.userId);
 			if (!orgUser) throw new NotFoundError("OrgUser", req.userId);
 			const parent = await discussion.getComment(req.orgId, req.params.commentId);
-			if (!parent) throw new NotFoundError("Comment", req.params.commentId);
+			if (!parent || parent.activityId === null) throw new NotFoundError("Comment", req.params.commentId);
 			return discussion.postComment(req.orgId, {
 				actor: orgUser,
 				activityId: parent.activityId,

package/dist/http/routes/discussion.js.map

@@ -1 +1 @@
-{"version":3,"file":"discussion.js","names":[],"sources":["../../../src/http/routes/discussion.ts"],"sourcesContent":["// Moderator-facing discussion routes. The learner surface (everything under\n// `/api/learn`) lives in routes/learn/comments.ts.\nimport type { FastifyInstance } from 'fastify';\nimport type { ZodTypeProvider } from 'fastify-type-provider-zod';\nimport { z } from 'zod';\nimport {\n  Comment,\n  CommentIdParam,\n  CommentsPage,\n  CommentsQuery,\n  CommentView,\n  ErrorBody,\n  PatchComment,\n  ReplyToComment,\n} from '../schemas/index.js';\nimport { NotFoundError } from '@headless-lms/core/shared/errors';\nimport type { Container } from '../../app/container.js';\n\nexport async function discussionRoutes(app: FastifyInstance, container: Container): Promise<void> {\n  const r = app.withTypeProvider<ZodTypeProvider>();\n  const discussion = container.discussion;\n\n  r.route({\n    method: 'GET',\n    url: '/api/comments',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'listComments',\n      tags: ['Discussion'],\n      summary: 'List comments, filtered by course, activity, author, status or reports',\n      querystring: CommentsQuery,\n      response: { 200: CommentsPage },\n    },\n    handler: async (req) => {\n      return discussion.listComments(req.orgId, req.query);\n    },\n  });\n\n  r.route({\n    method: 'DELETE',\n    url: '/api/comments/:commentId',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'moderateRemoveComment',\n      tags: ['Discussion'],\n      summary: 'Remove a comment as a moderator',\n      params: CommentIdParam,\n      response: { 200: Comment, 403: ErrorBody, 404: ErrorBody },\n    },\n    handler: async (req) => {\n      const orgUser = await container.organizations.getOrgUser(req.orgId, req.userId);\n      return discussion.remove(req.orgId, req.params.commentId, orgUser!);\n    },\n  });\n\n  r.route({\n    method: 'PATCH',\n    url: '/api/comments/:commentId',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'editComment',\n      tags: ['Discussion'],\n      summary: 'Publish a comment: approves a pending one, restores a removed one',\n      params: CommentIdParam,\n      body: PatchComment,\n      response: { 200: Comment, 403: ErrorBody, 404: ErrorBody },\n    },\n    handler: async (req) => {\n      const orgUser = await container.organizations.getOrgUser(req.orgId, req.userId);\n      if (!orgUser) {\n        throw new NotFoundError('OrgUser', req.userId);\n      }\n      return discussion.publish(req.orgId, req.params.commentId, orgUser);\n    },\n  });\n\n  r.route({\n    method: 'DELETE',\n    url: '/api/comments/:commentId/reports',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'dismissCommentReports',\n      tags: ['Discussion'],\n      summary: 'Dismiss every open report on a comment',\n      params: CommentIdParam,\n      response: { 204: z.void(), 403: ErrorBody, 404: ErrorBody },\n    },\n    handler: async (req, reply) => {\n      const orgUser = await container.organizations.getOrgUser(req.orgId, req.userId);\n      if (!orgUser) {\n        throw new NotFoundError('OrgUser', req.userId);\n      }\n      await discussion.resolveReports(req.orgId, req.params.commentId, orgUser);\n      return reply.code(204).send();\n    },\n  });\n\n  r.route({\n    method: 'POST',\n    url: '/api/comments/:commentId/replies',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'replyToComment',\n      tags: ['Discussion'],\n      summary: 'Reply to a comment from the moderation queue',\n      params: CommentIdParam,\n      body: ReplyToComment,\n      response: { 200: CommentView, 403: ErrorBody, 404: ErrorBody },\n    },\n    handler: async (req) => {\n      const orgUser = await container.organizations.getOrgUser(req.orgId, req.userId);\n      if (!orgUser) {\n        throw new NotFoundError('OrgUser', req.userId);\n      }\n      const parent = await discussion.getComment(req.orgId, req.params.commentId);\n      if (!parent) {\n        throw new NotFoundError('Comment', req.params.commentId);\n      }\n      // Replies nest one level: answering a reply attaches to its root.\n      return discussion.postComment(req.orgId, {\n        actor: orgUser,\n        activityId: parent.activityId,\n        parentId: parent.parentId ?? parent.id,\n        body: req.body.body,\n      });\n    },\n  });\n}\n"],"mappings":";;;;;;AAkBA,eAAsB,iBAAiB,KAAsB,WAAqC;CAChG,MAAM,IAAI,IAAI,iBAAkC;CAChD,MAAM,aAAa,UAAU;CAE7B,EAAE,MAAM;EACN,QAAQ;EACR,KAAK;EACL,YAAY,IAAI;EAChB,QAAQ;GACN,aAAa;GACb,MAAM,CAAC,YAAY;GACnB,SAAS;GACT,aAAa;GACb,UAAU,EAAE,KAAK,aAAa;EAChC;EACA,SAAS,OAAO,QAAQ;GACtB,OAAO,WAAW,aAAa,IAAI,OAAO,IAAI,KAAK;EACrD;CACF,CAAC;CAED,EAAE,MAAM;EACN,QAAQ;EACR,KAAK;EACL,YAAY,IAAI;EAChB,QAAQ;GACN,aAAa;GACb,MAAM,CAAC,YAAY;GACnB,SAAS;GACT,QAAQ;GACR,UAAU;IAAE,KAAK;IAAS,KAAK;IAAW,KAAK;GAAU;EAC3D;EACA,SAAS,OAAO,QAAQ;GACtB,MAAM,UAAU,MAAM,UAAU,cAAc,WAAW,IAAI,OAAO,IAAI,MAAM;GAC9E,OAAO,WAAW,OAAO,IAAI,OAAO,IAAI,OAAO,WAAW,OAAQ;EACpE;CACF,CAAC;CAED,EAAE,MAAM;EACN,QAAQ;EACR,KAAK;EACL,YAAY,IAAI;EAChB,QAAQ;GACN,aAAa;GACb,MAAM,CAAC,YAAY;GACnB,SAAS;GACT,QAAQ;GACR,MAAM;GACN,UAAU;IAAE,KAAK;IAAS,KAAK;IAAW,KAAK;GAAU;EAC3D;EACA,SAAS,OAAO,QAAQ;GACtB,MAAM,UAAU,MAAM,UAAU,cAAc,WAAW,IAAI,OAAO,IAAI,MAAM;GAC9E,IAAI,CAAC,SACH,MAAM,IAAI,cAAc,WAAW,IAAI,MAAM;GAE/C,OAAO,WAAW,QAAQ,IAAI,OAAO,IAAI,OAAO,WAAW,OAAO;EACpE;CACF,CAAC;CAED,EAAE,MAAM;EACN,QAAQ;EACR,KAAK;EACL,YAAY,IAAI;EAChB,QAAQ;GACN,aAAa;GACb,MAAM,CAAC,YAAY;GACnB,SAAS;GACT,QAAQ;GACR,UAAU;IAAE,KAAK,EAAE,KAAK;IAAG,KAAK;IAAW,KAAK;GAAU;EAC5D;EACA,SAAS,OAAO,KAAK,UAAU;GAC7B,MAAM,UAAU,MAAM,UAAU,cAAc,WAAW,IAAI,OAAO,IAAI,MAAM;GAC9E,IAAI,CAAC,SACH,MAAM,IAAI,cAAc,WAAW,IAAI,MAAM;GAE/C,MAAM,WAAW,eAAe,IAAI,OAAO,IAAI,OAAO,WAAW,OAAO;GACxE,OAAO,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK;EAC9B;CACF,CAAC;CAED,EAAE,MAAM;EACN,QAAQ;EACR,KAAK;EACL,YAAY,IAAI;EAChB,QAAQ;GACN,aAAa;GACb,MAAM,CAAC,YAAY;GACnB,SAAS;GACT,QAAQ;GACR,MAAM;GACN,UAAU;IAAE,KAAK;IAAa,KAAK;IAAW,KAAK;GAAU;EAC/D;EACA,SAAS,OAAO,QAAQ;GACtB,MAAM,UAAU,MAAM,UAAU,cAAc,WAAW,IAAI,OAAO,IAAI,MAAM;GAC9E,IAAI,CAAC,SACH,MAAM,IAAI,cAAc,WAAW,IAAI,MAAM;GAE/C,MAAM,SAAS,MAAM,WAAW,WAAW,IAAI,OAAO,IAAI,OAAO,SAAS;GAC1E,IAAI,CAAC,QACH,MAAM,IAAI,cAAc,WAAW,IAAI,OAAO,SAAS;GAGzD,OAAO,WAAW,YAAY,IAAI,OAAO;IACvC,OAAO;IACP,YAAY,OAAO;IACnB,UAAU,OAAO,YAAY,OAAO;IACpC,MAAM,IAAI,KAAK;GACjB,CAAC;EACH;CACF,CAAC;AACH"}
+{"version":3,"file":"discussion.js","names":[],"sources":["../../../src/http/routes/discussion.ts"],"sourcesContent":["// Moderator-facing discussion routes. The learner surface (everything under\n// `/api/member`) lives in routes/member/comments.ts.\nimport type { FastifyInstance, FastifyRequest } from 'fastify';\nimport type { ZodTypeProvider } from 'fastify-type-provider-zod';\nimport { z } from 'zod';\nimport {\n  Comment,\n  CommentIdParam,\n  CommentsPage,\n  CommentsQuery,\n  CommentView,\n  PatchComment,\n  ReplyToComment,\n  refusals,\n} from '../schemas/index.js';\nimport { NotFoundError } from '@headless-lms/core/shared/errors';\nimport type { Container } from '../../app/container.js';\nimport { resolveScope } from '../scope.js';\n\nexport async function discussionRoutes(app: FastifyInstance, container: Container): Promise<void> {\n  const r = app.withTypeProvider<ZodTypeProvider>();\n  const discussion = container.discussion;\n  const staff = async (req: FastifyRequest) => {\n    await resolveScope(container, req);\n  };\n\n  r.route({\n    method: 'GET',\n    url: '/api/comments',\n    preHandler: staff,\n    schema: {\n      operationId: 'listComments',\n      tags: ['Discussion'],\n      summary: 'List course comments for moderation (staff)',\n      description:\n        \"Staff only (owner, admin, instructor). Comments on course activities, filtered by course, activity, author, status or open reports; each row carries the author's email and the open reports.\",\n      querystring: CommentsQuery,\n      response: { 200: CommentsPage, ...refusals(403) },\n    },\n    handler: async (req) => {\n      return discussion.listComments(req.orgId, req.query);\n    },\n  });\n\n  r.route({\n    method: 'DELETE',\n    url: '/api/comments/:commentId',\n    preHandler: staff,\n    schema: {\n      operationId: 'moderateRemoveComment',\n      tags: ['Discussion'],\n      summary: 'Remove a course comment (staff)',\n      description:\n        'Staff only (owner, admin, instructor). Hides the comment and resolves its open reports as `removed`. Removing a removed comment returns it unchanged.',\n      params: CommentIdParam,\n      response: { 200: CommentView, ...refusals(403, 404) },\n    },\n    handler: async (req) => {\n      const orgUser = await container.organizations.getOrgUser(req.orgId, req.userId);\n      return discussion.remove(req.orgId, req.params.commentId, orgUser!, null);\n    },\n  });\n\n  r.route({\n    method: 'PATCH',\n    url: '/api/comments/:commentId',\n    preHandler: staff,\n    schema: {\n      operationId: 'publishComment',\n      tags: ['Discussion'],\n      summary: 'Publish a course comment (staff)',\n      description:\n        'Staff only (owner, admin, instructor). Approves a pending comment or restores a removed one; a published comment is returned unchanged.',\n      params: CommentIdParam,\n      body: PatchComment,\n      response: { 200: Comment, ...refusals(403, 404) },\n    },\n    handler: async (req) => {\n      const orgUser = await container.organizations.getOrgUser(req.orgId, req.userId);\n      if (!orgUser) {\n        throw new NotFoundError('OrgUser', req.userId);\n      }\n      return discussion.publish(req.orgId, req.params.commentId, orgUser, null);\n    },\n  });\n\n  r.route({\n    method: 'DELETE',\n    url: '/api/comments/:commentId/reports',\n    preHandler: staff,\n    schema: {\n      operationId: 'dismissCommentReports',\n      tags: ['Discussion'],\n      summary: 'Dismiss every open report on a course comment (staff)',\n      description: 'Staff only (owner, admin, instructor). The comment stays up.',\n      params: CommentIdParam,\n      response: { 204: z.void(), ...refusals(403, 404) },\n    },\n    handler: async (req, reply) => {\n      const orgUser = await container.organizations.getOrgUser(req.orgId, req.userId);\n      if (!orgUser) {\n        throw new NotFoundError('OrgUser', req.userId);\n      }\n      await discussion.resolveReports(req.orgId, req.params.commentId, orgUser, null);\n      return reply.code(204).send();\n    },\n  });\n\n  r.route({\n    method: 'POST',\n    url: '/api/comments/:commentId/replies',\n    preHandler: staff,\n    schema: {\n      operationId: 'replyToComment',\n      tags: ['Discussion'],\n      summary: 'Reply to a course comment from the moderation queue (staff)',\n      description:\n        'Staff only (owner, admin, instructor). Replies nest one level: answering a reply attaches to its root comment.',\n      params: CommentIdParam,\n      body: ReplyToComment,\n      response: { 200: CommentView, ...refusals(403, 404) },\n    },\n    handler: async (req) => {\n      const orgUser = await container.organizations.getOrgUser(req.orgId, req.userId);\n      if (!orgUser) {\n        throw new NotFoundError('OrgUser', req.userId);\n      }\n      const parent = await discussion.getComment(req.orgId, req.params.commentId);\n      if (!parent || parent.activityId === null) {\n        throw new NotFoundError('Comment', req.params.commentId);\n      }\n      // Replies nest one level: answering a reply attaches to its root.\n      return discussion.postComment(req.orgId, {\n        actor: orgUser,\n        activityId: parent.activityId,\n        parentId: parent.parentId ?? parent.id,\n        body: req.body.body,\n      });\n    },\n  });\n}\n"],"mappings":"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"}

package/dist/http/routes/downloads.js

@@ -1,9 +1,9 @@
+import { refusals } from "../schemas/shared.js";
 import { resolveScope } from "../scope.js";
-import { ErrorBody } from "../schemas/shared.js";
-import { AddDownloadAsset, CreateDownload, Download, DownloadAsset, DownloadAssetParams, DownloadIdParam, DownloadsPage, DownloadsQuery, RenameDownloadAsset, ReorderDownloadAssets, UpdateDownload } from "../schemas/downloads.js";
+import { AddDownloadAsset, CreateDownload, Download, DownloadAssetParams, DownloadFile, DownloadIdParam, DownloadsPage, DownloadsQuery, RenameDownloadAsset, ReorderDownloadAssets, UpdateDownload } from "../schemas/downloads.js";
 import "../schemas/index.js";
-import { NotFoundError } from "@headless-lms/core/shared/errors";
 import { z } from "zod";
+import { NotFoundError } from "@headless-lms/core/shared/errors";
 //#region src/http/routes/downloads.ts
 async function downloadsRoutes(app, container) {
 	const r = app.withTypeProvider();
@@ -14,10 +14,14 @@ async function downloadsRoutes(app, container) {
 		preHandler: app.requireOrgSession,
 		schema: {
 			operationId: "listDownloads",
-			tags: ["Downloads"],
-			summary: "List downloads",
+			tags: ["Content"],
+			summary: "List downloads (staff)",
+			description: "Staff only (owner, admin, instructor). Every download, drafts included, filtered by status and category and searched by title.",
 			querystring: DownloadsQuery,
-			response: { 200: DownloadsPage }
+			response: {
+				200: DownloadsPage,
+				...refusals(403)
+			}
 		},
 		handler: async (req) => {
 			const scope = await resolveScope(container, req);
@@ -30,12 +34,13 @@ async function downloadsRoutes(app, container) {
 		preHandler: app.requireOrgSession,
 		schema: {
 			operationId: "getDownload",
-			tags: ["Downloads"],
-			summary: "Get a download by id",
+			tags: ["Content"],
+			summary: "Get a download (staff)",
+			description: "Staff only (owner, admin, instructor).",
 			params: DownloadIdParam,
 			response: {
 				200: Download,
-				404: ErrorBody
+				...refusals(403, 404)
 			}
 		},
 		handler: async (req) => {
@@ -51,10 +56,14 @@ async function downloadsRoutes(app, container) {
 		preHandler: app.requireOrgSession,
 		schema: {
 			operationId: "createDownload",
-			tags: ["Downloads"],
-			summary: "Create a download",
+			tags: ["Content"],
+			summary: "Create a download (staff)",
+			description: "Staff only (owner, admin, instructor). The download starts as a draft. 409 when its slug is taken.",
 			body: CreateDownload,
-			response: { 201: Download }
+			response: {
+				201: Download,
+				...refusals(403, 409)
+			}
 		},
 		handler: async (req, reply) => {
 			const scope = await resolveScope(container, req);
@@ -68,13 +77,14 @@ async function downloadsRoutes(app, container) {
 		preHandler: app.requireOrgSession,
 		schema: {
 			operationId: "updateDownload",
-			tags: ["Downloads"],
-			summary: "Update a download",
+			tags: ["Content"],
+			summary: "Update a download (staff)",
+			description: "Staff only (owner, admin, instructor). Changes only the fields sent. `thumbnailAssetId` must be a ready library image (409 otherwise); null clears it.",
 			params: DownloadIdParam,
 			body: UpdateDownload,
 			response: {
 				200: Download,
-				404: ErrorBody
+				...refusals(403, 404, 409)
 			}
 		},
 		handler: async (req) => {
@@ -88,17 +98,21 @@ async function downloadsRoutes(app, container) {
 		preHandler: app.requireOrgSession,
 		schema: {
 			operationId: "deleteDownload",
-			tags: ["Downloads"],
-			summary: "Delete a download",
+			tags: ["Content"],
+			summary: "Delete a download (staff)",
+			description: "Staff only (owner, admin, instructor). Its library files survive.",
 			params: DownloadIdParam,
 			response: {
 				204: z.void(),
-				404: ErrorBody
+				...refusals(403, 404)
 			}
 		},
 		handler: async (req, reply) => {
 			const scope = await resolveScope(container, req);
-			await content.removeDownload(scope.orgId, req.params.downloadId);
+			await content.removeDownload(scope.orgId, req.params.downloadId, {
+				id: scope.orgUserId,
+				role: scope.role
+			});
 			return reply.code(204).send();
 		}
 	});
@@ -108,12 +122,13 @@ async function downloadsRoutes(app, container) {
 		preHandler: app.requireOrgSession,
 		schema: {
 			operationId: "listDownloadAssets",
-			tags: ["Downloads"],
-			summary: "List a download's assets in order",
+			tags: ["Content"],
+			summary: "List a download's files in order (staff)",
+			description: "Staff only (owner, admin, instructor).",
 			params: DownloadIdParam,
 			response: {
-				200: z.array(DownloadAsset),
-				404: ErrorBody
+				200: z.array(DownloadFile),
+				...refusals(403)
 			}
 		},
 		handler: async (req) => {
@@ -127,13 +142,14 @@ async function downloadsRoutes(app, container) {
 		preHandler: app.requireOrgSession,
 		schema: {
 			operationId: "addDownloadAsset",
-			tags: ["Downloads"],
-			summary: "Link a media-library asset to a download",
+			tags: ["Content"],
+			summary: "Add a library file to a download (staff)",
+			description: "Staff only (owner, admin, instructor). Added last. 409 when the file is not a ready library file or is already in the download. Returns the download's files.",
 			params: DownloadIdParam,
 			body: AddDownloadAsset,
 			response: {
-				200: z.array(DownloadAsset),
-				404: ErrorBody
+				200: z.array(DownloadFile),
+				...refusals(403, 404, 409)
 			}
 		},
 		handler: async (req) => {
@@ -147,14 +163,14 @@ async function downloadsRoutes(app, container) {
 		preHandler: app.requireOrgSession,
 		schema: {
 			operationId: "reorderDownloadAssets",
-			tags: ["Downloads"],
-			summary: "Reorder a download's assets (send the complete set)",
+			tags: ["Content"],
+			summary: "Reorder a download's files (staff)",
+			description: "Staff only (owner, admin, instructor). Send every file id of the download exactly once (409 otherwise). Returns the download's files.",
 			params: DownloadIdParam,
 			body: ReorderDownloadAssets,
 			response: {
-				200: z.array(DownloadAsset),
-				404: ErrorBody,
-				409: ErrorBody
+				200: z.array(DownloadFile),
+				...refusals(403, 404, 409)
 			}
 		},
 		handler: async (req) => {
@@ -168,13 +184,14 @@ async function downloadsRoutes(app, container) {
 		preHandler: app.requireOrgSession,
 		schema: {
 			operationId: "renameDownloadAsset",
-			tags: ["Downloads"],
-			summary: "Set an asset's display name within a download",
+			tags: ["Content"],
+			summary: "Set a file's display name within a download (staff)",
+			description: "Staff only (owner, admin, instructor). Null falls back to the filename. Returns the download's files.",
 			params: DownloadAssetParams,
 			body: RenameDownloadAsset,
 			response: {
-				200: z.array(DownloadAsset),
-				404: ErrorBody
+				200: z.array(DownloadFile),
+				...refusals(403, 404)
 			}
 		},
 		handler: async (req) => {
@@ -188,12 +205,13 @@ async function downloadsRoutes(app, container) {
 		preHandler: app.requireOrgSession,
 		schema: {
 			operationId: "removeDownloadAsset",
-			tags: ["Downloads"],
-			summary: "Unlink an asset from a download (the asset itself survives)",
+			tags: ["Content"],
+			summary: "Remove a file from a download (staff)",
+			description: "Staff only (owner, admin, instructor). The library file itself survives. Returns the download's files.",
 			params: DownloadAssetParams,
 			response: {
-				200: z.array(DownloadAsset),
-				404: ErrorBody
+				200: z.array(DownloadFile),
+				...refusals(403, 404)
 			}
 		},
 		handler: async (req) => {