chapterjs 0.0.0 → 0.1.2

package/dist/cli/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/cli.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { dev } from './dev.js';
+const HELP = `Usage: chapterjs <command>
+
+  dev                    Local development
+  build                  Validate and bundle the project`;
+const [command, ...args] = process.argv.slice(2);
+// package.json engines: global WebSocket and running .ts files without flags
+const [major = 0, minor = 0] = process.versions.node.split('.').map(Number);
+if (major < 22 || (major === 22 && minor < 18)) {
+    console.error(`✗ ChapterJS needs Node.js 22.18 or newer, you have ${process.version}. Install the latest LTS from https://nodejs.org`);
+    process.exit(1);
+}
+try {
+    switch (command) {
+        case 'dev':
+            await dev();
+            break;
+        case 'build':
+            console.log('build');
+            break;
+        default:
+            if (command && command !== 'help' && command !== '--help') {
+                console.error(`✗ Unknown command "${command}".\n`);
+            }
+            console.log(HELP);
+            process.exit(command && command !== 'help' && command !== '--help' ? 1 : 0);
+    }
+}
+catch (error) {
+    console.error(error instanceof Error ? `✗ ${error.message}` : error);
+    process.exit(1);
+}

package/dist/cli/dev.d.ts

@@ -0,0 +1 @@
+export declare function dev(): Promise<void>;

package/dist/cli/dev.js

