@headless-lms/server 0.2.0 → 0.4.0

package/dist/http/routes/assets.js

@@ -1,8 +1,9 @@
-import { ErrorBody } from "../schemas/shared.js";
-import { Asset, AssetIdParam, AssetsPage, AssetsQuery, DownloadTicket, RequestDownload, RequestUpload, UploadTicket } from "../schemas/assets.js";
+import { refusals } from "../schemas/shared.js";
+import { resolveScope } from "../scope.js";
+import { Asset, AssetIdParam, AssetsPage, AssetsQuery, RequestUpload, UploadTicket } from "../schemas/assets.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/assets.ts
 /** Resolve the session's active org to the domain org id, or 400 and return null. */
 async function resolveOrgId(req, reply) {
@@ -19,27 +20,30 @@ async function assetsRoutes(app, container) {
 	const r = app.withTypeProvider();
 	const assets = container.assets;
 	const tags = ["Assets"];
+	const staff = async (req) => {
+		await resolveScope(container, req);
+	};
 	r.route({
 		method: "POST",
 		url: "/api/uploads",
-		preHandler: app.requireOrgSession,
+		preHandler: staff,
 		schema: {
 			operationId: "requestUpload",
 			tags,
-			summary: "Register an asset and get a presigned upload URL",
+			summary: "Register a library asset and get a presigned upload URL (staff)",
+			description: "Staff only (owner, admin, instructor). The asset stays pending until you upload the file and confirm it.",
 			body: RequestUpload,
 			response: {
 				201: UploadTicket,
-				400: ErrorBody,
-				401: ErrorBody
+				...refusals(403)
 			}
 		},
 		handler: async (req, reply) => {
-			const orgId = await resolveOrgId(req, reply);
-			if (!orgId) return;
-			const ticket = await assets.requestUpload(orgId, {
-				uploadedBy: req.userId,
-				...req.body
+			const scope = await resolveScope(container, req);
+			const ticket = await assets.requestUpload(scope.orgId, {
+				...req.body,
+				source: "library",
+				uploadedBy: scope.orgUserId
 			});
 			return reply.code(201).send(ticket);
 		}
@@ -47,17 +51,16 @@ async function assetsRoutes(app, container) {
 	r.route({
 		method: "POST",
 		url: "/api/assets/:id/confirm",
-		preHandler: app.requireOrgSession,
+		preHandler: staff,
 		schema: {
 			operationId: "confirmAsset",
 			tags,
-			summary: "Confirm an upload completed (captures size + content type)",
+			summary: "Confirm a library upload completed (staff)",
+			description: "Staff only (owner, admin, instructor). Captures the stored size and content type: a pending library upload becomes ready; a ready one is returned unchanged. A member upload is finalized only by its uploader and is answered with 403.",
 			params: AssetIdParam,
 			response: {
 				200: Asset,
-				400: ErrorBody,
-				401: ErrorBody,
-				404: ErrorBody
+				...refusals(403, 404)
 			}
 		},
 		handler: async (req, reply) => {
@@ -71,16 +74,16 @@ async function assetsRoutes(app, container) {
 	r.route({
 		method: "GET",
 		url: "/api/assets",
-		preHandler: app.requireOrgSession,
+		preHandler: staff,
 		schema: {
 			operationId: "listAssets",
 			tags,
-			summary: "Browse the organization's media library",
+			summary: "Browse the organization's media library (staff)",
+			description: "Staff only (owner, admin, instructor). Library files by default; `source: member` lists members' uploads.",
 			querystring: AssetsQuery,
 			response: {
 				200: AssetsPage,
-				400: ErrorBody,
-				401: ErrorBody
+				...refusals(403)
 			}
 		},
 		handler: async (req, reply) => {
@@ -92,17 +95,16 @@ async function assetsRoutes(app, container) {
 	r.route({
 		method: "GET",
 		url: "/api/assets/:id",
-		preHandler: app.requireOrgSession,
+		preHandler: staff,
 		schema: {
 			operationId: "getAsset",
 			tags,
-			summary: "Get an asset's metadata",
+			summary: "Get an asset's metadata (staff)",
+			description: "Staff only (owner, admin, instructor).",
 			params: AssetIdParam,
 			response: {
 				200: Asset,
-				400: ErrorBody,
-				401: ErrorBody,
-				404: ErrorBody
+				...refusals(403, 404)
 			}
 		},
 		handler: async (req, reply) => {
@@ -114,55 +116,58 @@ async function assetsRoutes(app, container) {
 		}
 	});
 	r.route({
-		method: "POST",
-		url: "/api/assets/:id/download-url",
-		preHandler: app.requireOrgSession,
-		preValidation: (req, _reply, done) => {
-			req.body ??= {};
-			done();
-		},
+		method: "DELETE",
+		url: "/api/assets/:id",
+		preHandler: staff,
 		schema: {
-			operationId: "requestAssetDownload",
+			operationId: "deleteAsset",
 			tags,
-			summary: "Get a short-lived presigned URL to download/serve an asset",
+			summary: "Delete an asset nothing references (staff)",
+			description: "Staff only (owner, admin, instructor). Removes the row and the stored file. 409 while content still uses it.",
 			params: AssetIdParam,
-			body: RequestDownload,
 			response: {
-				200: DownloadTicket,
-				400: ErrorBody,
-				401: ErrorBody,
-				404: ErrorBody
+				204: z.void(),
+				...refusals(403, 404, 409)
 			}
 		},
 		handler: async (req, reply) => {
 			const orgId = await resolveOrgId(req, reply);
 			if (!orgId) return;
-			const ticket = await assets.requestDownload(orgId, req.params.id, req.body.filename);
-			if (!ticket) throw new NotFoundError("Asset", req.params.id);
-			return ticket;
+			if (!await assets.remove(orgId, req.params.id)) throw new NotFoundError("Asset", req.params.id);
+			return reply.code(204).send();
 		}
 	});
-	r.route({
-		method: "DELETE",
-		url: "/api/assets/:id",
-		preHandler: app.requireOrgSession,
+	for (const { suffix, download, operationId, summary } of [{
+		suffix: "file",
+		download: false,
+		operationId: "getLibraryFile",
+		summary: "Redirect to a library file to show it (staff)"
+	}, {
+		suffix: "download",
+		download: true,
+		operationId: "downloadLibraryFile",
+		summary: "Redirect to a library file saved under its filename (staff)"
+	}]) r.route({
+		method: "GET",
+		url: `/api/assets/:id/${suffix}`,
+		preHandler: staff,
 		schema: {
-			operationId: "deleteAsset",
+			operationId,
 			tags,
-			summary: "Delete an asset (removes the object from storage)",
+			summary,
+			description: "Staff only (owner, admin, instructor). Ready library files of the organization; member uploads and pending files answer 404.",
 			params: AssetIdParam,
 			response: {
-				204: z.void(),
-				400: ErrorBody,
-				401: ErrorBody,
-				404: ErrorBody
+				302: z.void(),
+				...refusals(403, 404)
 			}
 		},
 		handler: async (req, reply) => {
 			const orgId = await resolveOrgId(req, reply);
 			if (!orgId) return;
-			if (!await assets.remove(orgId, req.params.id)) throw new NotFoundError("Asset", req.params.id);
-			return reply.code(204).send();
+			const url = await assets.libraryFile(orgId, req.params.id, { download });
+			if (!url) throw new NotFoundError("Asset", req.params.id);
+			return reply.header("cache-control", "no-store").header("referrer-policy", "no-referrer").redirect(url, 302);
 		}
 	});
 }

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

@@ -1 +1 @@
-{"version":3,"file":"assets.js","names":[],"sources":["../../../src/http/routes/assets.ts"],"sourcesContent":["// HTTP routes for the assets media library + content delivery. All require a\n// session with an active organization; assets are stored under the org's\n// private prefix and served only through short-lived presigned URLs.\n//\n// `req.orgId` is already the domain organization id these tables key on — the\n// session guard translates it from better-auth's id once per request.\nimport type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';\nimport type { ZodTypeProvider } from 'fastify-type-provider-zod';\nimport { z } from 'zod';\nimport {\n  Asset,\n  AssetIdParam,\n  AssetsPage,\n  AssetsQuery,\n  DownloadTicket,\n  ErrorBody,\n  RequestDownload,\n  RequestUpload,\n  UploadTicket,\n} from '../schemas/index.js';\nimport { NotFoundError } from '@headless-lms/core/shared/errors';\nimport type { Container } from '../../app/container.js';\n\n/** Resolve the session's active org to the domain org id, or 400 and return null. */\nasync function resolveOrgId(req: FastifyRequest, reply: FastifyReply): Promise<string | null> {\n  if (!req.orgId) {\n    await reply.code(400).send({ error: 'no_active_org', message: 'No active organization' });\n    return null;\n  }\n  return req.orgId;\n}\n\nexport async function assetsRoutes(app: FastifyInstance, container: Container): Promise<void> {\n  const r = app.withTypeProvider<ZodTypeProvider>();\n  const assets = container.assets;\n  const tags = ['Assets'];\n\n  // Register an asset + get a presigned upload URL. Kept at /api/uploads as the\n  // \"start an upload\" action; the resulting asset lives in the library below.\n  r.route({\n    method: 'POST',\n    url: '/api/uploads',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'requestUpload',\n      tags,\n      summary: 'Register an asset and get a presigned upload URL',\n      body: RequestUpload,\n      response: { 201: UploadTicket, 400: ErrorBody, 401: ErrorBody },\n    },\n    handler: async (req, reply) => {\n      const orgId = await resolveOrgId(req, reply);\n      if (!orgId) {\n        return;\n      }\n      const ticket = await assets.requestUpload(orgId, {\n        // Domain `users.id`, like every other org-scoped row — not the auth id.\n        uploadedBy: req.userId,\n        ...req.body,\n      });\n      return reply.code(201).send(ticket);\n    },\n  });\n\n  r.route({\n    method: 'POST',\n    url: '/api/assets/:id/confirm',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'confirmAsset',\n      tags,\n      summary: 'Confirm an upload completed (captures size + content type)',\n      params: AssetIdParam,\n      response: { 200: Asset, 400: ErrorBody, 401: ErrorBody, 404: ErrorBody },\n    },\n    handler: async (req, reply) => {\n      const orgId = await resolveOrgId(req, reply);\n      if (!orgId) {\n        return;\n      }\n      const asset = await assets.confirm(orgId, req.params.id);\n      if (!asset) {\n        throw new NotFoundError('Asset', req.params.id);\n      }\n      return asset;\n    },\n  });\n\n  r.route({\n    method: 'GET',\n    url: '/api/assets',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'listAssets',\n      tags,\n      summary: \"Browse the organization's media library\",\n      querystring: AssetsQuery,\n      response: { 200: AssetsPage, 400: ErrorBody, 401: ErrorBody },\n    },\n    handler: async (req, reply) => {\n      const orgId = await resolveOrgId(req, reply);\n      if (!orgId) {\n        return;\n      }\n      return assets.list(orgId, req.query);\n    },\n  });\n\n  r.route({\n    method: 'GET',\n    url: '/api/assets/:id',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'getAsset',\n      tags,\n      summary: \"Get an asset's metadata\",\n      params: AssetIdParam,\n      response: { 200: Asset, 400: ErrorBody, 401: ErrorBody, 404: ErrorBody },\n    },\n    handler: async (req, reply) => {\n      const orgId = await resolveOrgId(req, reply);\n      if (!orgId) {\n        return;\n      }\n      const asset = await assets.get(orgId, req.params.id);\n      if (!asset) {\n        throw new NotFoundError('Asset', req.params.id);\n      }\n      return asset;\n    },\n  });\n\n  r.route({\n    method: 'POST',\n    url: '/api/assets/:id/download-url',\n    preHandler: app.requireOrgSession,\n    // Every body field is optional, so a bodyless POST is valid — the\n    // generated SDK omits the body entirely when no field is set, which\n    // Fastify hands to validation as `null`. Normalize before it gets there.\n    preValidation: (req, _reply, done) => {\n      req.body ??= {};\n      done();\n    },\n    schema: {\n      operationId: 'requestAssetDownload',\n      tags,\n      summary: 'Get a short-lived presigned URL to download/serve an asset',\n      params: AssetIdParam,\n      body: RequestDownload,\n      response: { 200: DownloadTicket, 400: ErrorBody, 401: ErrorBody, 404: ErrorBody },\n    },\n    handler: async (req, reply) => {\n      const orgId = await resolveOrgId(req, reply);\n      if (!orgId) {\n        return;\n      }\n      const ticket = await assets.requestDownload(orgId, req.params.id, req.body.filename);\n      if (!ticket) {\n        throw new NotFoundError('Asset', req.params.id);\n      }\n      return ticket;\n    },\n  });\n\n  r.route({\n    method: 'DELETE',\n    url: '/api/assets/:id',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'deleteAsset',\n      tags,\n      summary: 'Delete an asset (removes the object from storage)',\n      params: AssetIdParam,\n      response: { 204: z.void(), 400: ErrorBody, 401: ErrorBody, 404: ErrorBody },\n    },\n    handler: async (req, reply) => {\n      const orgId = await resolveOrgId(req, reply);\n      if (!orgId) {\n        return;\n      }\n      const removed = await assets.remove(orgId, req.params.id);\n      if (!removed) {\n        throw new NotFoundError('Asset', req.params.id);\n      }\n      return reply.code(204).send();\n    },\n  });\n}\n"],"mappings":"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"}
+{"version":3,"file":"assets.js","names":[],"sources":["../../../src/http/routes/assets.ts"],"sourcesContent":["// HTTP routes for the assets media library. All require a session with an\n// active organization; assets are stored under the org's private prefix and\n// served through stable staff URLs that redirect to a signed storage URL.\n//\n// `req.orgId` is already the domain organization id these tables key on — the\n// session guard translates it from better-auth's id once per request.\nimport type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';\nimport type { ZodTypeProvider } from 'fastify-type-provider-zod';\nimport { z } from 'zod';\nimport {\n  Asset,\n  AssetIdParam,\n  AssetsPage,\n  AssetsQuery,\n  RequestUpload,\n  UploadTicket,\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\n/** Resolve the session's active org to the domain org id, or 400 and return null. */\nasync function resolveOrgId(req: FastifyRequest, reply: FastifyReply): Promise<string | null> {\n  if (!req.orgId) {\n    await reply.code(400).send({ error: 'no_active_org', message: 'No active organization' });\n    return null;\n  }\n  return req.orgId;\n}\n\nexport async function assetsRoutes(app: FastifyInstance, container: Container): Promise<void> {\n  const r = app.withTypeProvider<ZodTypeProvider>();\n  const assets = container.assets;\n  const tags = ['Assets'];\n  const staff = async (req: FastifyRequest) => {\n    await resolveScope(container, req);\n  };\n\n  // Register an asset + get a presigned upload URL. Kept at /api/uploads as the\n  // \"start an upload\" action; the resulting asset lives in the library below.\n  r.route({\n    method: 'POST',\n    url: '/api/uploads',\n    preHandler: staff,\n    schema: {\n      operationId: 'requestUpload',\n      tags,\n      summary: 'Register a library asset and get a presigned upload URL (staff)',\n      description:\n        'Staff only (owner, admin, instructor). The asset stays pending until you upload the file and confirm it.',\n      body: RequestUpload,\n      response: { 201: UploadTicket, ...refusals(403) },\n    },\n    handler: async (req, reply) => {\n      const scope = await resolveScope(container, req);\n      const ticket = await assets.requestUpload(scope.orgId, {\n        ...req.body,\n        source: 'library',\n        uploadedBy: scope.orgUserId,\n      });\n      return reply.code(201).send(ticket);\n    },\n  });\n\n  r.route({\n    method: 'POST',\n    url: '/api/assets/:id/confirm',\n    preHandler: staff,\n    schema: {\n      operationId: 'confirmAsset',\n      tags,\n      summary: 'Confirm a library upload completed (staff)',\n      description:\n        'Staff only (owner, admin, instructor). Captures the stored size and content type: a pending library upload becomes ready; a ready one is returned unchanged. A member upload is finalized only by its uploader and is answered with 403.',\n      params: AssetIdParam,\n      response: { 200: Asset, ...refusals(403, 404) },\n    },\n    handler: async (req, reply) => {\n      const orgId = await resolveOrgId(req, reply);\n      if (!orgId) {\n        return;\n      }\n      const asset = await assets.confirm(orgId, req.params.id);\n      if (!asset) {\n        throw new NotFoundError('Asset', req.params.id);\n      }\n      return asset;\n    },\n  });\n\n  r.route({\n    method: 'GET',\n    url: '/api/assets',\n    preHandler: staff,\n    schema: {\n      operationId: 'listAssets',\n      tags,\n      summary: \"Browse the organization's media library (staff)\",\n      description:\n        \"Staff only (owner, admin, instructor). Library files by default; `source: member` lists members' uploads.\",\n      querystring: AssetsQuery,\n      response: { 200: AssetsPage, ...refusals(403) },\n    },\n    handler: async (req, reply) => {\n      const orgId = await resolveOrgId(req, reply);\n      if (!orgId) {\n        return;\n      }\n      return assets.list(orgId, req.query);\n    },\n  });\n\n  r.route({\n    method: 'GET',\n    url: '/api/assets/:id',\n    preHandler: staff,\n    schema: {\n      operationId: 'getAsset',\n      tags,\n      summary: \"Get an asset's metadata (staff)\",\n      description: 'Staff only (owner, admin, instructor).',\n      params: AssetIdParam,\n      response: { 200: Asset, ...refusals(403, 404) },\n    },\n    handler: async (req, reply) => {\n      const orgId = await resolveOrgId(req, reply);\n      if (!orgId) {\n        return;\n      }\n      const asset = await assets.get(orgId, req.params.id);\n      if (!asset) {\n        throw new NotFoundError('Asset', req.params.id);\n      }\n      return asset;\n    },\n  });\n\n  r.route({\n    method: 'DELETE',\n    url: '/api/assets/:id',\n    preHandler: staff,\n    schema: {\n      operationId: 'deleteAsset',\n      tags,\n      summary: 'Delete an asset nothing references (staff)',\n      description:\n        'Staff only (owner, admin, instructor). Removes the row and the stored file. 409 while content still uses it.',\n      params: AssetIdParam,\n      response: { 204: z.void(), ...refusals(403, 404, 409) },\n    },\n    handler: async (req, reply) => {\n      const orgId = await resolveOrgId(req, reply);\n      if (!orgId) {\n        return;\n      }\n      const removed = await assets.remove(orgId, req.params.id);\n      if (!removed) {\n        throw new NotFoundError('Asset', req.params.id);\n      }\n      return reply.code(204).send();\n    },\n  });\n\n  for (const { suffix, download, operationId, summary } of [\n    {\n      suffix: 'file',\n      download: false,\n      operationId: 'getLibraryFile',\n      summary: 'Redirect to a library file to show it (staff)',\n    },\n    {\n      suffix: 'download',\n      download: true,\n      operationId: 'downloadLibraryFile',\n      summary: 'Redirect to a library file saved under its filename (staff)',\n    },\n  ]) {\n    r.route({\n      method: 'GET',\n      url: `/api/assets/:id/${suffix}`,\n      preHandler: staff,\n      schema: {\n        operationId,\n        tags,\n        summary,\n        description:\n          'Staff only (owner, admin, instructor). Ready library files of the organization; member uploads and pending files answer 404.',\n        params: AssetIdParam,\n        response: { 302: z.void(), ...refusals(403, 404) },\n      },\n      handler: async (req, reply) => {\n        const orgId = await resolveOrgId(req, reply);\n        if (!orgId) {\n          return;\n        }\n        const url = await assets.libraryFile(orgId, req.params.id, { download });\n        if (!url) {\n          throw new NotFoundError('Asset', req.params.id);\n        }\n        return reply\n          .header('cache-control', 'no-store')\n          .header('referrer-policy', 'no-referrer')\n          .redirect(url, 302);\n      },\n    });\n  }\n}\n"],"mappings":";;;;;;;;AAuBA,eAAe,aAAa,KAAqB,OAA6C;CAC5F,IAAI,CAAC,IAAI,OAAO;EACd,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK;GAAE,OAAO;GAAiB,SAAS;EAAyB,CAAC;EACxF,OAAO;CACT;CACA,OAAO,IAAI;AACb;AAEA,eAAsB,aAAa,KAAsB,WAAqC;CAC5F,MAAM,IAAI,IAAI,iBAAkC;CAChD,MAAM,SAAS,UAAU;CACzB,MAAM,OAAO,CAAC,QAAQ;CACtB,MAAM,QAAQ,OAAO,QAAwB;EAC3C,MAAM,aAAa,WAAW,GAAG;CACnC;CAIA,EAAE,MAAM;EACN,QAAQ;EACR,KAAK;EACL,YAAY;EACZ,QAAQ;GACN,aAAa;GACb;GACA,SAAS;GACT,aACE;GACF,MAAM;GACN,UAAU;IAAE,KAAK;IAAc,GAAG,SAAS,GAAG;GAAE;EAClD;EACA,SAAS,OAAO,KAAK,UAAU;GAC7B,MAAM,QAAQ,MAAM,aAAa,WAAW,GAAG;GAC/C,MAAM,SAAS,MAAM,OAAO,cAAc,MAAM,OAAO;IACrD,GAAG,IAAI;IACP,QAAQ;IACR,YAAY,MAAM;GACpB,CAAC;GACD,OAAO,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,MAAM;EACpC;CACF,CAAC;CAED,EAAE,MAAM;EACN,QAAQ;EACR,KAAK;EACL,YAAY;EACZ,QAAQ;GACN,aAAa;GACb;GACA,SAAS;GACT,aACE;GACF,QAAQ;GACR,UAAU;IAAE,KAAK;IAAO,GAAG,SAAS,KAAK,GAAG;GAAE;EAChD;EACA,SAAS,OAAO,KAAK,UAAU;GAC7B,MAAM,QAAQ,MAAM,aAAa,KAAK,KAAK;GAC3C,IAAI,CAAC,OACH;GAEF,MAAM,QAAQ,MAAM,OAAO,QAAQ,OAAO,IAAI,OAAO,EAAE;GACvD,IAAI,CAAC,OACH,MAAM,IAAI,cAAc,SAAS,IAAI,OAAO,EAAE;GAEhD,OAAO;EACT;CACF,CAAC;CAED,EAAE,MAAM;EACN,QAAQ;EACR,KAAK;EACL,YAAY;EACZ,QAAQ;GACN,aAAa;GACb;GACA,SAAS;GACT,aACE;GACF,aAAa;GACb,UAAU;IAAE,KAAK;IAAY,GAAG,SAAS,GAAG;GAAE;EAChD;EACA,SAAS,OAAO,KAAK,UAAU;GAC7B,MAAM,QAAQ,MAAM,aAAa,KAAK,KAAK;GAC3C,IAAI,CAAC,OACH;GAEF,OAAO,OAAO,KAAK,OAAO,IAAI,KAAK;EACrC;CACF,CAAC;CAED,EAAE,MAAM;EACN,QAAQ;EACR,KAAK;EACL,YAAY;EACZ,QAAQ;GACN,aAAa;GACb;GACA,SAAS;GACT,aAAa;GACb,QAAQ;GACR,UAAU;IAAE,KAAK;IAAO,GAAG,SAAS,KAAK,GAAG;GAAE;EAChD;EACA,SAAS,OAAO,KAAK,UAAU;GAC7B,MAAM,QAAQ,MAAM,aAAa,KAAK,KAAK;GAC3C,IAAI,CAAC,OACH;GAEF,MAAM,QAAQ,MAAM,OAAO,IAAI,OAAO,IAAI,OAAO,EAAE;GACnD,IAAI,CAAC,OACH,MAAM,IAAI,cAAc,SAAS,IAAI,OAAO,EAAE;GAEhD,OAAO;EACT;CACF,CAAC;CAED,EAAE,MAAM;EACN,QAAQ;EACR,KAAK;EACL,YAAY;EACZ,QAAQ;GACN,aAAa;GACb;GACA,SAAS;GACT,aACE;GACF,QAAQ;GACR,UAAU;IAAE,KAAK,EAAE,KAAK;IAAG,GAAG,SAAS,KAAK,KAAK,GAAG;GAAE;EACxD;EACA,SAAS,OAAO,KAAK,UAAU;GAC7B,MAAM,QAAQ,MAAM,aAAa,KAAK,KAAK;GAC3C,IAAI,CAAC,OACH;GAGF,IAAI,CAAC,MADiB,OAAO,OAAO,OAAO,IAAI,OAAO,EAAE,GAEtD,MAAM,IAAI,cAAc,SAAS,IAAI,OAAO,EAAE;GAEhD,OAAO,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK;EAC9B;CACF,CAAC;CAED,KAAK,MAAM,EAAE,QAAQ,UAAU,aAAa,aAAa,CACvD;EACE,QAAQ;EACR,UAAU;EACV,aAAa;EACb,SAAS;CACX,GACA;EACE,QAAQ;EACR,UAAU;EACV,aAAa;EACb,SAAS;CACX,CACF,GACE,EAAE,MAAM;EACN,QAAQ;EACR,KAAK,mBAAmB;EACxB,YAAY;EACZ,QAAQ;GACN;GACA;GACA;GACA,aACE;GACF,QAAQ;GACR,UAAU;IAAE,KAAK,EAAE,KAAK;IAAG,GAAG,SAAS,KAAK,GAAG;GAAE;EACnD;EACA,SAAS,OAAO,KAAK,UAAU;GAC7B,MAAM,QAAQ,MAAM,aAAa,KAAK,KAAK;GAC3C,IAAI,CAAC,OACH;GAEF,MAAM,MAAM,MAAM,OAAO,YAAY,OAAO,IAAI,OAAO,IAAI,EAAE,SAAS,CAAC;GACvE,IAAI,CAAC,KACH,MAAM,IAAI,cAAc,SAAS,IAAI,OAAO,EAAE;GAEhD,OAAO,MACJ,OAAO,iBAAiB,UAAU,CAAC,CACnC,OAAO,mBAAmB,aAAa,CAAC,CACxC,SAAS,KAAK,GAAG;EACtB;CACF,CAAC;AAEL"}

package/dist/http/routes/automations.js

@@ -1,9 +1,9 @@
+import { refusals } from "../schemas/shared.js";
 import { resolveScope } from "../scope.js";
-import { ErrorBody } from "../schemas/shared.js";
 import { Automation, AutomationIdParam, AutomationRun, AutomationRunParams, AutomationRunsPage, AutomationRunsQuery, AutomationsQuery, AvailableAction, AvailableTriggers, CreateAutomationBody, UpdateAutomationBody } from "../schemas/automations.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/automations.ts
 async function automationsRoutes(app, container) {
 	const r = app.withTypeProvider();
@@ -16,9 +16,13 @@ async function automationsRoutes(app, container) {
 		schema: {
 			operationId: "listAutomations",
 			tags,
-			summary: "List automations, optionally only workflows or only webhooks",
+			summary: "List automations (staff)",
+			description: "Staff only (owner, admin, instructor). Optionally only workflows or only webhooks.",
 			querystring: AutomationsQuery,
-			response: { 200: z.array(Automation) }
+			response: {
+				200: z.array(Automation),
+				...refusals(403)
+			}
 		},
 		handler: async (req) => {
 			const scope = await resolveScope(container, req);
@@ -32,8 +36,12 @@ async function automationsRoutes(app, container) {
 		schema: {
 			operationId: "listAutomationActions",
 			tags,
-			summary: "List the actions automations can use",
-			response: { 200: z.array(AvailableAction) }
+			summary: "List the actions automations can use (staff)",
+			description: "Staff only (owner, admin, instructor).",
+			response: {
+				200: z.array(AvailableAction),
+				...refusals(403)
+			}
 		},
 		handler: async (req) => {
 			await resolveScope(container, req);
@@ -47,8 +55,12 @@ async function automationsRoutes(app, container) {
 		schema: {
 			operationId: "listAutomationTriggers",
 			tags,
-			summary: "List the domain events automations can react to",
-			response: { 200: AvailableTriggers }
+			summary: "List the domain events automations can react to (staff)",
+			description: "Staff only (owner, admin, instructor).",
+			response: {
+				200: AvailableTriggers,
+				...refusals(403)
+			}
 		},
 		handler: async (req) => {
 			await resolveScope(container, req);
@@ -62,9 +74,13 @@ async function automationsRoutes(app, container) {
 		schema: {
 			operationId: "createAutomation",
 			tags,
-			summary: "Create a workflow automation",
+			summary: "Create a workflow automation (staff)",
+			description: "Staff only (owner, admin, instructor). 400 when a trigger is reserved, not an event the system emits or an unsupported schedule, or an action is reserved for webhooks or no longer available.",
 			body: CreateAutomationBody,
-			response: { 201: Automation }
+			response: {
+				201: Automation,
+				...refusals(400, 403)
+			}
 		},
 		handler: async (req, reply) => {
 			const scope = await resolveScope(container, req);
@@ -79,11 +95,12 @@ async function automationsRoutes(app, container) {
 		schema: {
 			operationId: "getAutomation",
 			tags,
-			summary: "Get an automation by id",
+			summary: "Get an automation (staff)",
+			description: "Staff only (owner, admin, instructor). Workflows and webhooks alike.",
 			params: AutomationIdParam,
 			response: {
 				200: Automation,
-				404: ErrorBody
+				...refusals(403, 404)
 			}
 		},
 		handler: async (req) => {
@@ -100,13 +117,13 @@ async function automationsRoutes(app, container) {
 		schema: {
 			operationId: "updateAutomation",
 			tags,
-			summary: "Update a workflow automation (webhooks change through the webhook endpoints)",
+			summary: "Update a workflow automation (staff)",
+			description: "Staff only (owner, admin, instructor). Webhooks change through the webhook endpoints (409). 400 when a trigger is reserved, not an event the system emits or an unsupported schedule, or an action is reserved for webhooks or no longer available.",
 			params: AutomationIdParam,
 			body: UpdateAutomationBody,
 			response: {
 				200: Automation,
-				404: ErrorBody,
-				409: ErrorBody
+				...refusals(400, 403, 404, 409)
 			}
 		},
 		handler: async (req) => {
@@ -123,12 +140,12 @@ async function automationsRoutes(app, container) {
 		schema: {
 			operationId: "deleteAutomation",
 			tags,
-			summary: "Delete a workflow automation (webhooks are deleted through the webhook endpoints)",
+			summary: "Delete a workflow automation (staff)",
+			description: "Staff only (owner, admin, instructor). Webhooks are deleted through the webhook endpoints (409). Its runs stay readable.",
 			params: AutomationIdParam,
 			response: {
 				204: z.void(),
-				404: ErrorBody,
-				409: ErrorBody
+				...refusals(403, 404, 409)
 			}
 		},
 		handler: async (req, reply) => {
@@ -144,10 +161,14 @@ async function automationsRoutes(app, container) {
 		schema: {
 			operationId: "listAutomationRuns",
 			tags,
-			summary: "List an automation's runs — a deleted automation's runs remain reachable (audit trail)",
+			summary: "List an automation's runs (staff)",
+			description: "Staff only (owner, admin, instructor). A deleted automation's runs remain reachable as an audit trail, so an unknown id answers an empty page rather than 404. A run's event carries the fields a webhook delivery of that event would.",
 			params: AutomationIdParam,
 			querystring: AutomationRunsQuery,
-			response: { 200: AutomationRunsPage }
+			response: {
+				200: AutomationRunsPage,
+				...refusals(403)
+			}
 		},
 		handler: async (req) => {
 			const scope = await resolveScope(container, req);
@@ -161,13 +182,12 @@ async function automationsRoutes(app, container) {
 		schema: {
 			operationId: "rerunAutomationRun",
 			tags,
-			summary: "Run a finished run again",
-			description: "Dispatches the same run again with the automation's current steps; the new outcome replaces the run's previous one. For a webhook this resends the delivery to its current URL. A run that is still running can't be rerun (409).",
+			summary: "Run a finished run again (staff)",
+			description: "Staff only (owner, admin, instructor). Dispatches the same run again with the automation's current steps; the new outcome replaces the run's previous one. For a webhook this resends the delivery to its current URL. A run that is still running can't be rerun (409).",
 			params: AutomationRunParams,
 			response: {
 				200: AutomationRun,
-				404: ErrorBody,
-				409: ErrorBody
+				...refusals(403, 404, 409)
 			}
 		},
 		handler: async (req) => {

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

@@ -1 +1 @@
-{"version":3,"file":"automations.js","names":[],"sources":["../../../src/http/routes/automations.ts"],"sourcesContent":["// HTTP routes for the automations context: rules that match a trigger (a\n// domain event type) against enabled automations and run an ordered list of\n// actions, plus the run history each automation accumulates.\nimport type { FastifyInstance } from 'fastify';\nimport { z } from 'zod';\nimport type { ZodTypeProvider } from 'fastify-type-provider-zod';\nimport {\n  Automation,\n  AutomationIdParam,\n  AutomationRun,\n  AutomationRunParams,\n  AutomationRunsPage,\n  AutomationRunsQuery,\n  AutomationsQuery,\n  AvailableAction,\n  AvailableTriggers,\n  CreateAutomationBody,\n  ErrorBody,\n  UpdateAutomationBody,\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 automationsRoutes(app: FastifyInstance, container: Container): Promise<void> {\n  const r = app.withTypeProvider<ZodTypeProvider>();\n  const automations = container.automations;\n  const tags = ['Automations'];\n\n  r.route({\n    method: 'GET',\n    url: '/api/automations',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'listAutomations',\n      tags,\n      summary: 'List automations, optionally only workflows or only webhooks',\n      querystring: AutomationsQuery,\n      response: { 200: z.array(Automation) },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      return automations.list(scope.orgId, req.query);\n    },\n  });\n\n  // Before `/api/automations/:id` — otherwise `:id` would swallow these path segments.\n  r.route({\n    method: 'GET',\n    url: '/api/automations/actions',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'listAutomationActions',\n      tags,\n      summary: 'List the actions automations can use',\n      response: { 200: z.array(AvailableAction) },\n    },\n    handler: async (req) => {\n      await resolveScope(container, req);\n      return automations.availableActions();\n    },\n  });\n\n  r.route({\n    method: 'GET',\n    url: '/api/automations/triggers',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'listAutomationTriggers',\n      tags,\n      summary: 'List the domain events automations can react to',\n      response: { 200: AvailableTriggers },\n    },\n    handler: async (req) => {\n      await resolveScope(container, req);\n      return automations.availableTriggers();\n    },\n  });\n\n  r.route({\n    method: 'POST',\n    url: '/api/automations',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'createAutomation',\n      tags,\n      summary: 'Create a workflow automation',\n      body: CreateAutomationBody,\n      response: { 201: Automation },\n    },\n    handler: async (req, reply) => {\n      const scope = await resolveScope(container, req);\n      const automation = await automations.create(scope.orgId, req.body);\n      return reply.code(201).send(automation);\n    },\n  });\n\n  r.route({\n    method: 'GET',\n    url: '/api/automations/:id',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'getAutomation',\n      tags,\n      summary: 'Get an automation by id',\n      params: AutomationIdParam,\n      response: { 200: Automation, 404: ErrorBody },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      const automation = await automations.get(scope.orgId, req.params.id);\n      if (!automation) {\n        throw new NotFoundError('Automation', req.params.id);\n      }\n      return automation;\n    },\n  });\n\n  r.route({\n    method: 'PATCH',\n    url: '/api/automations/:id',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'updateAutomation',\n      tags,\n      summary: 'Update a workflow automation (webhooks change through the webhook endpoints)',\n      params: AutomationIdParam,\n      body: UpdateAutomationBody,\n      response: { 200: Automation, 404: ErrorBody, 409: ErrorBody },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      const automation = await automations.update(scope.orgId, req.params.id, req.body);\n      if (!automation) {\n        throw new NotFoundError('Automation', req.params.id);\n      }\n      return automation;\n    },\n  });\n\n  r.route({\n    method: 'DELETE',\n    url: '/api/automations/:id',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'deleteAutomation',\n      tags,\n      summary: 'Delete a workflow automation (webhooks are deleted through the webhook endpoints)',\n      params: AutomationIdParam,\n      response: { 204: z.void(), 404: ErrorBody, 409: ErrorBody },\n    },\n    handler: async (req, reply) => {\n      const scope = await resolveScope(container, req);\n      const deleted = await automations.delete(scope.orgId, req.params.id);\n      if (!deleted) {\n        throw new NotFoundError('Automation', req.params.id);\n      }\n      return reply.code(204).send();\n    },\n  });\n\n  r.route({\n    method: 'GET',\n    url: '/api/automations/:id/runs',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'listAutomationRuns',\n      tags,\n      summary:\n        \"List an automation's runs — a deleted automation's runs remain reachable (audit trail)\",\n      params: AutomationIdParam,\n      querystring: AutomationRunsQuery,\n      response: { 200: AutomationRunsPage },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      // No existence pre-check: runs deliberately survive automation deletion (audit trail).\n      return automations.listRuns(scope.orgId, req.params.id, req.query);\n    },\n  });\n\n  r.route({\n    method: 'POST',\n    url: '/api/automations/:id/runs/:runId/rerun',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'rerunAutomationRun',\n      tags,\n      summary: 'Run a finished run again',\n      description:\n        \"Dispatches the same run again with the automation's current steps; the new outcome replaces the run's previous one. For a webhook this resends the delivery to its current URL. A run that is still running can't be rerun (409).\",\n      params: AutomationRunParams,\n      response: { 200: AutomationRun, 404: ErrorBody, 409: ErrorBody },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      return automations.rerun(scope.orgId, req.params.id, req.params.runId);\n    },\n  });\n}\n"],"mappings":"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"}
+{"version":3,"file":"automations.js","names":[],"sources":["../../../src/http/routes/automations.ts"],"sourcesContent":["// HTTP routes for the automations context: rules that match a trigger (a\n// domain event type) against enabled automations and run an ordered list of\n// actions, plus the run history each automation accumulates.\nimport type { FastifyInstance } from 'fastify';\nimport { z } from 'zod';\nimport type { ZodTypeProvider } from 'fastify-type-provider-zod';\nimport {\n  Automation,\n  AutomationIdParam,\n  AutomationRun,\n  AutomationRunParams,\n  AutomationRunsPage,\n  AutomationRunsQuery,\n  AutomationsQuery,\n  AvailableAction,\n  AvailableTriggers,\n  CreateAutomationBody,\n  UpdateAutomationBody,\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 automationsRoutes(app: FastifyInstance, container: Container): Promise<void> {\n  const r = app.withTypeProvider<ZodTypeProvider>();\n  const automations = container.automations;\n  const tags = ['Automations'];\n\n  r.route({\n    method: 'GET',\n    url: '/api/automations',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'listAutomations',\n      tags,\n      summary: 'List automations (staff)',\n      description:\n        'Staff only (owner, admin, instructor). Optionally only workflows or only webhooks.',\n      querystring: AutomationsQuery,\n      response: { 200: z.array(Automation), ...refusals(403) },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      return automations.list(scope.orgId, req.query);\n    },\n  });\n\n  // Before `/api/automations/:id` — otherwise `:id` would swallow these path segments.\n  r.route({\n    method: 'GET',\n    url: '/api/automations/actions',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'listAutomationActions',\n      tags,\n      summary: 'List the actions automations can use (staff)',\n      description: 'Staff only (owner, admin, instructor).',\n      response: { 200: z.array(AvailableAction), ...refusals(403) },\n    },\n    handler: async (req) => {\n      await resolveScope(container, req);\n      return automations.availableActions();\n    },\n  });\n\n  r.route({\n    method: 'GET',\n    url: '/api/automations/triggers',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'listAutomationTriggers',\n      tags,\n      summary: 'List the domain events automations can react to (staff)',\n      description: 'Staff only (owner, admin, instructor).',\n      response: { 200: AvailableTriggers, ...refusals(403) },\n    },\n    handler: async (req) => {\n      await resolveScope(container, req);\n      return automations.availableTriggers();\n    },\n  });\n\n  r.route({\n    method: 'POST',\n    url: '/api/automations',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'createAutomation',\n      tags,\n      summary: 'Create a workflow automation (staff)',\n      description:\n        'Staff only (owner, admin, instructor). 400 when a trigger is reserved, not an event the system emits or an unsupported schedule, or an action is reserved for webhooks or no longer available.',\n      body: CreateAutomationBody,\n      response: { 201: Automation, ...refusals(400, 403) },\n    },\n    handler: async (req, reply) => {\n      const scope = await resolveScope(container, req);\n      const automation = await automations.create(scope.orgId, req.body);\n      return reply.code(201).send(automation);\n    },\n  });\n\n  r.route({\n    method: 'GET',\n    url: '/api/automations/:id',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'getAutomation',\n      tags,\n      summary: 'Get an automation (staff)',\n      description: 'Staff only (owner, admin, instructor). Workflows and webhooks alike.',\n      params: AutomationIdParam,\n      response: { 200: Automation, ...refusals(403, 404) },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      const automation = await automations.get(scope.orgId, req.params.id);\n      if (!automation) {\n        throw new NotFoundError('Automation', req.params.id);\n      }\n      return automation;\n    },\n  });\n\n  r.route({\n    method: 'PATCH',\n    url: '/api/automations/:id',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'updateAutomation',\n      tags,\n      summary: 'Update a workflow automation (staff)',\n      description:\n        'Staff only (owner, admin, instructor). Webhooks change through the webhook endpoints (409). 400 when a trigger is reserved, not an event the system emits or an unsupported schedule, or an action is reserved for webhooks or no longer available.',\n      params: AutomationIdParam,\n      body: UpdateAutomationBody,\n      response: { 200: Automation, ...refusals(400, 403, 404, 409) },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      const automation = await automations.update(scope.orgId, req.params.id, req.body);\n      if (!automation) {\n        throw new NotFoundError('Automation', req.params.id);\n      }\n      return automation;\n    },\n  });\n\n  r.route({\n    method: 'DELETE',\n    url: '/api/automations/:id',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'deleteAutomation',\n      tags,\n      summary: 'Delete a workflow automation (staff)',\n      description:\n        'Staff only (owner, admin, instructor). Webhooks are deleted through the webhook endpoints (409). Its runs stay readable.',\n      params: AutomationIdParam,\n      response: { 204: z.void(), ...refusals(403, 404, 409) },\n    },\n    handler: async (req, reply) => {\n      const scope = await resolveScope(container, req);\n      const deleted = await automations.delete(scope.orgId, req.params.id);\n      if (!deleted) {\n        throw new NotFoundError('Automation', req.params.id);\n      }\n      return reply.code(204).send();\n    },\n  });\n\n  r.route({\n    method: 'GET',\n    url: '/api/automations/:id/runs',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'listAutomationRuns',\n      tags,\n      summary: \"List an automation's runs (staff)\",\n      description:\n        \"Staff only (owner, admin, instructor). A deleted automation's runs remain reachable as an audit trail, so an unknown id answers an empty page rather than 404. A run's event carries the fields a webhook delivery of that event would.\",\n      params: AutomationIdParam,\n      querystring: AutomationRunsQuery,\n      response: { 200: AutomationRunsPage, ...refusals(403) },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      // No existence pre-check: runs deliberately survive automation deletion (audit trail).\n      return automations.listRuns(scope.orgId, req.params.id, req.query);\n    },\n  });\n\n  r.route({\n    method: 'POST',\n    url: '/api/automations/:id/runs/:runId/rerun',\n    preHandler: app.requireOrgSession,\n    schema: {\n      operationId: 'rerunAutomationRun',\n      tags,\n      summary: 'Run a finished run again (staff)',\n      description:\n        \"Staff only (owner, admin, instructor). Dispatches the same run again with the automation's current steps; the new outcome replaces the run's previous one. For a webhook this resends the delivery to its current URL. A run that is still running can't be rerun (409).\",\n      params: AutomationRunParams,\n      response: { 200: AutomationRun, ...refusals(403, 404, 409) },\n    },\n    handler: async (req) => {\n      const scope = await resolveScope(container, req);\n      return automations.rerun(scope.orgId, req.params.id, req.params.runId);\n    },\n  });\n}\n"],"mappings":"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"}

package/dist/http/routes/bundles.js

@@ -1,9 +1,9 @@
+import { refusals } from "../schemas/shared.js";
 import { resolveScope } from "../scope.js";
-import { ErrorBody } from "../schemas/shared.js";
 import { AddBundleItem, Bundle, BundleIdParam, BundleItem, BundleItemParams, BundlesPage, BundlesQuery, CreateBundle, UpdateBundle } from "../schemas/bundles.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/bundles.ts
 async function bundlesRoutes(app, container) {
 	const r = app.withTypeProvider();
@@ -15,9 +15,13 @@ async function bundlesRoutes(app, container) {
 		schema: {
 			operationId: "listBundles",
 			tags: ["Content"],
-			summary: "List bundles",
+			summary: "List bundles (staff)",
+			description: "Staff only (owner, admin, instructor).",
 			querystring: BundlesQuery,
-			response: { 200: BundlesPage }
+			response: {
+				200: BundlesPage,
+				...refusals(403)
+			}
 		},
 		handler: async (req) => {
 			const scope = await resolveScope(container, req);
@@ -31,11 +35,12 @@ async function bundlesRoutes(app, container) {
 		schema: {
 			operationId: "getBundle",
 			tags: ["Content"],
-			summary: "Get a bundle by id",
+			summary: "Get a bundle (staff)",
+			description: "Staff only (owner, admin, instructor).",
 			params: BundleIdParam,
 			response: {
 				200: Bundle,
-				404: ErrorBody
+				...refusals(403, 404)
 			}
 		},
 		handler: async (req) => {
@@ -52,11 +57,12 @@ async function bundlesRoutes(app, container) {
 		schema: {
 			operationId: "createBundle",
 			tags: ["Content"],
-			summary: "Create a bundle, optionally with initial content",
+			summary: "Create a bundle, optionally with initial content (staff)",
+			description: "Staff only (owner, admin, instructor). 404 when an initial content id is unknown.",
 			body: CreateBundle,
 			response: {
 				201: Bundle,
-				404: ErrorBody
+				...refusals(403, 404)
 			}
 		},
 		handler: async (req, reply) => {
@@ -72,12 +78,13 @@ async function bundlesRoutes(app, container) {
 		schema: {
 			operationId: "updateBundle",
 			tags: ["Content"],
-			summary: "Update a bundle",
+			summary: "Rename a bundle (staff)",
+			description: "Staff only (owner, admin, instructor).",
 			params: BundleIdParam,
 			body: UpdateBundle,
 			response: {
 				200: Bundle,
-				404: ErrorBody
+				...refusals(403, 404)
 			}
 		},
 		handler: async (req) => {
@@ -92,11 +99,12 @@ async function bundlesRoutes(app, container) {
 		schema: {
 			operationId: "deleteBundle",
 			tags: ["Content"],
-			summary: "Delete a bundle (its content survives)",
+			summary: "Delete a bundle (staff)",
+			description: "Staff only (owner, admin, instructor). Its content survives; access granted through the bundle ends.",
 			params: BundleIdParam,
 			response: {
 				204: z.void(),
-				404: ErrorBody
+				...refusals(403, 404)
 			}
 		},
 		handler: async (req, reply) => {
@@ -112,11 +120,12 @@ async function bundlesRoutes(app, container) {
 		schema: {
 			operationId: "listBundleItems",
 			tags: ["Content"],
-			summary: "List a bundle's content items",
+			summary: "List a bundle's content (staff)",
+			description: "Staff only (owner, admin, instructor).",
 			params: BundleIdParam,
 			response: {
 				200: z.array(BundleItem),
-				404: ErrorBody
+				...refusals(403)
 			}
 		},
 		handler: async (req) => {
@@ -131,12 +140,13 @@ async function bundlesRoutes(app, container) {
 		schema: {
 			operationId: "addBundleItem",
 			tags: ["Content"],
-			summary: "Add a content item to a bundle",
+			summary: "Add content to a bundle (staff)",
+			description: "Staff only (owner, admin, instructor). Everyone who holds the bundle can open the content from then on. Returns the bundle's content.",
 			params: BundleIdParam,
 			body: AddBundleItem,
 			response: {
 				200: z.array(BundleItem),
-				404: ErrorBody
+				...refusals(403, 404)
 			}
 		},
 		handler: async (req) => {
@@ -151,11 +161,12 @@ async function bundlesRoutes(app, container) {
 		schema: {
 			operationId: "removeBundleItem",
 			tags: ["Content"],
-			summary: "Remove a content item from a bundle (the content survives)",
+			summary: "Remove content from a bundle (staff)",
+			description: "Staff only (owner, admin, instructor). The content survives; access to it through the bundle ends. Returns the bundle's content.",
 			params: BundleItemParams,
 			response: {
 				200: z.array(BundleItem),
-				404: ErrorBody
+				...refusals(403, 404)
 			}
 		},
 		handler: async (req) => {