@headless-lms/server 0.2.0 → 0.3.0

package/dist/http/plugins/error-handler.js

@@ -1,75 +1,59 @@
-import { UnauthorizedError } from "./auth.js";
-import { NoActiveOrgError } from "../scope.js";
-import { OrganizationRuleError } from "@headless-lms/core/organizations";
-import { ActionInvocationError, AlreadyConnectedError, InvalidConfigError, UnknownIntegrationError } from "@headless-lms/core/integrations";
-import { AutomationKindMismatchError, InvalidTriggerError, ReservedActionError } from "@headless-lms/core/automations";
-import { ConflictError, ForbiddenError, NotFoundError } from "@headless-lms/core/shared/errors";
+import { classifyError } from "../errors.js";
+import { ActionInvocationError } from "@headless-lms/core/integrations";
+import { isResponseSerializationError } from "fastify-type-provider-zod";
 //#region src/http/plugins/error-handler.ts
+function routeOf(request) {
+	return `${request.method} ${request.routeOptions.url ?? "unmatched route"}`;
+}
 function errorHandler(error, request, reply) {
-	if (error instanceof NotFoundError) return reply.status(404).send({
-		error: "not_found",
-		message: error.message
-	});
-	if (error instanceof ConflictError) return reply.status(409).send({
-		error: "conflict",
-		message: error.message
-	});
-	if (error instanceof ForbiddenError) return reply.status(403).send({
-		error: "forbidden",
-		message: error.message
-	});
-	if (error instanceof OrganizationRuleError) return reply.status(409).send({
-		error: "conflict",
-		message: error.message
-	});
-	if (error instanceof AlreadyConnectedError) return reply.status(409).send({
-		error: "already_connected",
-		message: error.message
-	});
-	if (error instanceof UnknownIntegrationError) return reply.status(400).send({
-		error: "unknown_integration",
-		message: error.message
-	});
-	if (error instanceof InvalidConfigError) return reply.status(400).send({
-		error: "invalid_config",
-		message: error.message
-	});
-	if (error instanceof ActionInvocationError) return reply.status(502).send({
-		error: "action_failed",
-		message: error.message
-	});
-	if (error instanceof InvalidTriggerError) return reply.status(400).send({
-		error: "invalid_trigger",
-		message: error.message
-	});
-	if (error instanceof ReservedActionError) return reply.status(400).send({
-		error: "reserved_action",
-		message: error.message
-	});
-	if (error instanceof AutomationKindMismatchError) return reply.status(409).send({
-		error: "kind_mismatch",
-		message: error.message
-	});
-	if (error instanceof NoActiveOrgError) return reply.status(403).send({
-		error: "forbidden",
-		message: error.message
-	});
-	if (error instanceof UnauthorizedError) return reply.status(401).send({
-		error: "unauthorized",
-		message: error.message
-	});
-	const err = error;
-	if (typeof err.statusCode === "number" && err.statusCode >= 400 && err.statusCode < 500) return reply.status(err.statusCode).send({
-		error: err.code ?? "bad_request",
-		message: err.message ?? "Bad request"
-	});
-	request.log.error({ err: error }, `unhandled error in ${request.method} ${request.url}`);
+	if (error instanceof ActionInvocationError) {
+		request.log.error({
+			err: error,
+			integrationId: error.integrationId,
+			actionId: error.actionId
+		}, `integration action failed in ${routeOf(request)}`);
+		return reply.status(502).send({
+			error: "action_failed",
+			message: "The integration did not respond as expected"
+		});
+	}
+	const refusal = classifyError(error);
+	if (refusal) {
+		request.log.info({
+			status: refusal.status,
+			error: refusal.error,
+			message: refusal.message,
+			...refusal.issues && { issues: refusal.issues },
+			...refusal.error === "bad_request" && { cause: error.message }
+		}, `${routeOf(request)} refused`);
+		return reply.status(refusal.status).send({
+			error: refusal.error,
+			message: refusal.message,
+			...refusal.issues && { issues: refusal.issues }
+		});
+	}
+	if (isResponseSerializationError(error)) request.log.error({
+		err: error,
+		issues: error.cause.issues
+	}, `response of ${routeOf(request)} does not match its schema`);
+	else request.log.error({ err: error }, `unhandled error in ${routeOf(request)}`);
 	return reply.status(500).send({
 		error: "internal_error",
+		message: "Something went wrong on our side. Quote the request id when reporting it.",
 		requestId: request.id
 	});
 }
+function notFoundHandler(request, reply) {
+	request.log.info({
+		status: 404,
+		error: "not_found"
+	}, `${request.method} unmatched route refused`);
+	return reply.status(404).send({
+		error: "not_found",
+		message: `No route for ${request.method} ${request.url}`
+	});
+}
 //#endregion
-export { errorHandler };
+export { errorHandler, notFoundHandler };
 
 //# sourceMappingURL=error-handler.js.map

package/dist/http/plugins/error-handler.js.map