@@ -0,0 +1,206 @@
+import { handleComponentInteraction, loadComponents, watchComponents, } from '../components.js';
+import { Gateway, GatewayCloseError } from '../discord/gateway.js';
+import { GatewayCloseCodes } from '../discord/constants.js';
+import { EventRouter, eventIntents, filesMissingMessageContent, loadEvents, privilegedIntentsUsage, watchEvents, } from '../events.js';
+import { loadPresence, startPresenceLoop, watchPresence } from '../presence.js';
+import { describeRuntimeError } from '../utils/modules.js';
+/** Returns false when there is no `.env` file. */
+function loadEnv() {
+    try {
+        process.loadEnvFile('.env');
+        return true;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        return false;
+    }
+}
+/** The Bot page of the app in the Developer Portal, where the token and privileged intents are. */
+const botPage = (applicationId) => applicationId
+    ? `https://discord.com/developers/applications/${applicationId}/bot`
+    : 'https://discord.com/developers/applications > your application > Bot';
+const errorMessage = (error) => error instanceof Error ? error.message : String(error);
+function summarizeEvents(events) {
+    const counts = new Map();
+    for (const event of events)
+        counts.set(event.name, (counts.get(event.name) ?? 0) + 1);
+    return [...counts]
+        .map(([name, count]) => (count > 1 ? `${name} ×${count}` : name))
+        .join(', ');
+}
+let lastMessageContentNote = '';
+/** Explains it once per set of files, not on every reload. */
+function noteMessageContent(events, applicationId) {
+    const files = filesMissingMessageContent(events);
+    const key = files.join(',');
+    if (key === lastMessageContentNote)
+        return;
+    lastMessageContentNote = key;
+    if (files.length === 0)
+        return;
+    console.log(`ℹ ${files.join(', ')}: message.content is empty, except in DMs and in messages that mention the bot.\n` +
+        `  Nothing to do if that's enough for you. To read the text of every message, add\n` +
+        `  intents: ['MessageContent'] to defineEvent, then enable "Message Content Intent" in\n` +
+        `  ${botPage(applicationId)} (Privileged Gateway Intents).`);
+}
+/** After a reload error: the bot keeps the file's previous version. */
+const KEPT = '\n  Until you fix it, the bot keeps the last working version of this file, if any.';
+const COPY_GUILD_ID_HELP = 'To get it: Discord > User Settings > Advanced > enable Developer Mode, then right-click your server > Copy Server ID.';
+export async function dev() {
+    const hasEnvFile = loadEnv();
+    if (!hasEnvFile && !process.env.BOT_TOKEN) {
+        throw new Error(`No .env file in ${process.cwd()}.\n` +
+            '  Copy .env.example to .env, then fill in BOT_TOKEN and DEV_GUILD_ID.');
+    }
+    const token = process.env.BOT_TOKEN?.trim();
+    if (!token) {
+        throw new Error('BOT_TOKEN is missing from your .env file.\n' +
+            `  To get it: ${botPage(null)} > Reset Token.`);
+    }
+    if (token.startsWith('<')) {
+        throw new Error(`BOT_TOKEN still has the example value ${token}: replace it in your .env file with your bot's token.\n` +
+            `  To get it: ${botPage(null)} > Reset Token.`);
+    }
+    const devGuildId = process.env.DEV_GUILD_ID?.trim();
+    if (!devGuildId) {
+        throw new Error('DEV_GUILD_ID is missing from your .env file: it is the ID of the server where you test your bot.\n' +
+            `  ${COPY_GUILD_ID_HELP}`);
+    }
+    // https://docs.discord.com/developers/reference#snowflakes
+    if (!/^\d{17,20}$/.test(devGuildId)) {
+        throw new Error(`DEV_GUILD_ID "${devGuildId}" in your .env file is not a server ID (a number of 17 to 20 digits).\n` +
+            `  ${COPY_GUILD_ID_HELP}`);
+    }
+    let presence = await loadPresence();
+    const loaded = await loadEvents();
+    const components = await loadComponents();
+    const loadErrors = [...loaded.errors, ...components.errors];
+    if (loadErrors.length > 0)
+        throw new Error(loadErrors.join('\n✗ '));
+    let events = loaded.events;
+    const gateway = new Gateway({
+        token,
+        devGuildId,
+        dev: true,
+        presence: presence?.initial,
+        intents: eventIntents(events),
+    });
+    const { client } = gateway;
+    const onHandlerError = (file, error) => console.error(`✗ ${file}: ${describeRuntimeError(error)}`);
+    const router = new EventRouter(client, events, onHandlerError);
+    // Clicks on components of src/components/ go to their handler, not to interactionCreate
+    router.intercept = (event, data) => event === 'INTERACTION_CREATE' &&
+        handleComponentInteraction(client, data, onHandlerError);
+    gateway.on('dispatch', router.dispatch);
+    gateway.on('warning', (message) => console.warn(`⚠ ${message}`));
+    /** Intents known to work, kept while a reload tries new ones. */
+    let fallbackIntents = null;
+    /** Intents Discord refused after a reload, not retried until restart (identifies are limited per day). */
+    let refusedIntents = null;
+    gateway.on('ready', () => (fallbackIntents = null));
+    gateway.on('fatal', (error) => {
+        const disallowed = error instanceof GatewayCloseError &&
+            error.code === GatewayCloseCodes.DisallowedIntents;
+        const usage = disallowed ? privilegedIntentsUsage(events) : [];
+        console.error(`✗ ${error.message}`);
+        if (usage.length > 0) {
+            console.error(`  Requested by: ${usage.join(', ')}\n` +
+                `  Enable them in ${botPage(gateway.applicationId)} (Privileged Gateway Intents),\n` +
+                '  or remove them from your code.');
+        }
+        if (disallowed && fallbackIntents !== null) {
+            // Added by a reload: keep the bot running with the previous intents
+            console.error("  The bot keeps running without them, but the events that need them won't be received.\n" +
+                '  Restart chapterjs dev once they are enabled.');
+            refusedIntents = gateway.intents;
+            gateway.setIntents(fallbackIntents);
+            fallbackIntents = null;
+            gateway.login().catch(error => {
+                console.error(`✗ ${errorMessage(error)}`);
+                process.exit(1);
+            });
+            return;
+        }
+        process.exit(1);
+    });
+    gateway.on('resumed', () => console.log('↻ Reconnected to Discord'));
+    if (process.env.CHAPTER_DEBUG) {
+        gateway.on('dispatch', (event) => console.log(`← event ${event}`));
+        gateway.on('presenceUpdate', (presence) => console.log(`→ presence sent: ${presence.status} ${JSON.stringify(presence.activities)}`));
+    }
+    const shutdown = async () => {
+        await gateway.destroy();
+        process.exit(0);
+    };
+    process.once('SIGINT', shutdown);
+    process.once('SIGTERM', shutdown);
+    console.log('Connecting to Discord...');
+    const user = await gateway.login();
+    if (!gateway.guildIds.has(devGuildId)) {
+        await gateway.destroy();
+        // https://docs.discord.com/developers/topics/oauth2#bot-authorization-flow
+        const invite = new URL('https://discord.com/oauth2/authorize');
+        invite.searchParams.set('client_id', gateway.applicationId);
+        invite.searchParams.set('scope', 'bot applications.commands');
+        invite.searchParams.set('integration_type', '0'); // GUILD_INSTALL
+        invite.searchParams.set('guild_id', devGuildId);
+        invite.searchParams.set('disable_guild_select', 'true');
+        throw new Error(`${user.username} is not in your dev server ${devGuildId} (DEV_GUILD_ID) yet. Open this link to add it:\n  ${invite}\n\n` +
+            `  You need the "Manage Server" permission on this server, otherwise Discord won't let you continue.\n` +
+            `  Ask the server owner to open the link, or use a server you own as DEV_GUILD_ID.`);
+    }
+    console.log(`✓ Logged in as ${user.username} (${user.id})`);
+    console.log(`  Listening to server ${devGuildId} (DEV_GUILD_ID)`);
+    if (events.length > 0)
+        console.log(`  Events: ${summarizeEvents(events)}`);
+    if (components.ids.length > 0) {
+        console.log(`  Components: ${components.ids.join(', ')}`);
+    }
+    noteMessageContent(events, gateway.applicationId);
+    router.start();
+    watchComponents(async () => {
+        const result = await loadComponents();
+        for (const error of result.errors)
+            console.error(`✗ ${error}${KEPT}`);
+        console.log(`↻ src/components reloaded${result.ids.length > 0 ? ` (${result.ids.join(', ')})` : ''}`);
+    });
+    watchEvents(async () => {
+        const result = await loadEvents(process.cwd(), events);
+        for (const error of result.errors)
+            console.error(`✗ ${error}${KEPT}`);
+        events = result.events;
+        router.setEvents(events);
+        const intents = eventIntents(events);
+        if (intents !== gateway.intents && intents !== refusedIntents) {
+            console.log('↻ Intents changed: reconnecting to Discord');
+            fallbackIntents ??= gateway.intents;
+            gateway.setIntents(intents);
+        }
+        console.log(`↻ src/events reloaded${events.length > 0 ? ` (${summarizeEvents(events)})` : ''}`);
+        noteMessageContent(events, gateway.applicationId);
+    });
+    const presenceLogger = {
+        error: (error) => console.error(`✗ src/presence: ${errorMessage(error)}`),
+        warn: (message) => console.warn(`⚠ src/presence: ${message}`),
+    };
+    let stopPresenceLoop = presence
+        ? startPresenceLoop(gateway, presence, presenceLogger)
+        : null;
+    watchPresence(async () => {
+        try {
+            presence = await loadPresence();
+            stopPresenceLoop?.();
+            stopPresenceLoop = null;
+            if (presence)
+                stopPresenceLoop = startPresenceLoop(gateway, presence, presenceLogger);
+            else
+                gateway.setPresence({});
+            console.log('↻ src/presence reloaded');
+        }
+        catch (error) {
+            // Keep the bot running with the previous presence until the file is fixed
+            console.error(`✗ ${errorMessage(error)}${KEPT}`);
+        }
+    });
+}

