chapterjs 0.3.0 → 0.5.0

package/dist/structures/channel.d.ts

@@ -1,3 +1,4 @@
+import { type CollectMessagesOptions, type WaitForMessageOptions } from './wait.js';
 import type { CacheStore } from '../cache/store.js';
 import { Permissions, type PermissionResolvable } from '../discord/permissions.js';
 import { ChannelType, type CreateChannelInviteJSONParams, type ModifyGuildChannelJSONParams, type ModifyThreadJSONParams, type RawChannel, type RawForumTag, type RawThreadMember, type StartThreadWithoutMessageJSONParams } from '../discord/types/channel.js';
@@ -117,6 +118,18 @@ export interface TextBasedMethods {
      * @see https://docs.discord.com/developers/resources/message#get-channel-pins
      */
     fetchPins(): Promise<Message[]>;
+    /**
+     * Waits for the next message of the channel that fits: of a person
+     * (`from`), saying something (`matches`). Anyone's but a bot's by
+     * default. Resolves with the message, or `null` when `within` (one
+     * minute by default) passed first. A restart of the bot ends the wait.
+     */
+    waitForMessage(options?: WaitForMessageOptions): Promise<Message | null>;
+    /**
+     * Gathers the messages of the channel that fit, until `within` (one
+     * minute by default) passed or `max` came. Resolves with them, in order.
+     */
+    collectMessages(options?: CollectMessagesOptions): Promise<Message[]>;
 }
 /** What a role or a member is allowed or denied in one channel. */
 export interface PermissionOverwrite {

package/dist/structures/channel.js

@@ -1,3 +1,4 @@
+import { personId, readMatches, readWithin, waitFor, } from './wait.js';
 import { Limits } from '../discord/api.js';
 import { AddThreadMember, BulkDeleteMessages, CreateChannelInvite, CreateWebhook, DeleteChannelPermission, DeleteCloseChannel, DeleteMessage, EditChannelPermissions, FollowAnnouncementChannel, GetChannel, GetChannelInvites, GetChannelMessage, GetChannelMessages, GetChannelPins, GetChannelWebhooks, JoinThread, LeaveThread, ListThreadMembers, ModifyChannel, RemoveThreadMember, SetVoiceChannelStatus, StartThreadInForumOrMediaChannel, StartThreadWithoutMessage, TriggerTypingIndicator, } from '../discord/endpoints.js';
 import { channelMention } from '../discord/formatting.js';
@@ -180,7 +181,30 @@ const textBasedMethods = {
             before = last.pinned_at;
         }
     },
+    async waitForMessage(options = {}) {
+        const [message] = await waitForMessages(this, options, 1);
+        return message ?? null;
+    },
+    collectMessages(options = {}) {
+        const { max } = options;
+        if (max !== undefined && (!Number.isInteger(max) || max < 1)) {
+            throw new RangeError(`"max" is how many messages to gather at most, a whole number from 1: got ${max}.`);
+        }
+        return waitForMessages(this, options, max ?? Infinity);
+    },
 };
+/**
+ * The next messages of a channel that fit the options: what
+ * `waitForMessage()` and `collectMessages()` share.
+ */
+function waitForMessages(channel, options, max) {
+    const within = readWithin(options.within);
+    const from = personId(options.from);
+    const says = readMatches(options.matches);
+    return waitFor(channel, 'message', message => message.channelId === channel.id &&
+        (from ? message.author.id === from : !message.author.bot) &&
+        says(message), within, max);
+}
 /**
  * A channel of a server (not a thread).
  * @see https://docs.discord.com/developers/resources/channel#channel-object

package/dist/structures/context.d.ts

@@ -3,6 +3,7 @@ import type { Snowflake } from '../discord/types/common.js';
 import type { LoadedMessages } from '../messages/translate.js';
 import type { Rest } from '../rest/rest.js';
 import type { VoiceManager } from '../voice/connection.js';
+import type { Waiters } from '../waiting/waiters.js';
 import type { Entities } from './entities.js';
 /**
  * What every structure works with. It never leaves the framework: user code
@@ -22,6 +23,8 @@ export interface Context {
     messages: LoadedMessages | null;
     /** Where the bot is in voice; `null` outside a running bot. */
     voice: VoiceManager | null;
