chapterjs 0.3.0 → 0.5.0

package/dist/testing/harness.js

@@ -10,12 +10,17 @@ import { ComponentType, } from '../discord/types/component.js';
 import { InteractionType, } from '../discord/types/interaction.js';
 import { MessageFlags, MessageType, } from '../discord/types/message.js';
 import { PermissionFlags } from '../discord/types/permissions.js';
-import { commandName } from '../commands/tree.js';
+import { capitalize, commandName, describeCommand, } from '../commands/tree.js';
 import { componentStateOf } from '../components/declared.js';
 import { isPiece, renderedOf, resolve, } from '../components/instance.js';
 import { translatorOf } from '../messages/translate.js';
 import { toCamelCase } from '../util/case.js';
 import { expectThat, shown, TestFailure } from './failure.js';
+/** The type Discord gives each kind of menu command. */
+const MENU_COMMAND_TYPES = {
+    user: ApplicationCommandType.User,
+    message: ApplicationCommandType.Message,
+};
 /** A `Log` that keeps what is written, for the runner to show per check. */
 export function captureLog() {
     let current = { errors: [], warnings: [], infos: [] };
@@ -37,10 +42,27 @@ export function captureLog() {
 /** Watches what the bot does with the files, to wait for it. */
 export class Observer {
     #pending = new Set();
+    /**
+     * The runs of the files waiting for what comes next: each keeps one
+     * promise pending that only the test can end (`bot.say()`...).
+     */
+    #parked = new Set();
+    /** Resolves the next time a run starts or stops waiting. */
+    #parkChanged = () => { };
     #interactions = new Map();
     #interactionWaiters = new Map();
     #eventWaiters = [];
     observe = {
+        waits: {
+            parked: run => {
+                this.#parked.add(run);
+                this.#parkChanged();
+            },
+            resumed: run => {
+                this.#parked.delete(run);
+                this.#parkChanged();
+            },
+        },
         interaction: (raw, done) => {
             const settled = done.then(() => { }, () => { });
             this.#track(settled);
@@ -67,34 +89,47 @@ export class Observer {
         this.#pending.add(settled);
         settled.finally(() => this.#pending.delete(settled));
     }
-    /** Forgets the interactions seen so far: a new world starts. */
+    /**
+     * Forgets everything of the world before: a new world starts. What the
+     * files of the last one still run (a case given up on) is never waited
+     * for again.
+     */
     reset() {
         this.#interactions.clear();
+        this.#pending.clear();
+        this.#parked.clear();
+        this.#interactionWaiters.clear();
+        this.#eventWaiters.length = 0;
     }
-    /** Resolves once the files are done with the interaction `id`. */
+    /**
+     * Resolves once the files were given the interaction `id`: `settle()`
+     * then waits for them to be done with it.
+     */
     interaction(id, timeout) {
-        const known = this.#interactions.get(id);
-        if (known)
-            return known;
+        if (this.#interactions.has(id))
+            return Promise.resolve();
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
                 this.#interactionWaiters.delete(id);
                 reject(new TestFailure(`The bot did not receive the interaction within ${timeout / 1000} s.`));
             }, timeout);
-            this.#interactionWaiters.set(id, done => {
+            this.#interactionWaiters.set(id, () => {
                 clearTimeout(timer);
-                resolve(done);
+                resolve();
             });
         });
     }
-    /** Resolves once the files are done with the next event that matches. */
+    /**
+     * Resolves once the files were given the next event that matches:
+     * `settle()` then waits for them to be done with it.
+     */
     event(match, timeout) {
         return new Promise((resolve, reject) => {
             const waiter = {
                 match,
-                resolve: (done) => {
+                resolve: () => {
                     clearTimeout(timer);
-                    resolve(done);
+                    resolve();
                 },
             };
             const timer = setTimeout(() => {
@@ -106,13 +141,22 @@ export class Observer {
             this.#eventWaiters.push(waiter);
         });
     }
-    /** Resolves once nothing the files started is still running. */
+    /**
+     * Resolves once nothing the files started is still running, but what
+     * waits for the test to act (a run waiting for a message, a click...).
+     */
     async settle() {
-        while (this.#pending.size > 0) {
-            await Promise.all([...this.#pending]);
-        }
-        // Answers sent at the very end have reached the world by now.
-        await new Promise(resolve => setImmediate(resolve));
+        do {
+            while (this.#pending.size > this.#parked.size) {
+                const changed = new Promise(resolve => (this.#parkChanged = resolve));
+                // Looked at again as soon as one is done: the one left may be a
+                // run that waits, which only the test ends.
+                await Promise.race([...this.#pending, changed]);
+            }
+            // Answers sent at the very end have reached the world by now, and a
+            // wait given what just happened has started running again.
+            await new Promise(resolve => setImmediate(resolve));
+        } while (this.#pending.size > this.#parked.size);
     }
 }
 // ── The handles ──────────────────────────────────────────────────────
@@ -170,13 +214,24 @@ function collectComponents(components) {
     walk(components);
     return { buttons, menus };
 }
-const buttonHandle = (raw) => Object.freeze({
+/**
+ * The message a button or a menu was found on, kept out of sight: clicking
+ * it clicks that message, as a person would.
+ */
+const FOUND_ON = Symbol('found on');
+/** The id of the message a handle was found on, if it was found on one. */
+const foundOn = (target) => typeof target === 'object' && target !== null
+    ? target[FOUND_ON]
+    : undefined;
+/** Keeps the message a handle was found on, without showing it. */
+const onMessage = (handle, messageId) => Object.freeze(Object.defineProperty(handle, FOUND_ON, { value: messageId }));
+const buttonHandle = (raw, messageId) => onMessage({
     label: raw.label ?? null,
     style: BUTTON_STYLES[raw.style] ?? 'secondary',
     disabled: raw.disabled === true,
     customId: raw.custom_id ?? null,
-});
-const menuHandle = (raw) => Object.freeze({
+}, messageId);
+const menuHandle = (raw, messageId) => onMessage({
     type: MENU_TYPES[raw.type] ?? 'string',
     placeholder: raw.placeholder ?? null,
     disabled: raw.disabled === true,
@@ -187,7 +242,7 @@ const menuHandle = (raw) => Object.freeze({
         }))
         : [],
     customId: raw.custom_id,
-});
+}, messageId);
 /** Checks a message or an answer; written once for both. */
 function check(self, what, get) {
     const present = () => {
@@ -442,8 +497,8 @@ export class Session {
             return {
                 content: message.content,
                 embeds: toCamelCase(message.embeds),
-                buttons: buttons.map(buttonHandle),
-                menus: menus.map(menuHandle),
+                buttons: buttons.map(button => buttonHandle(button, raw.id)),
+                menus: menus.map(menu => menuHandle(menu, raw.id)),
                 ephemeral: ((message.flags ?? 0) & MessageFlags.Ephemeral) !== 0,
                 present: true,
             };
@@ -563,9 +618,14 @@ export class Session {
             opensForm(form) {
                 expectThat(record.modal !== null, `The bot should have opened a form, it ${record.original ? `answered ${shown(record.original.content)}` : 'opened none'}.`);
                 if (form) {
-                    const expected = 'customId' in form
-                        ? form.customId
-                        : self.#customIdOf(form, 'modal');
+                    // Only the name is compared: the form itself names it, with no
+                    // need for the data it was opened with.
+                    const state = componentStateOf(form);
+                    const expected = state?.kind === 'modal' && state.bound
+                        ? state.bound.name
+                        : typeof form === 'object' && 'customId' in form
+                            ? form.customId
+                            : self.#customIdOf(form, 'modal');
                     const opened = record.modal.custom_id.split(':')[0];
                     expectThat(opened === expected.split(':')[0], `The bot should have opened the form ${expected.split(':')[0]}, it opened ${opened}.`);
                 }
@@ -740,8 +800,11 @@ export class Session {
         return entry;
     }
     async use(command, ...args) {
-        const [given = {}, where] = args;
         const entry = this.#commandEntry(command);
+        if (entry.command.type !== 'slash') {
+            return this.#useMenu(entry, args[0], args[1]);
+        }
+        const [given = {}, where] = args;
         const actor = this.#actor(where);
         const channel = this.#place(where, actor, entry.command.where === 'dm');
         const { options, resolved } = this.#commandOptions(entry, given, channel);
@@ -773,6 +836,54 @@ export class Session {
             value: choice.value,
         }));
     }
+    /**
+     * Uses a menu command on a person or a message, as Discord's client
+     * does: on a message, in the channel of that message; on a person, where
+     * `where` says (`#general`, or the private conversation of a
+     * `where: 'dm'` command, by default).
+     */
+    async #useMenu(entry, target, where) {
+        const { type, path, where: place } = entry.command;
+        const kind = MENU_COMMAND_TYPES[type];
+        const name = describeCommand(entry.command);
+        const on = target?.on;
+        const actor = this.#actor(where);
+        const resolved = {};
+        let channel;
+        let targetId;
+        if (type === 'message') {
+            const message = on && !this.#isMember(on) ? this.world.findMessage(on.id) : undefined;
+            if (!message) {
+                throw new TestFailure(on && !this.#isMember(on)
+                    ? `The message ${on.id} does not exist any more: ${name} can not be used on it.`
+                    : `${capitalize(name)} is used on a message: bot.use(command, { on: message }), with a message of the test (await bot.say('...'), or one the bot sent).`);
+            }
+            const found = this.world.channels.get(message.channel_id);
+            if (!found) {
+                throw new TestFailure(`The channel of the message ${message.id} does not exist any more.`);
+            }
+            channel = found;
+            targetId = message.id;
+            (resolved.messages ??= {})[message.id] = message;
+        }
+        else {
+            if (!this.#isMember(on)) {
+                throw new TestFailure(`${capitalize(name)} is used on a person: bot.use(command, { on: bot.member('alice') }).`);
+            }
+            channel = this.#place(where, actor, place === 'dm');
+            targetId = this.#resolveMember(`${capitalize(name)}`, on, resolved, channel);
+        }
+        const registered = this.world.guildCommands.find(command => command.name === path[0] && command.type === kind);
+        const raw = this.#rawInteraction(InteractionType.ApplicationCommand, actor, channel, {
+            id: registered?.id ?? this.world.snowflake(),
+            name: path[0],
+            type: kind,
+            target_id: targetId,
+            resolved,
+            ...(channel.guild_id ? { guild_id: channel.guild_id } : {}),
+        });
+        return this.#reply(await this.#interact(raw));
+    }
     /** The `data` of a command interaction, subcommands nested as Discord does. */
     #commandData(entry, options, resolved) {
         const [name, ...rest] = entry.command.path;
@@ -788,7 +899,9 @@ export class Session {
                 },
             ];
         }
-        const registered = this.world.guildCommands.find(command => command.name === name);
+        const registered = this.world.guildCommands.find(command => command.name === name &&
+            (command.type ?? ApplicationCommandType.ChatInput) ===
+                ApplicationCommandType.ChatInput);
         return {
             id: registered?.id ?? this.world.snowflake(),
             name: name,
@@ -991,8 +1104,13 @@ export class Session {
         return [...this.project.components.values()].find(entry => entry.component.kind === kind && entry.component.name === name);
     }
     /** The message a component is on: the one given, or one of the bot. */
-    #messageFor(where, actor, channel, component) {
+    #messageFor(where, actor, channel, component, target) {
         const given = where?.on;
+        // Found on a message: that message, as long as it is there.
+        const found = given ? undefined : foundOn(target);
+        const sent = found ? this.world.findMessage(found) : undefined;
+        if (sent)
+            return sent;
         if (given) {
             const id = 'message' in given ? given.message?.id : given.id;
             const found = id ? this.world.findMessage(id) : undefined;
@@ -1036,11 +1154,7 @@ export class Session {
         const entry = this.#componentEntry('button', customId);
         const actor = this.#actor(where);
         const channel = this.#place(where, actor, entry?.component.kind === 'button' && entry.component.where === 'dm');
-        const message = this.#messageFor(where, actor, channel, {
-            type: ComponentType.Button,
-            style: 2,
-            custom_id: customId,
-        });
+        const message = this.#messageFor(where, actor, channel, { type: ComponentType.Button, style: 2, custom_id: customId }, button);
         const raw = this.#rawInteraction(InteractionType.MessageComponent, actor, channel, { custom_id: customId, component_type: ComponentType.Button }, message);
         return this.#reply(await this.#interact(raw));
     }
@@ -1091,8 +1205,10 @@ export class Session {
         const message = this.#messageFor(where, actor, channel, {
             type: componentType,
             custom_id: customId,
-            ...(componentType === ComponentType.StringSelect ? { options: [] } : {}),
-        });
+            ...(componentType === ComponentType.StringSelect
+                ? { options: [] }
+                : {}),
+        }, menu);
         const raw = this.#rawInteraction(InteractionType.MessageComponent, actor, channel, {
             custom_id: customId,
             component_type: componentType,
@@ -1377,6 +1493,10 @@ export class Session {
     settle() {
         return this.#observer.settle();
     }
+    async endWaits() {
+        this.bot.ctx.waiters?.close();
+        await this.#observer.settle();
+    }
     /**
      * Sends a gateway event to the bot and waits for the files to be done
      * with it. For the checks of `chapterjs test`, not for scenarios.

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
 export { scenario } from './scenario.js';
 export type { ScenarioDeclaration } from './scenario.js';
 export { TestFailure } from './failure.js';
-export type { ButtonTarget, FieldInputsOf, FormTarget, OptionInputsOf, SelectInput, SelectTarget, TestAssertions, TestBot, TestButton, TestChannel, TestChannelOptions, TestChannelType, TestFile, TestForm, TestMember, TestMemberOptions, TestMenu, TestMessage, TestReply, TestRole, TestRoleOptions, TestSuggestion, TestWhere, } from './harness.js';
+export type { ButtonTarget, FieldInputsOf, FormTarget, OptionInputsOf, SelectInput, SelectTarget, TestAssertions, TestBot, TestButton, TestChannel, TestChannelOptions, TestChannelType, TestFile, TestForm, TestMember, TestMemberOptions, TestMenu, TestMenuTarget, TestMessage, TestReply, TestRole, TestRoleOptions, TestSuggestion, TestWhere, } from './harness.js';

package/dist/testing/smoke.js

@@ -5,7 +5,7 @@
 // function threw: the content is the scenarios' business.
 import { Permissions } from '../discord/permissions.js';
 import { ChannelType } from '../discord/types/channel.js';
-import { commandName } from '../commands/tree.js';
+import { commandName, describeCommand, } from '../commands/tree.js';
 import { EVENTS } from '../events/registry.js';
 const UNICODE = '🙂 héllo wörld — ça va ?';
 const FILE = {
@@ -152,9 +152,90 @@ function hard(option) {
             ];
     }
 }
+/** The longest message Discord accepts. */
+const MAX_MESSAGE = 2000;
+/**
+ * The checks of a menu command: used on an ordinary message or person, and
+ * on the hard ones (a message at its longest, the bot, the owner, someone
+ * who left...).
+ */
+function menuCheck({ command, file }) {
+    const declaration = { config: { run: command.run } };
+    const subject = describeCommand(command);
+    const dm = command.where === 'dm';
+    const cases = [];
+    const use = (session, on, where = {}) => {
+        const by = userFor(session, command);
+        return Promise.resolve(on(session, by))
+            .then(target => session.use(declaration, { on: target }, {
+            by,
+            ...where,
+        }))
+            .then(() => { });
+    };
+    if (command.type === 'message') {
+        // The message is written where the menu is used.
+        const say = (content, author) => (session, by) => session.say(content, {
+            by: author?.(session) ?? session.someone,
+            ...(dm ? { in: 'dm', by } : {}),
+        });
+        cases.push({ label: 'on a message', run: session => use(session, say('Hello!')) }, {
+            label: 'on a message at its longest, with unicode',
+            run: session => use(session, say(`${UNICODE} ${textOf(MAX_MESSAGE)}`.slice(0, MAX_MESSAGE))),
+        });
+        if (!dm) {
+            cases.push({
+                label: 'on a message of the owner',
+                run: session => use(session, say('Hello!', current => current.owner)),
+            }, {
+                label: 'on a message of someone who left',
+                run: session => use(session, async (current, by) => {
+                    // Someone of its own, who writes and then leaves.
+                    const writer = current.member('gone-writer');
+                    const message = await say('Hello!', () => writer)(current, by);
+                    current.world.members.delete(writer.id);
+                    return message;
+                }),
+            });
+        }
+        if (command.where === 'both') {
+            cases.push({
+                label: 'in a private message',
+                run: session => use(session, (current, by) => current.say('Hello!', { by, in: 'dm' })),
+            });
+        }
+        return { subject, file, cases };
+    }
+    cases.push({
+        label: 'on someone',
+        run: session => use(session, current => current.member('alice')),
+    }, { label: 'on who uses it', run: session => use(session, (_, by) => by) }, { label: 'on the bot', run: session => use(session, current => current.me) });
+    if (!dm) {
+        cases.push({
+            label: 'on the owner',
+            run: session => use(session, current => current.owner),
+        }, {
+            label: 'on someone who left',
+            run: session => use(session, current => {
+                const gone = current.member('gone');
+                current.world.members.delete(gone.id);
+                return gone;
+            }),
+        });
+    }
+    if (command.where === 'both') {
+        cases.push({
+            label: 'in a private message',
+            run: session => use(session, (_, by) => by, { in: 'dm' }),
+        });
+    }
+    return { subject, file, cases };
+}
 /** The checks of the commands. */
 function commandChecks(project) {
     return [...project.commands.values()].map((entry) => {
+        if (entry.command.type !== 'slash')
+            return menuCheck(entry);
         const { command, file } = entry;
         const declaration = { config: { run: command.run } };
         const subject = `command ${commandName(command.path)}`;
@@ -274,6 +355,9 @@ function componentChecks(project) {
         const { component, file } = entry;
         if (component.kind === 'embed')
             continue;
+        // Only waited for (`message.waitForClick()`): nothing of its own runs.
+        if (component.kind !== 'modal' && !component.run)
+            continue;
         const { name, data } = component;
         const target = (values) => ({
             customId: [
@@ -644,6 +728,32 @@ function taskChecks(project) {
         ],
     }));
 }
+/**
+ * The check of the presence, when it has functions: each runs once, as
+ * the rotation would run it.
+ */
+function presenceChecks(project) {
+    const file = project.presenceFile;
+    const presence = project.presence;
+    if (!file || !presence)
+        return [];
+    const hasFunctions = typeof presence.activities === 'function' ||
+        presence.activities.some(one => typeof one.name === 'function');
+    if (!hasFunctions)
+        return [];
+    return [
+        {
+            subject: 'the presence',
+            file,
+            cases: [
+                {
+                    label: 'once',
+                    run: session => session.project.runPresence(session.bot),
+                },
+            ],
+        },
+    ];
+}
 /** Every check of the project, in the order of the report. */
 export function smokeChecks(project) {
     const events = eventChecks(project);
@@ -653,6 +763,7 @@ export function smokeChecks(project) {
             ...componentChecks(project),
             ...events.checks,
             ...taskChecks(project),
+            ...presenceChecks(project),
         ],
         notSimulated: events.notSimulated,
     };

package/dist/testing/world.js

@@ -59,6 +59,11 @@ const unknown = (what, code) => ({
     status: 404,
     body: { message: `Unknown ${what}`, code },
 });
+/** What Discord answers an action the bot is not high enough for. */
+const MISSING_PERMISSIONS = {
+    status: 403,
+    body: { message: 'Missing Permissions', code: 50013 },
+};
 /** The regular expression matching a documented path, placeholders filled. */
 function patternOf(path) {
     const source = path
@@ -238,15 +243,49 @@ export class World {
                 tertiary_color: null,
             },
             hoist: false,
-            position: options.position ?? this.roles.size,
+            position: options.position ?? 1,
             permissions: (options.permissions ?? 0n).toString(),
             managed: false,
             mentionable: false,
             flags: 0,
         };
+        // A new role goes at the bottom, just above @everyone, as Discord
+        // places it: the ones from there up move up one.
+        for (const other of this.roles.values()) {
+            if (other.position >= role.position && other.id !== this.guildId)
+                other.position += 1;
+        }
         this.roles.set(role.id, role);
         return role;
     }
+    /**
+     * Whether the bot may act on someone: kick, ban, change their nickname,
+     * roles or timeout. Never on the owner of the server, and only on members
+     * whose highest role is lower than the bot's.
+     * @see https://docs.discord.com/developers/topics/permissions#permission-hierarchy
+     */
+    #outranks(userId) {
+        if (userId === this.ownerId)
+            return false;
+        if (userId === this.botId)
+            return true;
+        const member = this.members.get(userId);
+        return !member || this.#highest(this.botId) > this.#highest(userId);
+    }
+    /**
+     * Whether the bot may give or take this role from someone: a role lower
+     * than its highest, on someone it outranks (itself included).
+     */
+    #givable(userId, roleId) {
+        const role = this.roles.get(roleId);
+        return (this.#outranks(userId) &&
+            (role?.position ?? 0) < this.#highest(this.botId));
+    }
+    /** The position of someone's highest role (0: @everyone only). */
+    #highest(userId) {
+        const member = this.members.get(userId);
+        return Math.max(0, ...(member?.roles ?? []).map(id => this.roles.get(id)?.position ?? 0));
+    }
     addChannel(name, options = {}) {
         const channel = {
             id: this.snowflake(),
@@ -750,6 +789,8 @@ export class World {
                 return found.refused;
             const { member } = found;
             const changes = body(request);
+            if (!this.#outranks(userId))
+                return MISSING_PERMISSIONS;
             if ('nick' in changes)
                 member.nick = changes.nick ?? null;
             if (Array.isArray(changes.roles))
@@ -783,6 +824,8 @@ export class World {
                 return found.refused;
             if (!this.roles.has(roleId))
                 return unknown('Role', 10011);
+            if (!this.#givable(userId, roleId))
+                return MISSING_PERMISSIONS;
             if (!found.member.roles.includes(roleId))
                 found.member.roles.push(roleId);
             this.memberUpdated(found.member);
@@ -794,6 +837,8 @@ export class World {
                 return found.refused;
             if (!this.roles.has(roleId))
                 return unknown('Role', 10011);
+            if (!this.#givable(userId, roleId))
+                return MISSING_PERMISSIONS;
             found.member.roles = found.member.roles.filter(id => id !== roleId);
             this.memberUpdated(found.member);
             return {};
@@ -802,6 +847,8 @@ export class World {
             const found = memberOr404(guildId, userId);
             if ('refused' in found)
                 return found.refused;
+            if (!this.#outranks(userId))
+                return MISSING_PERMISSIONS;
             this.removeMember(userId);
             return {};
         });
@@ -828,6 +875,8 @@ export class World {
             const user = this.users.get(userId);
             if (!user)
                 return unknown('User', 10013);
+            if (!this.#outranks(userId))
+                return MISSING_PERMISSIONS;
             const reason = request.headers['x-audit-log-reason'];
             this.bans.set(userId, {
                 user,
@@ -863,7 +912,7 @@ export class World {
             const failed = [];
             for (const id of ids) {
                 const user = this.users.get(id);
-                if (!user || this.bans.has(id)) {
+                if (!user || this.bans.has(id) || !this.#outranks(id)) {
                     failed.push(id);
                     continue;
                 }

package/dist/util/call-site.d.ts

@@ -0,0 +1,4 @@
+/** The stack of the moment a call is made. */
+export declare function callSite(): Error;
+/** Adds where the call was made to an error that came later. */
+export declare function fromSite(error: unknown, site: Error): unknown;

package/dist/util/call-site.js

@@ -0,0 +1,22 @@
+// Where a call of the files was made, for an error that comes later. An
+// error made after an `await` only has the lines of the files in its stack
+// when they awaited the call: `member.ban()` written without `await`, and
+// refused by Discord, would point nowhere in the project. `callSite()` is
+// taken when the call is made, before anything is awaited, and
+// `fromSite()` adds its lines to the error, so `locate()` finds the line
+// that asked whether the call was awaited or not.
+/** The stack of the moment a call is made. */
+export function callSite() {
+    return new Error('Called here');
+}
+/** Adds where the call was made to an error that came later. */
+export function fromSite(error, site) {
+    if (!(error instanceof Error) || typeof error.stack !== 'string') {
+        return error;
+    }
+    const frames = (site.stack ?? '').split('\n').slice(1).join('\n');
+    if (frames && !error.stack.includes(frames)) {
+        error.stack = `${error.stack}\n${frames}`;
+    }
+    return error;
+}

package/dist/voice/connection.d.ts

@@ -69,6 +69,8 @@ export declare class VoiceManager {
         secure?: boolean;
         joinTimeout?: number;
         endedGrace?: number;
+        /** Where nothing can play: what `join()` says at once. */
+        unavailable?: string;
     });
     /** The connection of the bot in a server, if it is in voice there. */
     connectionOf(guildId: Snowflake): VoiceConnection | null;