chapterjs 0.1.2 → 0.2.0

package/dist/commands/router.js

@@ -0,0 +1,228 @@
+// Runs the command someone used: finds its file, turns what Discord sent
+// into what `run` receives, and makes sure the person always gets an answer.
+import { Permissions } from '../discord/permissions.js';
+import { ApplicationCommandOptionType, ApplicationCommandType, } from '../discord/types/application-command.js';
+import { InteractionType, } from '../discord/types/interaction.js';
+import { timestamp, TimestampStyle } from '../discord/formatting.js';
+import { checkCooldown, MemoryCooldowns, } from '../interactions/cooldown.js';
+import { authorOf, placeContext, refuse, resolvePlace, runInteraction, } from '../interactions/dispatch.js';
+import { audienceLocale, translation } from '../messages/translate.js';
+import { CommandInteraction } from '../structures/interaction.js';
+import { remember } from '../structures/known.js';
+import { toCamelCase } from '../util/case.js';
+import { suggest } from './autocomplete.js';
+import { commandName } from './tree.js';
+/**
+ * How long a refusal for a cooldown may wait before deleting itself: the
+ * token of an interaction lives 15 minutes, with room for the request.
+ * @see https://docs.discord.com/developers/interactions/receiving-and-responding#interaction-object
+ */
+const DELETE_WITHIN = 14 * 60_000;
+const SUB = ApplicationCommandOptionType.SubCommand;
+const GROUP = ApplicationCommandOptionType.SubCommandGroup;
+export class CommandRouter {
+    #commands = new Map();
+    #options;
+    // Kept by the router, not the entries: a reload keeps the cooldowns.
+    #cooldowns;
+    // What was already said about suggestions, which come on every keystroke.
+    #warnedOnce = new Set();
+    constructor(options) {
+        this.#options = options;
+        this.#cooldowns = options.cooldowns ?? new MemoryCooldowns();
+    }
+    /** Replaces every command (after a load or a reload). */
+    set(entries) {
+        const commands = new Map();
+        for (const entry of entries) {
+            commands.set(entry.command.path.join(' '), entry);
+        }
+        this.#commands = commands;
+    }
+    /**
+     * Handles an Interaction Create event, if it is a slash command being
+     * used, or someone typing in one of its options with suggestions.
+     */
+    dispatch(ctx, raw) {
+        const autocomplete = raw.type === InteractionType.ApplicationCommandAutocomplete;
+        if (raw.type !== InteractionType.ApplicationCommand && !autocomplete) {
+            return;
+        }
+        const data = raw.data;
+        if (!data || data.type !== ApplicationCommandType.ChatInput)
+            return;
+        // `/mod roles add` comes as a command with nested options.
+        const path = [data.name];
+        let given = data.options ?? [];
+        while (given[0] && (given[0].type === SUB || given[0].type === GROUP)) {
+            path.push(given[0].name);
+            given = given[0].options ?? [];
+        }
+        const entry = this.#commands.get(path.join(' '));
+        if (autocomplete) {
+            suggest(ctx, raw, entry, given, this.#options, this.#warnedOnce);
+            return;
+        }
+        const name = commandName(path);
+        const author = authorOf(raw);
+        if (!author)
+            return;
+        const { user: _user, member: _member, message: _message, ...rest } = raw;
+        const user = ctx.entities.user(author.user);
+        const interaction = new CommandInteraction(ctx, rest, user, {
+            ephemeral: entry?.command.ephemeral ?? false,
+            commandName: name,
+        });
+        if (!entry) {
+            // Still registered on Discord, but its file is gone or broken.
+            refuse(interaction, 'unavailable');
+            return;
+        }
+        const { command, file } = entry;
+        const placed = resolvePlace(ctx, raw, user, author.member, command.where, message => this.#options.onWarning(file, `${name} ${message}`));
+        if (!placed.place) {
+            refuse(interaction, placed.refusal, { what: 'command' });
+            return;
+        }
+        const { place } = placed;
+        // What the member can do where the command was used, overwrites
+        // included: Discord computes it for us.
+        if (command.permissions !== 0n && author.member) {
+            const missing = new Permissions(author.member.permissions ?? '0').missing(command.permissions);
+            if (missing.length > 0) {
+                refuse(interaction, 'needsPermissions', {
+                    permissions: missing.join(', '),
+                    count: missing.length,
+                });
+                return;
+            }
+        }
+        // Used too soon: the person is told when, and nothing runs.
+        const again = checkCooldown(this.#cooldowns, path.join(' '), command.cooldown, {
+            user: user.id,
+            channel: place.channel.id,
+            guild: place.guild?.id,
+        });
+        if (again > 0) {
+            this.#refuseUntil(interaction, again);
+            return;
+        }
+        let options;
+        try {
+            options = this.#readOptions(ctx, raw, data, given, entry);
+        }
+        catch (error) {
+            this.#options.onError(file, error);
+            refuse(interaction, 'failed', { what: 'command' });
+            return;
+        }
+        remember(interaction, {
+            guild: place.guild ?? undefined,
+            member: place.member ?? undefined,
+            channel: place.channel,
+        });
+        const context = Object.freeze({
+            interaction,
+            options: Object.freeze(options),
+            user,
+            ...placeContext(place, command.where),
+            // `t` speaks the language of who will read the answer.
+            ...translation(ctx, audienceLocale({
+                person: raw.locale,
+                guild: place.guild,
+                ephemeral: command.ephemeral,
+            })),
+        });
+        runInteraction({
+            interaction,
+            file,
+            name,
+            what: 'command',
+            reporter: this.#options,
+            defer: () => interaction.defer(),
+            unanswered: 'finished without answering: the person sees "The application did not respond". Call interaction.reply() in run.',
+            run: () => command.run(context),
+        });
+    }
+    /**
+     * Tells the person when they can use the command again. Discord shows a
+     * relative time ("in 5 seconds") that counts down, but keeps counting
+     * ("52 seconds ago") once passed: the answer is deleted when the
+     * cooldown ends, as long as the interaction can still be edited (15
+     * minutes); beyond that, the date and time are shown instead.
+     */
+    #refuseUntil(interaction, until) {
+        const at = Math.ceil(until / 1000) * 1000;
+        const wait = at - Date.now();
+        const deletable = wait <= DELETE_WITHIN;
+        const when = timestamp(at, deletable ? TimestampStyle.Relative : TimestampStyle.LongDateShortTime);
+        const refused = refuse(interaction, 'cooldown', { what: 'command', when });
+        if (!deletable)
+            return;
+        const timer = setTimeout(() => {
+            refused.then(() => interaction.delete()).catch(() => { });
+        }, wait);
+        // Nothing of the bot waits for it: the process may stop meanwhile.
+        timer.unref();
+    }
+    /** The value of each declared option, as structures where it applies. */
+    #readOptions(ctx, raw, data, given, { command }) {
+        const values = new Map(given.map(option => [option.name, option.value]));
+        const resolved = data.resolved ?? {};
+        const guildId = raw.guild_id;
+        const userOf = (id) => {
+            const rawUser = resolved.users?.[id];
+            if (!rawUser)
+                return undefined;
+            const member = resolved.members?.[id];
+            // The member comes along: remembered, so `guild.members` has it.
+            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 options = {};
+        for (const option of command.options) {
+            const value = values.get(option.name);
+            if (value === undefined) {
+                options[option.name] = undefined;
+                continue;
+            }
+            const id = String(value);
+            switch (option.type) {
+                case 'user':
+                    options[option.name] = userOf(id);
+                    break;
+                case 'role':
+                    options[option.name] = roleOf(id);
+                    break;
+                case 'mentionable':
+                    options[option.name] = userOf(id) ?? roleOf(id);
+                    break;
+                case 'channel': {
+                    const partial = resolved.channels?.[id];
+                    options[option.name] =
+                        ctx.cache.channels.get(id) ??
+                            (partial
+                                ? ctx.entities.channel(partial, guildId)
+                                : undefined);
+                    break;
+                }
+                case 'attachment': {
+                    const attachment = resolved.attachments?.[id];
+                    options[option.name] = attachment
+                        ? toCamelCase(attachment)
+                        : undefined;
+                    break;
+                }
+                default:
+                    options[option.name] = value;
+            }
+        }
+        return options;
+    }
+}

