Merge branch 'draft-bots' into 'master'

Bot API

See merge request revolt/api!1

src/index.ts

@@ -39,6 +39,12 @@ async function generate(): Promise<Document> {
                     in: "header",
                     name: "x-session-token",
                     description: "Session is created by calling `/auth/login`.\n"
+                },
+                'Bot Token': {
+                    type: "apiKey",
+                    in: "header",
+                    name: "x-bot-token",
+                    description: "Bot tokens can be found by fetching `/bots/:id`.\n"
                 }
             }
         }

src/openapi/paths.ts

@@ -57,6 +57,9 @@ export function routeAuthenticated(summary: string, description: string, obj: Om
             {
                 'User ID': [],
                 'Session Token': []
+            },
+            {
+                'Bot Token': []
             }
         ]
     }

src/routes/bots.ts

@@ -0,0 +1,144 @@
+import { body, parameter, ref, success } from "../openapi/generators.js";
+import { group, resource, routeAuthenticated, tag } from "../openapi/paths.js";
+import { schema } from "../typescript.js";
+
+group("Bots");
+
+//#region Bots
+tag("Bots", "Create and edit bots.");
+
+resource('/bots/create', {
+    post: routeAuthenticated(
+        "Create Bot",
+        "Create a new Revolt bot.",
+        {
+            ...await body("Bot Details", schema`
+                interface ${'BotDetails'} {
+                    /**
+                     * Bot name
+                     * @minLength 1
+                     * @maxLength 32
+                     **/
+                    name: string;
+                }
+            `),
+            ...await success(
+                "Succesfully created a new bot.",
+                ref("Bot")
+            )
+        }
+    )
+});
+
+resource('/bots/@me', {
+    get: routeAuthenticated(
+        "Fetch Owned Bots",
+        "Fetch all of your bots.",
+        {
+            ...await success("Array of bot objects.", schema`
+                import type { Bot } from './Bots';
+                type ${'MyBots'} = Bot[];
+            `)
+        }
+    )
+});
+
+const botParams = {
+    parameters: [
+        await parameter('bot', 'Bot ID', ref("Id"))
+    ]
+}
+
+resource('/bots/:bot', {
+    get: routeAuthenticated(
+        "Fetch Bot",
+        "Fetch details of an owned bot.",
+        {
+            ...botParams,
+            ...await success("Bot", ref("Bot"))
+        }
+    ),
+    patch: routeAuthenticated(
+        "Edit Bot",
+        "Edit bot details.",
+        {
+            ...await body("Requested changes to bot object.", schema`
+                interface ${'EditBot'} {
+                    /**
+                     * Channel name
+                     * @minLength 1
+                     * @maxLength 32
+                     **/
+                    name?: string;
+
+                    /**
+                     * Whether the bot can be added by anyone
+                     **/
+                    public?: boolean;
+
+                    /**
+                     * Interactions URL
+                     * @minLength 1
+                     * @maxLength 2048
+                     **/
+                    interactionsURL?: string;
+
+                    /**
+                     * Field to remove from bot object
+                     */
+                    remove?: 'InteractionsURL';
+                }
+            `),
+            ...await success("Succesfully changed bot object.")
+        }
+    ),
+    delete: routeAuthenticated(
+        "Delete Bot",
+        "Delete a bot.",
+        {
+            ...botParams,
+            ...await success("Deleted bot.")
+        }
+    )
+});
+
+resource('/bots/:bot/invite', {
+    get: routeAuthenticated(
+        "Fetch Public Bot",
+        "Fetch details of a public (or owned) bot.",
+        {
+            ...botParams,
+            ...await success("Public Bot", ref('PublicBot'))
+        }
+    ),
+    post: routeAuthenticated(
+        "Invite Public Bot",
+        "Invite a bot to a server or group.",
+        {
+            ...botParams,
+            ...await body("Information about where to invite the bot.", schema`
+                import type { Id } from './_common';
+
+                type ${'InvitePublicBot'} = (
+                    {
+                        /**
+                         * Server ID to add the bot to.
+                         */
+                        server: Id
+                    } | 
+                    {
+                        /**
+                         * Group channel ID to add the bot to.
+                         */
+                        group: Id
+                    }
+                )
+            `),
+            ...await success("Added bot to server / group.")
+        }
+    )
+});
+//#endregion
+
+//#region Human Interactions
+//#endregion

src/routes/index.ts

@@ -4,6 +4,7 @@ export async function load() {
     await import('./users.js');
     await import('./channels.js');
     await import('./servers.js');
+    await import('./bots.js');
     await import('./misc.js');
 }
 

types/Bots.ts

@@ -0,0 +1,56 @@
+import type { Attachment } from "./Autumn";
+import type { Username } from "./Users";
+import type { Id } from "./_common";
+
+export interface Bot {
+    /**
+     * Bot ID
+     * 
+     * This matches the bot's User ID.
+     */
+    _id: Id
+
+    /**
+     * Bot owner's User ID
+     */
+    owner: Id
+
+    /**
+     * Bot authentication token
+     */
+    token: string
+
+    /**
+     * Whether the bot can be added by anyone
+     */
+    public: boolean
+
+    /**
+     * Interactions endpoint URL
+     * 
+     * Required for dynamic interactions such as bot commands and message actions. Events will be sent over HTTP and a response may be generated directly.
+     */
+    interactionsURL: string
+}
+
+export interface PublicBot {
+    /**
+     * Bot ID
+     */
+    _id: Id
+
+    /**
+     * Bot username
+     */
+    username: Username
+
+    /**
+     * Bot avatar
+     */
+    avatar?: Attachment
+
+    /**
+     * Bot description, taken from profile text
+     */
+    description?: string
+}

types/Users.ts

@@ -66,6 +66,16 @@ export enum Badges {
     EarlyAdopter = 256,
 }
 
+/**
+ * Bot information
+ */
+export interface BotInformation {
+    /**
+     * The User ID of the owner of this bot
+     */
+    owner: Id
+}
+
 export interface User {
     /**
      * User ID
@@ -101,6 +111,20 @@ export interface User {
      * Whether the user is online
      */
     online?: boolean
+
+    /**
+     * User flags
+     * 
+     * `0x1`: Account is suspended
+     * `0x2`: Account was deleted
+     * `0x4`: Account is banned
+     */
+    flags?: number
+
+    /**
+     * Bot information, present if user is a bot.
+     */
+    bot?: BotInformation
 }
 
 export interface Profile {