partial: admin import annotations

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

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

server/api/v1/admin/import/game/index.post.ts

@@ -14,6 +14,10 @@ const ImportGameBody = type({
   },
 }).configure(throwingArktype);
 
+/**
+ * Import a game as a background task.
+ * @response Task IDs can be used with the websocket endpoint /api/v1/task
+ */
 export default defineEventHandler<{ body: typeof ImportGameBody.infer }>(
   async (h3) => {
     const allowed = await aclManager.allowSystemACL(h3, ["import:game:new"]);

server/api/v1/admin/import/game/search.get.ts

@@ -1,16 +1,28 @@
+import { ArkErrors, type } from "arktype";
 import aclManager from "~/server/internal/acls";
 import metadataHandler from "~/server/internal/metadata";
 
-export default defineEventHandler(async (h3) => {
+const SearchGame = type({
+  q: "string",
+});
+
+/**
+ * Search metadata providers for a query. Results can be used to import a game with metadata.
+ */
+export default defineEventHandler<{ query: typeof SearchGame.infer }>(
+  async (h3) => {
     const allowed = await aclManager.allowSystemACL(h3, ["import:game:read"]);
     if (!allowed) throw createError({ statusCode: 403 });
 
     const query = getQuery(h3);
-  const search = query.q?.toString();
+    const search = SearchGame(query);
-  if (!search)
+    if (search instanceof ArkErrors)
-    throw createError({ statusCode: 400, statusMessage: "Invalid search" });
+      throw createError({
+        statusCode: 400,
+        statusMessage: "Invalid search: " + search.summary,
+      });
 
-  const results = await metadataHandler.search(search);
+    const results = await metadataHandler.search(search.q);
 
     if (results.length == 0)
       throw createError({
@@ -19,4 +31,5 @@ export default defineEventHandler(async (h3) => {
       });
 
     return results;
-});
+  },
+);

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

@@ -1,19 +1,28 @@
+import { ArkErrors, type } from "arktype";
 import aclManager from "~/server/internal/acls";
 import prisma from "~/server/internal/db/database";
 import libraryManager from "~/server/internal/library";
 
-export default defineEventHandler(async (h3) => {
+const Query = type({
+  id: "string",
+});
+
+/**
+ *  Fetch all versions available for import for a game (`id` in query params).
+ */
+export default defineEventHandler<{ query: typeof Query.infer }>(async (h3) => {
   const allowed = await aclManager.allowSystemACL(h3, ["import:version:read"]);
   if (!allowed) throw createError({ statusCode: 403 });
 
-  const query = await getQuery(h3);
+  const query = Query(await getQuery(h3));
-  const gameId = query.id?.toString();
+  if (query instanceof ArkErrors)
-  if (!gameId)
     throw createError({
       statusCode: 400,
-      statusMessage: "Missing id in request params",
+      statusMessage: "Invalid query params: " + query.summary,
     });
 
+  const gameId = query.id;
+
   const game = await prisma.game.findUnique({
     where: { id: gameId },
     select: { libraryId: true, libraryPath: true },

server/api/v1/admin/import/version/index.post.ts

@@ -19,7 +19,11 @@ const ImportVersion = type({
   umuId: "string = ''",
 }).configure(throwingArktype);
 
-export default defineEventHandler(async (h3) => {
+/**
+ * Import a version for a game.
+ */
+export default defineEventHandler<{ body: typeof ImportVersion.infer }>(
+  async (h3) => {
     const allowed = await aclManager.allowSystemACL(h3, ["import:version:new"]);
     if (!allowed) throw createError({ statusCode: 403 });
 
@@ -38,7 +42,10 @@ export default defineEventHandler(async (h3) => {
 
     const platformParsed = parsePlatform(platform);
     if (!platformParsed)
-    throw createError({ statusCode: 400, statusMessage: "Invalid platform." });
+      throw createError({
+        statusCode: 400,
+        statusMessage: "Invalid platform.",
+      });
 
     if (delta) {
       const validOverlayVersions = await prisma.gameVersion.count({
@@ -62,7 +69,8 @@ export default defineEventHandler(async (h3) => {
       if (!delta && !launch)
         throw createError({
           statusCode: 400,
-        statusMessage: "Launch executable is required for non-update versions",
+          statusMessage:
+            "Launch executable is required for non-update versions",
         });
     }
 
@@ -86,4 +94,5 @@ export default defineEventHandler(async (h3) => {
       });
 
     return { taskId: taskId };
-});
+  },
+);

server/api/v1/admin/import/version/preload.get.ts

@@ -1,18 +1,27 @@
+import { ArkErrors, type } from "arktype";
 import aclManager from "~/server/internal/acls";
 import libraryManager from "~/server/internal/library";
 
-export default defineEventHandler(async (h3) => {
+const Query = type({
+  id: "string",
+  version: "string",
+});
+
+/**
+ * Fetch recommendations for version import.
+ */
+export default defineEventHandler<{ query: typeof Query.infer }>(async (h3) => {
   const allowed = await aclManager.allowSystemACL(h3, ["import:version:read"]);
   if (!allowed) throw createError({ statusCode: 403 });
 
-  const query = await getQuery(h3);
+  const query = Query(await getQuery(h3));
-  const gameId = query.id?.toString();
+  if (query instanceof ArkErrors)
-  const versionName = query.version?.toString();
-  if (!gameId || !versionName)
     throw createError({
       statusCode: 400,
-      statusMessage: "Missing id or version in request params",
+      statusMessage: "Invalid query: " + query.summary,
     });
+  const gameId = query.id;
+  const versionName = query.version;
 
   const preload = await libraryManager.fetchUnimportedVersionInformation(
     gameId,