chapterjs 0.1.2 → 0.2.0

package/dist/components/router.js

@@ -0,0 +1,251 @@
+// Runs the component someone used: reads the id the framework wrote in it,
+// finds its declaration, turns what Discord sent into what `run` receives,
+// and makes sure the person always gets an answer.
+import { ComponentType, } from '../discord/types/component.js';
+import { InteractionType, } from '../discord/types/interaction.js';
+import { MessageFlags } from '../discord/types/message.js';
+import { authorOf, placeContext, refuse, resolvePlace, runInteraction, } from '../interactions/dispatch.js';
+import { audienceLocale, translation } from '../messages/translate.js';
+import { ComponentInteraction, ModalInteraction, } from '../structures/interaction.js';
+import { remember } from '../structures/known.js';
+import { toCamelCase } from '../util/case.js';
+import { decodeCustomId, readData } from './custom-id.js';
+import { SELECT_TYPES } from './select.js';
+/** What a component is called, for the person and the developer. */
+const WHAT_OF = {
+    button: 'button',
+    select: 'menu',
+    modal: 'form',
+};
+export class ComponentRouter {
+    #components = new Map();
+    #options;
+    constructor(options) {
+        this.#options = options;
+    }
+    /** Replaces every component (after a load or a reload). */
+    set(entries) {
+        const components = new Map();
+        for (const entry of entries) {
+            if (entry.component.kind !== 'embed') {
+                components.set(`${entry.component.kind}:${entry.component.name}`, entry);
+            }
+        }
+        this.#components = components;
+    }
+    /** Handles an Interaction Create event, if it is a component or a form. */
+    dispatch(ctx, raw) {
+        const isComponent = raw.type === InteractionType.MessageComponent;
+        const isModal = raw.type === InteractionType.ModalSubmit;
+        if (!isComponent && !isModal)
+            return;
+        const data = raw.data;
+        if (!data || typeof data.custom_id !== 'string')
+            return;
+        const author = authorOf(raw);
+        if (!author)
+            return;
+        const user = ctx.entities.user(author.user);
+        const { user: _user, member: _member, message: rawMessage, ...rest } = raw;
+        const message = rawMessage
+            ? ctx.entities.message(rawMessage, raw.guild_id)
+            : null;
+        // Only the person sees an ephemeral message: what answers a component
+        // on it (an update of that message, a reply) stays with them, whatever
+        // the file says, so `t` speaks their language.
+        // https://docs.discord.com/developers/resources/message#message-object-message-flags
+        const isPrivate = ((rawMessage?.flags ?? 0) &
+            MessageFlags.Ephemeral) !==
+            0;
+        const ephemeralOf = (component) => isPrivate || ('ephemeral' in component && component.ephemeral);
+        const { name, parts } = decodeCustomId(data.custom_id);
+        // A button, a menu and a form may share a name: what was used says
+        // which one is meant.
+        const kind = isModal
+            ? 'modal'
+            : data.component_type ===
+                ComponentType.Button
+                ? 'button'
+                : 'select';
+        const entry = this.#components.get(`${kind}:${name}`);
+        const what = WHAT_OF[kind];
+        const interaction = isModal
+            ? new ModalInteraction(ctx, rest, user, {
+                ephemeral: entry ? ephemeralOf(entry.component) : isPrivate,
+                message,
+            })
+            : new ComponentInteraction(ctx, rest, user, {
+                ephemeral: entry ? ephemeralOf(entry.component) : isPrivate,
+                message: message,
+            });
+        if (isComponent && !message)
+            return;
+        // Embeds are never in the map: what is left has a `run`.
+        if (!entry ||
+            entry.component.kind === 'embed' ||
+            (entry.component.kind === 'select' &&
+                SELECT_TYPES[entry.component.type] !==
+                    data.component_type)) {
+            // Sent before the export was renamed, removed or changed of kind.
+            refuse(interaction, 'gone', { what });
+            return;
+        }
+        const { component, file } = entry;
+        const values = readData(component.data, parts);
+        if (!values) {
+            // The data of the component changed since the message was sent.
+            refuse(interaction, 'outdated', { what });
+            return;
+        }
+        const placed = resolvePlace(ctx, raw, user, author.member, component.where, warning => this.#options.onWarning(file, `${name} ${warning}`));
+        if (!placed.place) {
+            refuse(interaction, placed.refusal, { what });
+            return;
+        }
+        const { place } = placed;
+        if (component.kind !== 'modal' &&
+            component.who === 'author' &&
+            rawMessage?.interaction_metadata?.user.id !== user.id) {
+            refuse(interaction, 'authorOnly', { what });
+            return;
+        }
+        remember(interaction, {
+            guild: place.guild ?? undefined,
+            member: place.member ?? undefined,
+            channel: place.channel,
+        });
+        let specific;
+        try {
+            specific =
+                component.kind === 'modal'
+                    ? {
+                        fields: this.#readFields(ctx, raw, component.fields, data),
+                    }
+                    : component.kind === 'select'
+                        ? this.#readValues(ctx, raw, component.type, data)
+                        : {};
+        }
+        catch (error) {
+            this.#options.onError(file, error);
+            refuse(interaction, 'failed', { what });
+            return;
+        }
+        const context = Object.freeze({
+            interaction,
+            user,
+            message,
+            data: Object.freeze(values),
+            ...specific,
+            ...placeContext(place, component.where),
+            // `t` speaks the language of who will read the answer.
+            ...translation(ctx, audienceLocale({
+                person: raw.locale,
+                guild: place.guild,
+                ephemeral: ephemeralOf(component),
+            })),
+        });
+        runInteraction({
+            interaction,
+            file,
+            name,
+            what,
+            reporter: this.#options,
+            // Nothing changes on screen while a component is answered; a form
+            // sent is like a command used.
+            defer: () => interaction instanceof ComponentInteraction
+                ? interaction.deferUpdate()
+                : interaction.defer(),
+            unanswered: `finished without answering: the person sees "This interaction failed". Call interaction.update() or interaction.reply() in run${component.kind === 'modal' ? '' : ', or interaction.deferUpdate() to change nothing'}.`,
+            run: () => component.run(context),
+        });
+    }
+    /** What the person picked in a menu, as structures where it applies. */
+    #readValues(ctx, raw, type, data) {
+        const values = resolveValues(ctx, raw, type, data.values ?? [], data.resolved ?? {});
+        return { values, value: values[0] };
+    }
+    /** What the person filled in, field by field. */
+    #readFields(ctx, raw, fields, data) {
+        const sent = new Map();
+        for (const top of data.components ?? []) {
+            if (top.type === ComponentType.Label && top.component?.custom_id) {
+                sent.set(top.component.custom_id, top.component);
+            }
+        }
+        const resolved = data.resolved ?? {};
+        const result = {};
+        for (const { name, field, required } of fields) {
+            if (field.type === 'note')
+                continue;
+            const input = sent.get(name);
+            switch (field.type) {
+                case 'text': {
+                    const text = input && 'value' in input ? input.value : '';
+                    result[name] = text === '' && !required ? undefined : text;
+                    break;
+                }
+                case 'radio': {
+                    const value = input && 'value' in input ? input.value : null;
+                    result[name] = value === null || value === '' ? undefined : value;
+                    break;
+                }
+                case 'checkbox':
+                    result[name] =
+                        input && 'value' in input ? input.value === true : false;
+                    break;
+                case 'select':
+                case 'checkboxes':
+                    result[name] =
+                        input && 'values' in input ? [...input.values] : [];
+                    break;
+                case 'files':
+                    result[name] = (input && 'values' in input ? input.values : [])
+                        .map(id => {
+                        const attachment = resolved.attachments?.[id];
+                        return attachment ? toCamelCase(attachment) : undefined;
+                    })
+                        .filter(one => one !== undefined);
+                    break;
+                default:
+                    result[name] = resolveValues(ctx, raw, field.type, input && 'values' in input ? input.values : [], resolved);
+            }
+        }
+        return result;
+    }
+}
+/** The things picked in a menu of the server, as structures. */
+function resolveValues(ctx, raw, type, ids, resolved) {
+    if (type === 'string')
+        return [...ids];
+    const guildId = raw.guild_id;
+    const userOf = (id) => {
+        const rawUser = resolved.users?.[id];
+        if (!rawUser)
+            return undefined;
+        const member = resolved.members?.[id];
+        if (member && guildId) {
+            ctx.entities.member(guildId, member, rawUser);
+        }
+        return ctx.entities.user(rawUser);
+    };
+    const roleOf = (id) => {
+        const role = resolved.roles?.[id];
+        return role && guildId ? ctx.entities.role(guildId, role) : undefined;
+    };
+    const channelOf = (id) => {
+        const partial = resolved.channels?.[id];
+        return (ctx.cache.channels.get(id) ??
+            (partial
+                ? ctx.entities.channel(partial, guildId)
+                : undefined));
+    };
+    return ids
+        .map(id => type === 'user'
+        ? userOf(id)
+        : type === 'role'
+            ? roleOf(id)
+            : type === 'channel'
+                ? channelOf(id)
+                : (userOf(id) ?? roleOf(id)))
+        .filter(one => one !== undefined);
+}

