@headless-lms/server 0.2.0 → 0.4.0

package/dist/http/routes/community-moderation.js

@@ -0,0 +1,425 @@
+import { PageQuery, refusals } from "../schemas/shared.js";
+import { resolveScope } from "../scope.js";
+import { CommentView, ResolveCommentFlags } from "../schemas/discussion.js";
+import { CommunityChatParam, CommunityCommentParam, CommunityIdParam, CommunityMembersPage, CommunityMembersQuery, CommunityMessageParam, CommunityPostParam, CommunitySpaceParam, SpaceMember, SpaceMemberParam, SpaceMembersPage } from "../schemas/community.js";
+import { PostView, ResolvePostFlags, SpaceQueue } from "../schemas/posts.js";
+import { Chat, OrgUserBody, ResolveMessageFlags } from "../schemas/chats.js";
+import "../schemas/index.js";
+import { z } from "zod";
+import { NotFoundError } from "@headless-lms/core/shared/errors";
+//#region src/http/routes/community-moderation.ts
+async function communityModerationRoutes(app, container) {
+	const r = app.withTypeProvider();
+	const tags = ["Communities"];
+	r.route({
+		method: "GET",
+		url: "/api/communities/:communityId/members",
+		schema: {
+			operationId: "listCommunityMembers",
+			tags,
+			summary: "List the people who hold a community (staff)",
+			description: "Staff only (owner, admin, instructor). Everyone with active access to the community, granted directly or through a bundle, paged and searched by name or email.",
+			params: CommunityIdParam,
+			querystring: CommunityMembersQuery,
+			response: {
+				200: CommunityMembersPage,
+				...refusals(403, 404)
+			}
+		},
+		handler: async (req) => {
+			const scope = await resolveScope(container, req);
+			const page = await container.reporting.admin.communityMembers(scope.orgId, req.params.communityId, req.query);
+			if (!page) throw new NotFoundError("Community", req.params.communityId);
+			return page;
+		}
+	});
+	r.route({
+		method: "GET",
+		url: "/api/communities/:communityId/spaces/:spaceId/members",
+		schema: {
+			operationId: "listCommunitySpaceMembers",
+			tags,
+			summary: "List the members, requests and invitations of a space (staff)",
+			description: "Staff only (owner, admin, instructor). The space's members, its open requests to join and its open invitations.",
+			params: CommunitySpaceParam,
+			querystring: PageQuery,
+			response: {
+				200: SpaceMembersPage,
+				...refusals(403, 404)
+			}
+		},
+		handler: async (req) => {
+			const scope = await resolveScope(container, req);
+			return container.entitlements.listSpaceMembers(scope.orgId, {
+				id: scope.orgUserId,
+				role: scope.role
+			}, req.params.communityId, req.params.spaceId, req.query);
+		}
+	});
+	r.route({
+		method: "POST",
+		url: "/api/communities/:communityId/spaces/:spaceId/members",
+		schema: {
+			operationId: "addCommunitySpaceMember",
+			tags,
+			summary: "Add a person to a space (staff)",
+			description: "Staff only (owner, admin, instructor). Places a member of the community straight into the space, with no request or invitation. 409 when the space is open to all members, the person is already placed, or the space is full.",
+			params: CommunitySpaceParam,
+			body: OrgUserBody,
+			response: {
+				201: SpaceMember,
+				...refusals(403, 404, 409)
+			}
+		},
+		handler: async (req, reply) => {
+			const scope = await resolveScope(container, req);
+			const member = await container.entitlements.addSpaceMember(scope.orgId, {
+				id: scope.orgUserId,
+				role: scope.role
+			}, req.params.communityId, req.params.spaceId, req.body.orgUserId);
+			return reply.code(201).send(member);
+		}
+	});
+	r.route({
+		method: "POST",
+		url: "/api/communities/:communityId/spaces/:spaceId/invites",
+		schema: {
+			operationId: "inviteCommunitySpaceMember",
+			tags,
+			summary: "Invite a person into a space (staff)",
+			description: "Staff only (owner, admin, instructor). Invites a member of the community into a `by_invite` space; they join when they accept. 403 when the person is staff or does not hold the community; 409 when the space is not invite-only or the person is already placed.",
+			params: CommunitySpaceParam,
+			body: OrgUserBody,
+			response: {
+				201: SpaceMember,
+				...refusals(403, 404, 409)
+			}
+		},
+		handler: async (req, reply) => {
+			const scope = await resolveScope(container, req);
+			const member = await container.entitlements.invite(scope.orgId, {
+				id: scope.orgUserId,
+				role: scope.role
+			}, req.params.communityId, req.params.spaceId, req.body.orgUserId);
+			return reply.code(201).send(member);
+		}
+	});
+	r.route({
+		method: "POST",
+		url: "/api/communities/:communityId/spaces/:spaceId/members/:orgUserId/approval",
+		schema: {
+			operationId: "approveCommunitySpaceRequest",
+			tags,
+			summary: "Approve a person's request to join a space (staff)",
+			description: "Staff only (owner, admin, instructor). Makes the requester an active member. 404 when the person has no open request; 409 when the space is full or they are already a member.",
+			params: SpaceMemberParam,
+			response: {
+				200: SpaceMember,
+				...refusals(403, 404, 409)
+			}
+		},
+		handler: async (req) => {
+			const scope = await resolveScope(container, req);
+			return container.entitlements.approve(scope.orgId, {
+				id: scope.orgUserId,
+				role: scope.role
+			}, req.params.communityId, req.params.spaceId, req.params.orgUserId);
+		}
+	});
+	r.route({
+		method: "POST",
+		url: "/api/communities/:communityId/spaces/:spaceId/members/:orgUserId/decline",
+		schema: {
+			operationId: "declineCommunitySpaceRequest",
+			tags,
+			summary: "Decline a person's request to join a space (staff)",
+			description: "Staff only (owner, admin, instructor). Closes the open request. 404 when the person has no open request; 409 when they are already a member.",
+			params: SpaceMemberParam,
+			response: {
+				200: SpaceMember,
+				...refusals(403, 404, 409)
+			}
+		},
+		handler: async (req) => {
+			const scope = await resolveScope(container, req);
+			return container.entitlements.decline(scope.orgId, {
+				id: scope.orgUserId,
+				role: scope.role
+			}, req.params.communityId, req.params.spaceId, req.params.orgUserId);
+		}
+	});
+	r.route({
+		method: "POST",
+		url: "/api/communities/:communityId/spaces/:spaceId/members/:orgUserId/removal",
+		schema: {
+			operationId: "removeCommunitySpaceMember",
+			tags,
+			summary: "Remove a person from a space (staff)",
+			description: "Staff only (owner, admin, instructor). Revokes the placement, whether it is a membership, a request or an invitation. 409 when the space is open to all members or the placement is already revoked.",
+			params: SpaceMemberParam,
+			response: {
+				200: SpaceMember,
+				...refusals(403, 404, 409)
+			}
+		},
+		handler: async (req) => {
+			const scope = await resolveScope(container, req);
+			return container.entitlements.remove(scope.orgId, {
+				id: scope.orgUserId,
+				role: scope.role
+			}, req.params.communityId, req.params.spaceId, req.params.orgUserId);
+		}
+	});
+	r.route({
+		method: "GET",
+		url: "/api/communities/:communityId/spaces/:spaceId/queue",
+		schema: {
+			operationId: "getCommunitySpaceQueue",
+			tags,
+			summary: "The moderation queue of a space (staff)",
+			description: "Staff only (owner, admin, instructor). Posts awaiting review, and the open flags on posts and on comments in the space. Each list holds at most the 100 oldest entries: pending posts by creation, flags by when they were raised; working the queue brings in the next ones.",
+			params: CommunitySpaceParam,
+			response: {
+				200: SpaceQueue,
+				...refusals(403, 404)
+			}
+		},
+		handler: async (req) => {
+			const scope = await resolveScope(container, req);
+			return container.posts.moderationQueue(scope.orgId, {
+				id: scope.orgUserId,
+				role: scope.role
+			}, req.params.communityId, req.params.spaceId);
+		}
+	});
+	r.route({
+		method: "POST",
+		url: "/api/communities/:communityId/posts/:postId/approval",
+		schema: {
+			operationId: "approveCommunityPost",
+			tags,
+			summary: "Publish a post that is awaiting review (staff)",
+			description: "Staff only (owner, admin, instructor). 409 when the post is not awaiting review.",
+			params: CommunityPostParam,
+			response: {
+				200: PostView,
+				...refusals(403, 404, 409)
+			}
+		},
+		handler: async (req) => {
+			const scope = await resolveScope(container, req);
+			return container.posts.approve(scope.orgId, req.params.postId, {
+				id: scope.orgUserId,
+				role: scope.role
+			}, req.params.communityId);
+		}
+	});
+	r.route({
+		method: "POST",
+		url: "/api/communities/:communityId/posts/:postId/removal",
+		schema: {
+			operationId: "removeCommunityPost",
+			tags,
+			summary: "Remove a post (staff)",
+			description: "Staff only (owner, admin, instructor). Takes a published or pending post down and resolves its open flags as `removed`. 409 when it is already removed or was never submitted.",
+			params: CommunityPostParam,
+			response: {
+				200: PostView,
+				...refusals(403, 404, 409)
+			}
+		},
+		handler: async (req) => {
+			const scope = await resolveScope(container, req);
+			return container.posts.remove(scope.orgId, req.params.postId, {
+				id: scope.orgUserId,
+				role: scope.role
+			}, req.params.communityId);
+		}
+	});
+	r.route({
+		method: "POST",
+		url: "/api/communities/:communityId/posts/:postId/restoration",
+		schema: {
+			operationId: "restoreCommunityPost",
+			tags,
+			summary: "Restore a removed post (staff)",
+			description: "Staff only (owner, admin, instructor). 409 when the post is not removed.",
+			params: CommunityPostParam,
+			response: {
+				200: PostView,
+				...refusals(403, 404, 409)
+			}
+		},
+		handler: async (req) => {
+			const scope = await resolveScope(container, req);
+			return container.posts.restore(scope.orgId, req.params.postId, {
+				id: scope.orgUserId,
+				role: scope.role
+			}, req.params.communityId);
+		}
+	});
+	r.route({
+		method: "POST",
+		url: "/api/communities/:communityId/posts/:postId/flags/resolution",
+		schema: {
+			operationId: "resolveCommunityPostFlags",
+			tags,
+			summary: "Dismiss the open flags on a post (staff)",
+			description: "Staff only (owner, admin, instructor). Closes every open flag on the post and leaves it up.",
+			params: CommunityPostParam,
+			body: ResolvePostFlags,
+			response: {
+				204: z.void(),
+				...refusals(403, 404)
+			}
+		},
+		handler: async (req, reply) => {
+			const scope = await resolveScope(container, req);
+			await container.posts.resolveFlags(scope.orgId, req.params.postId, {
+				id: scope.orgUserId,
+				role: scope.role
+			}, req.body.resolution, req.params.communityId);
+			return reply.code(204).send();
+		}
+	});
+	r.route({
+		method: "POST",
+		url: "/api/communities/:communityId/comments/:commentId/removal",
+		schema: {
+			operationId: "removeCommunityComment",
+			tags,
+			summary: "Remove a comment on a post (staff)",
+			description: "Staff only (owner, admin, instructor). Hides the comment and resolves its open flags as `removed`. Removing a removed comment returns it unchanged.",
+			params: CommunityCommentParam,
+			response: {
+				200: CommentView,
+				...refusals(403, 404)
+			}
+		},
+		handler: async (req) => {
+			const scope = await resolveScope(container, req);
+			return container.discussion.remove(scope.orgId, req.params.commentId, {
+				id: scope.orgUserId,
+				role: scope.role
+			}, req.params.communityId);
+		}
+	});
+	r.route({
+		method: "POST",
+		url: "/api/communities/:communityId/comments/:commentId/restoration",
+		schema: {
+			operationId: "restoreCommunityComment",
+			tags,
+			summary: "Restore a removed comment on a post (staff)",
+			description: "Staff only (owner, admin, instructor). Publishes the comment again. Restoring a comment that is not removed returns it unchanged.",
+			params: CommunityCommentParam,
+			response: {
+				200: CommentView,
+				...refusals(403, 404)
+			}
+		},
+		handler: async (req) => {
+			const scope = await resolveScope(container, req);
+			return container.discussion.restore(scope.orgId, req.params.commentId, {
+				id: scope.orgUserId,
+				role: scope.role
+			}, req.params.communityId);
+		}
+	});
+	r.route({
+		method: "POST",
+		url: "/api/communities/:communityId/comments/:commentId/flags/resolution",
+		schema: {
+			operationId: "resolveCommunityCommentFlags",
+			tags,
+			summary: "Dismiss the open flags on a comment (staff)",
+			description: "Staff only (owner, admin, instructor). Closes every open flag on the comment and leaves it up.",
+			params: CommunityCommentParam,
+			body: ResolveCommentFlags,
+			response: {
+				204: z.void(),
+				...refusals(403, 404)
+			}
+		},
+		handler: async (req, reply) => {
+			const scope = await resolveScope(container, req);
+			await container.discussion.resolveReports(scope.orgId, req.params.commentId, {
+				id: scope.orgUserId,
+				role: scope.role
+			}, req.params.communityId);
+			return reply.code(204).send();
+		}
+	});
+	r.route({
+		method: "POST",
+		url: "/api/communities/:communityId/messages/:messageId/flags/resolution",
+		schema: {
+			operationId: "resolveCommunityMessageFlags",
+			tags,
+			summary: "Dismiss the open flags on a message (staff)",
+			description: "Staff only (owner, admin, instructor). Closes every open flag on the message and leaves it up.",
+			params: CommunityMessageParam,
+			body: ResolveMessageFlags,
+			response: {
+				204: z.void(),
+				...refusals(403, 404)
+			}
+		},
+		handler: async (req, reply) => {
+			const scope = await resolveScope(container, req);
+			await container.chats.resolveMessageFlags(scope.orgId, {
+				id: scope.orgUserId,
+				role: scope.role
+			}, req.params.messageId, req.body.resolution, req.params.communityId);
+			return reply.code(204).send();
+		}
+	});
+	r.route({
+		method: "POST",
+		url: "/api/communities/:communityId/chats/:chatId/lock",
+		schema: {
+			operationId: "lockCommunityChat",
+			tags,
+			summary: "Lock a chat (staff)",
+			description: "Staff only (owner, admin, instructor). Nobody can send or edit messages until it is unlocked; its open message flags are resolved as `locked`. Locking a locked chat returns it unchanged.",
+			params: CommunityChatParam,
+			response: {
+				200: Chat,
+				...refusals(403, 404)
+			}
+		},
+		handler: async (req) => {
+			const scope = await resolveScope(container, req);
+			return container.chats.lock(scope.orgId, {
+				id: scope.orgUserId,
+				role: scope.role
+			}, req.params.chatId, req.params.communityId);
+		}
+	});
+	r.route({
+		method: "POST",
+		url: "/api/communities/:communityId/chats/:chatId/unlock",
+		schema: {
+			operationId: "unlockCommunityChat",
+			tags,
+			summary: "Unlock a chat (staff)",
+			description: "Staff only (owner, admin, instructor). Lets participants send messages again. Unlocking an unlocked chat returns it unchanged.",
+			params: CommunityChatParam,
+			response: {
+				200: Chat,
+				...refusals(403, 404)
+			}
+		},
+		handler: async (req) => {
+			const scope = await resolveScope(container, req);
+			return container.chats.unlock(scope.orgId, {
+				id: scope.orgUserId,
+				role: scope.role
+			}, req.params.chatId, req.params.communityId);
+		}
+	});
+}
+//#endregion
+export { communityModerationRoutes };
+
+//# sourceMappingURL=community-moderation.js.map