+    /** What the files are waiting for; `null` outside a running bot. */
+    waiters: Waiters | null;
 }
 /** The identity of the bot, for actions that need it. */
 export declare function selfOf(ctx: Context): {

package/dist/structures/entities.js

@@ -220,6 +220,7 @@ export function createContext(input) {
         self: null,
         messages: null,
         voice: null,
+        waiters: null,
     };
     ctx.entities = new Entities(ctx);
     return ctx;

package/dist/structures/interaction.d.ts

@@ -13,6 +13,12 @@ import type { User } from './user.js';
 export type InteractionData = Omit<RawInteraction, 'user' | 'member' | 'message'>;
 /** Only the framework reads how far an interaction was answered. */
 export declare let isUpdating: (interaction: Interaction) => boolean;
+/**
+ * Resolves once every answer asked so far was sent (or refused): what the
+ * framework waits for before saying a function never answered, since an
+ * answer asked without `await` is still on its way when it returns.
+ */
+export declare let answersSent: (interaction: Interaction) => Promise<void>;
 /** An answer to an interaction: its text, or its options. */
 export type InteractionReply = string | InteractionReplyOptions;
 /** The options of an answer: everything a message takes, except `replyTo` and `stickers`. */

package/dist/structures/interaction.js

@@ -1,3 +1,4 @@
+import { callSite, fromSite } from '../util/call-site.js';
 import { CreateFollowupMessage, CreateInteractionResponse, DeleteOriginalInteractionResponse, EditOriginalInteractionResponse, GetOriginalInteractionResponse, } from '../discord/endpoints.js';
 import { renderedOf } from '../components/instance.js';
 import { InteractionCallbackType, } from '../discord/types/interaction.js';
@@ -9,6 +10,12 @@ import { resolve } from '../components/instance.js';
 import { translatorOf } from '../messages/translate.js';
 /** Only the framework reads how far an interaction was answered. */
 export let isUpdating;
+/**
+ * Resolves once every answer asked so far was sent (or refused): what the
+ * framework waits for before saying a function never answered, since an
+ * answer asked without `await` is still on its way when it returns.
+ */
+export let answersSent;
 /** Answers with a change of the message: see `ComponentInteraction.update()`. */
 let updateMessage;
 let deferUpdateMessage;
@@ -33,6 +40,14 @@ export class Interaction extends IdStructure {
     #queue = Promise.resolve();
     static {
         isUpdating = interaction => interaction.#state === 'updating';
+        answersSent = async (interaction) => {
+            // Answers asked while waiting are queued after the ones before.
+            let last = null;
+            while (last !== interaction.#queue) {
+                last = interaction.#queue;
+                await last;
+            }
+        };
         updateMessage = (interaction, message) => {
             const { body, files } = buildMessage(message, {
                 edit: true,
@@ -151,6 +166,8 @@ export class Interaction extends IdStructure {
      * error keeps the line of user code that asked for the answer.
      */
     async #run(action) {
+        // Where the files asked, for an answer refused later (`callSite`).
+        const site = callSite();
         const previous = this.#queue;
         let release;
         this.#queue = new Promise(resolve => (release = resolve));
@@ -158,6 +175,9 @@ export class Interaction extends IdStructure {
         try {
             return await action();
         }
+        catch (error) {
+            throw fromSite(error, site);
+        }
         finally {
             release();
         }

package/dist/structures/invite.d.ts

@@ -1,6 +1,7 @@
 import type { Snowflake } from '../discord/types/common.js';
 import type { RawInvite, RawInviteMetadata } from '../discord/types/invite.js';
 import { Structure } from './base.js';
+import type { GuildChannel } from './channel.js';
 import type { Context } from './context.js';
 import type { User } from './user.js';
 export type InviteData = Omit<RawInvite, 'inviter'> & Partial<RawInviteMetadata>;
@@ -20,6 +21,11 @@ export declare class Invite extends Structure<InviteData> {
     get guildId(): Snowflake | null;
     /** The id of the channel the invite leads to. */
     get channelId(): Snowflake | null;
+    /**
+     * The channel the invite leads to, when the bot knows it. It never sends
+     * a request.
+     */
+    get channel(): GuildChannel | null;
     /** When the invite stops working; `null` when it never does. */
     get expiresAt(): Date | null;
     /** How many times the invite was used, when Discord says it. */

package/dist/structures/invite.js

@@ -27,6 +27,17 @@ export class Invite extends Structure {
     get channelId() {
         return dataOf(this).channel?.id ?? null;
     }
+    /**
+     * The channel the invite leads to, when the bot knows it. It never sends
+     * a request.
+     */
+    get channel() {
+        const id = this.channelId;
+        const found = id ? ctxOf(this).cache.channels.get(id) : undefined;
+        return found && found.guildId !== null && !found.isThread()
+            ? found
+            : null;
+    }
     /** When the invite stops working; `null` when it never does. */
     get expiresAt() {
         return toDate(dataOf(this).expires_at);

package/dist/structures/message.d.ts

@@ -10,6 +10,7 @@ import type { Guild } from './guild.js';
 import type { GuildMember } from './member.js';
 import { type Embed, type MessageEditOptions, type MessageInput } from './payload.js';
 import type { User } from './user.js';
+import { type WaitedReaction, type Click, type WaitForClickOptions, type WaitForReactionOptions } from './wait.js';
 /** What the message stores: users are kept as structures, not copies. */
 export type MessageData = Omit<RawMessage, 'author' | 'mentions'> & {
     guild_id?: Snowflake;
@@ -148,6 +149,22 @@ export declare class Message extends IdStructure<MessageData> {
      * @see https://docs.discord.com/developers/resources/channel#start-thread-from-message
      */
     startThread(options: Camelize<StartThreadFromMessageJSONParams>, reason?: string): Promise<ThreadChannel>;
+    /**
+     * Waits for a click on a button or a menu of this message: of a person
+     * (`from`), anyone by default. Resolves with the click, to answer with
+     * `click.interaction`, or `null` when `within` (one minute by default)
+     * passed first. A click taken here does not run the `run` of the button;
+     * a button that is only waited for needs none. A restart of the bot ends
+     * the wait.
+     */
+    waitForClick(options?: WaitForClickOptions): Promise<Click | null>;
+    /**
+     * Waits for a reaction added to this message: of a person (`from`),
+     * anyone's but a bot's by default, with an emoji (`emoji`), any by
+     * default. Resolves with it, or `null` when `within` (one minute by
+     * default) passed first. A restart of the bot ends the wait.
+     */
+    waitForReaction(options?: WaitForReactionOptions): Promise<WaitedReaction | null>;
 }
 /** One mechanism to send a message, used by channels, replies and users. */
 export declare function sendMessage(ctx: Context, channelId: Snowflake, message: MessageInput, guildId?: Snowflake): Promise<Message>;

package/dist/structures/message.js

@@ -6,6 +6,7 @@ import { ctxOf, dataOf, idOf, IdStructure, toDate } from './base.js';
 import { findGuild, knownChannel, knownMember } from './known.js';
 import { buildMessage, } from './payload.js';
 import { translatorOf } from '../messages/translate.js';
+import { personId, readEmoji, readWithin, waitFor, } from './wait.js';
 function emojiPath(emoji) {
     if (typeof emoji !== 'string')
         return reactionEmoji(emoji);
@@ -251,6 +252,38 @@ export class Message extends IdStructure {
         const raw = await rest.request(StartThreadFromMessage, [this.channelId, this.id], { body: toSnakeCase(options), reason });
         return entities.channel(raw);
     }
+    /**
+     * Waits for a click on a button or a menu of this message: of a person
+     * (`from`), anyone by default. Resolves with the click, to answer with
+     * `click.interaction`, or `null` when `within` (one minute by default)
+     * passed first. A click taken here does not run the `run` of the button;
+     * a button that is only waited for needs none. A restart of the bot ends
+     * the wait.
+     */
+    async waitForClick(options = {}) {
+        const within = readWithin(options.within);
+        const from = personId(options.from);
+        const [click] = await waitFor(this, 'click', offered => offered.messageId === this.id && (!from || offered.user.id === from), within);
+        return click ?? null;
+    }
+    /**
+     * Waits for a reaction added to this message: of a person (`from`),
+     * anyone's but a bot's by default, with an emoji (`emoji`), any by
+     * default. Resolves with it, or `null` when `within` (one minute by
+     * default) passed first. A restart of the bot ends the wait.
+     */
+    async waitForReaction(options = {}) {
+        const within = readWithin(options.within);
+        const from = personId(options.from);
+        const isEmoji = readEmoji(options.emoji);
+        const [reaction] = await waitFor(this, 'reaction', offered => offered.messageId === this.id &&
+            (from ? offered.user.id === from : !offered.user.bot) &&
+            isEmoji(offered.emoji), within);
+        if (!reaction)
+            return null;
+        const { messageId: _, ...rest } = reaction;
+        return Object.freeze(rest);
+    }
 }
 /** One mechanism to send a message, used by channels, replies and users. */
 export async function sendMessage(ctx, channelId, message, guildId) {

package/dist/structures/wait.d.ts

@@ -0,0 +1,105 @@
+import type { Snowflake } from '../discord/types/common.js';
+import type { Duration } from '../commands/command.js';
+import type { ButtonDeclaration } from '../components/button.js';
+import type { SelectDeclaration } from '../components/select.js';
+import type { WaitKind } from '../waiting/waiters.js';
+import type { Context } from './context.js';
+import type { ComponentInteraction } from './interaction.js';
+import type { GuildMember } from './member.js';
+import type { Message, ReactionEmoji } from './message.js';
+import type { User } from './user.js';
+/** A person, as a wait takes it: a user, a member, or an id. */
+export type PersonInput = User | GuildMember | Snowflake;
+/** What `channel.waitForMessage()` takes. */
+export interface WaitForMessageOptions {
+    /** Only a message of this person. Anyone but a bot by default. */
+    from?: PersonInput;
+    /**
+     * Only a message that says this: a text (the same, whatever the capitals
+     * and the spaces around), a regular expression, or a function of the
+     * message.
+     */
+    matches?: string | RegExp | ((message: Message) => boolean);
+    /**
+     * How long to wait: `'30s'`, `'2m'`. One minute by default, a second at
+     * least, a day at most.
+     */
+    within?: Duration;
+}
+/** What `channel.collectMessages()` takes. */
+export interface CollectMessagesOptions extends WaitForMessageOptions {
+    /** Stops once this many messages came. No limit by default: until `within`. */
+    max?: number;
+}
+/** What `message.waitForClick()` takes. */
+export interface WaitForClickOptions {
+    /** Only a click of this person. Anyone by default. */
+    from?: PersonInput;
+    /** How long to wait: `'30s'`, `'2m'`. One minute by default. */
+    within?: Duration;
+}
+/** What `message.waitForReaction()` takes. */
+export interface WaitForReactionOptions {
+    /** Only a reaction of this person. Anyone but a bot by default. */
+    from?: PersonInput;
+    /**
+     * Only this emoji: a standard one (`'👍'`), or a custom one by its name,
+     * its id or as Discord writes it (`'<:party:123>'`).
+     */
+    emoji?: string;
+    /** How long to wait: `'30s'`, `'2m'`. One minute by default. */
+    within?: Duration;
+}
+/** A click on a button or a menu of a message, as `waitForClick()` gives it. */
+export interface Click {
+    /**
+     * The click itself: answer it as in the `run` of a button, with
+     * `update()`, `reply()` or `deferUpdate()`. Without an answer within 2
+     * seconds, the bot changes nothing on screen for you (`deferUpdate()`).
+     */
+    readonly interaction: ComponentInteraction;
+    /** Who clicked. */
+    readonly user: User;
+    /** Who clicked, as a member of the server; `null` in a private message. */
+    readonly member: GuildMember | null;
+    /** The name of the button or menu: the name of its export. */
+    readonly name: string;
+    /** The data the button or menu carries. */
+    readonly data: Readonly<Record<string, string | number | boolean>>;
+    /**
+     * What was picked in a menu: the values of a menu of texts, the ids of
+     * the people, roles or channels of the others. Empty for a button.
+     */
+    readonly values: readonly string[];
+    /** Whether it is this button or this menu. */
+    is(component: ButtonDeclaration<never> | SelectDeclaration<never>): boolean;
+}
+/** A reaction added to a message, as `waitForReaction()` gives it. */
+export interface WaitedReaction {
+    /** The emoji. */
+    readonly emoji: ReactionEmoji;
+    /** Who reacted. */
+    readonly user: User;
+    /** Who reacted, as a member of the server; `null` in a private message. */
+    readonly member: GuildMember | null;
+}
+/** What the bot offers the waits for a click: `components/router.ts` builds it. */
+export interface OfferedClick extends Click {
+    readonly messageId: Snowflake;
+}
+/** What the bot offers the waits for a reaction: `core/bot.ts` builds it. */
+export interface OfferedReaction extends WaitedReaction {
+    readonly messageId: Snowflake;
+}
+/** The milliseconds of `within`, checked. */
+export declare function readWithin(within: unknown): number;
+/** The id of a person a wait is given, checked. */
+export declare function personId(from: unknown): Snowflake | undefined;
+/** Whether a message says what `matches` asks. */
+export declare function readMatches(matches: unknown): (message: Message) => boolean;
+/** Whether an emoji is the one `emoji` names. */
+export declare function readEmoji(emoji: unknown): (given: ReactionEmoji) => boolean;
+/** The waits of the bot, or why there are none. */
+export declare function waitersOf(structure: object): NonNullable<Context['waiters']>;
+/** Waits for what fits, `max` at most: what was taken, in order. */
+export declare function waitFor<T>(structure: object, kind: WaitKind, match: (offered: T) => boolean, within: number, max?: number): Promise<T[]>;

package/dist/structures/wait.js

@@ -0,0 +1,85 @@
+// What a structure waits for: the options of `channel.waitForMessage()`,
+// `channel.collectMessages()`, `message.waitForClick()` and
+// `message.waitForReaction()`, checked, and turned into the test a wait of
+// `waiting/` runs on what the bot offers it.
+import { DURATION_EXAMPLE, parseDuration } from '../util/duration.js';
+import { ctxOf } from './base.js';
+/** One minute: how long a wait lasts when the file does not say. */
+const DEFAULT_WITHIN = 60_000;
+const MIN_WITHIN = 1_000;
+/** A day: longer would be lost by any restart anyway. */
+const MAX_WITHIN = 86_400_000;
+/** The milliseconds of `within`, checked. */
+export function readWithin(within) {
+    if (within === undefined)
+        return DEFAULT_WITHIN;
+    const ms = typeof within === 'string' ? parseDuration(within) : null;
+    if (ms === null) {
+        throw new TypeError(`"within" is how long to wait, a duration (${DURATION_EXAMPLE}): got ${JSON.stringify(within) ?? typeof within}.`);
+    }
+    if (ms < MIN_WITHIN || ms > MAX_WITHIN) {
+        throw new RangeError(`"within" is ${JSON.stringify(within)}: a wait lasts between 1 second and 1 day.`);
+    }
+    return ms;
+}
+/** The id of a person a wait is given, checked. */
+export function personId(from) {
+    if (from === undefined)
+        return undefined;
+    if (typeof from === 'string' && /^\d+$/.test(from))
+        return from;
+    if (typeof from === 'object' &&
+        from !== null &&
+        typeof from.id === 'string') {
+        return from.id;
+    }
+    throw new TypeError(`"from" is the person to wait for: a user, a member or their id, got ${JSON.stringify(from) ?? typeof from}.`);
+}
+/** Whether a message says what `matches` asks. */
+export function readMatches(matches) {
+    if (matches === undefined)
+        return () => true;
+    if (typeof matches === 'string') {
+        const wanted = matches.trim().toLowerCase();
+        return message => message.content.trim().toLowerCase() === wanted;
+    }
+    if (matches instanceof RegExp) {
+        // A global or sticky expression keeps where it stopped: test from the start.
+        return message => {
+            matches.lastIndex = 0;
+            return matches.test(message.content);
+        };
+    }
+    if (typeof matches === 'function') {
+        return message => matches(message) === true;
+    }
+    throw new TypeError(`"matches" is a text, a regular expression or a function of the message, like matches: 'paris' or matches: /^paris$/i.`);
+}
+/** Whether an emoji is the one `emoji` names. */
+export function readEmoji(emoji) {
+    if (emoji === undefined)
+        return () => true;
+    if (typeof emoji !== 'string' || emoji.trim() === '') {
+        throw new TypeError(`"emoji" is the emoji to wait for: '👍', or a custom one by its name, its id or as '<:name:id>'.`);
+    }
+    const custom = /^<a?:(\w+):(\d+)>$/.exec(emoji.trim());
+    const wanted = custom ? custom[2] : emoji.trim();
+    return given => given.id === wanted || given.name === wanted;
+}
+/** The waits of the bot, or why there are none. */
+export function waitersOf(structure) {
+    const { waiters } = ctxOf(structure);
+    if (!waiters) {
+        throw new Error('Waiting for what comes next only works in a running bot: in a command, an event, a component or a task.');
+    }
+    return waiters;
+}
+/** Waits for what fits, `max` at most: what was taken, in order. */
+export function waitFor(structure, kind, match, within, max = 1) {
+    return waitersOf(structure).wait({
+        kind,
+        match: offered => match(offered),
+        max,
+        within,
+    });
+}

package/dist/testing/harness.d.ts

@@ -1,10 +1,11 @@
 import type { PermissionName } from '../discord/permissions.js';
 import type { Locale } from '../discord/types/common.js';
 import { type RawEmbed } from '../discord/types/message.js';
-import type { CommandDeclaration, CommandOption, CommandOptions, CommandWhere } from '../commands/command.js';
+import type { CommandDeclaration, CommandOption, CommandOptions, CommandWhere, MenuDeclaration, MenuType } from '../commands/command.js';
 import type { ButtonDeclaration } from '../components/button.js';
 import { type ButtonComponent, type ModalComponent, type SelectComponent } from '../components/instance.js';
 import type { CheckboxesField, CheckboxField, EntityField, FilesField, ModalDeclaration, ModalField, ModalFields, NoteField, RadioField, SelectField, TextField } from '../components/modal.js';
+import type { DataShape } from '../components/custom-id.js';
 import type { OptionValue } from '../components/options.js';
 import type { SelectDeclaration } from '../components/select.js';
 import type { Bot } from '../core/bot.js';
@@ -190,8 +191,12 @@ export interface TestReply extends TestAssertions<TestReply> {
     isDeferred(): TestReply;
     /** Checks that the bot changed the message of the button or menu. */
     updatesMessage(): TestReply;
-    /** Checks that the bot opened a form, this one when given. */
-    opensForm(form?: ModalDeclaration<ModalFields, never> | TestForm): TestReply;
+    /**
+     * Checks that the bot opened a form, this one when given: its export
+     * (whatever data it carries), the form called with its data, or one found
+     * on an answer.
+     */
+    opensForm<Fields extends ModalFields, Data extends DataShape>(form?: ModalDeclaration<Fields, Data> | ModalComponent | TestForm): TestReply;
     /** Checks that the bot answered with nothing visible (a deferred update). */
     changesNothing(): TestReply;
     /** The button with this label, to click it. Fails when there is none. */
@@ -258,6 +263,14 @@ export type SelectInput = string | TestMember | TestRole | TestChannel;
 export type ButtonTarget = ButtonDeclaration<never> | ButtonComponent | TestButton;
 export type SelectTarget = SelectDeclaration<never> | SelectComponent | TestMenu;
 export type FormTarget<Fields extends ModalFields = ModalFields> = ModalDeclaration<Fields, never> | ModalComponent | TestForm;
+/**
+ * What a menu command is used on in a test: a person for a `'user'` menu,
+ * a message for a `'message'` menu.
+ */
+export type TestMenuTarget<Type extends MenuType = MenuType> = {
+    /** The person or the message the menu is used on. */
+    readonly on: Type extends 'user' ? TestMember : TestMessage;
+};
 /** The arguments of `bot.use()`: the options may be left out when none is required. */
 type UseArgs<Options extends CommandOptions> = {} extends OptionInputsOf<Options> ? [options?: OptionInputsOf<Options>, where?: TestWhere] : [options: OptionInputsOf<Options>, where?: TestWhere];
 /**
@@ -291,7 +304,13 @@ export interface TestBot {
     role(name: string, options?: TestRoleOptions): TestRole;
     /** A channel of the server, made the first time the name is given. `#general` exists. */
     channel(name: string, options?: TestChannelOptions): TestChannel;
-    /** Uses a slash command, as a person would. Resolves once the bot answered. */
+    /**
+     * Uses a command, as a person would: a slash command with its options,
+     * or a menu command on what it is used on (`{ on: message }`,
+     * `{ on: member }`; a message menu is used in the channel of its
+     * message). Resolves once the bot answered.
+     */
+    use<Type extends MenuType, Where extends CommandWhere>(command: MenuDeclaration<Type, Where>, target: TestMenuTarget<Type>, where?: TestWhere): Promise<TestReply>;
     use<Options extends CommandOptions, Where extends CommandWhere>(command: CommandDeclaration<Options, Where>, ...args: UseArgs<Options>): Promise<TestReply>;
     /** Clicks a button. Resolves once the bot answered. */
     click(button: ButtonTarget, where?: TestWhere): Promise<TestReply>;
@@ -311,6 +330,12 @@ export interface TestBot {
     leave(member: TestMember): Promise<void>;
     /** Runs a task now, as if its time had come. Resolves once it is done. */
     run(task: TaskDeclaration, at?: Date): Promise<void>;
+    /**
+     * Ends everything the bot waits for (`waitForMessage()`,
+     * `waitForClick()`...) as if its time was up: time does not pass in the
+     * test server. Resolves once the bot handled it.
+     */
+    endWaits(): Promise<void>;
     /** Waits for everything the bot started to be done. */
     settle(): Promise<void>;
 }
@@ -329,13 +354,26 @@ export declare function captureLog(): {
 export declare class Observer {
     #private;
     readonly observe: ProjectObserver;
-    /** 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(): void;
-    /** 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: string, timeout: number): Promise<void>;
-    /** 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: (event: string, data: unknown) => boolean, timeout: number): Promise<void>;
-    /** 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...).
+     */
     settle(): Promise<void>;
 }
 /** The bot in its world, with the handles a test works with. */
@@ -362,6 +400,7 @@ export declare class Session implements TestBot {
     member(name: string, options?: TestMemberOptions): TestMember;
     role(name: string, options?: TestRoleOptions): TestRole;
     channel(name: string, options?: TestChannelOptions): TestChannel;
+    use<Type extends MenuType, Where extends CommandWhere>(command: MenuDeclaration<Type, Where>, target: TestMenuTarget<Type>, where?: TestWhere): Promise<TestReply>;
     use<Options extends CommandOptions, Where extends CommandWhere>(command: CommandDeclaration<Options, Where>, ...args: UseArgs<Options>): Promise<TestReply>;
     suggest<Options extends CommandOptions, Where extends CommandWhere>(command: CommandDeclaration<Options, Where>, option: keyof Options & string, typed: string, where?: TestWhere): Promise<TestSuggestion[]>;
     click(button: ButtonTarget, where?: TestWhere): Promise<TestReply>;
@@ -373,6 +412,7 @@ export declare class Session implements TestBot {
     leave(member: TestMember): Promise<void>;
     run(task: TaskDeclaration, at?: Date): Promise<void>;
     settle(): Promise<void>;
+    endWaits(): Promise<void>;
     /**
      * 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.