package/dist/components/select.d.ts

@@ -0,0 +1,146 @@
+import type { Snowflake } from '../discord/types/common.js';
+import { ChannelType } from '../discord/types/channel.js';
+import { type RawSelectMenu } from '../discord/types/component.js';
+import type { Channel } from '../structures/channel.js';
+import type { ComponentInteraction } from '../structures/interaction.js';
+import type { Role } from '../structures/role.js';
+import type { User } from '../structures/user.js';
+import type { TranslationContext } from '../messages/messages.js';
+import { type DynamicText } from './component.js';
+import type { ComponentWhere, InteractiveConfig, InteractiveContext, PlaceOf } from './component.js';
+import { type DataShape, type DataInputOf } from './custom-id.js';
+import type { Rendered, SelectComponent } from './instance.js';
+import { type LoadedOption, type OptionValue, type SelectOptions } from './options.js';
+/** The kinds of menus: texts you declare, or things of the server. */
+export type SelectType = 'string' | 'user' | 'role' | 'mentionable' | 'channel';
+/** The kinds of menus whose options are things of the server. */
+export type EntitySelectType = Exclude<SelectType, 'string'>;
+export declare const SELECT_TYPES: Record<SelectType, RawSelectMenu['type']>;
+/** What `run` receives for one picked thing, by kind of menu. */
+interface EntityValues {
+    user: User;
+    role: Role;
+    mentionable: User | Role;
+    channel: Channel;
+}
+/** What a select menu looks like. */
+export interface SelectLook<Data extends DataShape = DataShape> {
+    /**
+     * The text shown when nothing is picked (150 characters at most):
+     * written as is, or a function of `t` and the data, run when the
+     * message is sent.
+     */
+    placeholder?: DynamicText<Data>;
+    /** Shows the menu greyed out, impossible to use. */
+    disabled?: boolean;
+}
+/** What a message can change when it shows a menu. */
+export interface SelectInstanceOptions extends SelectLook {
+    /**
+     * What is picked when the menu appears: the values of the options for a
+     * menu of texts, the ids (or the things themselves) for the others.
+     */
+    defaults?: readonly (string | {
+        id: Snowflake;
+    })[];
+}
+/** What every select file declares, whatever its kind. */
+interface SelectConfigBase<Data extends DataShape, Where extends ComponentWhere> extends SelectLook<Data>, InteractiveConfig<Data, Where> {
+    /** How many things must be picked at least (0 to 25). 1 by default. */
+    min?: number;
+    /** How many things can be picked at most (1 to 25). 1 by default. */
+    max?: number;
+}
+/** What `run` receives when something is picked. */
+export type SelectContext<Picked, Data extends DataShape = {}, Where extends ComponentWhere = 'guild'> = InteractiveContext<Data> & TranslationContext & {
+    /** What was picked, in the order of the menu. */
+    values: Picked[];
+    /** The first thing picked; `undefined` when nothing was (a menu with `min: 0`). */
+    value: Picked | undefined;
+} & PlaceOf<Where, ComponentInteraction>;
+/** A menu of texts you declare. */
+export interface StringSelectConfig<Options extends SelectOptions, Data extends DataShape = {}, Where extends ComponentWhere = 'guild'> extends SelectConfigBase<Data, Where> {
+    /** The kind of menu: texts you declare, which is the default. */
+    type?: 'string';
+    /**
+     * The options (25 at most): a list of texts, an object from what is
+     * shown to what your code receives, or a list of `RichOption`.
+     */
+    options: Options;
+    /** What to do when something is picked. */
+    run: (context: SelectContext<OptionValue<Options>, Data, Where>) => unknown;
+}
+/** A menu of users, roles, users and roles, or channels of the server. */
+export interface EntitySelectConfig<Type extends EntitySelectType, Data extends DataShape = {}, Where extends ComponentWhere = 'guild'> extends SelectConfigBase<Data, Where> {
+    /** The kind of menu: what Discord lists. */
+    type: Type;
+    /** For a menu of channels: the kinds of channels listed. All by default. */
+    channelTypes?: readonly ChannelType[];
+    /** What to do when something is picked. */
+    run: (context: SelectContext<EntityValues[Type], Data, Where>) => unknown;
+}
+/** What a select file gives to `select()`: a menu of texts, or of things of the server. */
+export type SelectConfig<Options extends SelectOptions = SelectOptions, Type extends EntitySelectType = EntitySelectType, Data extends DataShape = {}, Where extends ComponentWhere = 'guild'> = StringSelectConfig<Options, Data, Where> | EntitySelectConfig<Type, Data, Where>;
+/**
+ * What `select()` returns: a declaration the framework finds in the exports
+ * of a file. Import it where you send a message, and call it with the data
+ * it carries; a menu without data is used as is, or called with what to
+ * show.
+ */
+export type SelectDeclaration<Data extends DataShape = {}> = {
+    /** What the file gave to `select()`, not checked yet. */
+    readonly config: unknown;
+} & ({} extends Data ? ((options?: SelectInstanceOptions) => SelectComponent) & SelectComponent : {} extends DataInputOf<Data> ? ((data?: DataInputOf<Data>, options?: SelectInstanceOptions) => SelectComponent) & SelectComponent : (data: DataInputOf<Data>, options?: SelectInstanceOptions) => SelectComponent);
+/**
+ * Declares a select menu. Export the result from any file of `src/`: the
+ * name of the export is what tells the menu apart, so you never write an
+ * id.
+ *
+ * ```ts
+ * import { select } from 'chapterjs';
+ *
+ * export const color = select({
+ *   placeholder: 'Pick a color',
+ *   options: { Red: 'red', Blue: 'blue' },
+ *   async run({ interaction, value }) {
+ *     await interaction.update({ content: `You picked ${value}.`, components: [] });
+ *   },
+ * });
+ * ```
+ */
+export declare function select<const Options extends SelectOptions, const Data extends DataShape = {}, const Where extends ComponentWhere = 'guild'>(config: StringSelectConfig<Options, Data, Where>): SelectDeclaration<Data>;
+export declare function select<const Type extends EntitySelectType, const Data extends DataShape = {}, const Where extends ComponentWhere = 'guild'>(config: EntitySelectConfig<Type, Data, Where>): SelectDeclaration<Data>;
+/** A select menu, checked. */
+export interface LoadedSelect {
+    readonly kind: 'select';
+    /** The name of the export that declares it: its id for Discord. */
+    readonly name: string;
+    readonly type: SelectType;
+    /** The options of a menu of texts, their texts maybe computed when sent. */
+    readonly options: readonly LoadedOption[];
+    readonly channelTypes: readonly ChannelType[] | undefined;
+    readonly look: SelectLook;
+    readonly min: number;
+    readonly max: number;
+    readonly data: DataShape;
+    readonly where: ComponentWhere;
+    readonly who: 'everyone' | 'author';
+    readonly ephemeral: boolean;
+    readonly run: (context: SelectContext<unknown, DataShape, ComponentWhere>) => unknown;
+}
+/** Checks `min` and `max` of a menu, a group of checkboxes or a file upload. */
+export declare function readRange(what: string, given: {
+    min?: unknown;
+    max?: unknown;
+}, limit: number, defaults: {
+    min: number;
+    max: number;
+}): {
+    min: number;
+    max: number;
+};
+export declare function readPlaceholder(what: string, value: unknown): DynamicText | undefined;
+export declare function readChannelTypes(what: string, value: unknown): ChannelType[] | undefined;
+/** The menu as Discord takes it, for the data and the options given. */
+export declare function renderSelect(loaded: LoadedSelect, args: readonly unknown[]): Rendered<'select'>;
+export {};

