feat: annotated client routes

server/api/v1/client/auth/callback/index.post.ts

@@ -1,30 +1,41 @@
+import { type } from "arktype";
+import { readDropValidatedBody, throwingArktype } from "~/server/arktype";
+import aclManager from "~/server/internal/acls";
 import clientHandler from "~/server/internal/clients/handler";
-import sessionHandler from "~/server/internal/session";
 
-export default defineEventHandler(async (h3) => {
+const AuthorizeBody = type({
-  const user = await sessionHandler.getSession(h3);
+  id: "string",
-  if (!user) throw createError({ statusCode: 403 });
+}).configure(throwingArktype);
 
-  const body = await readBody(h3);
+/**
-  const clientId = await body.id;
+ * Finalize the authorization for a client
+ */
+export default defineEventHandler<{ body: typeof AuthorizeBody.infer }>(
+  async (h3) => {
+    const userId = await aclManager.getUserIdACL(h3, []);
+    if (!userId) throw createError({ statusCode: 403 });
 
-  const client = await clientHandler.fetchClient(clientId);
+    const body = await readDropValidatedBody(h3, AuthorizeBody);
-  if (!client)
+    const clientId = body.id;
-    throw createError({
-      statusCode: 400,
-      statusMessage: "Invalid or expired client ID.",
-    });
 
-  if (client.userId != user.userId)
+    const client = await clientHandler.fetchClient(clientId);
-    throw createError({
+    if (!client)
-      statusCode: 403,
+      throw createError({
-      statusMessage: "Not allowed to authorize this client.",
+        statusCode: 400,
-    });
+        statusMessage: "Invalid or expired client ID.",
+      });
 
-  const token = await clientHandler.generateAuthToken(clientId);
+    if (client.userId != userId)
+      throw createError({
+        statusCode: 403,
+        statusMessage: "Not allowed to authorize this client.",
+      });
 
-  return {
+    const token = await clientHandler.generateAuthToken(clientId);
-    redirect: `drop://handshake/${clientId}/${token}`,
+
-    token: `${clientId}/${token}`,
+    return {
-  };
+      redirect: `drop://handshake/${clientId}/${token}`,
-});
+      token: `${clientId}/${token}`,
+    };
+  },
+);

server/api/v1/client/auth/code/index.get.ts

@@ -1,17 +1,22 @@
+import { ArkErrors, type } from "arktype";
+import aclManager from "~/server/internal/acls";
 import clientHandler from "~/server/internal/clients/handler";
-import sessionHandler from "~/server/internal/session";
 