package/dist/commands/tree.d.ts

@@ -0,0 +1,47 @@
+import { type BulkOverwriteGuildApplicationCommandsJSONParams } from '../discord/types/application-command.js';
+import type { LoadedCommand } from './declaration.js';
+/** A command with the file it comes from. */
+export interface CommandEntry {
+    file: string;
+    /** The export it is: `'default'`, or its name. */
+    export: string;
+    command: LoadedCommand;
+}
+/** Two declarations that can't both be commands. */
+export interface CommandConflict {
+    file: string;
+    export: string;
+    message: string;
+}
+export type CommandPayload = BulkOverwriteGuildApplicationCommandsJSONParams;
+/** `/mod ban` for `['mod', 'ban']`. */
+export declare const commandName: (path: readonly string[]) => string;
+/**
+ * Finds the declarations that can't be commands together, and leaves them
+ * out:
+ * - two commands with the same name;
+ * - a command that also has subcommands: Discord only lets people use the
+ *   subcommands.
+ */
+export declare function findConflicts(entries: readonly CommandEntry[]): {
+    valid: CommandEntry[];
+    conflicts: CommandConflict[];
+};
+/**
+ * The commands that only work in private messages. Discord does not offer
+ * the commands of one server there, so they can't be used with those.
+ * @see https://docs.discord.com/developers/interactions/application-commands#permissions
+ */
+export declare const privateOnly: (entries: readonly CommandEntry[]) => CommandEntry[];
+/**
+ * What to register for a set of commands. `guild` is for commands of one
+ * server (dev), where Discord takes no contexts: the commands that only
+ * work in private messages are left out, they could never run there.
+ *
+ * A folder has no file: Discord asks for its description but never shows
+ * it, so it is generated, and it is shown under the name of the folder in
+ * every language.
+ */
+export declare function buildCommands(entries: readonly CommandEntry[], { guild }: {
+    guild: boolean;
+}): CommandPayload[];