package/dist/components/select.js

@@ -0,0 +1,179 @@
+// `select()`, as the files of `src/components/selects/` import it from
+// 'chapterjs': a menu of texts you declare, or of users, roles, channels
+// of the server, and what to do with what is picked.
+// https://docs.discord.com/developers/components/reference#string-select
+import { Limits } from '../discord/api.js';
+import { ChannelType } from '../discord/types/channel.js';
+import { ComponentType, } from '../discord/types/component.js';
+import { isDynamic, resolveText, } from './component.js';
+import { checkData, encodeCustomId, } from './custom-id.js';
+import { createComponent } from './declared.js';
+import { hasDynamicOption, resolveOptions, } from './options.js';
+export const SELECT_TYPES = {
+    string: ComponentType.StringSelect,
+    user: ComponentType.UserSelect,
+    role: ComponentType.RoleSelect,
+    mentionable: ComponentType.MentionableSelect,
+    channel: ComponentType.ChannelSelect,
+};
+export function select(config) {
+    return createComponent('select', config, {
+        asPiece: true,
+        pieceKind: 'select',
+    });
+}
+const fail = (message) => {
+    throw new TypeError(message);
+};
+/** Checks `min` and `max` of a menu, a group of checkboxes or a file upload. */
+export function readRange(what, given, limit, defaults) {
+    const read = (key, fallback, low) => {
+        const value = given[key];
+        if (value === undefined)
+            return fallback;
+        if (!Number.isInteger(value) ||
+            value < low ||
+            value > limit) {
+            return fail(`"${key}" of ${what} is a whole number between ${low} and ${limit}, got ${JSON.stringify(value) ?? typeof value}.`);
+        }
+        return value;
+    };
+    const min = read('min', defaults.min, 0);
+    const max = read('max', defaults.max, 1);
+    if (min > max) {
+        fail(`${what} can never be used: its "min" (${min}) is greater than its "max" (${max}).`);
+    }
+    return { min, max };
+}
+export function readPlaceholder(what, value) {
+    if (value === undefined)
+        return undefined;
+    // A function is checked when the message is sent.
+    if (isDynamic(value))
+        return value;
+    if (typeof value !== 'string' ||
+        value.trim() === '' ||
+        value.length > Limits.SelectPlaceholder) {
+        return fail(`The placeholder of ${what} is a text of 1 to ${Limits.SelectPlaceholder} characters.`);
+    }
+    return value;
+}
+export function readChannelTypes(what, value) {
+    if (value === undefined)
+        return undefined;
+    const known = Object.values(ChannelType);
+    if (!Array.isArray(value) ||
+        value.length === 0 ||
+        !value.every(one => known.includes(one))) {
+        return fail(`"channelTypes" of ${what} is a list of ChannelType values, like [ChannelType.GuildText].`);
+    }
+    return value;
+}
+/** Checks what a message gives to change a menu. */
+function readInstanceOptions(loaded, name, given) {
+    if (given === undefined)
+        return { look: {}, defaults: undefined };
+    if (typeof given !== 'object' || given === null || Array.isArray(given)) {
+        fail(`The options of ${name} are an object like { placeholder: '...', defaults: [...] }.`);
+    }
+    const options = given;
+    for (const key of Object.keys(options)) {
+        if (!['placeholder', 'disabled', 'defaults'].includes(key)) {
+            fail(`"${key}" is not something ${name} takes when shown. It can take: placeholder, disabled, defaults.`);
+        }
+    }
+    const look = {};
+    const placeholder = readPlaceholder(name, options.placeholder);
+    if (placeholder !== undefined)
+        look.placeholder = placeholder;
+    if (options.disabled !== undefined) {
+        if (typeof options.disabled !== 'boolean')
+            fail(`"disabled" of ${name} is true or false.`);
+        look.disabled = options.disabled;
+    }
+    if (options.defaults === undefined)
+        return { look, defaults: undefined };
+    if (!Array.isArray(options.defaults)) {
+        fail(`"defaults" of ${name} is a list of what is picked when the menu appears.`);
+    }
+    const ids = options.defaults.map(item => {
+        const id = typeof item === 'string' ? item : item?.id;
+        if (typeof id !== 'string') {
+            return fail(`A default of ${name} is a text, or something with an id, got ${JSON.stringify(item) ?? typeof item}.`);
+        }
+        return id;
+    });
+    if (ids.length > loaded.max) {
+        fail(`${name} has ${ids.length} defaults, but ${loaded.max} can be picked at most.`);
+    }
+    if (loaded.type === 'string') {
+        for (const value of ids) {
+            if (!loaded.options.some(option => option.value === value)) {
+                fail(`${JSON.stringify(value)} is not an option of ${name}. Its options are: ${loaded.options.map(option => option.value).join(', ')}.`);
+            }
+        }
+        return { look, defaults: ids };
+    }
+    // Discord wants to know what each default is; a mentionable may be either,
+    // and a role id is also a guild id for @everyone: users first.
+    const kind = loaded.type === 'mentionable' ? 'user' : loaded.type;
+    return { look, defaults: ids.map(id => ({ id, type: kind })) };
+}
+/** The menu as Discord takes it, for the data and the options given. */
+export function renderSelect(loaded, args) {
+    const hasData = Object.keys(loaded.data).length > 0;
+    const { name } = loaded;
+    if (args.length > (hasData ? 2 : 1)) {
+        fail(`${name} takes ${hasData ? 'its data, then options' : 'options'} at most.`);
+    }
+    const values = checkData(name, loaded.data, hasData ? args[0] : undefined);
+    const { look, defaults } = readInstanceOptions(loaded, name, hasData ? args[1] : args[0]);
+    const merged = { ...loaded.look, ...look };
+    const dynamic = isDynamic(merged.placeholder) || hasDynamicOption(loaded.options);
+    const make = (context) => {
+        const placeholder = resolveText(`The placeholder of ${name}`, merged.placeholder, context, { max: Limits.SelectPlaceholder });
+        const base = {
+            custom_id: encodeCustomId(loaded.name, loaded.data, values),
+            ...(placeholder !== undefined ? { placeholder } : {}),
+            ...(loaded.min !== 1 ? { min_values: loaded.min } : {}),
+            ...(loaded.max !== 1 ? { max_values: loaded.max } : {}),
+            ...(merged.disabled ? { disabled: true } : {}),
+        };
+        if (loaded.type !== 'string') {
+            return {
+                type: SELECT_TYPES[loaded.type],
+                ...base,
+                ...(loaded.channelTypes
+                    ? { channel_types: [...loaded.channelTypes] }
+                    : {}),
+                ...(defaults
+                    ? { default_values: defaults }
+                    : {}),
+            };
+        }
+        const picked = defaults;
+        return {
+            type: ComponentType.StringSelect,
+            ...base,
+            options: resolveOptions(name, loaded.options, context)
+                .map(option => picked
+                ? {
+                    ...option,
+                    ...(picked.includes(option.value)
+                        ? { default: true }
+                        : { default: undefined }),
+                }
+                : option)
+                .map(option => option.default === undefined
+                ? (({ default: _d, ...rest }) => rest)(option)
+                : option),
+        };
+    };
+    // Texts computed when the message is sent wait for who will read it.
+    return {
+        kind: 'select',
+        raw: dynamic
+            ? t => make({ t, data: values })
+            : make({ t: undefined, data: values }),
+    };
+}

