Merge pull request #7633 from schrodingersket/openapi/accounts

NextJS API: Completed `/api/v2/accounts` endpoints…

Author: williamstein

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

@@ -0,0 +1,26 @@
+import { z } from "../../framework";
+
+import {
+  FailedAPIOperationSchema,
+  SuccessfulAPIOperationSchema,
+} from "../common";
+
+import { AccountIdSchema } from "./common";
+
+// OpenAPI spec
+//
+export const BanAccountInputSchema = z
+  .object({
+    account_id: AccountIdSchema.describe("Account id to ban."),
+  })
+  .describe(
+    "**Administrators only**. Used to ban a user's account from the system.",
+  );
+
+export const BanAccountOutputSchema = z.union([
+  FailedAPIOperationSchema,
+  SuccessfulAPIOperationSchema,
+]);
+
+export type BanAccountInput = z.infer<typeof BanAccountInputSchema>;
+export type BanAccountOutput = z.infer<typeof BanAccountOutputSchema>;

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

@@ -1,8 +1,50 @@
 import { z } from "../../framework";
 
-export const AccountIdSchema = z
-  .string()
-  .uuid()
-  .describe("Account id.");
+export const AccountIdSchema = z.string().uuid().describe("Account id.");
 
 export type AccountId = z.infer<typeof AccountIdSchema>;
+
+export const AccountEmailSchema = z
+  .string()
+  .describe("The account e-mail address.");
+
+export type AccountEmail = z.infer<typeof AccountEmailSchema>;
+
+export const AccountUserSchema = z
+  .object({
+    account_id: AccountIdSchema,
+    first_name: z.string().describe("User's first name.").nullish(),
+    last_name: z.string().describe("User's last name.").nullish(),
+    name: z.string().describe("Customizable username").nullish(),
+    last_active: z
+      .number()
+      .min(0)
+      .nullable()
+      .describe(
+        "UNIX timestamp indicating time at which the account was last active.",
+      ),
+    created: z
+      .number()
+      .min(0)
+      .describe(
+        "UNIX timestamp indicating time at which the account was created.",
+      ),
+    banned: z
+      .boolean()
+      .optional()
+      .describe("**Administrators only**. True if this user has been banned."),
+    email_address_verified: z
+      .boolean()
+      .nullish()
+      .describe("Set to `true` once the user's e-mail has been verified."),
+    email_address: AccountEmailSchema.optional().describe(
+      `The account e-mail address. 
+      
+       *Note*: For security reasons, the email_address *only* occurs in search queries 
+       that are by \`email_address\` (or for admins); email addresses of users queried 
+       by substring searches are not revealed.`,
+    ),
+  })
+  .describe("User account.");
+
+export type AccountUser = z.infer<typeof AccountUserSchema>;

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

@@ -0,0 +1,15 @@
+import { z } from "../../framework";
+
+import {
+  FailedAPIOperationSchema,
+  SuccessfulAPIOperationSchema,
+} from "../common";
+
+// OpenAPI spec
+//
+export const DeleteAccountOutputSchema = z.union([
+  FailedAPIOperationSchema,
+  SuccessfulAPIOperationSchema,
+]);
+
+export type DeleteAccountOutput = z.infer<typeof DeleteAccountOutputSchema>;

src/packages/next/lib/api/schema/accounts/get-email-address.ts

@@ -0,0 +1,30 @@
+import { z } from "../../framework";
+
+import { FailedAPIOperationSchema } from "../common";
+
+import { AccountEmailSchema, AccountIdSchema } from "./common";
+
+// OpenAPI spec
+//
+export const GetAccountEmailAddressInputSchema = z
+  .object({
+    account_id: AccountIdSchema,
+  })
+  .describe(
+    `**Administrators only**. Used to fetch the e-mail address associated with an
+      account id.`,
+  );
+
+export const GetAccountEmailAddressOutputSchema = z.union([
+  FailedAPIOperationSchema,
+  z.object({
+    email_address: AccountEmailSchema,
+  }),
+]);
+
+export type GetAccountEmailAddressInput = z.infer<
+  typeof GetAccountEmailAddressInputSchema
+>;
+export type GetAccountEmailAddressOutput = z.infer<
+  typeof GetAccountEmailAddressOutputSchema
+>;

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

@@ -0,0 +1,67 @@
+import { z } from "../../framework";
+
+import { FailedAPIOperationSchema } from "../common";
+
+import { AccountIdSchema } from "./common";
+import { RequestNoCacheSchema } from "../common";
+
+// OpenAPI spec
+//
+export const AccountProfileInputSchema = z
+  .object({
+    account_id: AccountIdSchema,
+    noCache: RequestNoCacheSchema,
+  })
+  .describe(
+    `Get the *public* profile for a given account or the private profile of the user 
+     making the request. This is public information if user the user knows the account_id. 
+     It is the color, the name, and the image.`,
+  );
+
+export const AccountProfileOutputSchema = z.union([
+  FailedAPIOperationSchema,
+  z.object({
+    profile: z
+      .object({
+        account_id: AccountIdSchema,
+        first_name: z.string().describe("First name of account holder."),
+        last_name: z.string().describe("Last name of account holder."),
+        image: z
+          .string()
+          .describe(
+            `Account avatar image. This value may be used directly in the \`src\` 
+             attribute of an HTML \`image\` tag`,
+          )
+          .optional(),
+        color: z
+          .string()
+          .describe(
+            `Background color for account avatar if an image is not provided.`,
+          )
+          .optional(),
+        name: z
+          .union([z.string().describe("Account username"), z.null()])
+          .describe(
+            `Account username. This is used to provide a nice URL for public content 
+             associated with this account.`,
+          ),
+        is_admin: z
+          .boolean()
+          .describe("_Included when the full profile is returned.")
+          .optional(),
+        is_partner: z
+          .boolean()
+          .describe("_Included when the full profile is returned.")
+          .optional(),
+        is_anonymous: z
+          .boolean()
+          .describe("_Included when the full profile is returned.")
+          .optional(),
+        email_address: z.string().describe("The account e-mail address."),
+      })
+      .describe("An object containing account profile information."),
+  }),
+]);
+
+export type AccountProfileInput = z.infer<typeof AccountProfileInputSchema>;
+export type AccountProfileOutput = z.infer<typeof AccountProfileOutputSchema>;