package/dist/commands/tree.js

@@ -0,0 +1,216 @@
+// Turns the commands of a project into what Discord registers: one
+// application command per top-level name, with its subcommands and groups.
+// https://docs.discord.com/developers/interactions/application-commands#subcommands-and-subcommand-groups
+import { ApplicationCommandOptionType, ApplicationCommandType, } from '../discord/types/application-command.js';
+import { ApplicationIntegrationType } from '../discord/types/application.js';
+import { InteractionContextType } from '../discord/types/interaction.js';
+import { siteName } from '../loader/loader.js';
+const TYPES = {
+    string: ApplicationCommandOptionType.String,
+    integer: ApplicationCommandOptionType.Integer,
+    number: ApplicationCommandOptionType.Number,
+    boolean: ApplicationCommandOptionType.Boolean,
+    user: ApplicationCommandOptionType.User,
+    channel: ApplicationCommandOptionType.Channel,
+    role: ApplicationCommandOptionType.Role,
+    mentionable: ApplicationCommandOptionType.Mentionable,
+    attachment: ApplicationCommandOptionType.Attachment,
+};
+/** A dictionary of translations, or nothing when there is none. */
+const localized = (translations) => translations && Object.keys(translations).length > 0
+    ? translations
+    : undefined;
+/** Adds the translations of a name and a description, when there are some. */
+function withLocales(target, names, descriptions) {
+    const nameLocalizations = localized(names);
+    const descriptionLocalizations = localized(descriptions);
+    return {
+        ...target,
+        ...(nameLocalizations ? { name_localizations: nameLocalizations } : {}),
+        ...(descriptionLocalizations
+            ? { description_localizations: descriptionLocalizations }
+            : {}),
+    };
+}
+function toOption(option, locales, autocomplete) {
+    const raw = withLocales({
+        type: TYPES[option.type],
+        name: option.name,
+        description: option.description,
+    }, locales?.names, locales?.descriptions);
+    if (option.required)
+        raw.required = true;
+    // Discord then asks the bot for suggestions while the person types.
+    // https://docs.discord.com/developers/interactions/application-commands#autocomplete
+    if (autocomplete)
+        raw.autocomplete = true;
+    if ('choices' in option && option.choices) {
+        const entries = Array.isArray(option.choices)
+            ? option.choices.map((value) => [String(value), value])
+            : Object.entries(option.choices);
+        raw.choices = entries.map(([name, value]) => {
+            const translations = localized(locales?.choices[name]);
+            return {
+                name,
+                value,
+                ...(translations ? { name_localizations: translations } : {}),
+            };
+        });
+    }
+    if (option.type === 'string') {
+        if (option.minLength !== undefined)
+            raw.min_length = option.minLength;
+        if (option.maxLength !== undefined)
+            raw.max_length = option.maxLength;
+    }
+    else if (option.type === 'integer' || option.type === 'number') {
+        if (option.min !== undefined)
+            raw.min_value = option.min;
+        if (option.max !== undefined)
+            raw.max_value = option.max;
+    }
+    else if (option.type === 'channel' && option.channelTypes) {
+        raw.channel_types = [...option.channelTypes];
+    }
+    return raw;
+}
+/** `/mod ban` for `['mod', 'ban']`. */
+export const commandName = (path) => `/${path.join(' ')}`;
+/**
+ * Finds the declarations that can't be commands together, and leaves them
+ * out:
+ * - two commands with the same name;
+ * - a command that also has subcommands: Discord only lets people use the
+ *   subcommands.
+ */
+export function findConflicts(entries) {
+    const conflicts = [];
+    const seen = new Map();
+    const unique = [...entries]
+        .sort((a, b) => a.file === b.file
+        ? a.export < b.export
+            ? -1
+            : 1
+        : a.file < b.file
+            ? -1
+            : 1)
+        .filter(entry => {
+        const key = entry.command.path.join(' ');
+        const first = seen.get(key);
+        if (!first) {
+            seen.set(key, entry);
+            return true;
+        }
+        conflicts.push({
+            file: entry.file,
+            export: entry.export,
+            message: `${commandName(entry.command.path)} is already declared in ${siteName(first)}: two commands can't have the same name.`,
+        });
+        return false;
+    });
+    const valid = unique.filter(entry => {
+        const { path } = entry.command;
+        const child = unique.find(other => other !== entry &&
+            other.command.path.length > path.length &&
+            path.every((part, index) => other.command.path[index] === part));
+        if (!child)
+            return true;
+        conflicts.push({
+            file: entry.file,
+            export: entry.export,
+            message: `${commandName(path)} can't be a command and have subcommands (${siteName(child)} is ${commandName(child.command.path)}): Discord only lets people use the subcommands. Make this one a subcommand too, for example name: '${[...path, 'run'].join(' ')}'.`,
+        });
+        return false;
+    });
+    return { valid, conflicts };
+}
+/**
+ * The commands that only work in private messages. Discord does not offer
+ * the commands of one server there, so they can't be used with those.
+ * @see https://docs.discord.com/developers/interactions/application-commands#permissions
+ */
+export const privateOnly = (entries) => entries.filter(entry => entry.command.where === 'dm');
+/**
+ * What to register for a set of commands. `guild` is for commands of one
+ * server (dev), where Discord takes no contexts: the commands that only
+ * work in private messages are left out, they could never run there.
+ *
+ * A folder has no file: Discord asks for its description but never shows
+ * it, so it is generated, and it is shown under the name of the folder in
+ * every language.
+ */
+export function buildCommands(entries, { guild }) {
+    const optionsOf = (command) => command.options.map(option => toOption(option, command.optionLocales[option.name], option.name in command.autocomplete));
+    const sub = (command) => withLocales({
+        type: ApplicationCommandOptionType.SubCommand,
+        name: command.path.at(-1),
+        description: command.description,
+        ...(command.options.length > 0 ? { options: optionsOf(command) } : {}),
+    }, command.names, command.descriptions);
+    const roots = new Map();
+    for (const { command } of entries) {
+        if (guild && command.where === 'dm')
+            continue;
+        const list = roots.get(command.path[0]) ?? [];
+        list.push(command);
+        roots.set(command.path[0], list);
+    }
+    return [...roots]
+        .sort(([a], [b]) => (a < b ? -1 : 1))
+        .map(([name, commands]) => {
+        const [first] = commands;
+        const leaf = commands.length === 1 && first.path.length === 1 ? first : null;
+        // What the server shows the command to by default: what every one of
+        // its subcommands asks for. Each subcommand checks its own on use.
+        const permissions = commands.reduce((bits, command) => bits & command.permissions, commands[0].permissions);
+        const payload = withLocales({
+            type: ApplicationCommandType.ChatInput,
+            name,
+            description: leaf?.description ?? `${name} commands`,
+            default_member_permissions: permissions === 0n ? null : String(permissions),
+            // Only for globally-scoped commands.
+            ...(guild
+                ? {}
+                : {
+                    integration_types: [ApplicationIntegrationType.GuildInstall],
+                    // A command is offered wherever one of its subcommands
+                    // works; each one refuses the place it does not work in.
+                    contexts: [
+                        ...(commands.some(command => command.where !== 'dm')
+                            ? [InteractionContextType.Guild]
+                            : []),
+                        ...(commands.some(command => command.where !== 'guild')
+                            ? [InteractionContextType.BotDm]
+                            : []),
+                    ],
+                }),
+            ...(commands.some(command => command.nsfw) ? { nsfw: true } : {}),
+        }, leaf?.names, leaf?.descriptions);
+        if (leaf) {
+            if (leaf.options.length > 0)
+                payload.options = optionsOf(leaf);
+            return payload;
+        }
+        const inGroups = new Map();
+        const options = [];
+        for (const command of [...commands].sort((a, b) => a.path.join('/') < b.path.join('/') ? -1 : 1)) {
+            if (command.path.length === 2)
+                options.push(sub(command));
+            else {
+                const list = inGroups.get(command.path[1]) ?? [];
+                list.push(command);
+                inGroups.set(command.path[1], list);
+            }
+        }
+        for (const [group, members] of inGroups) {
+            options.push({
+                type: ApplicationCommandOptionType.SubCommandGroup,
+                name: group,
+                description: `${group} commands`,
+                options: members.map(sub),
+            });
+        }
+        payload.options = options;
+        return payload;
+    });
+}

