partial: new documentation additions (company admin)

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

@@ -2,6 +2,9 @@ import { AuthMec } from "~/prisma/client/enums";
 import aclManager from "~/server/internal/acls";
 import authManager from "~/server/internal/auth";
 
+/**
+ * Fetches all the enabled authentication mechanisms on this instance, and their configuration, if enabled.
+ */
 export default defineEventHandler(async (h3) => {
   const allowed = await aclManager.allowSystemACL(h3, ["auth:read", "setup"]);
   if (!allowed) throw createError({ statusCode: 403 });

server/api/v1/admin/auth/invitation/index.delete.ts

@@ -8,7 +8,8 @@ const DeleteInvite = type({
 }).configure(throwingArktype);
 
 /**
- * Delete a simple auth invitation
+ * Deletes a "Simple" invitation
+ * @returns nothing
  */
 export default defineEventHandler<{
   body: typeof DeleteInvite.infer;

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

@@ -3,6 +3,9 @@ import { systemConfig } from "~/server/internal/config/sys-conf";
 import prisma from "~/server/internal/db/database";
 import taskHandler from "~/server/internal/tasks";
 
+/**
+ * Fetches a "Simple" invitation
+ */
 export default defineEventHandler(async (h3) => {
   const allowed = await aclManager.allowSystemACL(h3, [
     "auth:simple:invitation:read",

server/api/v1/admin/auth/invitation/index.post.ts

@@ -11,6 +11,9 @@ const CreateInvite = SharedRegisterValidator.partial()
   })
   .configure(throwingArktype);
 
+/**
+ * Creates a "Simple" invitation
+ */
 export default defineEventHandler(async (h3) => {
   const allowed = await aclManager.allowSystemACL(h3, [
     "auth:simple:invitation:new",

server/api/v1/admin/company/[id]/banner.post.ts

@@ -3,6 +3,11 @@ import prisma from "~/server/internal/db/database";
 import objectHandler from "~/server/internal/objects";
 import { handleFileUpload } from "~/server/internal/utils/handlefileupload";
 
+/**
+ * Multi-part form upload for the banner.
+ * @request `multipart/form-data` data. Only one file, can be named anything.
+ * @param id Company ID
+ */
 export default defineEventHandler(async (h3) => {
   const allowed = await aclManager.allowSystemACL(h3, ["company:update"]);
   if (!allowed) throw createError({ statusCode: 403 });

server/api/v1/admin/company/[id]/game.delete.ts

@@ -7,7 +7,12 @@ const GameDelete = type({
   id: "string",
 }).configure(throwingArktype);
 
-export default defineEventHandler(async (h3) => {
+/**
+ * Delete a game's association with a company
+ * @param id Company ID
+ */
+export default defineEventHandler<{ body: typeof GameDelete.infer }>(
+  async (h3) => {
     const allowed = await aclManager.allowSystemACL(h3, ["company:update"]);
     if (!allowed) throw createError({ statusCode: 403 });
 
@@ -34,4 +39,5 @@ export default defineEventHandler(async (h3) => {
     });
 
     return;
-});
+  },
+);

server/api/v1/admin/company/[id]/game.patch.ts

@@ -9,7 +9,12 @@ const GamePatch = type({
   id: "string",
 }).configure(throwingArktype);
 
-export default defineEventHandler(async (h3) => {
+/**
+ * Update a company's association with a game.
+ * @param id Company ID
+ */
+export default defineEventHandler<{ body: typeof GamePatch.infer }>(
+  async (h3) => {
     const allowed = await aclManager.allowSystemACL(h3, ["company:update"]);
     if (!allowed) throw createError({ statusCode: 403 });
 
@@ -34,4 +39,5 @@ export default defineEventHandler(async (h3) => {
     });
 
     return;
-});
+  },
+);

server/api/v1/admin/company/[id]/game.post.ts

@@ -9,7 +9,12 @@ const GamePost = type({
   id: "string",
 }).configure(throwingArktype);
 
-export default defineEventHandler(async (h3) => {
+/**
+ * Add a new game association to this company
+ * @param id Company ID
+ */
+export default defineEventHandler<{ body: typeof GamePost.infer }>(
+  async (h3) => {
     const allowed = await aclManager.allowSystemACL(h3, ["company:update"]);
     if (!allowed) throw createError({ statusCode: 403 });
 
@@ -66,4 +71,5 @@ export default defineEventHandler(async (h3) => {
     });
 
     return game;
-});
+  },
+);

server/api/v1/admin/company/[id]/icon.post.ts

@@ -3,6 +3,11 @@ import prisma from "~/server/internal/db/database";
 import objectHandler from "~/server/internal/objects";
 import { handleFileUpload } from "~/server/internal/utils/handlefileupload";
 
+/**
+ * Multi-part form upload for the icon of this company
+ * @request `multipart/form-data` data. Only one file, can be named anything.
+ * @param id Company ID
+ */
 export default defineEventHandler(async (h3) => {
   const allowed = await aclManager.allowSystemACL(h3, ["company:update"]);
   if (!allowed) throw createError({ statusCode: 403 });

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

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

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

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

server/api/v1/admin/company/[id]/index.patch.ts

@@ -1,6 +1,11 @@
 import aclManager from "~/server/internal/acls";
 import prisma from "~/server/internal/db/database";
 
+/**
+ * Update a company. Pass any fields into the body to be updated on the model
+ * @request Partial of the data returned by GET, minus the `developed` and `published` fields.
+ * @param id Company ID
+ */
 export default defineEventHandler(async (h3) => {
   const allowed = await aclManager.allowSystemACL(h3, ["company:update"]);
   if (!allowed) throw createError({ statusCode: 403 });

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

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

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

@@ -12,7 +12,11 @@ const CompanyCreate = type({
   website: "string",
 }).configure(throwingArktype);
 
-export default defineEventHandler(async (h3) => {
+/**
+ * Create a new company on this instance
+ */
+export default defineEventHandler<{ body: typeof CompanyCreate.infer }>(
+  async (h3) => {
     const allowed = await aclManager.allowSystemACL(h3, ["company:create"]);
     if (!allowed) throw createError({ statusCode: 403 });
 
@@ -44,4 +48,5 @@ export default defineEventHandler(async (h3) => {
     await pull();
 
     return company;
-});
+  },
+);

server/api/v1/index.get.ts

@@ -1,6 +1,6 @@
 import { systemConfig } from "~/server/internal/config/sys-conf";
 
-export default defineEventHandler((_h3) => {
+export default defineEventHandler(async (_h3) => {
   return {
     appName: "Drop",
     version: systemConfig.getDropVersion(),