src/packages/next/lib/api/schema/accounts/remove-ban.ts

@@ -0,0 +1,28 @@
+import { z } from "../../framework";
+
+import {
+  FailedAPIOperationSchema,
+  SuccessfulAPIOperationSchema,
+} from "../common";
+
+import { AccountIdSchema } from "./common";
+
+// OpenAPI spec
+//
+export const RemoveAccountBanInputSchema = z
+  .object({
+    account_id: AccountIdSchema.describe("Account id to remove ban for."),
+  })
+  .describe(
+    "**Administrators only**. Used to remove an existing ban on a user's account",
+  );
+
+export const RemoveAccountBanOutputSchema = z.union([
+  FailedAPIOperationSchema,
+  SuccessfulAPIOperationSchema,
+]);
+
+export type RemoveAccountBanInput = z.infer<typeof RemoveAccountBanInputSchema>;
+export type RemoveAccountBanOutput = z.infer<
+  typeof RemoveAccountBanOutputSchema
+>;

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

@@ -0,0 +1,29 @@
+import { z } from "../../framework";
+
+import { FailedAPIOperationSchema } from "../common";
+import { AccountUserSchema } from "./common";
+
+// OpenAPI spec
+//
+export const AccountSearchInputSchema = z
+  .object({
+    query: z.string()
+      .describe(`Comma- or space-delimited) list of account e-mail addresses, account ids, 
+      and/or first/last names to query for an account by.`),
+  })
+  .describe(
+    `Search for accounts matching a given query. If user is signed in, then their 
+      account id is used to prioritize the search.`,
+  );
+
+export const AccountSearchOutputSchema = z.union([
+  FailedAPIOperationSchema,
+  z
+    .array(AccountUserSchema)
+    .describe(
+      "List of matching accounts, sorted by last active and/or account creation date.",
+    ),
+]);
+
+export type AccountSearchInput = z.infer<typeof AccountSearchInputSchema>;
+export type AccountSearchOutput = z.infer<typeof AccountSearchOutputSchema>;

src/packages/next/lib/api/schema/accounts/send-verification-email.ts

@@ -0,0 +1,28 @@
+import { z } from "../../framework";
+
+import {
+  FailedAPIOperationSchema,
+  SuccessfulAPIOperationSchema,
+} from "../common";
+
+import { AccountEmailSchema } from "./common";
+
+// OpenAPI spec
+//
+export const SendAccountVerificationEmailInputSchema = z
+  .object({
+    email_address: AccountEmailSchema,
+  })
+  .describe("Send account verification email.");
+
+export const SendAccountVerificationEmailOutputSchema = z.union([
+  FailedAPIOperationSchema,
+  SuccessfulAPIOperationSchema,
+]);
+
+export type SendAccountVerificationEmailInput = z.infer<
+  typeof SendAccountVerificationEmailInputSchema
+>;
+export type SendAccountVerificationEmailOutput = z.infer<
+  typeof SendAccountVerificationEmailOutputSchema
+>;

src/packages/next/lib/api/schema/accounts/set-email-address.ts

@@ -0,0 +1,34 @@
+import { z } from "../../framework";
+
+import {
+  FailedAPIOperationSchema,
+  SuccessfulAPIOperationSchema,
+} from "../common";
+
+import { AccountEmailSchema } from "./common";
+
+// OpenAPI spec
+//
+export const SetAccountEmailAddressInputSchema = z
+  .object({
+    email_address: AccountEmailSchema,
+    password: z.string().describe("The password for the account."),
+  })
+  .describe(
+    `Set email address of an account. The password must also be provided. If the 
+     email address is already set in the database, then \`password\` must be the current 
+     correct password. If the email address is NOT set, then a new email address and 
+     password are set.`,
+  );
+
+export const SetAccountEmailAddressOutputSchema = z.union([
+  FailedAPIOperationSchema,
+  SuccessfulAPIOperationSchema,
+]);
+
+export type SetAccountEmailAddressInput = z.infer<
+  typeof SetAccountEmailAddressInputSchema
+>;
+export type SetAccountEmailAddressOutput = z.infer<
+  typeof SetAccountEmailAddressOutputSchema
+>;

src/packages/next/lib/api/schema/accounts/set-password.ts

@@ -0,0 +1,29 @@
+import { z } from "../../framework";
+
+import {
+  FailedAPIOperationSchema,
+  SuccessfulAPIOperationSchema,
+} from "../common";
+
+// OpenAPI spec
+//
+export const SetAccountPasswordInputSchema = z
+  .object({
+    currentPassword: z
+      .string()
+      .describe("The current password for the account."),
+    newPassword: z.string().describe("The new password for the account."),
+  })
+  .describe("Set password for an existing account.");
+
+export const SetAccountPasswordOutputSchema = z.union([
+  FailedAPIOperationSchema,
+  SuccessfulAPIOperationSchema,
+]);
+
+export type SetAccountPasswordInput = z.infer<
+  typeof SetAccountPasswordInputSchema
+>;
+export type SetAccountPasswordOutput = z.infer<
+  typeof SetAccountPasswordOutputSchema
+>;