@@ -1 +1 @@
-{"version":3,"file":"error-handler.js","names":[],"sources":["../../../src/http/plugins/error-handler.ts"],"sourcesContent":["import { ConflictError, ForbiddenError, NotFoundError } from '@headless-lms/core/shared/errors';\nimport { OrganizationRuleError } from '@headless-lms/core/organizations';\nimport {\n  ActionInvocationError,\n  AlreadyConnectedError,\n  InvalidConfigError,\n  UnknownIntegrationError,\n} from '@headless-lms/core/integrations';\nimport {\n  AutomationKindMismatchError,\n  InvalidTriggerError,\n  ReservedActionError,\n} from '@headless-lms/core/automations';\nimport { NoActiveOrgError } from '../scope.js';\nimport { UnauthorizedError } from './auth.js';\nimport type { FastifyReply, FastifyRequest } from 'fastify';\n\nexport function errorHandler(error: unknown, request: FastifyRequest, reply: FastifyReply) {\n  if (error instanceof NotFoundError) {\n    return reply.status(404).send({ error: 'not_found', message: error.message });\n  }\n  if (error instanceof ConflictError) {\n    return reply.status(409).send({ error: 'conflict', message: error.message });\n  }\n  if (error instanceof ForbiddenError) {\n    return reply.status(403).send({ error: 'forbidden', message: error.message });\n  }\n  if (error instanceof OrganizationRuleError) {\n    return reply.status(409).send({ error: 'conflict', message: error.message });\n  }\n  if (error instanceof AlreadyConnectedError) {\n    return reply.status(409).send({ error: 'already_connected', message: error.message });\n  }\n  if (error instanceof UnknownIntegrationError) {\n    return reply.status(400).send({ error: 'unknown_integration', message: error.message });\n  }\n  if (error instanceof InvalidConfigError) {\n    return reply.status(400).send({ error: 'invalid_config', message: error.message });\n  }\n  if (error instanceof ActionInvocationError) {\n    return reply.status(502).send({ error: 'action_failed', message: error.message });\n  }\n  if (error instanceof InvalidTriggerError) {\n    return reply.status(400).send({ error: 'invalid_trigger', message: error.message });\n  }\n  if (error instanceof ReservedActionError) {\n    return reply.status(400).send({ error: 'reserved_action', message: error.message });\n  }\n  if (error instanceof AutomationKindMismatchError) {\n    return reply.status(409).send({ error: 'kind_mismatch', message: error.message });\n  }\n  if (error instanceof NoActiveOrgError) {\n    return reply.status(403).send({ error: 'forbidden', message: error.message });\n  }\n  // No session at all — 401 so the client bounces to login, not a generic 403.\n  if (error instanceof UnauthorizedError) {\n    return reply.status(401).send({ error: 'unauthorized', message: error.message });\n  }\n  const err = error as { statusCode?: number; code?: string; message?: string };\n  if (typeof err.statusCode === 'number' && err.statusCode >= 400 && err.statusCode < 500) {\n    return reply\n      .status(err.statusCode)\n      .send({ error: err.code ?? 'bad_request', message: err.message ?? 'Bad request' });\n  }\n  request.log.error({ err: error }, `unhandled error in ${request.method} ${request.url}`);\n  return reply.status(500).send({ error: 'internal_error', requestId: request.id });\n}\n"],"mappings":";;;;;;;AAiBA,SAAgB,aAAa,OAAgB,SAAyB,OAAqB;CACzF,IAAI,iBAAiB,eACnB,OAAO,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK;EAAE,OAAO;EAAa,SAAS,MAAM;CAAQ,CAAC;CAE9E,IAAI,iBAAiB,eACnB,OAAO,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK;EAAE,OAAO;EAAY,SAAS,MAAM;CAAQ,CAAC;CAE7E,IAAI,iBAAiB,gBACnB,OAAO,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK;EAAE,OAAO;EAAa,SAAS,MAAM;CAAQ,CAAC;CAE9E,IAAI,iBAAiB,uBACnB,OAAO,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK;EAAE,OAAO;EAAY,SAAS,MAAM;CAAQ,CAAC;CAE7E,IAAI,iBAAiB,uBACnB,OAAO,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK;EAAE,OAAO;EAAqB,SAAS,MAAM;CAAQ,CAAC;CAEtF,IAAI,iBAAiB,yBACnB,OAAO,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK;EAAE,OAAO;EAAuB,SAAS,MAAM;CAAQ,CAAC;CAExF,IAAI,iBAAiB,oBACnB,OAAO,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK;EAAE,OAAO;EAAkB,SAAS,MAAM;CAAQ,CAAC;CAEnF,IAAI,iBAAiB,uBACnB,OAAO,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK;EAAE,OAAO;EAAiB,SAAS,MAAM;CAAQ,CAAC;CAElF,IAAI,iBAAiB,qBACnB,OAAO,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK;EAAE,OAAO;EAAmB,SAAS,MAAM;CAAQ,CAAC;CAEpF,IAAI,iBAAiB,qBACnB,OAAO,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK;EAAE,OAAO;EAAmB,SAAS,MAAM;CAAQ,CAAC;CAEpF,IAAI,iBAAiB,6BACnB,OAAO,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK;EAAE,OAAO;EAAiB,SAAS,MAAM;CAAQ,CAAC;CAElF,IAAI,iBAAiB,kBACnB,OAAO,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK;EAAE,OAAO;EAAa,SAAS,MAAM;CAAQ,CAAC;CAG9E,IAAI,iBAAiB,mBACnB,OAAO,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK;EAAE,OAAO;EAAgB,SAAS,MAAM;CAAQ,CAAC;CAEjF,MAAM,MAAM;CACZ,IAAI,OAAO,IAAI,eAAe,YAAY,IAAI,cAAc,OAAO,IAAI,aAAa,KAClF,OAAO,MACJ,OAAO,IAAI,UAAU,CAAC,CACtB,KAAK;EAAE,OAAO,IAAI,QAAQ;EAAe,SAAS,IAAI,WAAW;CAAc,CAAC;CAErF,QAAQ,IAAI,MAAM,EAAE,KAAK,MAAM,GAAG,sBAAsB,QAAQ,OAAO,GAAG,QAAQ,KAAK;CACvF,OAAO,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK;EAAE,OAAO;EAAkB,WAAW,QAAQ;CAAG,CAAC;AAClF"}
+{"version":3,"file":"error-handler.js","names":[],"sources":["../../../src/http/plugins/error-handler.ts"],"sourcesContent":["import type { FastifyReply, FastifyRequest } from 'fastify';\nimport { ActionInvocationError } from '@headless-lms/core/integrations';\nimport { isResponseSerializationError } from 'fastify-type-provider-zod';\nimport { classifyError } from '../errors.js';\n\nfunction routeOf(request: FastifyRequest): string {\n  return `${request.method} ${request.routeOptions.url ?? 'unmatched route'}`;\n}\n\nexport function errorHandler(error: unknown, request: FastifyRequest, reply: FastifyReply) {\n  if (error instanceof ActionInvocationError) {\n    request.log.error(\n      { err: error, integrationId: error.integrationId, actionId: error.actionId },\n      `integration action failed in ${routeOf(request)}`,\n    );\n    return reply.status(502).send({\n      error: 'action_failed',\n      message: 'The integration did not respond as expected',\n    });\n  }\n  const refusal = classifyError(error);\n  if (refusal) {\n    request.log.info(\n      {\n        status: refusal.status,\n        error: refusal.error,\n        message: refusal.message,\n        ...(refusal.issues && { issues: refusal.issues }),\n        ...(refusal.error === 'bad_request' && { cause: (error as Error).message }),\n      },\n      `${routeOf(request)} refused`,\n    );\n    return reply.status(refusal.status).send({\n      error: refusal.error,\n      message: refusal.message,\n      ...(refusal.issues && { issues: refusal.issues }),\n    });\n  }\n  if (isResponseSerializationError(error)) {\n    request.log.error(\n      { err: error, issues: error.cause.issues },\n      `response of ${routeOf(request)} does not match its schema`,\n    );\n  } else {\n    request.log.error({ err: error }, `unhandled error in ${routeOf(request)}`);\n  }\n  return reply.status(500).send({\n    error: 'internal_error',\n    message: 'Something went wrong on our side. Quote the request id when reporting it.',\n    requestId: request.id,\n  });\n}\n\nexport function notFoundHandler(request: FastifyRequest, reply: FastifyReply) {\n  request.log.info(\n    { status: 404, error: 'not_found' },\n    `${request.method} unmatched route refused`,\n  );\n  return reply\n    .status(404)\n    .send({ error: 'not_found', message: `No route for ${request.method} ${request.url}` });\n}\n"],"mappings":";;;;AAKA,SAAS,QAAQ,SAAiC;CAChD,OAAO,GAAG,QAAQ,OAAO,GAAG,QAAQ,aAAa,OAAO;AAC1D;AAEA,SAAgB,aAAa,OAAgB,SAAyB,OAAqB;CACzF,IAAI,iBAAiB,uBAAuB;EAC1C,QAAQ,IAAI,MACV;GAAE,KAAK;GAAO,eAAe,MAAM;GAAe,UAAU,MAAM;EAAS,GAC3E,gCAAgC,QAAQ,OAAO,GACjD;EACA,OAAO,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK;GAC5B,OAAO;GACP,SAAS;EACX,CAAC;CACH;CACA,MAAM,UAAU,cAAc,KAAK;CACnC,IAAI,SAAS;EACX,QAAQ,IAAI,KACV;GACE,QAAQ,QAAQ;GAChB,OAAO,QAAQ;GACf,SAAS,QAAQ;GACjB,GAAI,QAAQ,UAAU,EAAE,QAAQ,QAAQ,OAAO;GAC/C,GAAI,QAAQ,UAAU,iBAAiB,EAAE,OAAQ,MAAgB,QAAQ;EAC3E,GACA,GAAG,QAAQ,OAAO,EAAE,SACtB;EACA,OAAO,MAAM,OAAO,QAAQ,MAAM,CAAC,CAAC,KAAK;GACvC,OAAO,QAAQ;GACf,SAAS,QAAQ;GACjB,GAAI,QAAQ,UAAU,EAAE,QAAQ,QAAQ,OAAO;EACjD,CAAC;CACH;CACA,IAAI,6BAA6B,KAAK,GACpC,QAAQ,IAAI,MACV;EAAE,KAAK;EAAO,QAAQ,MAAM,MAAM;CAAO,GACzC,eAAe,QAAQ,OAAO,EAAE,2BAClC;MAEA,QAAQ,IAAI,MAAM,EAAE,KAAK,MAAM,GAAG,sBAAsB,QAAQ,OAAO,GAAG;CAE5E,OAAO,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK;EAC5B,OAAO;EACP,SAAS;EACT,WAAW,QAAQ;CACrB,CAAC;AACH;AAEA,SAAgB,gBAAgB,SAAyB,OAAqB;CAC5E,QAAQ,IAAI,KACV;EAAE,QAAQ;EAAK,OAAO;CAAY,GAClC,GAAG,QAAQ,OAAO,yBACpB;CACA,OAAO,MACJ,OAAO,GAAG,CAAC,CACX,KAAK;EAAE,OAAO;EAAa,SAAS,gBAAgB,QAAQ,OAAO,GAAG,QAAQ;CAAM,CAAC;AAC1F"}

