@headless-lms/server 0.3.0 → 0.5.0

package/dist/http/routes/communities.js

@@ -1,10 +1,10 @@
 import { refusals } from "../schemas/shared.js";
-import { resolveScope } from "../scope.js";
-import { CommunitiesPage, CommunitiesQuery, Community, CommunityAnalytics, CommunityIdParam, CommunitySpaceParam, CreateCommunity, CreateSpace, OrderedIds, PatchDmSettings, SetSpaceTopics, SpaceDetail, SpaceLinkBody, SpaceLinkParam, UpdateCommunity, UpdateSpace } from "../schemas/community.js";
+import { resolveActor } from "../scope.js";
+import { CommunitiesPage, CommunitiesQuery, Community, CommunityAnalytics, CommunityIdParam, CommunitySpaceParam, CreateCommunity, CreateSpace, OrderedIds, PatchCommunitySettings, SetSpaceTopics, SpaceDetail, SpaceLinkBody, SpaceLinkParam, UpdateCommunity, UpdateSpace } from "../schemas/community.js";
 import { MessageQueue } from "../schemas/chats.js";
+import { NotificationCategoryList, ReplaceNotificationCategories } from "../schemas/notifications.js";
 import "../schemas/index.js";
 import { z } from "zod";
-import { NotFoundError } from "@headless-lms/core/shared/errors";
 //#region src/http/routes/communities.ts
 async function communitiesRoutes(app, container) {
 	const r = app.withTypeProvider();
@@ -16,8 +16,8 @@ async function communitiesRoutes(app, container) {
 		schema: {
 			operationId: "listCommunities",
 			tags,
-			summary: "List communities (staff)",
-			description: "Staff only (owner, admin, instructor). Pages every community in the organization, drafts included, filtered by `status` and searched by title.",
+			summary: "List communities",
+			description: `Requires one of \`communities:read\`, \`communities:moderate\`. Pages every community in the organization, drafts included, filtered by \`status\` and searched by title.`,
 			querystring: CommunitiesQuery,
 			response: {
 				200: CommunitiesPage,
@@ -25,8 +25,8 @@ async function communitiesRoutes(app, container) {
 			}
 		},
 		handler: async (req) => {
-			const scope = await resolveScope(container, req);
-			return content.listCommunities(scope.orgId, req.query);
+			const actor = await resolveActor(container, req);
+			return content.listCommunities(req.query, actor);
 		}
 	});
 	r.route({
@@ -35,8 +35,8 @@ async function communitiesRoutes(app, container) {
 		schema: {
 			operationId: "createCommunity",
 			tags,
-			summary: "Create a community (staff)",
-			description: "Owner or admin only. The community starts as a draft with the default direct-message settings and no spaces. Members see it once it is published and they hold it.",
+			summary: "Create a community",
+			description: `Requires \`communities:write\`. The community starts as a draft with the default direct-message settings and no spaces. Members see it once it is published and they hold it.`,
 			body: CreateCommunity,
 			response: {
 				201: Community,
@@ -44,11 +44,8 @@ async function communitiesRoutes(app, container) {
 			}
 		},
 		handler: async (req, reply) => {
-			const scope = await resolveScope(container, req);
-			const community = await content.createCommunity(scope.orgId, req.body, {
-				id: scope.orgUserId,
-				role: scope.role
-			});
+			const actor = await resolveActor(container, req);
+			const community = await content.createCommunity(req.body, actor);
 			req.log.info({ communityId: community.id }, "community created");
 			return reply.code(201).send(community);
 		}
@@ -59,8 +56,8 @@ async function communitiesRoutes(app, container) {
 		schema: {
 			operationId: "getCommunity",
 			tags,
-			summary: "Get a community (staff)",
-			description: "Staff only (owner, admin, instructor). Any community of the organization, drafts included.",
+			summary: "Get a community",
+			description: `Requires one of \`communities:read\`, \`communities:moderate\`. Any community of the organization, drafts included.`,
 			params: CommunityIdParam,
 			response: {
 				200: Community,
@@ -68,10 +65,8 @@ async function communitiesRoutes(app, container) {
 			}
 		},
 		handler: async (req) => {
-			const scope = await resolveScope(container, req);
-			const community = await content.getCommunity(scope.orgId, req.params.communityId);
-			if (!community) throw new NotFoundError("Community", req.params.communityId);
-			return community;
+			const actor = await resolveActor(container, req);
+			return content.getCommunity(req.params.communityId, actor);
 		}
 	});
 	r.route({
@@ -80,8 +75,8 @@ async function communitiesRoutes(app, container) {
 		schema: {
 			operationId: "updateCommunity",
 			tags,
-			summary: "Update a community (staff)",
-			description: "Owner or admin only. Changes only the fields sent. `thumbnailAssetId` must be a ready library image (409 otherwise); null clears it.",
+			summary: "Update a community",
+			description: `Requires \`communities:write\`. Changes only the fields sent. \`thumbnailAssetId\` must be a ready library image (409 otherwise); null clears it. A file it does not already use must be uploaded for it, or the caller needs \`media:read\` (403 otherwise).`,
 			params: CommunityIdParam,
 			body: UpdateCommunity,
 			response: {
@@ -90,11 +85,8 @@ async function communitiesRoutes(app, container) {
 			}
 		},
 		handler: async (req) => {
-			const scope = await resolveScope(container, req);
-			return content.updateCommunity(scope.orgId, req.params.communityId, req.body, {
-				id: scope.orgUserId,
-				role: scope.role
-			});
+			const actor = await resolveActor(container, req);
+			return content.updateCommunity(req.params.communityId, req.body, actor);
 		}
 	});
 	r.route({
@@ -103,8 +95,8 @@ async function communitiesRoutes(app, container) {
 		schema: {
 			operationId: "deleteCommunity",
 			tags,
-			summary: "Delete a community (staff)",
-			description: "Owner or admin only. Links to the community from other spaces are removed with it.",
+			summary: "Delete a community",
+			description: `Requires \`communities:delete\`. Links to the community from other spaces are removed with it.`,
 			params: CommunityIdParam,
 			response: {
 				204: z.void(),
@@ -112,11 +104,8 @@ async function communitiesRoutes(app, container) {
 			}
 		},
 		handler: async (req, reply) => {
-			const scope = await resolveScope(container, req);
-			await content.deleteCommunity(scope.orgId, req.params.communityId, {
-				id: scope.orgUserId,
-				role: scope.role
-			});
+			const actor = await resolveActor(container, req);
+			await content.deleteCommunity(req.params.communityId, actor);
 			return reply.code(204).send();
 		}
 	});
@@ -124,23 +113,79 @@ async function communitiesRoutes(app, container) {
 		method: "PATCH",
 		url: "/api/communities/:communityId/settings",
 		schema: {
-			operationId: "patchCommunityDmSettings",
+			operationId: "patchCommunitySettings",
 			tags,
-			summary: "Change direct-message settings for a community (staff)",
-			description: "Owner or admin only. Changes only the settings sent; the rest keep their values. They decide who may message whom from then on.",
+			summary: "Change the direct-message and digest settings of a community",
+			description: `Requires \`communities:write\`. Changes only the settings sent; the rest keep their values. The direct-message settings decide who may message whom from then on. \`digest\` sets when the community digest goes out, or \`null\` stops it; the first digest after a change goes out at the next slot.`,
 			params: CommunityIdParam,
-			body: PatchDmSettings,
+			body: PatchCommunitySettings,
 			response: {
 				200: Community,
 				...refusals(403, 404)
 			}
 		},
 		handler: async (req) => {
-			const scope = await resolveScope(container, req);
-			return content.patchDmSettings(scope.orgId, req.params.communityId, req.body, {
-				id: scope.orgUserId,
-				role: scope.role
-			});
+			const actor = await resolveActor(container, req);
+			return content.patchCommunitySettings(req.params.communityId, req.body, actor);
+		}
+	});
+	r.route({
+		method: "GET",
+		url: "/api/communities/:communityId/notification-categories",
+		schema: {
+			operationId: "getCommunityNotificationCategories",
+			tags: ["Notifications"],
+			summary: "Get a community's notification categories",
+			description: `Requires \`communities:read\`. On the community. The list in use for the community, with \`source\` saying whether it is the default or a stored list.`,
+			params: CommunityIdParam,
+			response: {
+				200: NotificationCategoryList,
+				...refusals(403, 404)
+			}
+		},
+		handler: async (req) => {
+			const actor = await resolveActor(container, req);
+			return container.notificationCategories.community.get(req.params.communityId, actor);
+		}
+	});
+	r.route({
+		method: "PUT",
+		url: "/api/communities/:communityId/notification-categories",
+		schema: {
+			operationId: "replaceCommunityNotificationCategories",
+			tags: ["Notifications"],
+			summary: "Replace a community's notification categories",
+			description: `Requires \`communities:write\`. On the community. Stores the whole list for this community; other communities keep theirs. 422 when a key repeats, a type cannot be in a community list, a reason is not allowed for its type, a channel is not configured, \`perSpace\` is set on a type that cannot occur in a space, \`spaceDefaults\` appears without \`perSpace\` or names a channel the category does not offer, or earlier categories already cover everything a category covers.`,
+			params: CommunityIdParam,
+			body: ReplaceNotificationCategories,
+			response: {
+				200: NotificationCategoryList,
+				...refusals(400, 403, 404, 422)
+			}
+		},
+		handler: async (req) => {
+			const actor = await resolveActor(container, req);
+			return container.notificationCategories.community.replace(req.params.communityId, req.body.categories, actor);
+		}
+	});
+	r.route({
+		method: "DELETE",
+		url: "/api/communities/:communityId/notification-categories",
+		schema: {
+			operationId: "resetCommunityNotificationCategories",
+			tags: ["Notifications"],
+			summary: "Go back to the default notification categories for a community",
+			description: `Requires \`communities:write\`. On the community. Removes the stored list; the default applies again.`,
+			params: CommunityIdParam,
+			response: {
+				204: z.void(),
+				...refusals(403, 404)
+			}
+		},
+		handler: async (req, reply) => {
+			const actor = await resolveActor(container, req);
+			await container.notificationCategories.community.reset(req.params.communityId, actor);
+			return reply.code(204).send();
 		}
 	});
 	r.route({
@@ -149,8 +194,8 @@ async function communitiesRoutes(app, container) {
 		schema: {
 			operationId: "publishCommunity",
 			tags,
-			summary: "Publish a community (staff)",
-			description: "Owner or admin only. Makes the community visible to the people who hold it.",
+			summary: "Publish a community",
+			description: `Requires \`communities:write\`. Makes the community visible to the people who hold it.`,
 			params: CommunityIdParam,
 			response: {
 				200: Community,
@@ -158,11 +203,8 @@ async function communitiesRoutes(app, container) {
 			}
 		},
 		handler: async (req) => {
-			const scope = await resolveScope(container, req);
-			return content.publishCommunity(scope.orgId, req.params.communityId, {
-				id: scope.orgUserId,
-				role: scope.role
-			});
+			const actor = await resolveActor(container, req);
+			return content.publishCommunity(req.params.communityId, actor);
 		}
 	});
 	r.route({
@@ -171,8 +213,8 @@ async function communitiesRoutes(app, container) {
 		schema: {
 			operationId: "unpublishCommunity",
 			tags,
-			summary: "Unpublish a community (staff)",
-			description: "Owner or admin only. Hides the community from members again; nothing in it is deleted.",
+			summary: "Unpublish a community",
+			description: `Requires \`communities:write\`. Hides the community from members again; nothing in it is deleted.`,
 			params: CommunityIdParam,
 			response: {
 				200: Community,
@@ -180,11 +222,8 @@ async function communitiesRoutes(app, container) {
 			}
 		},
 		handler: async (req) => {
-			const scope = await resolveScope(container, req);
-			return content.unpublishCommunity(scope.orgId, req.params.communityId, {
-				id: scope.orgUserId,
-				role: scope.role
-			});
+			const actor = await resolveActor(container, req);
+			return content.unpublishCommunity(req.params.communityId, actor);
 		}
 	});
 	r.route({
@@ -193,8 +232,8 @@ async function communitiesRoutes(app, container) {
 		schema: {
 			operationId: "getCommunityAnalytics",
 			tags,
-			summary: "Staff analytics for a community",
-			description: "Staff only (owner, admin, instructor). Membership, activity and moderation counts for one community.",
+			summary: "Analytics for a community",
+			description: `Requires \`communities:read\`. Membership, activity and moderation counts for one community.`,
 			params: CommunityIdParam,
 			response: {
 				200: CommunityAnalytics,
@@ -202,10 +241,8 @@ async function communitiesRoutes(app, container) {
 			}
 		},
 		handler: async (req) => {
-			const scope = await resolveScope(container, req);
-			const stats = await container.reporting.admin.communityAnalytics(scope.orgId, req.params.communityId);
-			if (!stats) throw new NotFoundError("Community", req.params.communityId);
-			return stats;
+			const actor = await resolveActor(container, req);
+			return container.reporting.admin.communityAnalytics(req.params.communityId, actor);
 		}
 	});
 	r.route({
@@ -214,8 +251,8 @@ async function communitiesRoutes(app, container) {
 		schema: {
 			operationId: "getCommunityMessageQueue",
 			tags,
-			summary: "Open message flags in a community (staff)",
-			description: "Staff only (owner, admin, instructor). The messages in the community's chats with open flags, with the flags and the chat each is in. Holds at most the 100 oldest open flags; working the queue brings in the next ones.",
+			summary: "Open message flags in a community",
+			description: `Requires \`communities:moderate\`. The messages in the community's chats with open flags, with the flags and the chat each is in. Holds at most the 100 oldest open flags; working the queue brings in the next ones.`,
 			params: CommunityIdParam,
 			response: {
 				200: MessageQueue,
@@ -223,11 +260,8 @@ async function communitiesRoutes(app, container) {
 			}
 		},
 		handler: async (req) => {
-			const scope = await resolveScope(container, req);
-			return container.chats.messageQueue(scope.orgId, {
-				id: scope.orgUserId,
-				role: scope.role
-			}, req.params.communityId);
+			const actor = await resolveActor(container, req);
+			return container.chats.messageQueue(req.params.communityId, actor);
 		}
 	});
 	r.route({
@@ -236,8 +270,8 @@ async function communitiesRoutes(app, container) {
 		schema: {
 			operationId: "listCommunitySpaces",
 			tags,
-			summary: "List the spaces in a community (staff)",
-			description: "Staff only (owner, admin, instructor). Every space in order, with its topics and links.",
+			summary: "List the spaces in a community",
+			description: `Requires one of \`communities:read\`, \`communities:moderate\`. Every space in order, with its topics and links.`,
 			params: CommunityIdParam,
 			response: {
 				200: z.array(SpaceDetail),
@@ -245,8 +279,8 @@ async function communitiesRoutes(app, container) {
 			}
 		},
 		handler: async (req) => {
-			const scope = await resolveScope(container, req);
-			return content.listSpaces(scope.orgId, req.params.communityId);
+			const actor = await resolveActor(container, req);
+			return content.listSpaces(req.params.communityId, actor);
 		}
 	});
 	r.route({
@@ -255,8 +289,8 @@ async function communitiesRoutes(app, container) {
 		schema: {
 			operationId: "createSpace",
 			tags,
-			summary: "Create a space (staff)",
-			description: "Owner or admin only. The space is added last. An `all_members` space cannot have a capacity (409).",
+			summary: "Create a space",
+			description: `Requires \`communities:write\`. The space is added last. An \`all_members\` space cannot have a capacity (409).`,
 			params: CommunityIdParam,
 			body: CreateSpace,
 			response: {
@@ -265,11 +299,8 @@ async function communitiesRoutes(app, container) {
 			}
 		},
 		handler: async (req, reply) => {
-			const scope = await resolveScope(container, req);
-			const space = await content.createSpace(scope.orgId, req.params.communityId, req.body, {
-				id: scope.orgUserId,
-				role: scope.role
-			});
+			const actor = await resolveActor(container, req);
+			const space = await content.createSpace(req.params.communityId, req.body, actor);
 			return reply.code(201).send(space);
 		}
 	});
@@ -279,8 +310,8 @@ async function communitiesRoutes(app, container) {
 		schema: {
 			operationId: "reorderSpaces",
 			tags,
-			summary: "Reorder the spaces in a community (staff)",
-			description: "Owner or admin only. Send every space id of the community exactly once (409 otherwise).",
+			summary: "Reorder the spaces in a community",
+			description: `Requires \`communities:write\`. Send every space id of the community exactly once (409 otherwise).`,
 			params: CommunityIdParam,
 			body: OrderedIds,
 			response: {
@@ -289,11 +320,8 @@ async function communitiesRoutes(app, container) {
 			}
 		},
 		handler: async (req) => {
-			const scope = await resolveScope(container, req);
-			return content.reorderSpaces(scope.orgId, req.params.communityId, req.body.ids, {
-				id: scope.orgUserId,
-				role: scope.role
-			});
+			const actor = await resolveActor(container, req);
+			return content.reorderSpaces(req.params.communityId, req.body.ids, actor);
 		}
 	});
 	r.route({
@@ -302,8 +330,8 @@ async function communitiesRoutes(app, container) {
 		schema: {
 			operationId: "getSpace",
 			tags,
-			summary: "Get a space (staff)",
-			description: "Staff only (owner, admin, instructor). The space with its topics and links.",
+			summary: "Get a space",
+			description: `Requires \`communities:read\`. The space with its topics and links.`,
 			params: CommunitySpaceParam,
 			response: {
 				200: SpaceDetail,
@@ -311,10 +339,8 @@ async function communitiesRoutes(app, container) {
 			}
 		},
 		handler: async (req) => {
-			const scope = await resolveScope(container, req);
-			const space = await content.getCommunitySpace(scope.orgId, req.params.communityId, req.params.spaceId);
-			if (!space) throw new NotFoundError("Space", req.params.spaceId);
-			return space;
+			const actor = await resolveActor(container, req);
+			return content.getCommunitySpace(req.params.communityId, req.params.spaceId, actor);
 		}
 	});
 	r.route({
@@ -323,8 +349,8 @@ async function communitiesRoutes(app, container) {
 		schema: {
 			operationId: "updateSpace",
 			tags,
-			summary: "Update a space (staff)",
-			description: "Owner or admin only. Changes only the fields sent; `settings` merges into the current settings. An `all_members` space cannot have a capacity (409).",
+			summary: "Update a space",
+			description: `Requires \`communities:write\`. Changes only the fields sent; \`settings\` merges into the current settings. An \`all_members\` space cannot have a capacity (409).`,
 			params: CommunitySpaceParam,
 			body: UpdateSpace,
 			response: {
@@ -333,11 +359,8 @@ async function communitiesRoutes(app, container) {
 			}
 		},
 		handler: async (req) => {
-			const scope = await resolveScope(container, req);
-			return content.updateSpace(scope.orgId, req.params.communityId, req.params.spaceId, req.body, {
-				id: scope.orgUserId,
-				role: scope.role
-			});
+			const actor = await resolveActor(container, req);
+			return content.updateSpace(req.params.communityId, req.params.spaceId, req.body, actor);
 		}
 	});
 	r.route({
@@ -346,8 +369,8 @@ async function communitiesRoutes(app, container) {
 		schema: {
 			operationId: "deleteSpace",
 			tags,
-			summary: "Delete a space (staff)",
-			description: "Owner or admin only. The space and everything in it go.",
+			summary: "Delete a space",
+			description: `Requires \`communities:write\`. The space and everything in it go.`,
 			params: CommunitySpaceParam,
 			response: {
 				204: z.void(),
@@ -355,11 +378,8 @@ async function communitiesRoutes(app, container) {
 			}
 		},
 		handler: async (req, reply) => {
-			const scope = await resolveScope(container, req);
-			await content.deleteSpace(scope.orgId, req.params.communityId, req.params.spaceId, {
-				id: scope.orgUserId,
-				role: scope.role
-			});
+			const actor = await resolveActor(container, req);
+			await content.deleteSpace(req.params.communityId, req.params.spaceId, actor);
 			return reply.code(204).send();
 		}
 	});
@@ -369,8 +389,8 @@ async function communitiesRoutes(app, container) {
 		schema: {
 			operationId: "setSpaceTopics",
 			tags,
-			summary: "Replace the topics on a space (staff)",
-			description: "Owner or admin only. The list replaces the current topics: an entry with an `id` keeps and renames that topic, one without adds a topic, and a topic left out is deleted. Names must be unique (409), and a topic that posts use cannot be deleted (409).",
+			summary: "Replace the topics on a space",
+			description: `Requires \`communities:write\`. The list replaces the current topics: an entry with an \`id\` keeps and renames that topic, one without adds a topic, and a topic left out is deleted. Names must be unique (409), and a topic that posts use cannot be deleted (409).`,
 			params: CommunitySpaceParam,
 			body: SetSpaceTopics,
 			response: {
@@ -379,11 +399,8 @@ async function communitiesRoutes(app, container) {
 			}
 		},
 		handler: async (req) => {
-			const scope = await resolveScope(container, req);
-			return content.setSpaceTopics(scope.orgId, req.params.communityId, req.params.spaceId, req.body, {
-				id: scope.orgUserId,
-				role: scope.role
-			});
+			const actor = await resolveActor(container, req);
+			return content.setSpaceTopics(req.params.communityId, req.params.spaceId, req.body, actor);
 		}
 	});
 	r.route({
@@ -392,8 +409,8 @@ async function communitiesRoutes(app, container) {
 		schema: {
 			operationId: "addSpaceLink",
 			tags,
-			summary: "Link a course, download, or community into a space (staff)",
-			description: "Owner or admin only. The link is added last. Linking the same content twice is a 409.",
+			summary: "Link a course, download, or community into a space",
+			description: `Requires \`communities:write\`. The link is added last. Linking the same content twice is a 409.`,
 			params: CommunitySpaceParam,
 			body: SpaceLinkBody,
 			response: {
@@ -402,11 +419,8 @@ async function communitiesRoutes(app, container) {
 			}
 		},
 		handler: async (req, reply) => {
-			const scope = await resolveScope(container, req);
-			const space = await content.addSpaceLink(scope.orgId, req.params.communityId, req.params.spaceId, req.body.contentId, {
-				id: scope.orgUserId,
-				role: scope.role
-			});
+			const actor = await resolveActor(container, req);
+			const space = await content.addSpaceLink(req.params.communityId, req.params.spaceId, req.body.contentId, actor);
 			return reply.code(201).send(space);
 		}
 	});
@@ -416,8 +430,8 @@ async function communitiesRoutes(app, container) {
 		schema: {
 			operationId: "removeSpaceLink",
 			tags,
-			summary: "Remove a link from a space (staff)",
-			description: "Owner or admin only. The linked content itself is untouched.",
+			summary: "Remove a link from a space",
+			description: `Requires \`communities:write\`. The linked content itself is untouched.`,
 			params: SpaceLinkParam,
 			response: {
 				200: SpaceDetail,
@@ -425,11 +439,8 @@ async function communitiesRoutes(app, container) {
 			}
 		},
 		handler: async (req) => {
-			const scope = await resolveScope(container, req);
-			return content.removeSpaceLink(scope.orgId, req.params.communityId, req.params.spaceId, req.params.linkId, {
-				id: scope.orgUserId,
-				role: scope.role
-			});
+			const actor = await resolveActor(container, req);
+			return content.removeSpaceLink(req.params.communityId, req.params.spaceId, req.params.linkId, actor);
 		}
 	});
 	r.route({
@@ -438,8 +449,8 @@ async function communitiesRoutes(app, container) {
 		schema: {
 			operationId: "reorderSpaceLinks",
 			tags,
-			summary: "Reorder the links in a space (staff)",
-			description: "Owner or admin only. Send every link id of the space exactly once (409 otherwise).",
+			summary: "Reorder the links in a space",
+			description: `Requires \`communities:write\`. Send every link id of the space exactly once (409 otherwise).`,
 			params: CommunitySpaceParam,
 			body: OrderedIds,
 			response: {
@@ -448,11 +459,8 @@ async function communitiesRoutes(app, container) {
 			}
 		},
 		handler: async (req) => {
-			const scope = await resolveScope(container, req);
-			return content.reorderSpaceLinks(scope.orgId, req.params.communityId, req.params.spaceId, req.body.ids, {
-				id: scope.orgUserId,
-				role: scope.role
-			});
+			const actor = await resolveActor(container, req);
+			return content.reorderSpaceLinks(req.params.communityId, req.params.spaceId, req.body.ids, actor);
 		}
 	});
 }