package/dist/commands/twins.d.ts

@@ -0,0 +1,15 @@
+import type { RawApplicationCommand } from '../discord/types/application-command.js';
+import type { CommandPayload } from './tree.js';
+/** Whether a command of the project is the one Discord has for everyone. */
+export declare function sameDefinition(ours: CommandPayload, theirs: RawApplicationCommand): boolean;
+/**
+ * The commands to give one server, without the ones that are already there
+ * for everyone exactly as declared (`twins`: shown once, by the other).
+ * A command that changed is kept: its new form must be there to be tried,
+ * next to the one in production until that one is updated.
+ */
+export declare function withoutGlobalTwins(commands: readonly CommandPayload[], global: readonly RawApplicationCommand[]): {
+    kept: CommandPayload[];
+    twins: string[];
+    changed: string[];
+};

package/dist/commands/twins.js

@@ -0,0 +1,78 @@
+// A bot can have a command for everyone and a command of one server with
+// the same name: Discord then shows both in that server. A dev bot that
+// shares its token with the bot in production would show every command
+// twice in the dev server. So the dev server only gets the commands that
+// are not already there for everyone, exactly as the project declares them.
+// https://docs.discord.com/developers/interactions/application-commands#registering-a-command
+/** What says how a command looks and works: the rest is not compared. */
+const DEFINITION = new Set([
+    'type',
+    'name',
+    'description',
+    'name_localizations',
+    'description_localizations',
+    'default_member_permissions',
+    'nsfw',
+    'options',
+    'required',
+    'choices',
+    'value',
+    'min_value',
+    'max_value',
+    'min_length',
+    'max_length',
+    'channel_types',
+    'autocomplete',
+]);
+const isEmpty = (value) => value === null ||
+    value === undefined ||
+    value === false ||
+    (Array.isArray(value) && value.length === 0) ||
+    (typeof value === 'object' && Object.keys(value).length === 0);
+/**
+ * A definition in one form, whoever wrote it: Discord sends back what it
+ * was given with more fields, and says "nothing" in several ways (a field
+ * left out, `null`, `false`, an empty list).
+ */
+function canonical(value, top = true) {
+    if (Array.isArray(value))
+        return value.map(item => canonical(item, top));
+    if (typeof value !== 'object' || value === null)
+        return value;
+    const entries = Object.entries(value)
+        // Translations are dictionaries: their keys are languages, all kept.
+        .filter(([key]) => !top || DEFINITION.has(key))
+        .map(([key, child]) => [key, canonical(child, !key.endsWith('_localizations'))])
+        .filter(([, child]) => !isEmpty(child))
+        .sort(([a], [b]) => (a < b ? -1 : 1));
+    return Object.fromEntries(entries);
+}
+/** Whether a command of the project is the one Discord has for everyone. */
+export function sameDefinition(ours, theirs) {
+    return JSON.stringify(canonical(ours)) === JSON.stringify(canonical(theirs));
+}
+/**
+ * The commands to give one server, without the ones that are already there
+ * for everyone exactly as declared (`twins`: shown once, by the other).
+ * A command that changed is kept: its new form must be there to be tried,
+ * next to the one in production until that one is updated.
+ */
+export function withoutGlobalTwins(commands, global) {
+    const byName = new Map(global
+        .filter(command => (command.type ?? 1) === 1)
+        .map(command => [command.name, command]));
+    const kept = [];
+    const twins = [];
+    const changed = [];
+    for (const command of commands) {
+        const other = byName.get(command.name);
+        if (other && sameDefinition(command, other)) {
+            twins.push(command.name);
+            continue;
+        }
+        if (other)
+            changed.push(command.name);
+        kept.push(command);
+    }
+    return { kept, twins, changed };
+}