package/dist/components.d.ts

@@ -0,0 +1,97 @@
+import { type Client } from './discord/client.js';
+import { Interaction } from './structures/Interaction.js';
+import type { Member } from './structures/Member.js';
+import type { Message } from './structures/Message.js';
+import type { User } from './structures/User.js';
+/** Values a component carries in its `custom_id`, given back to its handler. */
+export type ComponentData = Record<string, string | number | boolean | null>;
+declare const BUTTON_STYLES: {
+    readonly primary: 1;
+    readonly secondary: 2;
+    readonly success: 3;
+    readonly danger: 4;
+};
+export type ButtonStyle = keyof typeof BUTTON_STYLES;
+export interface ButtonContext<D> {
+    client: Client;
+    interaction: Interaction;
+    /** Data given with `new MyButton({ data })`. */
+    data: D;
+    /** Who clicked. */
+    user: User;
+    /** Who clicked, as a server member. Null in DMs. */
+    member: Member | null;
+    /** Message the button is attached to. */
+    message: Message | null;
+}
+export interface ButtonAppearance {
+    /** Up to 80 characters. */
+    label?: string;
+    /** Defaults to `primary`. */
+    style?: ButtonStyle;
+    /** A unicode emoji (`'🎮'`) or a custom one (`'<:name:id>'`). */
+    emoji?: string;
+    disabled?: boolean;
+}
+export interface ButtonDefinition<D> extends ButtonAppearance {
+    /** Runs when the button is clicked. Answer within 3 seconds, or `interaction.defer()`. */
+    handler: (context: ButtonContext<D>) => unknown;
+}
+/** Changes made where the button is used: appearance, and the data it carries. */
+export type ButtonOptions<D> = ButtonAppearance & ([D] extends [undefined] ? {
+    data?: undefined;
+} : {
+    data: D;
+});
+/** A button ready to be sent, e.g. in `message.reply({ components: [button] })`. */
+export interface ButtonComponent {
+    /** Path of its file in src/components, e.g. `buttons/selectRole`. */
+    readonly id: string;
+    readonly customId: string;
+    toJSON(): Record<string, unknown>;
+}
+/** What `defineButton` returns: `new MyButton(options)`, or `MyButton` as is. */
+export interface ButtonClass<D> {
+    new (...options: [D] extends [undefined] ? [options?: ButtonOptions<D>] : [options: ButtonOptions<D>]): ButtonComponent;
+    readonly id: string;
+}
+/**
+ * Defines a button in `src/components/` (e.g. `src/components/buttons/selectRole.ts`)
+ * that handles its own clicks: they never reach interactionCreate. Its
+ * `custom_id` is generated from its path.
+ *
+ *   export default defineButton({ label: 'Hi', handler: ({ interaction }) => … });
+ *   message.reply({ components: [new SelectRole({ style: 'danger' })] });
+ *
+ * Pass a type to carry data: `defineButton<{ roleId: string }>(…)`, then
+ * `new SelectRole({ data: { roleId } })`.
+ */
+export declare function defineButton<D extends ComponentData | undefined = undefined>(definition: ButtonDefinition<D>): ButtonClass<D>;
+/** Something accepted in `components`: a framework component, a raw object, or a row (array). */
+export type ComponentInput = object | ComponentInput[];
+/**
+ * Converts `components` to what Discord expects: framework components become
+ * JSON, consecutive buttons are put in action rows (5 per row), a select menu
+ * gets its own row, and an array is one row.
+ */
+export declare function serializeComponents(components: ComponentInput[]): object[];
+export interface LoadComponentsResult {
+    /** Ids of the loaded components, e.g. `buttons/selectRole`. */
+    ids: string[];
+    /** One message per invalid file, prefixed with its path. */
+    errors: string[];
+}
+/**
+ * Imports every file of `src/components/` to register its handler, so buttons
+ * sent before a restart keep working. A file that fails to load keeps its
+ * previous definition.
+ */
+export declare function loadComponents(cwd?: string): Promise<LoadComponentsResult>;
+/** Calls `onChange` when anything under `src/components/` changes. */
+export declare function watchComponents(onChange: () => void, cwd?: string): import("fs").FSWatcher | null;
+/**
+ * Runs the handler of a framework component. Returns false when the
+ * interaction isn't for one, so it goes to interactionCreate instead.
+ */
+export declare function handleComponentInteraction(client: Client, data: any, onError: (file: string, error: unknown) => void): boolean;
+export {};