package/dist/http/routes/community-moderation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"community-moderation.js","names":[],"sources":["../../../src/http/routes/community-moderation.ts"],"sourcesContent":["import type { FastifyInstance } from 'fastify';\nimport type { ZodTypeProvider } from 'fastify-type-provider-zod';\nimport { z } from 'zod';\nimport type { Container } from '../../app/container.js';\nimport { NotFoundError } from '@headless-lms/core/shared/errors';\nimport { resolveScope } from '../scope.js';\nimport {\n  Chat,\n  CommentView,\n  CommunityChatParam,\n  CommunityCommentParam,\n  CommunityIdParam,\n  CommunityMembersPage,\n  CommunityMembersQuery,\n  CommunityMessageParam,\n  CommunityPostParam,\n  CommunitySpaceParam,\n  OrgUserBody,\n  PageQuery,\n  PostView,\n  ResolveCommentFlags,\n  ResolveMessageFlags,\n  ResolvePostFlags,\n  SpaceMember,\n  SpaceMemberParam,\n  SpaceMembersPage,\n  SpaceQueue,\n  refusals,\n} from '../schemas/index.js';\n\nexport async function communityModerationRoutes(\n  app: FastifyInstance,\n  container: Container,\n): Promise<void> {\n  const r = app.withTypeProvider<ZodTypeProvider>();\n  const tags = ['Communities'];\n\n  r.route({\n    method: 'GET',\n    url: '/api/communities/:communityId/members',\n    schema: {\n      operationId: 'listCommunityMembers',\n      tags,\n      summary: 'List the people who hold a community (staff)',\n      description:\n        'Staff only (owner, admin, instructor). Everyone with active access to the community, granted directly or through a bundle, paged and searched by name or email.',\n      params: CommunityIdParam,\n      querystring: CommunityMembersQuery,\n      response: { 200: CommunityMembersPage, ...refusals(403, 404) },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      const page = await container.reporting.admin.communityMembers(\n        scope.orgId,\n        req.params.communityId,\n        req.query,\n      );\n      if (!page) {\n        throw new NotFoundError('Community', req.params.communityId);\n      }\n      return page;\n    },\n  });\n\n  r.route({\n    method: 'GET',\n    url: '/api/communities/:communityId/spaces/:spaceId/members',\n    schema: {\n      operationId: 'listCommunitySpaceMembers',\n      tags,\n      summary: 'List the members, requests and invitations of a space (staff)',\n      description:\n        \"Staff only (owner, admin, instructor). The space's members, its open requests to join and its open invitations.\",\n      params: CommunitySpaceParam,\n      querystring: PageQuery,\n      response: { 200: SpaceMembersPage, ...refusals(403, 404) },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      return container.entitlements.listSpaceMembers(\n        scope.orgId,\n        { id: scope.orgUserId, role: scope.role },\n        req.params.communityId,\n        req.params.spaceId,\n        req.query,\n      );\n    },\n  });\n\n  r.route({\n    method: 'POST',\n    url: '/api/communities/:communityId/spaces/:spaceId/members',\n    schema: {\n      operationId: 'addCommunitySpaceMember',\n      tags,\n      summary: 'Add a person to a space (staff)',\n      description:\n        'Staff only (owner, admin, instructor). Places a member of the community straight into the space, with no request or invitation. 409 when the space is open to all members, the person is already placed, or the space is full.',\n      params: CommunitySpaceParam,\n      body: OrgUserBody,\n      response: { 201: SpaceMember, ...refusals(403, 404, 409) },\n    },\n    handler: async (req, reply) => {\n      const scope = await resolveScope(container, req);\n      const member = await container.entitlements.addSpaceMember(\n        scope.orgId,\n        { id: scope.orgUserId, role: scope.role },\n        req.params.communityId,\n        req.params.spaceId,\n        req.body.orgUserId,\n      );\n      return reply.code(201).send(member);\n    },\n  });\n\n  r.route({\n    method: 'POST',\n    url: '/api/communities/:communityId/spaces/:spaceId/invites',\n    schema: {\n      operationId: 'inviteCommunitySpaceMember',\n      tags,\n      summary: 'Invite a person into a space (staff)',\n      description:\n        'Staff only (owner, admin, instructor). Invites a member of the community into a `by_invite` space; they join when they accept. 403 when the person is staff or does not hold the community; 409 when the space is not invite-only or the person is already placed.',\n      params: CommunitySpaceParam,\n      body: OrgUserBody,\n      response: { 201: SpaceMember, ...refusals(403, 404, 409) },\n    },\n    handler: async (req, reply) => {\n      const scope = await resolveScope(container, req);\n      const member = await container.entitlements.invite(\n        scope.orgId,\n        { id: scope.orgUserId, role: scope.role },\n        req.params.communityId,\n        req.params.spaceId,\n        req.body.orgUserId,\n      );\n      return reply.code(201).send(member);\n    },\n  });\n\n  r.route({\n    method: 'POST',\n    url: '/api/communities/:communityId/spaces/:spaceId/members/:orgUserId/approval',\n    schema: {\n      operationId: 'approveCommunitySpaceRequest',\n      tags,\n      summary: \"Approve a person's request to join a space (staff)\",\n      description:\n        'Staff only (owner, admin, instructor). Makes the requester an active member. 404 when the person has no open request; 409 when the space is full or they are already a member.',\n      params: SpaceMemberParam,\n      response: { 200: SpaceMember, ...refusals(403, 404, 409) },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      return container.entitlements.approve(\n        scope.orgId,\n        { id: scope.orgUserId, role: scope.role },\n        req.params.communityId,\n        req.params.spaceId,\n        req.params.orgUserId,\n      );\n    },\n  });\n\n  r.route({\n    method: 'POST',\n    url: '/api/communities/:communityId/spaces/:spaceId/members/:orgUserId/decline',\n    schema: {\n      operationId: 'declineCommunitySpaceRequest',\n      tags,\n      summary: \"Decline a person's request to join a space (staff)\",\n      description:\n        'Staff only (owner, admin, instructor). Closes the open request. 404 when the person has no open request; 409 when they are already a member.',\n      params: SpaceMemberParam,\n      response: { 200: SpaceMember, ...refusals(403, 404, 409) },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      return container.entitlements.decline(\n        scope.orgId,\n        { id: scope.orgUserId, role: scope.role },\n        req.params.communityId,\n        req.params.spaceId,\n        req.params.orgUserId,\n      );\n    },\n  });\n\n  r.route({\n    method: 'POST',\n    url: '/api/communities/:communityId/spaces/:spaceId/members/:orgUserId/removal',\n    schema: {\n      operationId: 'removeCommunitySpaceMember',\n      tags,\n      summary: 'Remove a person from a space (staff)',\n      description:\n        'Staff only (owner, admin, instructor). Revokes the placement, whether it is a membership, a request or an invitation. 409 when the space is open to all members or the placement is already revoked.',\n      params: SpaceMemberParam,\n      response: { 200: SpaceMember, ...refusals(403, 404, 409) },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      return container.entitlements.remove(\n        scope.orgId,\n        { id: scope.orgUserId, role: scope.role },\n        req.params.communityId,\n        req.params.spaceId,\n        req.params.orgUserId,\n      );\n    },\n  });\n\n  r.route({\n    method: 'GET',\n    url: '/api/communities/:communityId/spaces/:spaceId/queue',\n    schema: {\n      operationId: 'getCommunitySpaceQueue',\n      tags,\n      summary: 'The moderation queue of a space (staff)',\n      description:\n        'Staff only (owner, admin, instructor). Posts awaiting review, and the open flags on posts and on comments in the space. Each list holds at most the 100 oldest entries: pending posts by creation, flags by when they were raised; working the queue brings in the next ones.',\n      params: CommunitySpaceParam,\n      response: { 200: SpaceQueue, ...refusals(403, 404) },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      return container.posts.moderationQueue(\n        scope.orgId,\n        { id: scope.orgUserId, role: scope.role },\n        req.params.communityId,\n        req.params.spaceId,\n      );\n    },\n  });\n\n  r.route({\n    method: 'POST',\n    url: '/api/communities/:communityId/posts/:postId/approval',\n    schema: {\n      operationId: 'approveCommunityPost',\n      tags,\n      summary: 'Publish a post that is awaiting review (staff)',\n      description:\n        'Staff only (owner, admin, instructor). 409 when the post is not awaiting review.',\n      params: CommunityPostParam,\n      response: { 200: PostView, ...refusals(403, 404, 409) },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      return container.posts.approve(\n        scope.orgId,\n        req.params.postId,\n        { id: scope.orgUserId, role: scope.role },\n        req.params.communityId,\n      );\n    },\n  });\n\n  r.route({\n    method: 'POST',\n    url: '/api/communities/:communityId/posts/:postId/removal',\n    schema: {\n      operationId: 'removeCommunityPost',\n      tags,\n      summary: 'Remove a post (staff)',\n      description:\n        'Staff only (owner, admin, instructor). Takes a published or pending post down and resolves its open flags as `removed`. 409 when it is already removed or was never submitted.',\n      params: CommunityPostParam,\n      response: { 200: PostView, ...refusals(403, 404, 409) },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      return container.posts.remove(\n        scope.orgId,\n        req.params.postId,\n        { id: scope.orgUserId, role: scope.role },\n        req.params.communityId,\n      );\n    },\n  });\n\n  r.route({\n    method: 'POST',\n    url: '/api/communities/:communityId/posts/:postId/restoration',\n    schema: {\n      operationId: 'restoreCommunityPost',\n      tags,\n      summary: 'Restore a removed post (staff)',\n      description: 'Staff only (owner, admin, instructor). 409 when the post is not removed.',\n      params: CommunityPostParam,\n      response: { 200: PostView, ...refusals(403, 404, 409) },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      return container.posts.restore(\n        scope.orgId,\n        req.params.postId,\n        { id: scope.orgUserId, role: scope.role },\n        req.params.communityId,\n      );\n    },\n  });\n\n  r.route({\n    method: 'POST',\n    url: '/api/communities/:communityId/posts/:postId/flags/resolution',\n    schema: {\n      operationId: 'resolveCommunityPostFlags',\n      tags,\n      summary: 'Dismiss the open flags on a post (staff)',\n      description:\n        'Staff only (owner, admin, instructor). Closes every open flag on the post and leaves it up.',\n      params: CommunityPostParam,\n      body: ResolvePostFlags,\n      response: { 204: z.void(), ...refusals(403, 404) },\n    },\n    handler: async (req, reply) => {\n      const scope = await resolveScope(container, req);\n      await container.posts.resolveFlags(\n        scope.orgId,\n        req.params.postId,\n        { id: scope.orgUserId, role: scope.role },\n        req.body.resolution,\n        req.params.communityId,\n      );\n      return reply.code(204).send();\n    },\n  });\n\n  r.route({\n    method: 'POST',\n    url: '/api/communities/:communityId/comments/:commentId/removal',\n    schema: {\n      operationId: 'removeCommunityComment',\n      tags,\n      summary: 'Remove a comment on a post (staff)',\n      description:\n        'Staff only (owner, admin, instructor). Hides the comment and resolves its open flags as `removed`. Removing a removed comment returns it unchanged.',\n      params: CommunityCommentParam,\n      response: { 200: CommentView, ...refusals(403, 404) },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      return container.discussion.remove(\n        scope.orgId,\n        req.params.commentId,\n        { id: scope.orgUserId, role: scope.role },\n        req.params.communityId,\n      );\n    },\n  });\n\n  r.route({\n    method: 'POST',\n    url: '/api/communities/:communityId/comments/:commentId/restoration',\n    schema: {\n      operationId: 'restoreCommunityComment',\n      tags,\n      summary: 'Restore a removed comment on a post (staff)',\n      description:\n        'Staff only (owner, admin, instructor). Publishes the comment again. Restoring a comment that is not removed returns it unchanged.',\n      params: CommunityCommentParam,\n      response: { 200: CommentView, ...refusals(403, 404) },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      return container.discussion.restore(\n        scope.orgId,\n        req.params.commentId,\n        { id: scope.orgUserId, role: scope.role },\n        req.params.communityId,\n      );\n    },\n  });\n\n  r.route({\n    method: 'POST',\n    url: '/api/communities/:communityId/comments/:commentId/flags/resolution',\n    schema: {\n      operationId: 'resolveCommunityCommentFlags',\n      tags,\n      summary: 'Dismiss the open flags on a comment (staff)',\n      description:\n        'Staff only (owner, admin, instructor). Closes every open flag on the comment and leaves it up.',\n      params: CommunityCommentParam,\n      body: ResolveCommentFlags,\n      response: { 204: z.void(), ...refusals(403, 404) },\n    },\n    handler: async (req, reply) => {\n      const scope = await resolveScope(container, req);\n      await container.discussion.resolveReports(\n        scope.orgId,\n        req.params.commentId,\n        { id: scope.orgUserId, role: scope.role },\n        req.params.communityId,\n      );\n      return reply.code(204).send();\n    },\n  });\n\n  r.route({\n    method: 'POST',\n    url: '/api/communities/:communityId/messages/:messageId/flags/resolution',\n    schema: {\n      operationId: 'resolveCommunityMessageFlags',\n      tags,\n      summary: 'Dismiss the open flags on a message (staff)',\n      description:\n        'Staff only (owner, admin, instructor). Closes every open flag on the message and leaves it up.',\n      params: CommunityMessageParam,\n      body: ResolveMessageFlags,\n      response: { 204: z.void(), ...refusals(403, 404) },\n    },\n    handler: async (req, reply) => {\n      const scope = await resolveScope(container, req);\n      await container.chats.resolveMessageFlags(\n        scope.orgId,\n        { id: scope.orgUserId, role: scope.role },\n        req.params.messageId,\n        req.body.resolution,\n        req.params.communityId,\n      );\n      return reply.code(204).send();\n    },\n  });\n\n  r.route({\n    method: 'POST',\n    url: '/api/communities/:communityId/chats/:chatId/lock',\n    schema: {\n      operationId: 'lockCommunityChat',\n      tags,\n      summary: 'Lock a chat (staff)',\n      description:\n        'Staff only (owner, admin, instructor). Nobody can send or edit messages until it is unlocked; its open message flags are resolved as `locked`. Locking a locked chat returns it unchanged.',\n      params: CommunityChatParam,\n      response: { 200: Chat, ...refusals(403, 404) },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      return container.chats.lock(\n        scope.orgId,\n        { id: scope.orgUserId, role: scope.role },\n        req.params.chatId,\n        req.params.communityId,\n      );\n    },\n  });\n\n  r.route({\n    method: 'POST',\n    url: '/api/communities/:communityId/chats/:chatId/unlock',\n    schema: {\n      operationId: 'unlockCommunityChat',\n      tags,\n      summary: 'Unlock a chat (staff)',\n      description:\n        'Staff only (owner, admin, instructor). Lets participants send messages again. Unlocking an unlocked chat returns it unchanged.',\n      params: CommunityChatParam,\n      response: { 200: Chat, ...refusals(403, 404) },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      return container.chats.unlock(\n        scope.orgId,\n        { id: scope.orgUserId, role: scope.role },\n        req.params.chatId,\n        req.params.communityId,\n      );\n    },\n  });\n}\n"],"mappings":"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"}