-export default defineEventHandler(async (h3) => {
+const Query = type({
-  const user = await sessionHandler.getSession(h3);
+  code: "string.upper",
-  if (!user) throw createError({ statusCode: 403 });
+});
 
-  const query = getQuery(h3);
+/**
-  const code = query.code?.toString()?.toUpperCase();
+ * Fetch client ID by authorize code
-  if (!code)
+ */
-    throw createError({
+export default defineEventHandler<{ query: typeof Query.infer }>(async (h3) => {
-      statusCode: 400,
+  const userId = await aclManager.getUserIdACL(h3, []);
-      statusMessage: "Code required in query params.",
+  if (!userId) throw createError({ statusCode: 403 });
-    });
+
+  const query = Query(getQuery(h3));
+  if (query instanceof ArkErrors)
+    throw createError({ statusCode: 400, statusMessage: query.summary });
+  const code = query.code;
 
   const clientId = await clientHandler.fetchClientIdByCode(code);
   if (!clientId)

server/api/v1/client/auth/code/index.post.ts

@@ -1,35 +1,46 @@
+import { type } from "arktype";
+import { readDropValidatedBody, throwingArktype } from "~/server/arktype";
+import aclManager from "~/server/internal/acls";
 import clientHandler from "~/server/internal/clients/handler";
-import sessionHandler from "~/server/internal/session";
 
-export default defineEventHandler(async (h3) => {
+const CodeAuthorize = type({
-  const user = await sessionHandler.getSession(h3);
+  id: "string",
-  if (!user) throw createError({ statusCode: 403 });
+}).configure(throwingArktype);
 
-  const body = await readBody(h3);
+/**
-  const clientId = await body.id;
+ * Authorize code by client ID, and send token via WS to client
+ */
+export default defineEventHandler<{ body: typeof CodeAuthorize.infer }>(
+  async (h3) => {
+    const userId = await aclManager.getUserIdACL(h3, []);
+    if (!userId) throw createError({ statusCode: 403 });
 
-  const client = await clientHandler.fetchClient(clientId);
+    const body = await readDropValidatedBody(h3, CodeAuthorize);
-  if (!client)
+    const clientId = body.id;
-    throw createError({
-      statusCode: 400,
-      statusMessage: "Invalid or expired client ID.",
-    });
 
-  if (client.userId != user.userId)
+    const client = await clientHandler.fetchClient(clientId);
-    throw createError({
+    if (!client)
-      statusCode: 403,
+      throw createError({
-      statusMessage: "Not allowed to authorize this client.",
+        statusCode: 400,
-    });
+        statusMessage: "Invalid or expired client ID.",
+      });
 
-  if (!client.peer)
+    if (client.userId != userId)
-    throw createError({
+      throw createError({
-      statusCode: 500,
+        statusCode: 403,
-      statusMessage: "No client listening for authorization.",
+        statusMessage: "Not allowed to authorize this client.",
-    });
+      });
 
-  const token = await clientHandler.generateAuthToken(clientId);
+    if (!client.peer)
+      throw createError({
+        statusCode: 500,
+        statusMessage: "No client listening for authorization.",
+      });
 
-  await clientHandler.sendAuthToken(clientId, token);
+    const token = await clientHandler.generateAuthToken(clientId);
 
-  return;
+    await clientHandler.sendAuthToken(clientId, token);
-});
+
+    return;
+  },
+);

server/api/v1/client/auth/code/ws.get.ts

@@ -1,6 +1,10 @@
 import type { FetchError } from "ofetch";
 import clientHandler from "~/server/internal/clients/handler";
 
+/**
+ * Client route to listen for code authorization. 
+ * @request Pass the code in the `Authorization` header
+ */
 export default defineWebSocketHandler({
   async open(peer) {
     try {

server/api/v1/client/auth/handshake.post.ts

@@ -1,45 +1,52 @@
+import { type } from "arktype";
+import { readDropValidatedBody, throwingArktype } from "~/server/arktype";
 import clientHandler from "~/server/internal/clients/handler";
 import { useCertificateAuthority } from "~/server/plugins/ca";
 
-export default defineEventHandler(async (h3) => {
+const HandshakeBody = type({
-  const body = await readBody(h3);
+  clientId: "string",
-  const clientId = body.clientId;
+  token: "string",
-  const token = body.token;
+}).configure(throwingArktype);
-  if (!clientId || !token)
-    throw createError({
-      statusCode: 400,
-      statusMessage: "Missing token or client ID from body",
-    });
 
-  const metadata = await clientHandler.fetchClient(clientId);
+/**
-  if (!metadata)
+ * Client route to complete handshake, after the user has authorize it. 
-    throw createError({
+ */
-      statusCode: 403,
+export default defineEventHandler<{ body: typeof HandshakeBody.infer }>(
-      statusMessage: "Invalid client ID",
+  async (h3) => {
-    });
+    const body = await readDropValidatedBody(h3, HandshakeBody);
-  if (!metadata.authToken || !metadata.userId)
+    const clientId = body.clientId;
-    throw createError({
+    const token = body.token;
-      statusCode: 400,
-      statusMessage: "Un-authorized client ID",
-    });
-  if (metadata.authToken !== token)
-    throw createError({
-      statusCode: 403,
-      statusMessage: "Invalid token",
-    });
 
-  const certificateAuthority = useCertificateAuthority();
+    const metadata = await clientHandler.fetchClient(clientId);
-  const bundle = await certificateAuthority.generateClientCertificate(
+    if (!metadata)
-    clientId,
+      throw createError({
-    metadata.data.name,
+        statusCode: 403,
-  );
+        statusMessage: "Invalid client ID",
+      });
+    if (!metadata.authToken || !metadata.userId)
+      throw createError({
+        statusCode: 400,
+        statusMessage: "Un-authorized client ID",
+      });
+    if (metadata.authToken !== token)
+      throw createError({
+        statusCode: 403,
+        statusMessage: "Invalid token",
+      });
 
-  const client = await clientHandler.finialiseClient(clientId);
+    const certificateAuthority = useCertificateAuthority();
-  await certificateAuthority.storeClientCertificate(clientId, bundle);
+    const bundle = await certificateAuthority.generateClientCertificate(
+      clientId,
+      metadata.data.name,
+    );
 
-  return {
+    const client = await clientHandler.finialiseClient(clientId);
-    private: bundle.priv,
+    await certificateAuthority.storeClientCertificate(clientId, bundle);
-    certificate: bundle.cert,
+
-    id: client.id,
+    return {
-  };
+      private: bundle.priv,
-});
+      certificate: bundle.cert,
+      id: client.id,
+    };
+  },
+);

server/api/v1/client/auth/index.get.ts

@@ -1,17 +1,22 @@
+import { ArkErrors, type } from "arktype";
+import aclManager from "~/server/internal/acls";
 import clientHandler from "~/server/internal/clients/handler";
-import sessionHandler from "~/server/internal/session";
 
-export default defineEventHandler(async (h3) => {
+const Query = type({
-  const user = await sessionHandler.getSession(h3);
+  id: "string",
-  if (!user) throw createError({ statusCode: 403 });
+});
 
-  const query = getQuery(h3);
+/**
-  const providedClientId = query.id?.toString();
+ * Fetch details about an authorization request, and claim it for the current user
-  if (!providedClientId)
+ */
-    throw createError({
+export default defineEventHandler<{ query: typeof Query.infer }>(async (h3) => {
-      statusCode: 400,
+  const userId = await aclManager.getUserIdACL(h3, []);
-      statusMessage: "Provide client ID in request params as 'id'",
+  if (!userId) throw createError({ statusCode: 403 });
-    });
+
+  const query = Query(getQuery(h3));
+  if (query instanceof ArkErrors)
+    throw createError({ statusCode: 400, statusMessage: query.summary });
+  const providedClientId = query.id;
 
   const client = await clientHandler.fetchClient(providedClientId);
   if (!client)
@@ -20,13 +25,13 @@ export default defineEventHandler(async (h3) => {
       statusMessage: "Request not found.",
     });
 
-  if (client.userId && user.userId !== client.userId)
+  if (client.userId && userId !== client.userId)
     throw createError({
       statusCode: 400,
       statusMessage: "Client already claimed.",
     });
 
-  await clientHandler.attachUserId(providedClientId, user.userId);
+  await clientHandler.attachUserId(providedClientId, userId);
 
   return client.data;
 });

server/api/v1/client/auth/initiate.post.ts

@@ -17,55 +17,61 @@ const ClientAuthInitiate = type({
   mode: type.valueOf(AuthMode).default(AuthMode.Callback),
 }).configure(throwingArktype);
 
-export default defineEventHandler(async (h3) => {
+/**
-  const body = await readDropValidatedBody(h3, ClientAuthInitiate);
+ * Client route to initiate authorization flow. 
+ * @response The requested callback or code.
+ */
+export default defineEventHandler<{ body: typeof ClientAuthInitiate.infer }>(
+  async (h3) => {
+    const body = await readDropValidatedBody(h3, ClientAuthInitiate);
 
-  const platformRaw = body.platform;
+    const platformRaw = body.platform;
-  const capabilities: Partial<CapabilityConfiguration> =
+    const capabilities: Partial<CapabilityConfiguration> =
-    body.capabilities ?? {};
+      body.capabilities ?? {};
 
-  const platform = parsePlatform(platformRaw);
+    const platform = parsePlatform(platformRaw);
-  if (!platform)
+    if (!platform)
-    throw createError({
+      throw createError({
-      statusCode: 400,
+        statusCode: 400,
-      statusMessage: "Invalid or unsupported platform",
+        statusMessage: "Invalid or unsupported platform",
+      });
+
+    const capabilityIterable = Object.entries(capabilities) as Array<
+      [InternalClientCapability, object]
+    >;
+    if (
+      capabilityIterable.length > 0 &&
+      capabilityIterable
+        .map(([capability]) => validCapabilities.find((v) => capability == v))
+        .filter((e) => e).length == 0
+    )
+      throw createError({
+        statusCode: 400,
+        statusMessage: "Invalid capabilities.",
+      });
+
+    if (
+      capabilityIterable.length > 0 &&
+      capabilityIterable.filter(
+        ([capability, configuration]) =>
+          !capabilityManager.validateCapabilityConfiguration(
+            capability,
+            configuration,
+          ),
+      ).length > 0
+    )
+      throw createError({
+        statusCode: 400,
+        statusMessage: "Invalid capability configuration.",
+      });
+
+    const result = await clientHandler.initiate({
+      name: body.name,
+      platform,
+      capabilities,
+      mode: body.mode,
     });
 
-  const capabilityIterable = Object.entries(capabilities) as Array<
+    return result;
-    [InternalClientCapability, object]
+  },
-  >;
+);
-  if (
-    capabilityIterable.length > 0 &&
-    capabilityIterable
-      .map(([capability]) => validCapabilities.find((v) => capability == v))
-      .filter((e) => e).length == 0
-  )
-    throw createError({
-      statusCode: 400,
-      statusMessage: "Invalid capabilities.",
-    });
-
-  if (
-    capabilityIterable.length > 0 &&
-    capabilityIterable.filter(
-      ([capability, configuration]) =>
-        !capabilityManager.validateCapabilityConfiguration(
-          capability,
-          configuration,
-        ),
-    ).length > 0
-  )
-    throw createError({
-      statusCode: 400,
-      statusMessage: "Invalid capability configuration.",
-    });
-
-  const result = await clientHandler.initiate({
-    name: body.name,
-    platform,
-    capabilities,
-    mode: body.mode,
-  });
-
-  return result;
-});

server/api/v1/client/auth/session.post.ts

@@ -1 +0,0 @@
-export default defineEventHandler((_h3) => {});

server/api/v1/client/capability/index.post.ts

@@ -1,63 +0,0 @@
-import type { InternalClientCapability } from "~/server/internal/clients/capabilities";
-import capabilityManager, {
-  validCapabilities,
-} from "~/server/internal/clients/capabilities";
-import { defineClientEventHandler } from "~/server/internal/clients/event-handler";
-import notificationSystem from "~/server/internal/notifications";
-
-export default defineClientEventHandler(
-  async (h3, { clientId, fetchClient, fetchUser }) => {
-    const body = await readBody(h3);
-    const rawCapability = body.capability;
-    const configuration = body.configuration;
-
-    if (!rawCapability || typeof rawCapability !== "string")
-      throw createError({
-        statusCode: 400,
-        statusMessage: "capability must be a string",
-      });
-
-    if (!configuration || typeof configuration !== "object")
-      throw createError({
-        statusCode: 400,
-        statusMessage: "configuration must be an object",
-      });
-
-    const capability = rawCapability as InternalClientCapability;
-
-    if (!validCapabilities.includes(capability))
-      throw createError({
-        statusCode: 400,
-        statusMessage: "Invalid capability.",
-      });
-
-    const isValid = await capabilityManager.validateCapabilityConfiguration(
-      capability,
-      configuration,
-    );
-    if (!isValid)
-      throw createError({
-        statusCode: 400,
-        statusMessage: "Invalid capability configuration.",
-      });
-
-    await capabilityManager.upsertClientCapability(
-      capability,
-      configuration,
-      clientId,
-    );
-
-    const client = await fetchClient();
-    const user = await fetchUser();
-
-    await notificationSystem.push(user.id, {
-      nonce: `capability-${clientId}-${capability}`,
-      title: `"${client.name}" can now access ${capability}`,
-      description: `A device called "${client.name}" now has access to your ${capability}.`,
-      actions: ["Review|/account/devices"],
-      acls: ["user:clients:read"],
-    });
-
-    return {};
-  },
-);

server/api/v1/client/chunk.get.ts

@@ -1,3 +1,4 @@
+import { ArkErrors, type } from "arktype";
 import cacheHandler from "~/server/internal/cache";
 import { defineClientEventHandler } from "~/server/internal/clients/event-handler";
 import prisma from "~/server/internal/db/database";
@@ -10,74 +11,93 @@ const gameLookupCache = cacheHandler.createCache<{
   libraryPath: string;
 }>("downloadGameLookupCache");
 
-export default defineClientEventHandler(async (h3) => {
+const Query = type({
-  const query = getQuery(h3);
+  id: "string",
-  const gameId = query.id?.toString();
+  version: "string",
-  const versionName = query.version?.toString();
+  name: "string",
-  const filename = query.name?.toString();
+  chunk: "string.numeric.parse",
-  const chunkIndex = parseInt(query.chunk?.toString() ?? "?");
-
-  if (!gameId || !versionName || !filename || Number.isNaN(chunkIndex))
-    throw createError({
-      statusCode: 400,
-      statusMessage: "Invalid chunk arguments",
-    });
-
-  let game = await gameLookupCache.getItem(gameId);
-  if (!game) {
-    game = await prisma.game.findUnique({
-      where: {
-        id: gameId,
-      },
-      select: {
-        libraryId: true,
-        libraryPath: true,
-      },
-    });
-    if (!game || !game.libraryId)
-      throw createError({ statusCode: 400, statusMessage: "Invalid game ID" });
-
-    await gameLookupCache.setItem(gameId, game);
-  }
-
-  if (!game.libraryId)
-    throw createError({
-      statusCode: 500,
-      statusMessage: "Somehow, we got here.",
-    });
-
-  const peek = await libraryManager.peekFile(
-    game.libraryId,
-    game.libraryPath,
-    versionName,
-    filename,
-  );
-  if (!peek)
-    throw createError({ status: 400, statusMessage: "Failed to peek file" });
-
-  const start = chunkIndex * chunkSize;
-  const end = Math.min((chunkIndex + 1) * chunkSize, peek.size);
-  const currentChunkSize = end - start;
-  setHeader(h3, "Content-Length", currentChunkSize);
-
-  if (start >= end)
-    throw createError({
-      statusCode: 400,
-      statusMessage: "Invalid chunk index",
-    });
-
-  const gameReadStream = await libraryManager.readFile(
-    game.libraryId,
-    game.libraryPath,
-    versionName,
-    filename,
-    { start, end },
-  );
-  if (!gameReadStream)
-    throw createError({
-      statusCode: 400,
-      statusMessage: "Failed to create stream",
-    });
-
-  return sendStream(h3, gameReadStream);
 });
+
+/**
+ * v1 download API
+ * @deprecated
+ * @response Raw binary data (`application/octet-stream`)
+ */
+export default defineClientEventHandler<unknown, { query: typeof Query.infer }>(
+  async (h3) => {
+    const query = Query(getQuery(h3));
+    if (query instanceof ArkErrors)
+      throw createError({ statusCode: 400, statusMessage: query.summary });
+    const gameId = query.id;
+    const versionName = query.version;
+    const filename = query.name;
+    const chunkIndex = query.chunk;
+
+    if (!gameId || !versionName || !filename || Number.isNaN(chunkIndex))
+      throw createError({
+        statusCode: 400,
+        statusMessage: "Invalid chunk arguments",
+      });
+
+    let game = await gameLookupCache.getItem(gameId);
+    if (!game) {
+      game = await prisma.game.findUnique({
+        where: {
+          id: gameId,
+        },
+        select: {
+          libraryId: true,
+          libraryPath: true,
+        },
+      });
+      if (!game || !game.libraryId)
+        throw createError({
+          statusCode: 400,
+          statusMessage: "Invalid game ID",
+        });
+
+      await gameLookupCache.setItem(gameId, game);
+    }
+
+    if (!game.libraryId)
+      throw createError({
+        statusCode: 500,
+        statusMessage: "Somehow, we got here.",
+      });
+
+    const peek = await libraryManager.peekFile(
+      game.libraryId,
+      game.libraryPath,
+      versionName,
+      filename,
+    );
+    if (!peek)
+      throw createError({ status: 400, statusMessage: "Failed to peek file" });
+
+    const start = chunkIndex * chunkSize;
+    const end = Math.min((chunkIndex + 1) * chunkSize, peek.size);
+    const currentChunkSize = end - start;
+    setHeader(h3, "Content-Length", currentChunkSize);
+
+    if (start >= end)
+      throw createError({
+        statusCode: 400,
+        statusMessage: "Invalid chunk index",
+      });
+
+    const gameReadStream = await libraryManager.readFile(
+      game.libraryId,
+      game.libraryPath,
+      versionName,
+      filename,
+      { start, end },
+    );
+    if (!gameReadStream)
+      throw createError({
+        statusCode: 400,
+        statusMessage: "Failed to create stream",
+      });
+
+    return sendStream(h3, gameReadStream);
+  },
+);

server/api/v1/client/collection/[id]/entry.delete.ts

@@ -1,7 +1,17 @@
+import { type } from "arktype";
+import { throwingArktype } from "~/server/arktype";
 import { defineClientEventHandler } from "~/server/internal/clients/event-handler";
 import userLibraryManager from "~/server/internal/userlibrary";
 
-export default defineClientEventHandler(async (h3, { fetchUser }) => {
+const EntryRemove = type({
+  id: "string",
+}).configure(throwingArktype);
+
+/**
+ * Remove entry from user's collection
+ * @param id Collection ID
+ */
+export default defineClientEventHandler(async (h3, { fetchUser, body }) => {
   const user = await fetchUser();
 
   const id = getRouterParam(h3, "id");
@@ -11,10 +21,7 @@ export default defineClientEventHandler(async (h3, { fetchUser }) => {
       statusMessage: "ID required in route params",
     });
 
-  const body = await readBody(h3);
   const gameId = body.id;
-  if (!gameId)
-    throw createError({ statusCode: 400, statusMessage: "Game ID required" });
 
   const successful = await userLibraryManager.collectionRemove(
     gameId,
@@ -27,4 +34,4 @@ export default defineClientEventHandler(async (h3, { fetchUser }) => {
       statusMessage: "Collection not found",
     });
   return {};
-});
+}, EntryRemove);

server/api/v1/client/collection/[id]/entry.post.ts

@@ -1,7 +1,17 @@
+import { type } from "arktype";
+import { throwingArktype } from "~/server/arktype";
 import { defineClientEventHandler } from "~/server/internal/clients/event-handler";
 import userLibraryManager from "~/server/internal/userlibrary";
 
-export default defineClientEventHandler(async (h3, { fetchUser }) => {
+const AddEntry = type({
+  id: "string",
+}).configure(throwingArktype);
+
+/**
+ * Add entry to collection by game ID
+ * @param id Collection ID
+ */
+export default defineClientEventHandler(async (h3, { fetchUser, body }) => {
   const user = await fetchUser();
 
   const id = getRouterParam(h3, "id");
@@ -11,10 +21,7 @@ export default defineClientEventHandler(async (h3, { fetchUser }) => {
       statusMessage: "ID required in route params",
     });
 
-  const body = await readBody(h3);
   const gameId = body.id;
-  if (!gameId)
-    throw createError({ statusCode: 400, statusMessage: "Game ID required" });
 
   return await userLibraryManager.collectionAdd(gameId, id, user.id);
-});
+}, AddEntry);

server/api/v1/client/collection/[id]/index.delete.ts

@@ -1,15 +1,14 @@
 import { defineClientEventHandler } from "~/server/internal/clients/event-handler";
 import userLibraryManager from "~/server/internal/userlibrary";
 
+/**
+ * Delete collection by ID
+ * @param id Collection ID
+ */
 export default defineClientEventHandler(async (h3, { fetchUser }) => {
   const user = await fetchUser();
 
-  const id = getRouterParam(h3, "id");
+  const id = getRouterParam(h3, "id")!;
-  if (!id)
-    throw createError({
-      statusCode: 400,
-      statusMessage: "ID required in route params",
-    });
 
   // Verify collection exists and user owns it
   // Will not return the default collection
@@ -27,5 +26,5 @@ export default defineClientEventHandler(async (h3, { fetchUser }) => {
     });
 
   await userLibraryManager.deleteCollection(id);
-  return { success: true };
+  return;
 });

server/api/v1/client/collection/[id]/index.get.ts

@@ -1,15 +1,14 @@
 import { defineClientEventHandler } from "~/server/internal/clients/event-handler";
 import userLibraryManager from "~/server/internal/userlibrary";
 
+/**
+ * Fetch collection by ID
+ * @param id Collection ID
+ */
 export default defineClientEventHandler(async (h3, { fetchUser }) => {
   const user = await fetchUser();
 
-  const id = getRouterParam(h3, "id");
+  const id = getRouterParam(h3, "id")!;
-  if (!id)
-    throw createError({
-      statusCode: 400,
-      statusMessage: "ID required in route params",
-    });
 
   // Fetch specific collection
   // Will not return the default collection

server/api/v1/client/collection/default/entry.delete.ts

@@ -1,15 +1,20 @@
+import { type } from "arktype";
+import { throwingArktype } from "~/server/arktype";
 import { defineClientEventHandler } from "~/server/internal/clients/event-handler";
 import userLibraryManager from "~/server/internal/userlibrary";
 
-export default defineClientEventHandler(async (h3, { fetchUser }) => {
+const EntryDelete = type({
+  id: "string",
+}).configure(throwingArktype);
+
+/**
+ * Remove game from user's library
+ */
+export default defineClientEventHandler(async (h3, { fetchUser, body }) => {
   const user = await fetchUser();
 
-  const body = await readBody(h3);
-
   const gameId = body.id;
-  if (!gameId)
-    throw createError({ statusCode: 400, statusMessage: "Game ID required" });
 
   await userLibraryManager.libraryRemove(gameId, user.id);
   return {};
-});
+}, EntryDelete);

server/api/v1/client/collection/default/entry.post.ts

@@ -1,15 +1,21 @@
+import { type } from "arktype";
+import { throwingArktype } from "~/server/arktype";
 import { defineClientEventHandler } from "~/server/internal/clients/event-handler";
 import userLibraryManager from "~/server/internal/userlibrary";
 
-export default defineClientEventHandler(async (h3, { fetchUser }) => {
+const AddEntry = type({
+  id: "string",
+}).configure(throwingArktype);
+
+/**
+ * Add game to user's library
+ */
+export default defineClientEventHandler(async (h3, { fetchUser, body }) => {
   const user = await fetchUser();
 
-  const body = await readBody(h3);
   const gameId = body.id;
-  if (!gameId)
-    throw createError({ statusCode: 400, statusMessage: "Game ID required" });
 
   // Add the game to the default collection
   await userLibraryManager.libraryAdd(gameId, user.id);
   return {};
-});
+}, AddEntry);

server/api/v1/client/collection/default/index.get.ts

@@ -1,6 +1,9 @@
 import { defineClientEventHandler } from "~/server/internal/clients/event-handler";
 import userLibraryManager from "~/server/internal/userlibrary";
 
+/**
+ * Fetch user's library
+ */
 export default defineClientEventHandler(async (h3, { fetchUser }) => {
   const user = await fetchUser();
 

server/api/v1/client/collection/index.get.ts

@@ -1,6 +1,9 @@
 import { defineClientEventHandler } from "~/server/internal/clients/event-handler";
 import userLibraryManager from "~/server/internal/userlibrary";
 
+/**
+ * Fetch all of user's collections
+ */
 export default defineClientEventHandler(async (h3, { fetchUser }) => {
   const user = await fetchUser();
 

server/api/v1/client/collection/index.post.ts

@@ -1,14 +1,19 @@
+import { type } from "arktype";
+import { throwingArktype } from "~/server/arktype";
 import { defineClientEventHandler } from "~/server/internal/clients/event-handler";
 import userLibraryManager from "~/server/internal/userlibrary";
 
-export default defineClientEventHandler(async (h3, { fetchUser }) => {
+const CreateCollection = type({
+  name: "string",
+}).configure(throwingArktype);
+
+/**
+ * Create new collection
+ */
+export default defineClientEventHandler(async (h3, { fetchUser, body }) => {
   const user = await fetchUser();
 
-  const body = await readBody(h3);
-
   const name = body.name;
-  if (!name)
-    throw createError({ statusCode: 400, statusMessage: "Requires name" });
 
   // Create the collection using the manager
   const newCollection = await userLibraryManager.collectionCreate(
@@ -16,4 +21,4 @@ export default defineClientEventHandler(async (h3, { fetchUser }) => {
     user.id,
   );
   return newCollection;
-});
+}, CreateCollection);

server/api/v1/client/game/[id]/index.get.ts

@@ -1,10 +1,12 @@
 import { defineClientEventHandler } from "~/server/internal/clients/event-handler";
 import prisma from "~/server/internal/db/database";
 
+/**
+ * Fetch game by ID
+ * @param id Game ID
+ */
 export default defineClientEventHandler(async (h3) => {
-  const id = getRouterParam(h3, "id");
+  const id = getRouterParam(h3, "id")!;
-  if (!id)
-    throw createError({ statusCode: 400, statusMessage: "No ID in route" });
 
   const game = await prisma.game.findUnique({
     where: {

server/api/v1/client/game/manifest.get.ts

@@ -1,15 +1,23 @@
+import { ArkErrors, type } from "arktype";
 import { defineClientEventHandler } from "~/server/internal/clients/event-handler";
 import manifestGenerator from "~/server/internal/downloads/manifest";
 
+const Query = type({
+  id: "string",
+  version: "string",
+});
+
+/**
+ * Fetch Droplet manifest from game ID and version
+ * @request `id` and `version` query params are required.
+ */
 export default defineClientEventHandler(async (h3) => {
-  const query = getQuery(h3);
+  const query = Query(getQuery(h3));
-  const id = query.id?.toString();
+  if (query instanceof ArkErrors)
-  const version = query.version?.toString();
+    throw createError({ statusCode: 400, statusMessage: query.summary });
-  if (!id || !version)
+  
-    throw createError({
+  const id = query.id;
-      statusCode: 400,
+  const version = query.version;
-      statusMessage: "Missing id or version in query",
-    });
 
   const manifest = await manifestGenerator.generateManifest(id, version);
   if (!manifest)

server/api/v1/client/game/version.get.ts

@@ -1,15 +1,22 @@
+import { ArkErrors, type } from "arktype";
 import { defineClientEventHandler } from "~/server/internal/clients/event-handler";
 import prisma from "~/server/internal/db/database";
 
+const Query = type({
+  id: "string",
+  version: "string",
+});
+
+/**
+ * Fetch version metadata from game ID and version name
+ * @request `id` and `version` query params are required.
+ */
 export default defineClientEventHandler(async (h3) => {
-  const query = getQuery(h3);
+  const query = Query(getQuery(h3));
-  const id = query.id?.toString();
+  if (query instanceof ArkErrors)
-  const version = query.version?.toString();
+    throw createError({ statusCode: 400, statusMessage: query.summary });
-  if (!id || !version)
+  const id = query.id;
-    throw createError({
+  const version = query.version;
-      statusCode: 400,
-      statusMessage: "Missing id or version in query",
-    });
 
   const gameVersion = await prisma.gameVersion.findUnique({
     where: {
@@ -18,6 +25,9 @@ export default defineClientEventHandler(async (h3) => {
         versionName: version,
       },
     },
+    omit: {
+      dropletManifest: true,
+    },
   });
 
   if (!gameVersion)

server/api/v1/client/game/versions.get.ts

@@ -1,6 +1,10 @@
 import { defineClientEventHandler } from "~/server/internal/clients/event-handler";
 import prisma from "~/server/internal/db/database";
 
+/**
+ * Fetch all versions for game ID
+ * @request `id` required in query params
+ */
 export default defineClientEventHandler(async (h3) => {
   const query = getQuery(h3);
   const id = query.id?.toString();

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

@@ -1,13 +1,12 @@
 import { defineClientEventHandler } from "~/server/internal/clients/event-handler";
 import newsManager from "~/server/internal/news";
 
+/**
+ * Fetch new article by ID
+ * @param id Article ID
+ */
 export default defineClientEventHandler(async (h3) => {
-  const id = h3.context.params?.id;
+  const id = getRouterParam(h3, "id")!;
-  if (!id)
-    throw createError({
-      statusCode: 400,
-      message: "Missing news ID",
-    });
 
   const news = await newsManager.fetchById(id);
   if (!news)

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

@@ -1,29 +1,45 @@
+import { ArkErrors, type } from "arktype";
+import { getQuery } from "h3";
+import aclManager from "~/server/internal/acls";
 import { defineClientEventHandler } from "~/server/internal/clients/event-handler";
 import newsManager from "~/server/internal/news";
 
-export default defineClientEventHandler(async (h3) => {
+const NewsFetch = type({
-  const query = getQuery(h3);
+  "order?": "'asc' | 'desc'",
-
+  "tags?": "string[]",
-  const orderBy = query.order as "asc" | "desc";
+  "limit?": "string.numeric.parse",
-  if (orderBy) {
+  "skip?": "string.numeric.parse",
-    if (typeof orderBy !== "string" || !["asc", "desc"].includes(orderBy))
+  "search?": "string",
-      throw createError({ statusCode: 400, statusMessage: "Invalid order" });
-  }
-
-  const tags = query.tags as string[] | undefined;
-  if (tags) {
-    if (typeof tags !== "object" || !Array.isArray(tags))
-      throw createError({ statusCode: 400, statusMessage: "Invalid tags" });
-  }
-
-  const options = {
-    take: parseInt(query.limit as string),
-    skip: parseInt(query.skip as string),
-    orderBy: orderBy,
-    ...(tags && { tags: tags.map((e) => e.toString()) }),
-    search: query.search as string,
-  };
-
-  const news = await newsManager.fetch(options);
-  return news;
 });
+
+/**
+ * Fetch instance news articles
+ */
+export default defineClientEventHandler<ReturnType<typeof newsManager.fetch>, { query: typeof NewsFetch.infer }>(
+  async (h3) => {
+    const userId = await aclManager.getUserIdACL(h3, ["news:read"]);
+    if (!userId)
+      throw createError({
+        statusCode: 403,
+        statusMessage: "Requires authentication",
+      });
+
+    const query = NewsFetch(getQuery(h3));
+    if (query instanceof ArkErrors)
+      throw createError({ statusCode: 400, statusMessage: query.summary });
+
+    const orderBy = query.order;
+    const tags = query.tags;
+
+    const options = {
+      take: Math.min(query.limit ?? 10, 10),
+      skip: query.skip ?? 0,
+      orderBy: orderBy,
+      ...(tags && { tags: tags.map((e) => e.toString()) }),
+      search: query.search,
+    };
+
+    const news = await newsManager.fetch(options);
+    return news;
+  },
+);

server/api/v1/client/object/[id]/index.get.ts

@@ -1,9 +1,12 @@
 import { defineClientEventHandler } from "~/server/internal/clients/event-handler";
 import objectHandler from "~/server/internal/objects";
 
+/**
+ * Fetch object by ID
+ * @param id Object ID
+ */
 export default defineClientEventHandler(async (h3, utils) => {
-  const id = getRouterParam(h3, "id");
+  const id = getRouterParam(h3, "id")!;
-  if (!id) throw createError({ statusCode: 400, statusMessage: "Invalid ID" });
 
   const user = await utils.fetchUser();
 

server/api/v1/client/user/index.get.ts

@@ -1,5 +1,8 @@
 import { defineClientEventHandler } from "~/server/internal/clients/event-handler";
 
+/**
+ * Fetch user data for this client
+ */
 export default defineClientEventHandler(async (h3, { fetchUser }) => {
   const user = await fetchUser();
 

server/api/v1/client/user/library.get.ts

@@ -1,6 +1,9 @@
 import { defineClientEventHandler } from "~/server/internal/clients/event-handler";
 import userLibraryManager from "~/server/internal/userlibrary";
 
+/**
+ * Fetch library for user
+ */
 export default defineClientEventHandler(async (_h3, { fetchUser }) => {
   const user = await fetchUser();
   const library = await userLibraryManager.fetchLibrary(user.id);

server/api/v1/client/user/webtoken.post.ts

@@ -4,6 +4,9 @@ import type { UserACL } from "~/server/internal/acls";
 import { defineClientEventHandler } from "~/server/internal/clients/event-handler";
 import prisma from "~/server/internal/db/database";
 
+/**
+ * Generate API token with limited API scopes to render store in client
+ */
 export default defineClientEventHandler(
   async (h3, { fetchUser, fetchClient, clientId }) => {
     const user = await fetchUser();

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

@@ -14,7 +14,7 @@ const NewsFetch = type({
 /**
  * Fetch instance news articles
  */
-export default defineEventHandler<{ query: typeof NewsFetch.infer }>(
+export default defineEventHandler<{ query: typeof NewsFetch.infer }, ReturnType<typeof newsManager.fetch>>(
   async (h3) => {
     const userId = await aclManager.getUserIdACL(h3, ["news:read"]);
     if (!userId)

server/internal/clients/event-handler.ts

@@ -16,9 +16,9 @@ type ClientUtils<R> = {
 
 const NONCE_LENIENCE = 30_000;
 
-type ClientEventHandlerRequest<T> = {
+type ClientEventHandlerRequest<T, Q = {[key: string]: any }> = {
-  body: T;
+  body?: T;
-  query: { [key: string]: string | string[] };
+  query?: Q;
 };
 
 interface ClientEventHandler<