package/dist/components/button.d.ts

@@ -0,0 +1,79 @@
+import { ButtonStyle } from '../discord/types/component.js';
+import type { TranslationContext } from '../messages/messages.js';
+import type { ComponentInteraction } from '../structures/interaction.js';
+import type { EmojiInput } from '../structures/message.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 ButtonComponent, type Rendered } from './instance.js';
+/**
+ * The color of a button: `'primary'` (blurple), `'secondary'` (grey),
+ * `'success'` (green) or `'danger'` (red).
+ * @see https://docs.discord.com/developers/components/reference#button-button-styles
+ */
+export type ButtonStyleName = 'primary' | 'secondary' | 'success' | 'danger';
+export declare const BUTTON_STYLES: Record<ButtonStyleName, ButtonStyle>;
+/** What a button looks like. Everything is optional when it is put in a message: what the file says is the default. */
+export interface ButtonLook<Data extends DataShape = DataShape> {
+    /**
+     * The text on the button (80 characters at most): written as is, or a
+     * function of `t` and the data, run when the message is sent.
+     */
+    label?: DynamicText<Data>;
+    /** An emoji on the button, before the label. */
+    emoji?: EmojiInput;
+    /** The color of the button. `'primary'` by default. */
+    style?: ButtonStyleName;
+    /** Shows the button greyed out, impossible to click. */
+    disabled?: boolean;
+}
+/** What `run` receives when the button is clicked. */
+export type ButtonContext<Data extends DataShape = {}, Where extends ComponentWhere = 'guild'> = InteractiveContext<Data> & TranslationContext & PlaceOf<Where, ComponentInteraction>;
+/** What a file gives to `button()`. */
+export interface ButtonConfig<Data extends DataShape = {}, Where extends ComponentWhere = 'guild'> extends ButtonLook<Data>, InteractiveConfig<Data, Where> {
+    /** What to do when someone clicks the button. */
+    run: (context: ButtonContext<Data, Where>) => unknown;
+}
+/**
+ * What `button()` 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
+ * the button carries (`ban({ userId })`); a button without data is used as
+ * is (`confirm`), or called with a look (`confirm({ disabled: true })`).
+ */
+export type ButtonDeclaration<Data extends DataShape = {}> = {
+    /** What the file gave to `button()`, not checked yet. */
+    readonly config: unknown;
+} & ({} extends Data ? ((look?: ButtonLook) => ButtonComponent) & ButtonComponent : {} extends DataInputOf<Data> ? ((data?: DataInputOf<Data>, look?: ButtonLook) => ButtonComponent) & ButtonComponent : (data: DataInputOf<Data>, look?: ButtonLook) => ButtonComponent);
+/**
+ * Declares a button. Export the result from any file of `src/`: the name
+ * of the export is what tells the button apart, so you never write an id.
+ *
+ * ```ts
+ * import { button } from 'chapterjs';
+ *
+ * export const confirm = button({
+ *   label: 'Confirm',
+ *   style: 'success',
+ *   async run({ interaction }) {
+ *     await interaction.update({ content: 'Confirmed!', components: [] });
+ *   },
+ * });
+ * ```
+ */
+export declare function button<const Data extends DataShape = {}, const Where extends ComponentWhere = 'guild'>(config: ButtonConfig<Data, Where>): ButtonDeclaration<Data>;
+/** A button, checked. */
+export interface LoadedButton {
+    readonly kind: 'button';
+    /** The name of the export that declares it: its id for Discord. */
+    readonly name: string;
+    readonly look: Required<Pick<ButtonLook, 'style' | 'disabled'>> & Pick<ButtonLook, 'label' | 'emoji'>;
+    readonly data: DataShape;
+    readonly where: ComponentWhere;
+    readonly who: 'everyone' | 'author';
+    readonly ephemeral: boolean;
+    readonly run: (context: ButtonContext<DataShape, ComponentWhere>) => unknown;
+}
+/** Checks what a message gives to change the look of a button. */
+export declare function readLook(what: string, look: unknown): ButtonLook;
+/** The button as Discord takes it, for the data and the look given. */
+export declare function renderButton(loaded: LoadedButton, args: readonly unknown[]): Rendered<'button'>;