package/dist/http/routes/course-analytics.js

@@ -1,5 +1,5 @@
+import { refusals } from "../schemas/shared.js";
 import { resolveScope } from "../scope.js";
-import { ErrorBody } from "../schemas/shared.js";
 import { CourseIdParam } from "../schemas/content.js";
 import { EnrollmentSeries, EnrollmentSeriesQuery } from "../schemas/dashboard.js";
 import { CourseAnalytics } from "../schemas/course-analytics.js";
@@ -15,16 +15,17 @@ async function courseAnalyticsRoutes(app, container) {
 		schema: {
 			operationId: "getCourseAnalytics",
 			tags: ["Reporting"],
-			summary: "Completion and engagement stats for a course",
+			summary: "Completion and engagement stats for a course (staff)",
+			description: "Staff only (owner, admin, instructor).",
 			params: CourseIdParam,
 			response: {
 				200: CourseAnalytics,
-				404: ErrorBody
+				...refusals(403, 404)
 			}
 		},
 		handler: async (req) => {
 			const scope = await resolveScope(container, req);
-			const analytics = await container.reporting.courses.analytics(scope.orgId, req.params.id);
+			const analytics = await container.reporting.admin.courseAnalytics(scope.orgId, req.params.id);
 			if (!analytics) throw new NotFoundError("Course", req.params.id);
 			return analytics;
 		}
@@ -36,17 +37,18 @@ async function courseAnalyticsRoutes(app, container) {
 		schema: {
 			operationId: "getCourseEnrollmentSeries",
 			tags: ["Reporting"],
-			summary: "Enrollments granted per day for a course over a trailing window",
+			summary: "Enrollments granted per day for a course over a trailing window (staff)",
+			description: "Staff only (owner, admin, instructor).",
 			params: CourseIdParam,
 			querystring: EnrollmentSeriesQuery,
 			response: {
 				200: EnrollmentSeries,
-				404: ErrorBody
+				...refusals(403, 404)
 			}
 		},
 		handler: async (req) => {
 			const scope = await resolveScope(container, req);
-			const series = await container.reporting.courses.enrollments(scope.orgId, req.params.id, req.query.days);
+			const series = await container.reporting.admin.courseEnrollments(scope.orgId, req.params.id, req.query.days);
 			if (!series) throw new NotFoundError("Course", req.params.id);
 			return series;
 		}

package/dist/http/routes/course-analytics.js.map

@@ -1 +1 @@
-{"version":3,"file":"course-analytics.js","names":[],"sources":["../../../src/http/routes/course-analytics.ts"],"sourcesContent":["// HTTP routes for per-course analytics (reporting).\nimport type { FastifyInstance } from 'fastify';\nimport type { ZodTypeProvider } from 'fastify-type-provider-zod';\nimport {\n  CourseAnalytics,\n  CourseIdParam,\n  EnrollmentSeries,\n  EnrollmentSeriesQuery,\n  ErrorBody,\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 courseAnalyticsRoutes(\n  app: FastifyInstance,\n  container: Container,\n): Promise<void> {\n  const r = app.withTypeProvider<ZodTypeProvider>();\n\n  r.route({\n    method: 'GET',\n    url: '/api/courses/:id/analytics',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'getCourseAnalytics',\n      tags: ['Reporting'],\n      summary: 'Completion and engagement stats for a course',\n      params: CourseIdParam,\n      response: { 200: CourseAnalytics, 404: ErrorBody },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      const analytics = await container.reporting.courses.analytics(scope.orgId, req.params.id);\n      if (!analytics) {\n        throw new NotFoundError('Course', req.params.id);\n      }\n      return analytics;\n    },\n  });\n\n  r.route({\n    method: 'GET',\n    url: '/api/courses/:id/analytics/enrollments',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'getCourseEnrollmentSeries',\n      tags: ['Reporting'],\n      summary: 'Enrollments granted per day for a course over a trailing window',\n      params: CourseIdParam,\n      querystring: EnrollmentSeriesQuery,\n      response: { 200: EnrollmentSeries, 404: ErrorBody },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      const series = await container.reporting.courses.enrollments(\n        scope.orgId,\n        req.params.id,\n        req.query.days,\n      );\n      if (!series) {\n        throw new NotFoundError('Course', req.params.id);\n      }\n      return series;\n    },\n  });\n}\n"],"mappings":";;;;;;;;AAcA,eAAsB,sBACpB,KACA,WACe;CACf,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,QAAQ;GACR,UAAU;IAAE,KAAK;IAAiB,KAAK;GAAU;EACnD;EACA,SAAS,OAAO,QAAQ;GACtB,MAAM,QAAQ,MAAM,aAAa,WAAW,GAAG;GAC/C,MAAM,YAAY,MAAM,UAAU,UAAU,QAAQ,UAAU,MAAM,OAAO,IAAI,OAAO,EAAE;GACxF,IAAI,CAAC,WACH,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,WAAW;GAClB,SAAS;GACT,QAAQ;GACR,aAAa;GACb,UAAU;IAAE,KAAK;IAAkB,KAAK;GAAU;EACpD;EACA,SAAS,OAAO,QAAQ;GACtB,MAAM,QAAQ,MAAM,aAAa,WAAW,GAAG;GAC/C,MAAM,SAAS,MAAM,UAAU,UAAU,QAAQ,YAC/C,MAAM,OACN,IAAI,OAAO,IACX,IAAI,MAAM,IACZ;GACA,IAAI,CAAC,QACH,MAAM,IAAI,cAAc,UAAU,IAAI,OAAO,EAAE;GAEjD,OAAO;EACT;CACF,CAAC;AACH"}
+{"version":3,"file":"course-analytics.js","names":[],"sources":["../../../src/http/routes/course-analytics.ts"],"sourcesContent":["// HTTP routes for per-course analytics (reporting).\nimport type { FastifyInstance } from 'fastify';\nimport type { ZodTypeProvider } from 'fastify-type-provider-zod';\nimport {\n  CourseAnalytics,\n  CourseIdParam,\n  EnrollmentSeries,\n  EnrollmentSeriesQuery,\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 courseAnalyticsRoutes(\n  app: FastifyInstance,\n  container: Container,\n): Promise<void> {\n  const r = app.withTypeProvider<ZodTypeProvider>();\n\n  r.route({\n    method: 'GET',\n    url: '/api/courses/:id/analytics',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'getCourseAnalytics',\n      tags: ['Reporting'],\n      summary: 'Completion and engagement stats for a course (staff)',\n      description: 'Staff only (owner, admin, instructor).',\n      params: CourseIdParam,\n      response: { 200: CourseAnalytics, ...refusals(403, 404) },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      const analytics = await container.reporting.admin.courseAnalytics(scope.orgId, req.params.id);\n      if (!analytics) {\n        throw new NotFoundError('Course', req.params.id);\n      }\n      return analytics;\n    },\n  });\n\n  r.route({\n    method: 'GET',\n    url: '/api/courses/:id/analytics/enrollments',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'getCourseEnrollmentSeries',\n      tags: ['Reporting'],\n      summary: 'Enrollments granted per day for a course over a trailing window (staff)',\n      description: 'Staff only (owner, admin, instructor).',\n      params: CourseIdParam,\n      querystring: EnrollmentSeriesQuery,\n      response: { 200: EnrollmentSeries, ...refusals(403, 404) },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      const series = await container.reporting.admin.courseEnrollments(\n        scope.orgId,\n        req.params.id,\n        req.query.days,\n      );\n      if (!series) {\n        throw new NotFoundError('Course', req.params.id);\n      }\n      return series;\n    },\n  });\n}\n"],"mappings":";;;;;;;;AAcA,eAAsB,sBACpB,KACA,WACe;CACf,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,QAAQ;GACR,UAAU;IAAE,KAAK;IAAiB,GAAG,SAAS,KAAK,GAAG;GAAE;EAC1D;EACA,SAAS,OAAO,QAAQ;GACtB,MAAM,QAAQ,MAAM,aAAa,WAAW,GAAG;GAC/C,MAAM,YAAY,MAAM,UAAU,UAAU,MAAM,gBAAgB,MAAM,OAAO,IAAI,OAAO,EAAE;GAC5F,IAAI,CAAC,WACH,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,WAAW;GAClB,SAAS;GACT,aAAa;GACb,QAAQ;GACR,aAAa;GACb,UAAU;IAAE,KAAK;IAAkB,GAAG,SAAS,KAAK,GAAG;GAAE;EAC3D;EACA,SAAS,OAAO,QAAQ;GACtB,MAAM,QAAQ,MAAM,aAAa,WAAW,GAAG;GAC/C,MAAM,SAAS,MAAM,UAAU,UAAU,MAAM,kBAC7C,MAAM,OACN,IAAI,OAAO,IACX,IAAI,MAAM,IACZ;GACA,IAAI,CAAC,QACH,MAAM,IAAI,cAAc,UAAU,IAAI,OAAO,EAAE;GAEjD,OAAO;EACT;CACF,CAAC;AACH"}

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();
@@ -15,9 +15,13 @@ async function coursesRoutes(app, container) {
 		schema: {
 			operationId: "listCourses",
 			tags: ["Content"],
-			summary: "List courses",
+			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);
@@ -31,11 +35,12 @@ async function coursesRoutes(app, container) {
 		schema: {
 			operationId: "getCourse",
 			tags: ["Content"],
-			summary: "Get a course by id",
+			summary: "Get a course (staff)",
+			description: "Staff only (owner, admin, instructor).",
 			params: CourseIdParam,
 			response: {
 				200: Course,
-				404: ErrorBody
+				...refusals(403, 404)
 			}
 		},
 		handler: async (req) => {
@@ -52,9 +57,13 @@ async function coursesRoutes(app, container) {
 		schema: {
 			operationId: "createCourse",
 			tags: ["Content"],
-			summary: "Create a course",
+			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);
@@ -69,12 +78,13 @@ async function coursesRoutes(app, container) {
 		schema: {
 			operationId: "updateCourse",
 			tags: ["Content"],
-			summary: "Update a course",
+			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) => {
@@ -89,12 +99,13 @@ async function coursesRoutes(app, container) {
 		schema: {
 			operationId: "updateCourseSettings",
 			tags: ["Content"],
-			summary: "Update a course settings",
+			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) => {
@@ -110,16 +121,20 @@ async function coursesRoutes(app, container) {
 		schema: {
 			operationId: "deleteCourse",
 			tags: ["Content"],
-			summary: "Delete a course",
+			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();
 		}
 	});