partial: annotate rest of admin routes

server/api/v1/admin/index.get.ts

@@ -1,5 +1,8 @@
 import aclManager from "~/server/internal/acls";
 
+/**
+ * Check if we are an admin/system
+ */
 export default defineEventHandler(async (h3) => {
   const allowed = await aclManager.allowSystemACL(h3, []);
   if (!allowed) return false;

server/api/v1/admin/library/index.get.ts

@@ -1,6 +1,9 @@
 import aclManager from "~/server/internal/acls";
 import libraryManager from "~/server/internal/library";
 
+/**
+ * Fetch library data for admin UI
+ */
 export default defineEventHandler(async (h3) => {
   const allowed = await aclManager.allowSystemACL(h3, ["library:read"]);
   if (!allowed) throw createError({ statusCode: 403 });

server/api/v1/admin/library/sources/index.delete.ts

@@ -8,6 +8,9 @@ const DeleteLibrarySource = type({
   id: "string",
 }).configure(throwingArktype);
 
+/**
+ * Delete a given library source
+ */
 export default defineEventHandler<{ body: typeof DeleteLibrarySource.infer }>(
   async (h3) => {
     const allowed = await aclManager.allowSystemACL(h3, [

server/api/v1/admin/library/sources/index.get.ts

@@ -4,6 +4,9 @@ import libraryManager from "~/server/internal/library";
 
 export type WorkingLibrarySource = LibraryModel & { working: boolean };
 
+/**
+ * Fetch all library sources on this instance
+ */
 export default defineEventHandler(async (h3) => {
   const allowed = await aclManager.allowSystemACL(h3, [
     "library:sources:read",

server/api/v1/admin/library/sources/index.patch.ts

@@ -12,6 +12,9 @@ const UpdateLibrarySource = type({
   options: "object",
 }).configure(throwingArktype);
 
+/**
+ * Update a library source's options. Validates options and live-updates the source.
+ */
 export default defineEventHandler<{ body: typeof UpdateLibrarySource.infer }>(
   async (h3) => {
     const allowed = await aclManager.allowSystemACL(h3, [

server/api/v1/admin/library/sources/index.post.ts

@@ -14,6 +14,9 @@ const CreateLibrarySource = type({
   options: "object",
 }).configure(throwingArktype);
 
+/**
+ * Create a new library source with options
+ */
 export default defineEventHandler<{ body: typeof CreateLibrarySource.infer }>(
   async (h3) => {
     const allowed = await aclManager.allowSystemACL(h3, [

server/api/v1/admin/news/[id]/index.delete.ts

@@ -2,6 +2,10 @@ import { defineEventHandler, createError } from "h3";
 import aclManager from "~/server/internal/acls";
 import newsManager from "~/server/internal/news";
 
+/**
+ * Delete a news article
+ * @param id Article ID
+ */
 export default defineEventHandler(async (h3) => {
   const allowed = await aclManager.allowSystemACL(h3, ["news:delete"]);
   if (!allowed)

server/api/v1/admin/news/[id]/index.get.ts

@@ -2,6 +2,10 @@ import { defineEventHandler, createError } from "h3";
 import aclManager from "~/server/internal/acls";
 import newsManager from "~/server/internal/news";
 
+/**
+ * Fetch a single news article
+ * @param id Article ID
+ */
 export default defineEventHandler(async (h3) => {
   const allowed = await aclManager.allowSystemACL(h3, ["news:read"]);
   if (!allowed)

server/api/v1/admin/news/index.get.ts

@@ -2,6 +2,9 @@ import { defineEventHandler, getQuery } from "h3";
 import aclManager from "~/server/internal/acls";
 import newsManager from "~/server/internal/news";
 
+/**
+ * Fetch all news articles.
+ */
 export default defineEventHandler(async (h3) => {
   const allowed = await aclManager.allowSystemACL(h3, ["news:read"]);
   if (!allowed)

server/api/v1/admin/news/index.post.ts

@@ -11,51 +11,56 @@ const CreateNews = type({
   tags: "string = '[]'",
 });
 
-export default defineEventHandler(async (h3) => {
-  const allowed = await aclManager.allowSystemACL(h3, ["news:create"]);
-  if (!allowed) throw createError({ statusCode: 403 });
+/**
+ * Create a new news article
+ */
+export default defineEventHandler<{ body: typeof CreateNews.infer }>(
+  async (h3) => {
+    const allowed = await aclManager.allowSystemACL(h3, ["news:create"]);
+    if (!allowed) throw createError({ statusCode: 403 });
 
-  const form = await readMultipartFormData(h3);
-  if (!form)
-    throw createError({
-      statusCode: 400,
-      statusMessage: "This endpoint requires multipart form data.",
+    const form = await readMultipartFormData(h3);
+    if (!form)
+      throw createError({
+        statusCode: 400,
+        statusMessage: "This endpoint requires multipart form data.",
+      });
+
+    const uploadResult = await handleFileUpload(h3, {}, ["internal:read"], 1);
+    if (!uploadResult)
+      throw createError({
+        statusCode: 400,
+        statusMessage: "Failed to upload file",
+      });
+
+    const [imageIds, options, pull, _dump] = uploadResult;
+
+    const body = await CreateNews(options);
+    if (body instanceof ArkErrors)
+      throw createError({ statusCode: 400, statusMessage: body.summary });
+
+    const parsedTags = JSON.parse(body.tags);
+    if (typeof parsedTags !== "object" || !Array.isArray(parsedTags))
+      throw createError({
+        statusCode: 400,
+        statusMessage: "Tags must be an array",
+      });
+
+    const imageId = imageIds.at(0);
+
+    const article = await newsManager.create({
+      title: body.title,
+      description: body.description,
+      content: body.content,
+
+      tags: parsedTags,
+
+      ...(imageId && { imageObjectId: imageId }),
+      authorId: "system",
     });
 
-  const uploadResult = await handleFileUpload(h3, {}, ["internal:read"], 1);
-  if (!uploadResult)
-    throw createError({
-      statusCode: 400,
-      statusMessage: "Failed to upload file",
-    });
+    await pull();
 
-  const [imageIds, options, pull, _dump] = uploadResult;
-
-  const body = await CreateNews(options);
-  if (body instanceof ArkErrors)
-    throw createError({ statusCode: 400, statusMessage: body.summary });
-
-  const parsedTags = JSON.parse(body.tags);
-  if (typeof parsedTags !== "object" || !Array.isArray(parsedTags))
-    throw createError({
-      statusCode: 400,
-      statusMessage: "Tags must be an array",
-    });
-
-  const imageId = imageIds.at(0);
-
-  const article = await newsManager.create({
-    title: body.title,
-    description: body.description,
-    content: body.content,
-
-    tags: parsedTags,
-
-    ...(imageId && { imageObjectId: imageId }),
-    authorId: "system",
-  });
-
-  await pull();
-
-  return article;
-});
+    return article;
+  },
+);

server/api/v1/admin/settings/dummy-data.get.ts

@@ -1,6 +1,9 @@
 import aclManager from "~/server/internal/acls";
 import prisma from "~/server/internal/db/database";
 
+/**
+ * Fetch dummy data for rendering the settings page.
+ */
 export default defineEventHandler(async (h3) => {
   const allowed = await aclManager.getUserACL(h3, ["settings:read"]);
   if (!allowed) throw createError({ statusCode: 403 });

server/api/v1/admin/settings/index.patch.ts

@@ -8,6 +8,9 @@ const UpdateSettings = type({
   showGamePanelTextDecoration: "boolean",
 });
 
+/**
+ * Update global Drop settings.
+ */
 export default defineEventHandler<{ body: typeof UpdateSettings.infer }>(
   async (h3) => {
     const allowed = await aclManager.allowSystemACL(h3, ["settings:update"]);

server/api/v1/admin/tags/[id]/index.delete.ts

@@ -2,9 +2,8 @@ import aclManager from "~/server/internal/acls";
 import prisma from "~/server/internal/db/database";
 
 /**
- * This route allows you to delete game organization tags.
- * 
- * @param {string} id test
+ * Delete game tags.
+ * @param id Tag ID
  */
 export default defineEventHandler(async (h3) => {
   const allowed = await aclManager.allowSystemACL(h3, ["tags:delete"]);

server/api/v1/admin/tags/index.get.ts

@@ -1,6 +1,9 @@
 import aclManager from "~/server/internal/acls";
 import prisma from "~/server/internal/db/database";
 
+/**
+ * Fetch all game tags
+ */
 export default defineEventHandler(async (h3) => {
   const allowed = await aclManager.allowSystemACL(h3, ["tags:read"]);
   if (!allowed) throw createError({ statusCode: 403 });

server/api/v1/admin/tags/index.post.ts

@@ -7,16 +7,21 @@ const CreateTag = type({
   name: "string",
 }).configure(throwingArktype);
 
-export default defineEventHandler(async (h3) => {
-  const allowed = await aclManager.allowSystemACL(h3, ["tags:read"]);
-  if (!allowed) throw createError({ statusCode: 403 });
+/**
+ * Create a game tag
+ */
+export default defineEventHandler<{ body: typeof CreateTag.infer }>(
+  async (h3) => {
+    const allowed = await aclManager.allowSystemACL(h3, ["tags:read"]);
+    if (!allowed) throw createError({ statusCode: 403 });
 
-  const body = await readDropValidatedBody(h3, CreateTag);
+    const body = await readDropValidatedBody(h3, CreateTag);
 
-  const tag = await prisma.gameTag.create({
-    data: {
-      ...body,
-    },
-  });
-  return tag;
-});
+    const tag = await prisma.gameTag.create({
+      data: {
+        ...body,
+      },
+    });
+    return tag;
+  },
+);

server/api/v1/admin/task/index.get.ts

@@ -2,6 +2,9 @@ import aclManager from "~/server/internal/acls";
 import prisma from "~/server/internal/db/database";
 import taskHandler from "~/server/internal/tasks";
 
+/**
+ * Fetches all tasks that the current token has access to (ACL-based)
+ */
 export default defineEventHandler(async (h3) => {
   const allowed = await aclManager.allowSystemACL(h3, ["task:read"]);
   if (!allowed) throw createError({ statusCode: 403 });

server/api/v1/admin/users/[id]/index.delete.ts

@@ -2,6 +2,10 @@ import { defineEventHandler, createError } from "h3";
 import aclManager from "~/server/internal/acls";
 import prisma from "~/server/internal/db/database";
 
+/**
+ * Delete a user
+ * @param id User ID
+ */
 export default defineEventHandler(async (h3) => {
   const allowed = await aclManager.allowSystemACL(h3, ["user:delete"]);
   if (!allowed)

server/api/v1/admin/users/[id]/index.get.ts

@@ -1,6 +1,10 @@
 import aclManager from "~/server/internal/acls";
 import prisma from "~/server/internal/db/database";
 
+/**
+ * Fetch a user by ID
+ * @param id User ID
+ */
 export default defineEventHandler(async (h3) => {
   const allowed = await aclManager.allowSystemACL(h3, ["user:read"]);
   if (!allowed) throw createError({ statusCode: 403 });

server/api/v1/admin/users/index.get.ts

@@ -1,6 +1,9 @@
 import aclManager from "~/server/internal/acls";
 import prisma from "~/server/internal/db/database";
 
+/**
+ * Fetch all users and their enabled authentication mechanisms
+ */
 export default defineEventHandler(async (h3) => {
   const allowed = await aclManager.allowSystemACL(h3, ["user:read"]);
   if (!allowed) throw createError({ statusCode: 403 });