Merge pull request #7724 from schrodingersket/feature/7665

Account Management API: Added new `/api/v2/projects/update` API route…

Author: williamstein

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

@@ -0,0 +1,52 @@
+import { z } from "../../framework";
+
+import { FailedAPIOperationSchema, OkAPIOperationSchema } from "../common";
+
+import { ProjectIdSchema } from "./common";
+import { AccountIdSchema } from "../accounts/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(),
+    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(),
+  })
+  .describe(
+    `Update an existing project's title, name, and/or description. If the API client is an 
+     admin, they may act on any project. Otherwise, the client may only update projects 
+     for which they are listed as collaborators.`,
+  );
+
+export const UpdateProjectOutputSchema = z.union([
+  FailedAPIOperationSchema,
+  OkAPIOperationSchema,
+]);
+
+export type UpdateProjectInput = z.infer<typeof UpdateProjectInputSchema>;
+export type UpdateProjectOutput = z.infer<typeof UpdateProjectOutputSchema>;

src/packages/next/pages/api/v2/accounts/set-name.ts

@@ -9,14 +9,16 @@ import getAccountId from "lib/account/get-account";
 import getParams from "lib/api/get-params";
 
 import { apiRoute, apiRouteOperation } from "lib/api";
+import { SuccessStatus } from "lib/api/status";
 import {
   SetAccountNameInputSchema,
   SetAccountNameOutputSchema,
 } from "lib/api/schema/accounts/set-name";
 
 async function handle(req, res) {
   try {
-    res.json(await get(req));
+    await get(req);
+    res.json(SuccessStatus);
   } catch (err) {
     res.json({ error: `${err.message ? err.message : err}` });
     return;
@@ -34,7 +36,9 @@ async function get(req) {
 
   // This user MUST be an admin:
   if (account_id && !(await userIsInGroup(client_account_id, "admin"))) {
-    throw Error("Only admins are authorized to specify an account id.");
+    throw Error(
+      "The `account_id` field may only be specified by account administrators.",
+    );
   }
 
   return userQuery({

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

@@ -0,0 +1,77 @@
+/*
+Set project title, description, etc.
+*/
+
+import userIsInGroup from "@cocalc/server/accounts/is-in-group";
+import setProject from "@cocalc/server/projects/set-one";
+
+import getAccountId from "lib/account/get-account";
+import getParams from "lib/api/get-params";
+
+import { OkStatus } from "lib/api/status";
+import { apiRoute, apiRouteOperation } from "lib/api";
+import {
+  UpdateProjectInputSchema,
+  UpdateProjectOutputSchema,
+} from "lib/api/schema/projects/update";
+
+async function handle(req, res) {
+  try {
+    await get(req);
+    res.json(OkStatus);
+  } catch (err) {
+    res.json({ error: `${err.message ? err.message : err}` });
+    return;
+  }
+}
+
+async function get(req) {
+  const client_account_id = await getAccountId(req);
+
+  if (client_account_id == null) {
+    throw Error("Must be signed in to update project.");
+  }
+
+  const { account_id, project_id, title, description, name } = getParams(req);
+
+  // If the API client is an admin, they may act on any project on behalf of any account.
+  // Otherwise, the client may only update projects for which they are listed as
+  // collaborators.
+  //
+  if (account_id && !(await userIsInGroup(client_account_id, "admin"))) {
+    throw Error(
+      "The `account_id` field may only be specified by account administrators.",
+    );
+  }
+
+  return setProject({
+    acting_account_id: account_id || client_account_id,
+    project_id,
+    project_update: {
+      title,
+      description,
+      name,
+    },
+  });
+}
+
+export default apiRoute({
+  update: apiRouteOperation({
+    method: "POST",
+    openApiOperation: {
+      tags: ["Projects", "Admin"],
+    },
+  })
+    .input({
+      contentType: "application/json",
+      body: UpdateProjectInputSchema,
+    })
+    .outputs([
+      {
+        status: 200,
+        contentType: "application/json",
+        body: UpdateProjectOutputSchema,
+      },
+    ])
+    .handler(handle),
+});

src/packages/server/projects/get.ts

@@ -7,14 +7,21 @@
 import getPool from "@cocalc/database/pool";
 import { isValidUUID } from "@cocalc/util/misc";
 
+export interface DBProject {
+  project_id: string;
+  title?: string;
+  description?: string;
+  name?: string;
+}
+
 // I may add more fields and more options later...
 export default async function getProjects({
   account_id,
   limit = 50,
 }: {
   account_id: string;
   limit?: number;
-}): Promise<{ project_id: string; title?: string; description?: string }[]> {
+}): Promise<DBProject[]> {
   if (!isValidUUID(account_id)) {
     throw Error("account_id must be a UUIDv4");
   }
@@ -23,8 +30,8 @@ export default async function getProjects({
   }
   const pool = getPool();
   const { rows } = await pool.query(
-    `SELECT project_id, title, description FROM projects WHERE DELETED IS NOT true AND users ? $1 AND (users#>>'{${account_id},hide}')::BOOLEAN IS NOT TRUE ORDER BY last_edited DESC LIMIT $2`,
-    [account_id, limit]
+    `SELECT project_id, title, description, name FROM projects WHERE DELETED IS NOT true AND users ? $1 AND (users#>>'{${account_id},hide}')::BOOLEAN IS NOT TRUE ORDER BY last_edited DESC LIMIT $2`,
+    [account_id, limit],
   );
   return rows;
 }

src/packages/server/projects/set-one.ts

@@ -0,0 +1,38 @@
+/* Updates an existing project's name, title, and/or description. May be
+   restricted such that the query is executed as though by a specific account_id.
+
+   This function is simply a wrapper around the userQuery function.
+*/
+import userQuery from "@cocalc/database/user-query";
+
+import { DBProject } from "./get";
+
+export default async function setProject({
+  acting_account_id,
+  project_id,
+  project_update,
+}: {
+  // This function executes as though the account id below made the request; this has the
+  // effect of enforcing an authorization check that the acting account is allowed to
+  // modify the desired project.
+  //
+  acting_account_id: string;
+  project_id: string;
+  project_update: Omit<DBProject, "project_id">;
+}): Promise<DBProject | undefined> {
+  const { description, title, name } = project_update;
+  return userQuery({
+    account_id: acting_account_id,
+    query: {
+      projects: {
+        // Any provided values must be non-empty in order for userQuery to SET values
+        // instead of fetching them.
+        //
+        project_id,
+        ...(name && { name }),
+        ...(title && { title }),
+        ...(description && { description }),
+      },
+    },
+  });
+}