Account Management API: Added admin support and documentation to get account projects via /api/v2/projects/get.

Author: schrodingersket

src/packages/next/lib/api/schema/accounts/common.ts

@@ -4,6 +4,14 @@ export const AccountIdSchema = z.string().uuid().describe("Account id.");
 
 export type AccountId = z.infer<typeof AccountIdSchema>;
 
+export const AdminAccountIdSchema = AccountIdSchema.optional().describe(
+  `**Administrators only**. Optional account id to set name(s) for. If this field is 
+     not provided, it is assumed that this operation pertains to the account id of the 
+     user making the request.`,
+);
+
+export type AdminAccountId = z.infer<typeof AdminAccountIdSchema>;
+
 export const AccountEmailSchema = z
   .string()
   .describe("The account e-mail address.");

src/packages/next/lib/api/schema/projects/common.ts

@@ -1,8 +1,28 @@
 import { z } from "../../framework";
 
-export const ProjectIdSchema = z
-  .string()
-  .uuid()
-  .describe("Project id.");
+export const ProjectIdSchema = z.string().uuid().describe("Project id.");
 
 export type ProjectId = z.infer<typeof ProjectIdSchema>;
+
+export const ProjectTitleSchema = z
+  .string()
+  .describe(
+    "The short title of the project. Should use no special formatting, except hashtags.",
+  );
+
+export type ProjectTitle = z.infer<typeof ProjectTitleSchema>;
+
+export const ProjectDescriptionSchema = z.string().describe(
+  `A longer textual description of the project. This can include hashtags and should 
+   be formatted using markdown.`,
+);
+
+export type ProjectDescription = z.infer<typeof ProjectDescriptionSchema>;
+
+export const ProjectNameSchema = z.string().describe(
+  `The optional name of this project. Must be globally unique (up to case) across all 
+   projects with a given *owner*. It can be between 1 and 100 characters from a-z, A-Z, 
+   0-9, period, and dash.`,
+);
+
+export type ProjectName = z.infer<typeof ProjectNameSchema>;

src/packages/next/lib/api/schema/projects/get.ts

@@ -0,0 +1,39 @@
+import { z } from "../../framework";
+
+import { FailedAPIOperationSchema } from "../common";
+
+import { AdminAccountIdSchema } from "../accounts/common";
+
+import { ProjectIdSchema } from "./common";
+
+// OpenAPI spec
+//
+export const GetAccountProjectsInputSchema = z
+  .object({
+    account_id: AdminAccountIdSchema,
+    limit: z
+      .number()
+      .default(50)
+      .describe("Upper bound on the number of projects to return.")
+      .nullish(),
+  })
+  .describe("Gets projects for a particular account.");
+
+export const GetAccountProjectsOutputSchema = z.union([
+  FailedAPIOperationSchema,
+  z
+    .array(
+      z.object({
+        project_id: ProjectIdSchema,
+        title: ProjectIdSchema,
+      }),
+    )
+    .describe("An array of projects corresponding to a particular account."),
+]);
+
+export type GetAccountProjectsInput = z.infer<
+  typeof GetAccountProjectsInputSchema
+>;
+export type GetAccountProjectsOutput = z.infer<
+  typeof GetAccountProjectsOutputSchema
+>;

src/packages/next/lib/api/schema/projects/update.ts

@@ -2,40 +2,24 @@ import { z } from "../../framework";
 
 import { FailedAPIOperationSchema, OkAPIOperationSchema } from "../common";
 
-import { ProjectIdSchema } from "./common";
-import { AccountIdSchema } from "../accounts/common";
+import { AdminAccountIdSchema } from "../accounts/common";
+
+import {
+  ProjectDescriptionSchema,
+  ProjectIdSchema,
+  ProjectNameSchema,
+  ProjectTitleSchema,
+} from "./common";
 
 // OpenAPI spec
 //
 export const UpdateProjectInputSchema = z
   .object({
-    account_id: AccountIdSchema.describe(
-      `**Administrators only**. If provided, this operation will be executed on behalf of 
-       the account corresponding to this id.`,
-    ).optional(),
+    account_id: AdminAccountIdSchema,
     project_id: ProjectIdSchema,
-    title: z
-      .string()
-      .describe(
-        `The short title of the project. Should use no special formatting, except 
-         hashtags.`,
-      )
-      .optional(),
-    description: z
-      .string()
-      .describe(
-        `A longer textual description of the project. This can include hashtags and should 
-         be formatted using markdown.`,
-      )
-      .optional(),
-    name: z
-      .string()
-      .describe(
-        `The optional name of this project. Must be globally unique (up to case) across 
-         all projects with a given *owner*. It can be between 1 and 100 characters from 
-         a-z A-Z 0-9 period and dash.`,
-      )
-      .optional(),
+    title: ProjectTitleSchema.optional(),
+    description: ProjectDescriptionSchema.optional(),
+    name: ProjectNameSchema.optional(),
   })
   .describe(
     `Update an existing project's title, name, and/or description. If the API client is an 

src/packages/next/pages/api/v2/index.ts

@@ -11,7 +11,8 @@ export default docsApiRoute({
       version: "1.0.0",
       summary: `This is the CoCalc HTTP API. To get started, you'll need to 
                 [create an API key](https://doc.cocalc.com/apikeys.html).`,
-      description: "foo bar",
+      description: `This is the CoCalc HTTP API. To get started, you'll need to 
+                [create an API key](https://doc.cocalc.com/apikeys.html).`,
     },
     externalDocs: {
       url: "https://doc.cocalc.com",

src/packages/next/pages/api/v2/projects/get.ts

@@ -1,16 +1,61 @@
 /* Get projects that the authenticated user is a collaborator on. */
 
-import getAccountId from "lib/account/get-account";
 import getProjects from "@cocalc/server/projects/get";
+import userIsInGroup from "@cocalc/server/accounts/is-in-group";
+import getAccountId from "lib/account/get-account";
 import getParams from "lib/api/get-params";
+import { apiRoute, apiRouteOperation } from "lib/api";
 
-export default async function handle(req, res) {
-  const account_id = await getAccountId(req);
+import {
+  GetAccountProjectsInputSchema,
+  GetAccountProjectsOutputSchema,
+} from "lib/api/schema/projects/get";
+
+async function handle(req, res) {
+  const client_account_id = await getAccountId(req);
   try {
-    if (account_id == null) throw Error("must be authenticated");
-    const { limit } = getParams(req);
-    res.json(await getProjects({ account_id, limit }));
+    if (client_account_id == null) {
+      throw Error("Must be signed in.");
+    }
+
+    const { account_id, limit } = getParams(req);
+
+    // User must be an admin to specify account_id field
+    //
+    if (account_id && !(await userIsInGroup(client_account_id, "admin"))) {
+      throw Error(
+        "The `account_id` field may only be specified by account administrators.",
+      );
+    }
+
+    res.json(
+      await getProjects({
+        account_id: account_id || client_account_id,
+        limit,
+      }),
+    );
   } catch (err) {
     res.json({ error: err.message });
   }
 }
+
+export default apiRoute({
+  get: apiRouteOperation({
+    method: "POST",
+    openApiOperation: {
+      tags: ["Projects", "Admin"],
+    },
+  })
+    .input({
+      contentType: "application/json",
+      body: GetAccountProjectsInputSchema,
+    })
+    .outputs([
+      {
+        status: 200,
+        contentType: "application/json",
+        body: GetAccountProjectsOutputSchema,
+      },
+    ])
+    .handler(handle),
+});