package/dist/http/plugins/openapi.js

@@ -1,8 +1,21 @@
-import { version } from "../../package.js";
+import { ErrorBody, ValidationErrorBody } from "../schemas/shared.js";
+import { version } from "../../packages/server/package.js";
 import { jsonSchemaTransform, jsonSchemaTransformObject } from "fastify-type-provider-zod";
 import swagger from "@fastify/swagger";
 import swaggerUi from "@fastify/swagger-ui";
 //#region src/http/plugins/openapi.ts
+const PUBLIC_ROUTES = /* @__PURE__ */ new Set(["GET /api/organizations/invites/:token"]);
+function withDefaultResponses(schema, method, url) {
+	if (!schema || !url.startsWith("/api/") || url.startsWith("/api/auth/")) return schema;
+	const response = { ...schema.response ?? {} };
+	if ((schema.body || schema.querystring || schema.params) && !response["400"]) response["400"] = ValidationErrorBody;
+	if (!PUBLIC_ROUTES.has(`${method} ${url}`) && !response["401"]) response["401"] = ErrorBody;
+	if (!response["500"]) response["500"] = ErrorBody;
+	return {
+		...schema,
+		response
+	};
+}
 function registerOpenApi(app, config) {
 	app.register(swagger, {
 		openapi: {
@@ -37,10 +50,34 @@ function registerOpenApi(app, config) {
 					name: "Discussion",
 					description: "Learner comments, replies, reactions and moderation"
 				},
+				{
+					name: "Communities",
+					description: "Communities, their spaces, topics, and direct-message settings"
+				},
+				{
+					name: "Posts",
+					description: "Posts in a space, reactions, and the moderation queue"
+				},
+				{
+					name: "Chats",
+					description: "Direct and group chats inside one community"
+				},
+				{
+					name: "Profile",
+					description: "The signed-in member profile"
+				},
+				{
+					name: "Notifications",
+					description: "What happened to the signed-in member, and how they want to be told"
+				},
 				{
 					name: "Assets",
 					description: "The org media library: uploads, serving and lifecycle"
 				},
+				{
+					name: "Files",
+					description: "Stable file URLs that check access and redirect to a signed storage URL"
+				},
 				{
 					name: "Automations",
 					description: "Workflows and webhooks that react to system events"
@@ -52,10 +89,20 @@ function registerOpenApi(app, config) {
 				{
 					name: "Reporting",
 					description: "Reporting and analytics"
+				},
+				{
+					name: "Access",
+					description: "Access scopes, connected apps and API keys"
 				}
 			]
 		},
-		transform: jsonSchemaTransform,
+		transform: (input) => {
+			const method = String(Array.isArray(input.route.method) ? input.route.method[0] : input.route.method);
+			return jsonSchemaTransform({
+				...input,
+				schema: withDefaultResponses(input.schema, method, input.url)
+			});
+		},
 		transformObject: jsonSchemaTransformObject
 	});
 	app.register(swaggerUi, { routePrefix: "/docs" });

package/dist/http/plugins/openapi.js.map

@@ -1 +1 @@
-{"version":3,"file":"openapi.js","names":["pkg.version"],"sources":["../../../src/http/plugins/openapi.ts"],"sourcesContent":["// OpenAPI documentation. @fastify/swagger reads the Zod route schemas (via the\n// transform) to build the spec the frontend SDK is generated from; it must be\n// registered before the routes so its onRoute hook captures them. UI + JSON are\n// served under /docs.\nimport type { FastifyInstance } from 'fastify';\nimport swagger from '@fastify/swagger';\nimport swaggerUi from '@fastify/swagger-ui';\nimport { jsonSchemaTransform, jsonSchemaTransformObject } from 'fastify-type-provider-zod';\nimport type { ServerConfig } from '../config.js';\nimport pkg from '../../../package.json' with { type: 'json' };\n\nexport function registerOpenApi(app: FastifyInstance, config: ServerConfig): void {\n  app.register(swagger, {\n    openapi: {\n      info: {\n        title: 'Headless LMS API',\n        version: pkg.version,\n        description: 'API documentation for the Headless LMS platform',\n        license: {\n          name: 'MIT',\n          url: 'https://opensource.org/licenses/MIT',\n        },\n      },\n      servers: [{ url: config.publicUrl }],\n      tags: [\n        {\n          name: 'Organizations',\n          description: 'The tenant: its members, roles, invites and students',\n        },\n        {\n          name: 'Content',\n          description: 'Authored content: courses and downloads, their structure and delivery',\n        },\n        { name: 'Entitlements', description: 'Access grants to content' },\n        {\n          name: 'Progress',\n          description: 'Per-student progress and completion through course content',\n        },\n        { name: 'Discussion', description: 'Learner comments, replies, reactions and moderation' },\n        { name: 'Assets', description: 'The org media library: uploads, serving and lifecycle' },\n        { name: 'Automations', description: 'Workflows and webhooks that react to system events' },\n        { name: 'Integrations', description: 'Connections to external services' },\n        { name: 'Reporting', description: 'Reporting and analytics' },\n      ],\n    },\n    transform: jsonSchemaTransform,\n    transformObject: jsonSchemaTransformObject,\n  });\n  app.register(swaggerUi, { routePrefix: '/docs' });\n}\n"],"mappings":";;;;;AAWA,SAAgB,gBAAgB,KAAsB,QAA4B;CAChF,IAAI,SAAS,SAAS;EACpB,SAAS;GACP,MAAM;IACJ,OAAO;IACEA;IACT,aAAa;IACb,SAAS;KACP,MAAM;KACN,KAAK;IACP;GACF;GACA,SAAS,CAAC,EAAE,KAAK,OAAO,UAAU,CAAC;GACnC,MAAM;IACJ;KACE,MAAM;KACN,aAAa;IACf;IACA;KACE,MAAM;KACN,aAAa;IACf;IACA;KAAE,MAAM;KAAgB,aAAa;IAA2B;IAChE;KACE,MAAM;KACN,aAAa;IACf;IACA;KAAE,MAAM;KAAc,aAAa;IAAsD;IACzF;KAAE,MAAM;KAAU,aAAa;IAAwD;IACvF;KAAE,MAAM;KAAe,aAAa;IAAqD;IACzF;KAAE,MAAM;KAAgB,aAAa;IAAmC;IACxE;KAAE,MAAM;KAAa,aAAa;IAA0B;GAC9D;EACF;EACA,WAAW;EACX,iBAAiB;CACnB,CAAC;CACD,IAAI,SAAS,WAAW,EAAE,aAAa,QAAQ,CAAC;AAClD"}
+{"version":3,"file":"openapi.js","names":["pkg.version"],"sources":["../../../src/http/plugins/openapi.ts"],"sourcesContent":["// OpenAPI documentation. @fastify/swagger reads the Zod route schemas (via the\n// transform) to build the spec the frontend SDK is generated from; it must be\n// registered before the routes so its onRoute hook captures them. UI + JSON are\n// served under /docs.\nimport type { FastifyInstance } from 'fastify';\nimport swagger from '@fastify/swagger';\nimport swaggerUi from '@fastify/swagger-ui';\nimport { jsonSchemaTransform, jsonSchemaTransformObject } from 'fastify-type-provider-zod';\nimport type { ServerConfig } from '../config.js';\nimport { ErrorBody, ValidationErrorBody } from '../schemas/shared.js';\nimport pkg from '../../../package.json' with { type: 'json' };\n\nconst PUBLIC_ROUTES = new Set(['GET /api/organizations/invites/:token']);\n\ntype RouteSchema = {\n  body?: unknown;\n  querystring?: unknown;\n  params?: unknown;\n  response?: Record<string, unknown>;\n};\n\nfunction withDefaultResponses(\n  schema: RouteSchema | undefined,\n  method: string,\n  url: string,\n): RouteSchema | undefined {\n  if (!schema || !url.startsWith('/api/') || url.startsWith('/api/auth/')) {\n    return schema;\n  }\n  const response: Record<string, unknown> = { ...(schema.response ?? {}) };\n  if ((schema.body || schema.querystring || schema.params) && !response['400']) {\n    response['400'] = ValidationErrorBody;\n  }\n  if (!PUBLIC_ROUTES.has(`${method} ${url}`) && !response['401']) {\n    response['401'] = ErrorBody;\n  }\n  if (!response['500']) {\n    response['500'] = ErrorBody;\n  }\n  return { ...schema, response };\n}\n\nexport function registerOpenApi(app: FastifyInstance, config: ServerConfig): void {\n  app.register(swagger, {\n    openapi: {\n      info: {\n        title: 'Headless LMS API',\n        version: pkg.version,\n        description: 'API documentation for the Headless LMS platform',\n        license: {\n          name: 'MIT',\n          url: 'https://opensource.org/licenses/MIT',\n        },\n      },\n      servers: [{ url: config.publicUrl }],\n      tags: [\n        {\n          name: 'Organizations',\n          description: 'The tenant: its members, roles, invites and students',\n        },\n        {\n          name: 'Content',\n          description: 'Authored content: courses and downloads, their structure and delivery',\n        },\n        { name: 'Entitlements', description: 'Access grants to content' },\n        {\n          name: 'Progress',\n          description: 'Per-student progress and completion through course content',\n        },\n        { name: 'Discussion', description: 'Learner comments, replies, reactions and moderation' },\n        {\n          name: 'Communities',\n          description: 'Communities, their spaces, topics, and direct-message settings',\n        },\n        { name: 'Posts', description: 'Posts in a space, reactions, and the moderation queue' },\n        { name: 'Chats', description: 'Direct and group chats inside one community' },\n        { name: 'Profile', description: 'The signed-in member profile' },\n        {\n          name: 'Notifications',\n          description: 'What happened to the signed-in member, and how they want to be told',\n        },\n        { name: 'Assets', description: 'The org media library: uploads, serving and lifecycle' },\n        {\n          name: 'Files',\n          description: 'Stable file URLs that check access and redirect to a signed storage URL',\n        },\n        { name: 'Automations', description: 'Workflows and webhooks that react to system events' },\n        { name: 'Integrations', description: 'Connections to external services' },\n        { name: 'Reporting', description: 'Reporting and analytics' },\n        { name: 'Access', description: 'Access scopes, connected apps and API keys' },\n      ],\n    },\n    transform: (input) => {\n      const method = String(\n        Array.isArray(input.route.method) ? input.route.method[0] : input.route.method,\n      );\n      return jsonSchemaTransform({\n        ...input,\n        schema: withDefaultResponses(input.schema as RouteSchema | undefined, method, input.url),\n      } as typeof input);\n    },\n    transformObject: jsonSchemaTransformObject,\n  });\n  app.register(swaggerUi, { routePrefix: '/docs' });\n}\n"],"mappings":";;;;;;AAYA,MAAM,gCAAgB,IAAI,IAAI,CAAC,uCAAuC,CAAC;AASvE,SAAS,qBACP,QACA,QACA,KACyB;CACzB,IAAI,CAAC,UAAU,CAAC,IAAI,WAAW,OAAO,KAAK,IAAI,WAAW,YAAY,GACpE,OAAO;CAET,MAAM,WAAoC,EAAE,GAAI,OAAO,YAAY,CAAC,EAAG;CACvE,KAAK,OAAO,QAAQ,OAAO,eAAe,OAAO,WAAW,CAAC,SAAS,QACpE,SAAS,SAAS;CAEpB,IAAI,CAAC,cAAc,IAAI,GAAG,OAAO,GAAG,KAAK,KAAK,CAAC,SAAS,QACtD,SAAS,SAAS;CAEpB,IAAI,CAAC,SAAS,QACZ,SAAS,SAAS;CAEpB,OAAO;EAAE,GAAG;EAAQ;CAAS;AAC/B;AAEA,SAAgB,gBAAgB,KAAsB,QAA4B;CAChF,IAAI,SAAS,SAAS;EACpB,SAAS;GACP,MAAM;IACJ,OAAO;IACEA;IACT,aAAa;IACb,SAAS;KACP,MAAM;KACN,KAAK;IACP;GACF;GACA,SAAS,CAAC,EAAE,KAAK,OAAO,UAAU,CAAC;GACnC,MAAM;IACJ;KACE,MAAM;KACN,aAAa;IACf;IACA;KACE,MAAM;KACN,aAAa;IACf;IACA;KAAE,MAAM;KAAgB,aAAa;IAA2B;IAChE;KACE,MAAM;KACN,aAAa;IACf;IACA;KAAE,MAAM;KAAc,aAAa;IAAsD;IACzF;KACE,MAAM;KACN,aAAa;IACf;IACA;KAAE,MAAM;KAAS,aAAa;IAAwD;IACtF;KAAE,MAAM;KAAS,aAAa;IAA8C;IAC5E;KAAE,MAAM;KAAW,aAAa;IAA+B;IAC/D;KACE,MAAM;KACN,aAAa;IACf;IACA;KAAE,MAAM;KAAU,aAAa;IAAwD;IACvF;KACE,MAAM;KACN,aAAa;IACf;IACA;KAAE,MAAM;KAAe,aAAa;IAAqD;IACzF;KAAE,MAAM;KAAgB,aAAa;IAAmC;IACxE;KAAE,MAAM;KAAa,aAAa;IAA0B;IAC5D;KAAE,MAAM;KAAU,aAAa;IAA6C;GAC9E;EACF;EACA,YAAY,UAAU;GACpB,MAAM,SAAS,OACb,MAAM,QAAQ,MAAM,MAAM,MAAM,IAAI,MAAM,MAAM,OAAO,KAAK,MAAM,MAAM,MAC1E;GACA,OAAO,oBAAoB;IACzB,GAAG;IACH,QAAQ,qBAAqB,MAAM,QAAmC,QAAQ,MAAM,GAAG;GACzF,CAAiB;EACnB;EACA,iBAAiB;CACnB,CAAC;CACD,IAAI,SAAS,WAAW,EAAE,aAAa,QAAQ,CAAC;AAClD"}

package/dist/http/routes/access.d.ts

@@ -0,0 +1,7 @@
+import { Container } from "../../app/container.js";
+import { FastifyInstance } from "fastify";
+//#region src/http/routes/access.d.ts
+declare function accessRoutes(app: FastifyInstance, container: Container): Promise<void>;
+//#endregion
+export { accessRoutes };
+//# sourceMappingURL=access.d.ts.map

package/dist/http/routes/access.js

@@ -0,0 +1,140 @@
+import { refusals } from "../schemas/shared.js";
+import { resolveScope } from "../scope.js";
+import { ApiKeyIdParam, ApiKeyList, ClientIdParam, ConnectedAppList, CreateApiKey, CreatedApiKey, ScopeOptionList } from "../schemas/access.js";
+import "../schemas/index.js";
+import { assertRoleHoldsScopes, scopeOptions } from "@headless-lms/core/organizations";
+import { z } from "zod";
+//#region src/http/routes/access.ts
+async function accessRoutes(app, container) {
+	const r = app.withTypeProvider();
+	const tags = ["Access"];
+	r.route({
+		method: "GET",
+		url: "/api/access/scopes",
+		preHandler: app.requireOrgSession,
+		schema: {
+			operationId: "listAccessScopes",
+			tags,
+			summary: "Every access scope and whether your role can grant it",
+			description: "Staff only (owner, admin, instructor). Each scope an app connection or API key can carry, marked with whether your role holds it. Only allowed scopes can be granted.",
+			response: {
+				200: ScopeOptionList,
+				...refusals(403)
+			}
+		},
+		handler: async (req) => {
+			return scopeOptions((await resolveScope(container, req)).role);
+		}
+	});
+	r.route({
+		method: "GET",
+		url: "/api/access/apps",
+		preHandler: app.requireOrgSession,
+		schema: {
+			operationId: "listConnectedApps",
+			tags,
+			summary: "Apps connected to this organization as you",
+			description: "Staff only (owner, admin, instructor). The apps you connected to this organization, each with the scopes you granted and when.",
+			response: {
+				200: ConnectedAppList,
+				...refusals(403)
+			}
+		},
+		handler: async (req) => {
+			const scope = await resolveScope(container, req);
+			return container.auth.listConnectedApps(req.headers, scope.authOrgId);
+		}
+	});
+	r.route({
+		method: "DELETE",
+		url: "/api/access/apps/:clientId",
+		preHandler: app.requireOrgSession,
+		schema: {
+			operationId: "revokeConnectedApp",
+			tags,
+			summary: "Disconnect an app",
+			description: "Staff only (owner, admin, instructor). Revokes your consent and refresh tokens for the app in this organization; its next call is refused.",
+			params: ClientIdParam,
+			response: {
+				204: z.void(),
+				...refusals(403)
+			}
+		},
+		handler: async (req, reply) => {
+			const scope = await resolveScope(container, req);
+			await container.auth.revokeConnectedApp(req.headers, scope.authOrgId, req.params.clientId);
+			return reply.code(204).send();
+		}
+	});
+	r.route({
+		method: "GET",
+		url: "/api/access/api-keys",
+		preHandler: app.requireOrgSession,
+		schema: {
+			operationId: "listApiKeys",
+			tags,
+			summary: "Your API keys for this organization",
+			description: "Staff only (owner, admin, instructor). Your keys for this organization with their scopes. The key itself is never returned again after it is created.",
+			response: {
+				200: ApiKeyList,
+				...refusals(403)
+			}
+		},
+		handler: async (req) => {
+			const scope = await resolveScope(container, req);
+			return container.auth.listApiKeys(req.headers, scope.authOrgId);
+		}
+	});
+	r.route({
+		method: "POST",
+		url: "/api/access/api-keys",
+		preHandler: app.requireOrgSession,
+		schema: {
+			operationId: "createApiKey",
+			tags,
+			summary: "Create an API key",
+			description: "Staff only (owner, admin, instructor). The key acts as you in this organization with the scopes given. 403 when your role cannot hold one of them. The key is returned once.",
+			body: CreateApiKey,
+			response: {
+				201: CreatedApiKey,
+				...refusals(400, 403)
+			}
+		},
+		handler: async (req, reply) => {
+			const scope = await resolveScope(container, req);
+			assertRoleHoldsScopes(scope.role, req.body.scopes);
+			const created = await container.auth.createApiKey({
+				authUserId: req.authUser.id,
+				orgId: scope.authOrgId,
+				name: req.body.name,
+				scopes: req.body.scopes
+			});
+			return reply.code(201).send(created);
+		}
+	});
+	r.route({
+		method: "DELETE",
+		url: "/api/access/api-keys/:id",
+		preHandler: app.requireOrgSession,
+		schema: {
+			operationId: "deleteApiKey",
+			tags,
+			summary: "Delete an API key",
+			description: "Staff only (owner, admin, instructor). 404 when the key is not one of yours in this organization.",
+			params: ApiKeyIdParam,
+			response: {
+				204: z.void(),
+				...refusals(403, 404)
+			}
+		},
+		handler: async (req, reply) => {
+			const scope = await resolveScope(container, req);
+			await container.auth.deleteApiKey(req.headers, scope.authOrgId, req.params.id);
+			return reply.code(204).send();
+		}
+	});
+}
+//#endregion
+export { accessRoutes };
+
+//# sourceMappingURL=access.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"access.js","names":[],"sources":["../../../src/http/routes/access.ts"],"sourcesContent":["import type { FastifyInstance } from 'fastify';\nimport type { ZodTypeProvider } from 'fastify-type-provider-zod';\nimport { z } from 'zod';\nimport { assertRoleHoldsScopes, scopeOptions } from '@headless-lms/core/organizations';\nimport type { Container } from '../../app/container.js';\nimport {\n  ApiKeyIdParam,\n  ApiKeyList,\n  ClientIdParam,\n  ConnectedAppList,\n  CreateApiKey,\n  CreatedApiKey,\n  refusals,\n  ScopeOptionList,\n} from '../schemas/index.js';\nimport { resolveScope } from '../scope.js';\n\nexport async function accessRoutes(app: FastifyInstance, container: Container): Promise<void> {\n  const r = app.withTypeProvider<ZodTypeProvider>();\n  const tags = ['Access'];\n\n  r.route({\n    method: 'GET',\n    url: '/api/access/scopes',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'listAccessScopes',\n      tags,\n      summary: 'Every access scope and whether your role can grant it',\n      description:\n        'Staff only (owner, admin, instructor). Each scope an app connection or API key can carry, marked with whether your role holds it. Only allowed scopes can be granted.',\n      response: { 200: ScopeOptionList, ...refusals(403) },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      return scopeOptions(scope.role);\n    },\n  });\n\n  r.route({\n    method: 'GET',\n    url: '/api/access/apps',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'listConnectedApps',\n      tags,\n      summary: 'Apps connected to this organization as you',\n      description:\n        'Staff only (owner, admin, instructor). The apps you connected to this organization, each with the scopes you granted and when.',\n      response: { 200: ConnectedAppList, ...refusals(403) },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      return container.auth.listConnectedApps(req.headers, scope.authOrgId);\n    },\n  });\n\n  r.route({\n    method: 'DELETE',\n    url: '/api/access/apps/:clientId',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'revokeConnectedApp',\n      tags,\n      summary: 'Disconnect an app',\n      description:\n        'Staff only (owner, admin, instructor). Revokes your consent and refresh tokens for the app in this organization; its next call is refused.',\n      params: ClientIdParam,\n      response: { 204: z.void(), ...refusals(403) },\n    },\n    handler: async (req, reply) => {\n      const scope = await resolveScope(container, req);\n      await container.auth.revokeConnectedApp(req.headers, scope.authOrgId, req.params.clientId);\n      return reply.code(204).send();\n    },\n  });\n\n  r.route({\n    method: 'GET',\n    url: '/api/access/api-keys',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'listApiKeys',\n      tags,\n      summary: 'Your API keys for this organization',\n      description:\n        'Staff only (owner, admin, instructor). Your keys for this organization with their scopes. The key itself is never returned again after it is created.',\n      response: { 200: ApiKeyList, ...refusals(403) },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      return container.auth.listApiKeys(req.headers, scope.authOrgId);\n    },\n  });\n\n  r.route({\n    method: 'POST',\n    url: '/api/access/api-keys',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'createApiKey',\n      tags,\n      summary: 'Create an API key',\n      description:\n        'Staff only (owner, admin, instructor). The key acts as you in this organization with the scopes given. 403 when your role cannot hold one of them. The key is returned once.',\n      body: CreateApiKey,\n      response: { 201: CreatedApiKey, ...refusals(400, 403) },\n    },\n    handler: async (req, reply) => {\n      const scope = await resolveScope(container, req);\n      assertRoleHoldsScopes(scope.role, req.body.scopes);\n      const created = await container.auth.createApiKey({\n        authUserId: req.authUser.id,\n        orgId: scope.authOrgId,\n        name: req.body.name,\n        scopes: req.body.scopes,\n      });\n      return reply.code(201).send(created);\n    },\n  });\n\n  r.route({\n    method: 'DELETE',\n    url: '/api/access/api-keys/:id',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'deleteApiKey',\n      tags,\n      summary: 'Delete an API key',\n      description:\n        'Staff only (owner, admin, instructor). 404 when the key is not one of yours in this organization.',\n      params: ApiKeyIdParam,\n      response: { 204: z.void(), ...refusals(403, 404) },\n    },\n    handler: async (req, reply) => {\n      const scope = await resolveScope(container, req);\n      await container.auth.deleteApiKey(req.headers, scope.authOrgId, req.params.id);\n      return reply.code(204).send();\n    },\n  });\n}\n"],"mappings":";;;;;;;AAiBA,eAAsB,aAAa,KAAsB,WAAqC;CAC5F,MAAM,IAAI,IAAI,iBAAkC;CAChD,MAAM,OAAO,CAAC,QAAQ;CAEtB,EAAE,MAAM;EACN,QAAQ;EACR,KAAK;EACL,YAAY,IAAI;EAChB,QAAQ;GACN,aAAa;GACb;GACA,SAAS;GACT,aACE;GACF,UAAU;IAAE,KAAK;IAAiB,GAAG,SAAS,GAAG;GAAE;EACrD;EACA,SAAS,OAAO,QAAQ;GAEtB,OAAO,cAAa,MADA,aAAa,WAAW,GAAG,EAAA,CACrB,IAAI;EAChC;CACF,CAAC;CAED,EAAE,MAAM;EACN,QAAQ;EACR,KAAK;EACL,YAAY,IAAI;EAChB,QAAQ;GACN,aAAa;GACb;GACA,SAAS;GACT,aACE;GACF,UAAU;IAAE,KAAK;IAAkB,GAAG,SAAS,GAAG;GAAE;EACtD;EACA,SAAS,OAAO,QAAQ;GACtB,MAAM,QAAQ,MAAM,aAAa,WAAW,GAAG;GAC/C,OAAO,UAAU,KAAK,kBAAkB,IAAI,SAAS,MAAM,SAAS;EACtE;CACF,CAAC;CAED,EAAE,MAAM;EACN,QAAQ;EACR,KAAK;EACL,YAAY,IAAI;EAChB,QAAQ;GACN,aAAa;GACb;GACA,SAAS;GACT,aACE;GACF,QAAQ;GACR,UAAU;IAAE,KAAK,EAAE,KAAK;IAAG,GAAG,SAAS,GAAG;GAAE;EAC9C;EACA,SAAS,OAAO,KAAK,UAAU;GAC7B,MAAM,QAAQ,MAAM,aAAa,WAAW,GAAG;GAC/C,MAAM,UAAU,KAAK,mBAAmB,IAAI,SAAS,MAAM,WAAW,IAAI,OAAO,QAAQ;GACzF,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;GACA,SAAS;GACT,aACE;GACF,UAAU;IAAE,KAAK;IAAY,GAAG,SAAS,GAAG;GAAE;EAChD;EACA,SAAS,OAAO,QAAQ;GACtB,MAAM,QAAQ,MAAM,aAAa,WAAW,GAAG;GAC/C,OAAO,UAAU,KAAK,YAAY,IAAI,SAAS,MAAM,SAAS;EAChE;CACF,CAAC;CAED,EAAE,MAAM;EACN,QAAQ;EACR,KAAK;EACL,YAAY,IAAI;EAChB,QAAQ;GACN,aAAa;GACb;GACA,SAAS;GACT,aACE;GACF,MAAM;GACN,UAAU;IAAE,KAAK;IAAe,GAAG,SAAS,KAAK,GAAG;GAAE;EACxD;EACA,SAAS,OAAO,KAAK,UAAU;GAC7B,MAAM,QAAQ,MAAM,aAAa,WAAW,GAAG;GAC/C,sBAAsB,MAAM,MAAM,IAAI,KAAK,MAAM;GACjD,MAAM,UAAU,MAAM,UAAU,KAAK,aAAa;IAChD,YAAY,IAAI,SAAS;IACzB,OAAO,MAAM;IACb,MAAM,IAAI,KAAK;IACf,QAAQ,IAAI,KAAK;GACnB,CAAC;GACD,OAAO,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,OAAO;EACrC;CACF,CAAC;CAED,EAAE,MAAM;EACN,QAAQ;EACR,KAAK;EACL,YAAY,IAAI;EAChB,QAAQ;GACN,aAAa;GACb;GACA,SAAS;GACT,aACE;GACF,QAAQ;GACR,UAAU;IAAE,KAAK,EAAE,KAAK;IAAG,GAAG,SAAS,KAAK,GAAG;GAAE;EACnD;EACA,SAAS,OAAO,KAAK,UAAU;GAC7B,MAAM,QAAQ,MAAM,aAAa,WAAW,GAAG;GAC/C,MAAM,UAAU,KAAK,aAAa,IAAI,SAAS,MAAM,WAAW,IAAI,OAAO,EAAE;GAC7E,OAAO,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK;EAC9B;CACF,CAAC;AACH"}

package/dist/http/routes/activities.js

@@ -1,3 +1,4 @@
+import { refusals } from "../schemas/shared.js";
 import { resolveScope } from "../scope.js";
 import { ActivityAssetList, ActivityList, ActivityPathParam, CourseIdPathParam, CreateModule, ModuleList, ModulePathParam, ReorderInput, SaveActivity, UpdateModule } from "../schemas/activities.js";
 import "../schemas/index.js";
@@ -13,9 +14,13 @@ async function activitiesRoutes(app, container) {
 		schema: {
 			operationId: "listModules",
 			tags,
-			summary: "List a course's modules",
+			summary: "List a course's modules (staff)",
+			description: "Staff only (owner, admin, instructor). Modules in order, each with its activities.",
 			params: CourseIdPathParam,
-			response: { 200: ModuleList }
+			response: {
+				200: ModuleList,
+				...refusals(403)
+			}
 		},
 		handler: async (req) => {
 			const scope = await resolveScope(container, req);
@@ -29,13 +34,17 @@ async function activitiesRoutes(app, container) {
 		schema: {
 			operationId: "listActivities",
 			tags,
-			summary: "List a course's activities",
+			summary: "List a course's activities (staff)",
+			description: "Staff only (owner, admin, instructor). Every activity, published or not.",
 			params: CourseIdPathParam,
-			response: { 200: ActivityList }
+			response: {
+				200: ActivityList,
+				...refusals(403)
+			}
 		},
 		handler: async (req) => {
 			const scope = await resolveScope(container, req);
-			return content.listCourseActivities(scope.orgId, req.params.courseId);
+			return content.listCourseActivityViews(scope.orgId, req.params.courseId);
 		}
 	});
 	r.route({
@@ -45,9 +54,13 @@ async function activitiesRoutes(app, container) {
 		schema: {
 			operationId: "listActivityAssets",
 			tags,
-			summary: "List a course's activity→asset links",
+			summary: "List the library files each activity of a course uses (staff)",
+			description: "Staff only (owner, admin, instructor). One row per activity and file, as recorded when the activity was saved.",
 			params: CourseIdPathParam,
-			response: { 200: ActivityAssetList }
+			response: {
+				200: ActivityAssetList,
+				...refusals(403)
+			}
 		},
 		handler: async (req) => {
 			const scope = await resolveScope(container, req);
@@ -61,10 +74,14 @@ async function activitiesRoutes(app, container) {
 		schema: {
 			operationId: "createModule",
 			tags,
-			summary: "Add a module",
+			summary: "Add a module (staff)",
+			description: "Staff only (owner, admin, instructor). Added last. Returns the course's modules.",
 			params: CourseIdPathParam,
 			body: CreateModule,
-			response: { 200: ModuleList }
+			response: {
+				200: ModuleList,
+				...refusals(403)
+			}
 		},
 		handler: async (req) => {
 			const scope = await resolveScope(container, req);
@@ -78,10 +95,14 @@ async function activitiesRoutes(app, container) {
 		schema: {
 			operationId: "reorderModules",
 			tags,
-			summary: "Reorder modules",
+			summary: "Reorder a course's modules (staff)",
+			description: "Staff only (owner, admin, instructor). Ids that are not modules of the course are ignored. Returns the course's modules.",
 			params: CourseIdPathParam,
 			body: ReorderInput,
-			response: { 200: ModuleList }
+			response: {
+				200: ModuleList,
+				...refusals(403)
+			}
 		},
 		handler: async (req) => {
 			const scope = await resolveScope(container, req);
@@ -95,10 +116,14 @@ async function activitiesRoutes(app, container) {
 		schema: {
 			operationId: "updateModule",
 			tags,
-			summary: "Rename a module",
+			summary: "Rename a module (staff)",
+			description: "Staff only (owner, admin, instructor). Returns the course's modules.",
 			params: ModulePathParam,
 			body: UpdateModule,
-			response: { 200: ModuleList }
+			response: {
+				200: ModuleList,
+				...refusals(403, 404)
+			}
 		},
 		handler: async (req) => {
 			const scope = await resolveScope(container, req);
@@ -112,9 +137,13 @@ async function activitiesRoutes(app, container) {
 		schema: {
 			operationId: "deleteModule",
 			tags,
-			summary: "Delete a module",
+			summary: "Delete a module (staff)",
+			description: "Staff only (owner, admin, instructor). Returns the course's modules.",
 			params: ModulePathParam,
-			response: { 200: ModuleList }
+			response: {
+				200: ModuleList,
+				...refusals(403, 404)
+			}
 		},
 		handler: async (req) => {
 			const scope = await resolveScope(container, req);
@@ -128,10 +157,14 @@ async function activitiesRoutes(app, container) {
 		schema: {
 			operationId: "reorderActivities",
 			tags,
-			summary: "Reorder activities in a module",
+			summary: "Reorder the activities in a module (staff)",
+			description: "Staff only (owner, admin, instructor). Send every activity id of the module once (409 otherwise). Returns the course's modules.",
 			params: ModulePathParam,
 			body: ReorderInput,
-			response: { 200: ModuleList }
+			response: {
+				200: ModuleList,
+				...refusals(403, 404, 409)
+			}
 		},
 		handler: async (req) => {
 			const scope = await resolveScope(container, req);
@@ -145,10 +178,14 @@ async function activitiesRoutes(app, container) {
 		schema: {
 			operationId: "createActivity",
 			tags,
-			summary: "Add an activity",
+			summary: "Add an activity (staff)",
+			description: "Staff only (owner, admin, instructor). Records the library files the activity uses; each must be a ready library file (409 otherwise). Returns the course's modules.",
 			params: ModulePathParam,
 			body: SaveActivity,
-			response: { 200: ModuleList }
+			response: {
+				200: ModuleList,
+				...refusals(403, 404, 409)
+			}
 		},
 		handler: async (req) => {
 			const scope = await resolveScope(container, req);
@@ -162,10 +199,14 @@ async function activitiesRoutes(app, container) {
 		schema: {
 			operationId: "updateActivity",
 			tags,
-			summary: "Update an activity",
+			summary: "Update an activity (staff)",
+			description: "Staff only (owner, admin, instructor). Replaces its content and records the library files it uses; each must be a ready library file (409 otherwise). Returns the course's modules.",
 			params: ActivityPathParam,
 			body: SaveActivity,
-			response: { 200: ModuleList }
+			response: {
+				200: ModuleList,
+				...refusals(403, 404, 409)
+			}
 		},
 		handler: async (req) => {
 			const scope = await resolveScope(container, req);
@@ -179,9 +220,13 @@ async function activitiesRoutes(app, container) {
 		schema: {
 			operationId: "deleteActivity",
 			tags,
-			summary: "Delete an activity",
+			summary: "Delete an activity (staff)",
+			description: "Staff only (owner, admin, instructor). Returns the course's modules.",
 			params: ActivityPathParam,
-			response: { 200: ModuleList }
+			response: {
+				200: ModuleList,
+				...refusals(403, 404)
+			}
 		},
 		handler: async (req) => {
 			const scope = await resolveScope(container, req);