@headless-lms/server 0.3.0 → 0.5.0

package/dist/http/routes/organizations.js

@@ -1,16 +1,28 @@
 import { refusals } from "../schemas/shared.js";
-import { resolveScope } from "../scope.js";
+import { resolveActor, resolveCaller } from "../scope.js";
+import { AssignmentList, ContentIdParam, CreateRole, MembersPage, MembersQuery, OrgRoleList, OrgRoleView, OrgUserContentParam, OrgUserIdParam, RoleKeyParam, SetRole, TransferOwnership, UpdateRole } from "../schemas/members.js";
 import { CreateOrganization, Organization, UpdateOrganization } from "../schemas/organizations.js";
-import { MemberIdParam, MemberRoleChange, MembersPage, MembersQuery, UpdateMemberRole } from "../schemas/members.js";
 import { AcceptInvite, AcceptInviteResult, CreateInvite, GetInviteResult, Invite, InviteTokenParam } from "../schemas/invites.js";
+import { NotificationCategoryDefaults, NotificationCategoryList, NotificationChannelInfos, NotificationListScopeQuery, NotificationTypeInfos, 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/organizations.ts
+function inviteView(invite) {
+	return {
+		id: invite.id,
+		email: invite.email,
+		roleKey: invite.roleKey,
+		status: invite.status,
+		expiresAt: invite.expiresAt,
+		createdAt: invite.createdAt
+	};
+}
 async function organizationsRoutes(app, container) {
 	const r = app.withTypeProvider();
 	const organizations = container.organizations;
 	const tags = ["Organizations"];
+	const peopleTags = ["People"];
+	const roleTags = ["Roles"];
 	r.route({
 		method: "POST",
 		url: "/api/organizations",
@@ -24,7 +36,7 @@ async function organizationsRoutes(app, container) {
 			response: { 201: Organization }
 		},
 		handler: async (req, reply) => {
-			const org = await container.orgProvider.createOrganization(req.headers, req.body);
+			const org = await organizations.createOrganization(req.body, req.headers);
 			return reply.code(201).send({
 				name: org.name,
 				slug: org.slug,
@@ -40,102 +52,272 @@ async function organizationsRoutes(app, container) {
 		schema: {
 			operationId: "updateOrganization",
 			tags,
-			summary: "Update the active organization (staff)",
-			description: "Owner or admin. Changes its name or slug; 409 when the slug is taken.",
+			summary: "Update the active organization",
+			description: `Requires \`organizations:write\`. Changes its name or slug; 409 when the slug is taken.`,
 			body: UpdateOrganization,
 			response: {
 				200: Organization,
 				...refusals(403, 409)
 			}
 		},
-		handler: async (req, reply) => {
-			const scope = await resolveScope(container, req);
-			const org = await container.orgProvider.updateOrganization(req.headers, scope.authOrgId, req.body);
-			return reply.send({
+		handler: async (req) => {
+			const actor = await resolveActor(container, req);
+			const org = await organizations.updateOrganization(req.body, actor);
+			return {
 				id: org.id,
 				name: org.name,
 				slug: org.slug,
 				createdAt: org.createdAt.toISOString()
-			});
+			};
 		}
 	});
 	r.route({
-		method: "GET",
-		url: "/api/organizations/members",
+		method: "POST",
+		url: "/api/organizations/transfer-ownership",
 		preHandler: app.requireOrgSession,
 		schema: {
-			operationId: "listMembers",
+			operationId: "transferOwnership",
 			tags,
-			summary: "List the organization's team members (staff)",
-			description: "Staff only (owner, admin, instructor). The team: everyone in the organization who is not a student.",
-			querystring: MembersQuery,
+			summary: "Transfer ownership of the organization",
+			description: "Owner only. The new owner must be an active member. The previous owner takes the named org role, Member by default. 403 for anyone else, including the owner's API keys.",
+			body: TransferOwnership,
 			response: {
-				200: MembersPage,
-				...refusals(403)
+				204: z.void(),
+				...refusals(403, 404, 409)
 			}
 		},
-		handler: async (req) => {
-			const scope = await resolveScope(container, req);
-			return organizations.listMembers(scope.orgId, req.query);
+		handler: async (req, reply) => {
+			const actor = await resolveActor(container, req);
+			await organizations.transferOwnership(req.body, actor);
+			return reply.code(204).send();
 		}
 	});
+	r.route({
+		method: "GET",
+		url: "/api/organizations/roles",
+		preHandler: app.requireOrgSession,
+		schema: {
+			operationId: "listRoles",
+			tags: roleTags,
+			summary: "The organization's roles",
+			description: `Requires \`roles:read\`. Each role with its levels, permissions and the number of people who hold it.`,
+			response: {
+				200: OrgRoleList,
+				...refusals(403)
+			}
+		},
+		handler: async (req) => organizations.listRoles(await resolveActor(container, req))
+	});
+	r.route({
+		method: "GET",
+		url: "/api/organizations/roles/:key",
+		preHandler: app.requireOrgSession,
+		schema: {
+			operationId: "getRole",
+			tags: roleTags,
+			summary: "Read a role",
+			description: "Requires `roles:read`.",
+			params: RoleKeyParam,
+			response: {
+				200: OrgRoleView,
+				...refusals(403, 404)
+			}
+		},
+		handler: async (req) => organizations.getRole(req.params.key, await resolveActor(container, req))
+	});
 	r.route({
 		method: "PATCH",
-		url: "/api/organizations/members/:id/role",
+		url: "/api/organizations/roles/:key",
 		preHandler: app.requireOrgSession,
 		schema: {
-			operationId: "updateMemberRole",
-			tags,
-			summary: "Change a member's role (staff)",
-			description: "Owner or admin only. The owner role can be neither granted nor changed (409), and only a moderator can become a student.",
-			params: MemberIdParam,
-			body: UpdateMemberRole,
+			operationId: "updateRole",
+			tags: roleTags,
+			summary: "Rename or change a role",
+			description: `Requires \`roles:write\`. A rename needs nothing else. Changing permissions, levels or the team flag needs every permission the role holds before and after the change (403 names the missing ones). Owner and Member can only be renamed (409). Names are unique in the organization (409).`,
+			params: RoleKeyParam,
+			body: UpdateRole,
+			response: {
+				200: OrgRoleView,
+				...refusals(400, 403, 404, 409)
+			}
+		},
+		handler: async (req) => organizations.updateRole(req.params.key, req.body, await resolveActor(container, req))
+	});
+	r.route({
+		method: "POST",
+		url: "/api/organizations/roles",
+		preHandler: app.requireOrgSession,
+		schema: {
+			operationId: "createRole",
+			tags: roleTags,
+			summary: "Add a role",
+			description: `Requires \`roles:write\`. The role starts from a deployment role (\`base\`) and needs every permission it holds.`,
+			body: CreateRole,
 			response: {
-				200: MemberRoleChange,
+				201: OrgRoleView,
+				...refusals(400, 403, 409)
+			}
+		},
+		handler: async (req, reply) => reply.code(201).send(await organizations.createRole(req.body, await resolveActor(container, req)))
+	});
+	r.route({
+		method: "DELETE",
+		url: "/api/organizations/roles/:key/customization",
+		preHandler: app.requireOrgSession,
+		schema: {
+			operationId: "resetRole",
+			tags: roleTags,
+			summary: "Reset a role to the deployment's version",
+			description: `Requires \`roles:write\`. Needs every permission the role holds before and after.`,
+			params: RoleKeyParam,
+			response: {
+				200: OrgRoleView,
 				...refusals(403, 404, 409)
 			}
 		},
-		handler: async (req) => {
-			const scope = await resolveScope(container, req);
-			const ctx = {
-				orgId: scope.orgId,
-				authOrgId: scope.authOrgId,
-				headers: req.headers
-			};
-			const member = await organizations.updateMemberRole(ctx, {
-				id: scope.orgUserId,
-				role: scope.role
-			}, req.params.id, req.body.role);
-			if (!member) throw new NotFoundError("Member", req.params.id);
-			return member;
+		handler: async (req) => organizations.resetRole(req.params.key, await resolveActor(container, req))
+	});
+	r.route({
+		method: "DELETE",
+		url: "/api/organizations/roles/:key",
+		preHandler: app.requireOrgSession,
+		schema: {
+			operationId: "deleteRole",
+			tags: roleTags,
+			summary: "Delete a role the organization added",
+			description: `Requires \`roles:delete\`. Refused while anyone holds it (409, with the count).`,
+			params: RoleKeyParam,
+			response: {
+				204: z.void(),
+				...refusals(403, 404, 409)
+			}
+		},
+		handler: async (req, reply) => {
+			await organizations.deleteRole(req.params.key, await resolveActor(container, req));
+			return reply.code(204).send();
 		}
 	});
+	r.route({
+		method: "GET",
+		url: "/api/organizations/people",
+		preHandler: app.requireOrgSession,
+		schema: {
+			operationId: "listTeam",
+			tags: peopleTags,
+			summary: "The organization's team",
+			description: `Requires \`people:read\`. Everyone with an org role other than Member or a role on a content item, invited people included.`,
+			querystring: MembersQuery,
+			response: {
+				200: MembersPage,
+				...refusals(403)
+			}
+		},
+		handler: async (req) => organizations.listTeam(req.query, await resolveActor(container, req))
+	});
+	r.route({
+		method: "GET",
+		url: "/api/organizations/people/:orgUserId/roles",
+		preHandler: app.requireOrgSession,
+		schema: {
+			operationId: "listPersonRoles",
+			tags: peopleTags,
+			summary: "A person's roles",
+			description: `Requires \`people:read\`. Their org role and every role they hold on a content item.`,
+			params: OrgUserIdParam,
+			response: {
+				200: AssignmentList,
+				...refusals(403)
+			}
+		},
+		handler: async (req) => organizations.listAssignments(req.params.orgUserId, await resolveActor(container, req))
+	});
+	r.route({
+		method: "PUT",
+		url: "/api/organizations/people/:orgUserId/roles/org",
+		preHandler: app.requireOrgSession,
+		schema: {
+			operationId: "setOrgRole",
+			tags: peopleTags,
+			summary: "Set a person's org role",
+			description: `Requires \`people:write\`. Needs every permission the old and the new role hold. Nobody changes their own roles, and the owner's role changes only by transfer.`,
+			params: OrgUserIdParam,
+			body: SetRole,
+			response: {
+				200: AssignmentList,
+				...refusals(403, 404, 409)
+			}
+		},
+		handler: async (req) => organizations.setOrgRole(req.params.orgUserId, req.body.roleKey, await resolveActor(container, req))
+	});
+	r.route({
+		method: "PUT",
+		url: "/api/organizations/people/:orgUserId/roles/content/:contentId",
+		preHandler: app.requireOrgSession,
+		schema: {
+			operationId: "assignRole",
+			tags: peopleTags,
+			summary: "Give a person a role on a content item",
+			description: `Requires \`people:write\`. The role must list the item's type as a level. Needs every permission the old and the new role give there.`,
+			params: OrgUserContentParam,
+			body: SetRole,
+			response: {
+				200: AssignmentList,
+				...refusals(403, 404, 409)
+			}
+		},
+		handler: async (req) => organizations.assignRole(req.params.orgUserId, req.params.contentId, req.body.roleKey, await resolveActor(container, req))
+	});
 	r.route({
 		method: "DELETE",
-		url: "/api/organizations/members/:id",
+		url: "/api/organizations/people/:orgUserId/roles/content/:contentId",
 		preHandler: app.requireOrgSession,
 		schema: {
-			operationId: "removeMember",
-			tags,
-			summary: "Remove an organization member (staff)",
-			description: "Owner or admin only. Removing a pending member cancels their invite. The owner cannot be removed (409).",
-			params: MemberIdParam,
+			operationId: "unassignRole",
+			tags: peopleTags,
+			summary: "Remove a person's role on a content item",
+			description: "Requires `people:write`.",
+			params: OrgUserContentParam,
+			response: {
+				200: AssignmentList,
+				...refusals(403, 404)
+			}
+		},
+		handler: async (req) => organizations.unassignRole(req.params.orgUserId, req.params.contentId, await resolveActor(container, req))
+	});
+	r.route({
+		method: "GET",
+		url: "/api/organizations/content/:contentId/roles",
+		preHandler: app.requireOrgSession,
+		schema: {
+			operationId: "listRolesOn",
+			tags: peopleTags,
+			summary: "The people with a role on a content item",
+			description: "Requires `people:read`.",
+			params: ContentIdParam,
+			response: {
+				200: AssignmentList,
+				...refusals(403)
+			}
+		},
+		handler: async (req) => organizations.listAssignmentsOn(req.params.contentId, await resolveActor(container, req))
+	});
+	r.route({
+		method: "DELETE",
+		url: "/api/organizations/people/:orgUserId",
+		preHandler: app.requireOrgSession,
+		schema: {
+			operationId: "removePerson",
+			tags: peopleTags,
+			summary: "Remove a person from the organization",
+			description: `Requires \`people:delete\`. Needs every permission the person holds, where they hold it. Revokes their API keys and connected apps here. The owner can't be removed (409); neither can someone whose posts must be kept (409).`,
+			params: OrgUserIdParam,
 			response: {
 				204: z.void(),
 				...refusals(403, 404, 409)
 			}
 		},
 		handler: async (req, reply) => {
-			const scope = await resolveScope(container, req);
-			const ctx = {
-				orgId: scope.orgId,
-				authOrgId: scope.authOrgId,
-				headers: req.headers
-			};
-			if (!await organizations.removeMember(ctx, {
-				id: scope.orgUserId,
-				role: scope.role
-			}, req.params.id)) throw new NotFoundError("Member", req.params.id);
+			await organizations.removePerson(req.params.orgUserId, await resolveActor(container, req));
 			return reply.code(204).send();
 		}
 	});
@@ -145,38 +327,60 @@ async function organizationsRoutes(app, container) {
 		preHandler: app.requireOrgSession,
 		schema: {
 			operationId: "createInvite",
-			tags,
-			summary: "Invite a member or student into the active organization (staff)",
-			description: "Owner or admin only. A student is created by this call, so their access can be granted before they accept. 409 when a student with that email is already in the organization.",
+			tags: peopleTags,
+			summary: "Invite a person with an org role",
+			description: `Requires \`people:write\`. The person is created by this call, so access and item roles can be given before they accept. Needs every permission the role holds; never \`owner\` (409).`,
 			body: CreateInvite,
 			response: {
 				201: Invite,
-				...refusals(403, 409)
+				...refusals(403, 404, 409)
 			}
 		},
 		handler: async (req, reply) => {
-			const scope = await resolveScope(container, req);
-			const invite = await organizations.createInvite({
-				id: scope.orgUserId,
-				role: scope.role
-			}, {
-				orgId: scope.orgId,
-				inviterUserId: scope.userId,
-				email: req.body.email,
-				role: req.body.role,
-				...req.body.firstName !== void 0 && { firstName: req.body.firstName },
-				...req.body.lastName !== void 0 && { lastName: req.body.lastName },
-				sendEmail: req.body.sendEmail
-			});
-			req.log.debug({ inviteId: invite.id }, "created invite");
-			return reply.code(201).send({
-				id: invite.id,
-				email: invite.email,
-				role: invite.role,
-				status: invite.status,
-				expiresAt: invite.expiresAt,
-				createdAt: invite.createdAt
-			});
+			const caller = await resolveCaller(container, req);
+			const invite = await organizations.createInvite(req.body, caller.actor, caller.userId);
+			return reply.code(201).send(inviteView(invite));
+		}
+	});
+	r.route({
+		method: "POST",
+		url: "/api/organizations/people/:orgUserId/invite/resend",
+		preHandler: app.requireOrgSession,
+		schema: {
+			operationId: "resendInvite",
+			tags: peopleTags,
+			summary: "Resend a person's pending invite",
+			description: `Requires \`people:write\`. Issues a new link; the resender becomes the inviter.`,
+			params: OrgUserIdParam,
+			response: {
+				204: z.void(),
+				...refusals(403, 404)
+			}
+		},
+		handler: async (req, reply) => {
+			const caller = await resolveCaller(container, req);
+			await organizations.resendInvite(req.params.orgUserId, caller.actor, caller.userId);
+			return reply.code(204).send();
+		}
+	});
+	r.route({
+		method: "DELETE",
+		url: "/api/organizations/people/:orgUserId/invite",
+		preHandler: app.requireOrgSession,
+		schema: {
+			operationId: "cancelInvite",
+			tags: peopleTags,
+			summary: "Cancel a person's pending invite",
+			description: `Requires \`people:write\`. Someone still invited who holds no access and no item role is removed with it.`,
+			params: OrgUserIdParam,
+			response: {
+				204: z.void(),
+				...refusals(403, 404)
+			}
+		},
+		handler: async (req, reply) => {
+			await organizations.cancelInvite(req.params.orgUserId, await resolveActor(container, req));
+			return reply.code(204).send();
 		}
 	});
 	r.route({
@@ -184,7 +388,7 @@ async function organizationsRoutes(app, container) {
 		url: "/api/organizations/invites/:token",
 		schema: {
 			operationId: "getInvite",
-			tags,
+			tags: peopleTags,
 			summary: "Read an invite by its token",
 			description: "Public: no session needed. The same 404 answers forged, expired and accepted tokens, so a probe learns nothing.",
 			params: InviteTokenParam,
@@ -193,16 +397,7 @@ async function organizationsRoutes(app, container) {
 				...refusals(404)
 			}
 		},
-		handler: async (req) => {
-			const invite = await organizations.peekInvite(req.params.token);
-			if (!invite) throw new NotFoundError("Invite", "token");
-			const person = await container.identity.getUserByEmail(invite.email);
-			return {
-				email: invite.email,
-				firstName: person?.firstName ?? null,
-				lastName: person?.lastName ?? null
-			};
-		}
+		handler: async (req) => organizations.describeInvite(req.params.token)
 	});
 	r.route({
 		method: "POST",
@@ -210,9 +405,9 @@ async function organizationsRoutes(app, container) {
 		preHandler: app.requireSession,
 		schema: {
 			operationId: "acceptInvite",
-			tags,
+			tags: peopleTags,
 			summary: "Accept an invite with the signed-in account",
-			description: "For any signed-in person whose email matches the invitation. Makes the invite's organization the session's active one. 400 when the token is invalid or expired, or the email does not match.",
+			description: "For any signed-in person whose email matches the invitation. Makes the invite's organization the session's active one. 400 when the token is invalid or expired, the email does not match, or the inviter no longer holds the role.",
 			body: AcceptInvite,
 			response: {
 				200: AcceptInviteResult,
@@ -220,23 +415,133 @@ async function organizationsRoutes(app, container) {
 			}
 		},
 		handler: async (req) => {
-			const user = await container.identity.getUserByExternalId(req.authUser.id);
-			if (!user) throw new NotFoundError("User", req.authUser.id);
-			const accepted = await container.organizations.acceptInvite({
+			await organizations.acceptInvite({
 				token: req.body.token,
-				userId: user.id,
+				authUserId: req.authUser.id,
 				email: req.authUser.email
-			});
-			const org = await container.organizations.getById(accepted.orgId);
-			if (!org) throw new NotFoundError("Organization", accepted.orgId);
-			const stamped = await container.sessions.stampActiveOrganization(req.headers, org.id);
-			req.log.info({
-				accepted,
-				stamped
-			}, "accepted invite");
+			}, req.headers);
 			return {};
 		}
 	});
+	const notificationTags = ["Notifications"];
+	r.route({
+		method: "GET",
+		url: "/api/notification-types",
+		preHandler: app.requireOrgSession,
+		schema: {
+			operationId: "listNotificationTypes",
+			tags: notificationTags,
+			summary: "List the notification types a category list can cover",
+			description: `Requires one of \`notification_categories:read\`, \`communities:read\`. \`scope=org\` lists the types the org list can cover and needs \`notification_categories:read\`; \`scope=community\` lists those a community list can cover and also takes \`communities:read\` on any community. Each type carries all its scopes, so an editor can tell which types can be per space.`,
+			querystring: NotificationListScopeQuery,
+			response: {
+				200: NotificationTypeInfos,
+				...refusals(403)
+			}
+		},
+		handler: async (req) => {
+			const actor = await resolveActor(container, req);
+			return container.notificationCatalog.types(actor, req.query.scope);
+		}
+	});
+	r.route({
+		method: "GET",
+		url: "/api/notification-channels",
+		preHandler: app.requireOrgSession,
+		schema: {
+			operationId: "listNotificationChannels",
+			tags: notificationTags,
+			summary: "List the notification channels this deployment can deliver on",
+			description: `Requires one of \`notification_categories:read\`, \`communities:read\`. \`communities:read\` on any community is enough. \`inApp\` is always first.`,
+			response: {
+				200: NotificationChannelInfos,
+				...refusals(403)
+			}
+		},
+		handler: async (req) => {
+			const actor = await resolveActor(container, req);
+			return container.notificationCatalog.channels(actor);
+		}
+	});
+	r.route({
+		method: "GET",
+		url: "/api/notification-categories",
+		preHandler: app.requireOrgSession,
+		schema: {
+			operationId: "getOrgNotificationCategories",
+			tags: notificationTags,
+			summary: "Get the organization's notification categories",
+			description: `Requires \`notification_categories:read\`. The list in use for notifications outside any community, with \`source\` saying whether it is the default or a stored list.`,
+			response: {
+				200: NotificationCategoryList,
+				...refusals(403)
+			}
+		},
+		handler: async (req) => {
+			const actor = await resolveActor(container, req);
+			return container.notificationCategories.org.get(actor.orgId, actor);
+		}
+	});
+	r.route({
+		method: "PUT",
+		url: "/api/notification-categories",
+		preHandler: app.requireOrgSession,
+		schema: {
+			operationId: "replaceOrgNotificationCategories",
+			tags: notificationTags,
+			summary: "Replace the organization's notification categories",
+			description: `Requires \`notification_categories:write\`. Stores the whole list. 422 when a key repeats, a type cannot be in the org list, a reason is not allowed for its type, a channel is not configured, or earlier categories already cover everything a category covers.`,
+			body: ReplaceNotificationCategories,
+			response: {
+				200: NotificationCategoryList,
+				...refusals(400, 403, 422)
+			}
+		},
+		handler: async (req) => {
+			const actor = await resolveActor(container, req);
+			return container.notificationCategories.org.replace(actor.orgId, req.body.categories, actor);
+		}
+	});
+	r.route({
+		method: "DELETE",
+		url: "/api/notification-categories",
+		preHandler: app.requireOrgSession,
+		schema: {
+			operationId: "resetOrgNotificationCategories",
+			tags: notificationTags,
+			summary: "Go back to the default notification categories for the organization",
+			description: `Requires \`notification_categories:write\`. Removes the stored list; the default applies again.`,
+			response: {
+				204: z.void(),
+				...refusals(403)
+			}
+		},
+		handler: async (req, reply) => {
+			const actor = await resolveActor(container, req);
+			await container.notificationCategories.org.reset(actor.orgId, actor);
+			return reply.code(204).send();
+		}
+	});
+	r.route({
+		method: "GET",
+		url: "/api/notification-categories/defaults",
+		preHandler: app.requireOrgSession,
+		schema: {
+			operationId: "getDefaultNotificationCategories",
+			tags: notificationTags,
+			summary: "Get the default notification categories",
+			description: `Requires one of \`notification_categories:read\`, \`communities:read\`. The default org list (\`scope=org\`, which needs \`notification_categories:read\`) or community list (\`scope=community\`, which also takes \`communities:read\` on any community), offering only the configured channels.`,
+			querystring: NotificationListScopeQuery,
+			response: {
+				200: NotificationCategoryDefaults,
+				...refusals(403)
+			}
+		},
+		handler: async (req) => {
+			const actor = await resolveActor(container, req);
+			return { categories: container.notificationCatalog.defaults(actor, req.query.scope) };
+		}
+	});
 }
 //#endregion
 export { organizationsRoutes };