package/dist/components.js

@@ -0,0 +1,260 @@
+import { existsSync } from 'node:fs';
+import { relative, resolve, sep } from 'node:path';
+import { emitWarning } from './discord/client.js';
+import { Interaction, InteractionType } from './structures/Interaction.js';
+import { callerFile, importFresh, scriptFiles, watchTree, } from './utils/modules.js';
+// https://docs.discord.com/developers/components/reference
+/**
+ * Prefix of the `custom_id`s generated by the framework, so their
+ * interactions are routed to their component instead of interactionCreate.
+ */
+const CUSTOM_ID_PREFIX = 'cjs:';
+const DATA_SEPARATOR = '|';
+/** https://docs.discord.com/developers/components/reference#anatomy-of-a-component-custom-id */
+const MAX_CUSTOM_ID_LENGTH = 100;
+const COMPONENT = Symbol.for('chapterjs.component');
+// https://docs.discord.com/developers/components/reference#button-button-styles
+const BUTTON_STYLES = {
+    primary: 1,
+    secondary: 2,
+    success: 3,
+    danger: 4,
+};
+/**
+ * Latest definition of each component, by id. Updated each time a component
+ * file is (re)imported, so buttons imported elsewhere before a reload still
+ * use the new appearance and handler.
+ */
+const registry = new Map();
+const componentsDir = (cwd) => resolve(cwd, 'src', 'components');
+/**
+ * Defines a button in `src/components/` (e.g. `src/components/buttons/selectRole.ts`)
+ * that handles its own clicks: they never reach interactionCreate. Its
+ * `custom_id` is generated from its path.
+ *
+ *   export default defineButton({ label: 'Hi', handler: ({ interaction }) => … });
+ *   message.reply({ components: [new SelectRole({ style: 'danger' })] });
+ *
+ * Pass a type to carry data: `defineButton<{ roleId: string }>(…)`, then
+ * `new SelectRole({ data: { roleId } })`.
+ */
+export function defineButton(definition) {
+    validateAppearance(definition);
+    if (typeof definition?.handler !== 'function') {
+        throw new Error("defineButton() needs a handler, the function run on click: defineButton({ label: 'Click me', handler: ({ interaction }) => { … } }).");
+    }
+    const file = callerFile();
+    const cwd = process.cwd();
+    const relativeToComponents = file ? relative(componentsDir(cwd), file) : '..';
+    if (relativeToComponents.startsWith('..')) {
+        throw new Error(`defineButton() can only be used in a file of src/components/${file ? ` (found in ${relative(cwd, file)})` : ''}: create the button in its own file there, then import it where you use it.`);
+    }
+    const id = relativeToComponents
+        .replace(/\.[mc]?[jt]s$/, '')
+        .split(sep)
+        .join('/');
+    registry.set(id, { id, file: relative(cwd, file), definition });
+    class Button {
+        static id = id;
+        static [COMPONENT] = true;
+        id = id;
+        #options;
+        constructor(options) {
+            validateAppearance(options ?? {});
+            this.#options = options ?? {};
+        }
+        get customId() {
+            return toCustomId(id, this.#options.data);
+        }
+        // https://docs.discord.com/developers/components/reference#button-button-structure
+        toJSON() {
+            const latest = registry.get(id)?.definition ?? definition;
+            const { label, style, emoji, disabled } = { ...latest, ...this.#options };
+            return {
+                type: 2,
+                style: BUTTON_STYLES[style ?? 'primary'],
+                custom_id: this.customId,
+                ...(label !== undefined && { label }),
+                ...(emoji !== undefined && { emoji: toPartialEmoji(emoji) }),
+                ...(disabled !== undefined && { disabled }),
+            };
+        }
+    }
+    return Button;
+}
+function validateAppearance(appearance) {
+    if (appearance.style !== undefined &&
+        !Object.hasOwn(BUTTON_STYLES, appearance.style)) {
+        throw new Error(`Button style "${appearance.style}" doesn't exist. Available styles: ${Object.keys(BUTTON_STYLES).join(', ')}.`);
+    }
+    if (appearance.label !== undefined && appearance.label.length > 80) {
+        throw new Error(`Button label is ${appearance.label.length} characters long, Discord allows 80: "${appearance.label}".`);
+    }
+}
+function toCustomId(id, data) {
+    const customId = CUSTOM_ID_PREFIX +
+        id +
+        (data === undefined ? '' : DATA_SEPARATOR + JSON.stringify(data));
+    if (customId.length > MAX_CUSTOM_ID_LENGTH) {
+        throw new Error(`The data of the button ${id} is too long: with its file path, it takes ${customId.length} characters and Discord allows ${MAX_CUSTOM_ID_LENGTH}. ` +
+            'Store less in data (e.g. an id instead of a whole object), or shorten the file path.');
+    }
+    return customId;
+}
+/** `'🎮'`, `'<:name:id>'` or `'<a:name:id>'` → partial emoji object. */
+function toPartialEmoji(emoji) {
+    const custom = /^<(a?):(\w+):(\d+)>$/.exec(emoji);
+    if (!custom)
+        return { name: emoji };
+    return {
+        id: custom[3],
+        name: custom[2],
+        ...(custom[1] && { animated: true }),
+    };
+}
+const isComponentClass = (value) => typeof value === 'function' && COMPONENT in value;
+// https://docs.discord.com/developers/components/reference#component-object-component-types
+const ACTION_ROW = 1;
+const BUTTON = 2;
+/** Components that must be in an action row: button and select menus. */
+const ROW_CHILDREN = new Set([2, 3, 5, 6, 7, 8]);
+/** https://docs.discord.com/developers/components/reference#action-row */
+const MAX_BUTTONS_PER_ROW = 5;
+/**
+ * Converts `components` to what Discord expects: framework components become
+ * JSON, consecutive buttons are put in action rows (5 per row), a select menu
+ * gets its own row, and an array is one row.
+ */
+export function serializeComponents(components) {
+    const toJSON = (component) => {
+        if (isComponentClass(component))
+            return new component().toJSON();
+        if (Array.isArray(component)) {
+            return { type: ACTION_ROW, components: component.map(toJSON) };
+        }
+        const value = component;
+        return typeof value.toJSON === 'function' ? value.toJSON() : value;
+    };
+    const rows = [];
+    let buttons = null;
+    for (const component of components) {
+        const json = toJSON(component);
+        if (json.type === BUTTON && !Array.isArray(component)) {
+            if (!buttons || buttons.length === MAX_BUTTONS_PER_ROW) {
+                buttons = [];
+                rows.push({ type: ACTION_ROW, components: buttons });
+            }
+            buttons.push(json);
+            continue;
+        }
+        buttons = null;
+        rows.push(ROW_CHILDREN.has(json.type)
+            ? { type: ACTION_ROW, components: [json] }
+            : json);
+    }
+    assertUniqueCustomIds(rows);
+    return rows;
+}
+function assertUniqueCustomIds(components) {
+    const seen = new Set();
+    const visit = (component) => {
+        if (typeof component.custom_id === 'string') {
+            if (seen.has(component.custom_id)) {
+                throw new Error(`This message has the same button twice (custom_id "${component.custom_id}"), Discord requires them to be different. ` +
+                    'Give each one different data: new MyButton({ data: … }).');
+            }
+            seen.add(component.custom_id);
+        }
+        for (const child of component.components ?? [])
+            visit(child);
+    };
+    components.forEach(visit);
+}
+/**
+ * Imports every file of `src/components/` to register its handler, so buttons
+ * sent before a restart keep working. A file that fails to load keeps its
+ * previous definition.
+ */
+export async function loadComponents(cwd = process.cwd()) {
+    const ids = [];
+    const errors = [];
+    const dir = componentsDir(cwd);
+    for (const path of existsSync(dir) ? scriptFiles(dir) : []) {
+        const file = relative(cwd, path);
+        const expected = relative(dir, path)
+            .replace(/\.[mc]?[jt]s$/, '')
+            .split(sep)
+            .join('/');
+        try {
+            const value = (await importFresh(path)).default;
+            if (!isComponentClass(value)) {
+                throw new Error("doesn't export a component. Add at the end of the file: export default defineButton({ label: '…', handler: ({ interaction }) => { … } })");
+            }
+            if (value.id !== expected) {
+                throw new Error(`exports the button of src/components/${value.id}: each file of src/components/ must define its own button with defineButton(). ` +
+                    'Import it from where it is used instead.');
+            }
+            ids.push(expected);
+        }
+        catch (error) {
+            errors.push(`${file}: ${error instanceof Error ? error.message : String(error)}`);
+            if (registry.has(expected))
+                ids.push(expected);
+        }
+    }
+    for (const id of registry.keys())
+        if (!ids.includes(id))
+            registry.delete(id);
+    return { ids, errors };
+}
+/** Calls `onChange` when anything under `src/components/` changes. */
+export function watchComponents(onChange, cwd = process.cwd()) {
+    return watchTree(resolve(cwd, 'src'), path => path === 'components' || path.startsWith(`components${sep}`), onChange);
+}
+/**
+ * Runs the handler of a framework component. Returns false when the
+ * interaction isn't for one, so it goes to interactionCreate instead.
+ */
+export function handleComponentInteraction(client, data, onError) {
+    const customId = data?.data?.custom_id;
+    if (data?.type !== InteractionType.MessageComponent ||
+        typeof customId !== 'string' ||
+        !customId.startsWith(CUSTOM_ID_PREFIX)) {
+        return false;
+    }
+    const body = customId.slice(CUSTOM_ID_PREFIX.length);
+    const separator = body.indexOf(DATA_SEPARATOR);
+    const id = separator === -1 ? body : body.slice(0, separator);
+    const interaction = new Interaction(client, data);
+    const component = registry.get(id);
+    let componentData;
+    try {
+        componentData =
+            separator === -1 ? undefined : JSON.parse(body.slice(separator + 1));
+    }
+    catch {
+        componentData = Symbol.for('invalid');
+    }
+    if (!component || componentData === Symbol.for('invalid')) {
+        emitWarning(client, component
+            ? `The button ${id} was clicked, but its data can't be read: ${customId}`
+            : // The file was deleted or renamed since the message was sent
+                `A button of src/components/${id} was clicked, but this file doesn't exist anymore (deleted or renamed after the message was sent). ` +
+                    'The user was told the button no longer works.');
+        interaction
+            .reply({ content: "This button doesn't work anymore.", ephemeral: true })
+            .catch(error => onError(`src/components/${id}`, error));
+        return true;
+    }
+    Promise.resolve()
+        .then(() => component.definition.handler({
+        client,
+        interaction,
+        data: componentData,
+        user: interaction.user,
+        member: interaction.member,
+        message: interaction.message,
+    }))
+        .catch(error => onError(component.file, error));
+    return true;
+}

package/dist/context.d.ts

@@ -0,0 +1,72 @@
+import type { Client } from './discord/client.js';
+import type { EventName } from './discord/events.js';
+import type { APIRateLimitedEvent, GatewayObject, PartialEmoji, Snowflake } from './discord/types.js';
+import { Channel } from './structures/Channel.js';
+import { Guild } from './structures/Guild.js';
+import { Interaction } from './structures/Interaction.js';
+import { Member } from './structures/Member.js';
+import { Message } from './structures/Message.js';
+import { Reaction } from './structures/Reaction.js';
+import { Role } from './structures/Role.js';
+import { User } from './structures/User.js';
+/**
+ * What a handler receives. Each event only fills some keys, named after what
+ * it is about (`message` in messageCreate, `member` in guildMemberAdd…):
+ * reading a key the event doesn't have throws an error listing the right ones.
+ * Every event has `client` and `data`, the raw payload sent by Discord.
+ */
+export interface EventContext {
+    client: Client;
+    /** Payload sent by Discord, https://docs.discord.com/developers/events/gateway-events */
+    data: any;
+    user: User;
+    member: Member;
+    members: Member[];
+    message: Message;
+    /** Server of the event, for events that only happen in servers. Elsewhere, use `channel.guild`. */
+    guild: Guild;
+    guilds: Guild[];
+    channel: Channel;
+    thread: Channel;
+    threads: Channel[];
+    role: Role;
+    interaction: Interaction;
+    reaction: Reaction;
+    messageId: Snowflake;
+    messageIds: Snowflake[];
+    userId: Snowflake;
+    roleId: Snowflake;
+    scheduledEventId: Snowflake;
+    soundId: Snowflake;
+    integrationId: Snowflake;
+    /** Id of the poll answer. */
+    answerId: number;
+    /** Invite code. */
+    code: string;
+    emoji: PartialEmoji;
+    /** guildCreate/guildDelete: the guild is unavailable because of an outage. In guildDelete, false means the bot was removed. */
+    unavailable: boolean;
+    rateLimit: APIRateLimitedEvent;
+    permissions: GatewayObject;
+    rule: GatewayObject;
+    execution: GatewayObject;
+    entry: GatewayObject;
+    emojis: GatewayObject[];
+    stickers: GatewayObject[];
+    scheduledEvent: GatewayObject;
+    sound: GatewayObject;
+    sounds: GatewayObject[];
+    integration: GatewayObject;
+    invite: GatewayObject;
+    voiceState: GatewayObject;
+    voiceServer: GatewayObject;
+    effect: GatewayObject;
+    stageInstance: GatewayObject;
+    presence: GatewayObject;
+    entitlement: GatewayObject;
+    subscription: GatewayObject;
+    threadMember: GatewayObject;
+    channels: GatewayObject[];
+}
+/** Builds the context of one event, shared by all its handlers. */
+export declare function createContext(name: EventName, client: Client, data: unknown): EventContext;