package/dist/core/bot.d.ts

@@ -0,0 +1,99 @@
+import { type CacheOptions } from '../cache/cache.js';
+import type { Snowflake } from '../discord/types/common.js';
+import type { GatewayDispatchEventName, GatewayDispatchEvents, RawGatewayPresenceUpdate } from '../discord/types/gateway-events.js';
+import { Gateway, type GatewayOptions } from '../gateway/gateway.js';
+import type { ShardEvent } from '../gateway/shard.js';
+import { type RestOptions } from '../rest/rest.js';
+import type { Context } from '../structures/context.js';
+/** What a dispatched event is, besides its data. */
+export interface DispatchInfo {
+    shardId: number;
+    /**
+     * For Guild Create: `true` when the bot just joined the server, `false`
+     * when it was already in it and Discord is only sending its data (after
+     * connecting, or after an outage).
+     */
+    joined: boolean;
+    /** What `beforeDispatch` returned for this event. */
+    before: unknown;
+}
+export type BotEvent = ShardEvent
+/** Every server the bot is in has sent its data (or took too long). */
+ | {
+    type: 'guildsReady';
+}
+/** Applying an event to the cache failed: the event is still delivered. */
+ | {
+    type: 'stateError';
+    event: GatewayDispatchEventName;
+    error: unknown;
+}
+/** Something went wrong with a voice connection, which goes on or ends. */
+ | {
+    type: 'voiceWarning';
+    message: string;
+};
+export interface BotOptions {
+    token: string;
+    /** The version of the framework. */
+    version: string;
+    intents: number;
+    presence?: RawGatewayPresenceUpdate | undefined;
+    cache?: CacheOptions;
+    shards?: GatewayOptions['shards'];
+    identifyGate?: GatewayOptions['identifyGate'];
+    /** Called for every event, once the cache reflects it. */
+    onDispatch?: <E extends GatewayDispatchEventName>(event: E, data: GatewayDispatchEvents[E], info: DispatchInfo) => void;
+    /**
+     * Called for every event before the cache reflects it: the last moment
+     * to read what the event removes. What it returns is given back to
+     * `onDispatch`.
+     */
+    beforeDispatch?: <E extends GatewayDispatchEventName>(event: E, data: GatewayDispatchEvents[E]) => unknown;
+    onEvent?: (event: BotEvent) => void;
+    /**
+     * The servers the bot pays attention to. Events of the others are dropped
+     * before anything else, as if the bot was not in them: this is how a dev
+     * bot only sees its dev server. What belongs to no server is decided by
+     * `privateEvents`.
+     */
+    guildFilter?: (guildId: Snowflake) => boolean;
+    /**
+     * Whether what happens outside servers (private messages, commands used
+     * there) is for this bot. Default: true. Discord sends it to every
+     * process of the bot that runs its first shard: when a dev bot and a
+     * production bot share a token, only one may answer.
+     */
+    privateEvents?: boolean;
+    /**
+     * How long to wait for the data of every server after connecting, in
+     * milliseconds, before going on without the ones that did not come
+     * (an outage of Discord). Default: 15000.
+     */
+    guildsTimeout?: number;
+    /** Only tests change these. */
+    rest?: Partial<RestOptions>;
+    gateway?: Pick<GatewayOptions, 'backoff' | 'identifyInterval'>;
+    voice?: {
+        secure?: boolean;
+    };
+}
+export interface Bot {
+    readonly ctx: Context;
+    readonly gateway: Gateway;
+    /**
+     * Connects to Discord, and resolves once every shard is ready and every
+     * server has sent its data.
+     */
+    connect(): Promise<void>;
+    /** Disconnects cleanly: the bot goes offline right away. */
+    close(): Promise<void>;
+    /**
+     * Changes what the bot shows under its name (its status and activity)
+     * on every shard of this process. Discord's limit on presence updates is
+     * respected: when it is reached, the latest presence is sent as soon as
+     * it allows.
+     */
+    setPresence(presence: RawGatewayPresenceUpdate): void;
+}
+export declare function createBot(options: BotOptions): Bot;