meocord 2.1.1 → 3.1.0

package/dist/cjs/core/index.cjs

@@ -4,7 +4,7 @@ require('reflect-metadata');
 var inversify = require('inversify');
 var discord_js = require('discord.js');
 var theme = require('../_shared/theme-Bz-D4RbT.cjs');
-var controller_decorator = require('../_shared/controller.decorator-DX5lFlPZ.cjs');
+var controller_decorator = require('../_shared/controller.decorator-MUHA_A3z.cjs');
 var lodashEs = require('lodash-es');
 var enum_index = require('../enum/index.cjs');
 var Table = require('cli-table3');
@@ -26,7 +26,59 @@ const createErrorEmbed = (description)=>{
     return embed;
 };
 
+/**
+ * The name a builder registers under, which is what Discord deduplicates on.
+ *
+ * Read from the built payload rather than from the `@Command` argument: a builder is
+ * free to name the command something other than the string it was handed, and it is
+ * the payload Discord sees.
+ */ function commandNameOf(builder) {
+    try {
+        const json = typeof builder.toJSON === 'function' ? builder.toJSON() : builder;
+        return typeof json?.name === 'string' ? json.name : undefined;
+    } catch  {
+        // A builder missing a required field throws from toJSON. Surfacing that is the
+        // registration call's job, where it is reported against the command Discord
+        // rejected -- deduplication should not be what turns it into a startup crash.
+        return undefined;
+    }
+}
 class MeoCordApp {
+    /**
+   * Runs an event handler so a failure inside it cannot take the process down.
+   *
+   * discord.js calls listeners without awaiting them, so a rejection escaping one has
+   * nothing left to settle it: Node reports an unhandled rejection, which terminates
+   * the process by default. Losing the whole bot because one reaction landed on a
+   * deleted message, or one controller could not be resolved, is a worse failure than
+   * the one that caused it -- every other user is served by the same process.
+   *
+   * Nothing is silenced. The error is logged against the event that produced it, so a
+   * genuine misconfiguration -- an unbound controller, a missing dependency -- shows
+   * up on the very first interaction rather than staying hidden.
+   *
+   * @param event - The gateway event being handled, named in the log.
+   * @param run - The handler to run.
+   */ async runListener(event, run) {
+        try {
+            await run();
+        } catch (error) {
+            this.logger.error(`Unhandled error while handling "${event}":`, error);
+        }
+    }
+    /**
+   * Rotates the bot's activity.
+   *
+   * Guarded separately from {@link runListener}: this runs on a timer rather than an
+   * event, and a throw from a timer callback is an uncaught exception no listener
+   * wrapper can reach.
+   */ updateActivity() {
+        try {
+            this.bot.user?.setActivity(lodashEs.sample(this.activities));
+        } catch (error) {
+            this.logger.error('Could not update the bot activity:', error);
+        }
+    }
     getInstance(controllerClass) {
         if (!this.controllerInstancesCache.has(controllerClass)) {
             this.controllerInstancesCache.set(controllerClass, this.container.get(controllerClass));
@@ -36,30 +88,20 @@ class MeoCordApp {
     async start() {
         try {
             this.logger.log('Starting bot...');
-            this.bot.on('clientReady', async ()=>{
-                this.activityInterval = setInterval(()=>{
-                    this.bot.user?.setActivity(lodashEs.sample(this.activities));
-                }, 10000);
-                await this.registerCommands();
-            });
-            this.bot.on('interactionCreate', async (interaction)=>{
-                await this.handleInteraction(interaction);
-            });
-            this.bot.on('messageCreate', async (message)=>{
-                await this.handleMessage(message);
-            });
-            this.bot.on('messageReactionAdd', async (reaction, user)=>{
-                await this.handleReaction(reaction, {
-                    user,
-                    action: enum_index.ReactionHandlerAction.ADD
-                });
-            });
-            this.bot.on('messageReactionRemove', async (reaction, user)=>{
-                await this.handleReaction(reaction, {
-                    user,
-                    action: enum_index.ReactionHandlerAction.REMOVE
-                });
-            });
+            this.bot.on('clientReady', ()=>this.runListener('clientReady', async ()=>{
+                    this.activityInterval = setInterval(()=>this.updateActivity(), 10000);
+                    await this.registerCommands();
+                }));
+            this.bot.on('interactionCreate', (interaction)=>this.runListener('interactionCreate', ()=>this.handleInteraction(interaction)));
+            this.bot.on('messageCreate', (message)=>this.runListener('messageCreate', ()=>this.handleMessage(message)));
+            this.bot.on('messageReactionAdd', (reaction, user)=>this.runListener('messageReactionAdd', ()=>this.handleReaction(reaction, {
+                        user,
+                        action: enum_index.ReactionHandlerAction.ADD
+                    })));
+            this.bot.on('messageReactionRemove', (reaction, user)=>this.runListener('messageReactionRemove', ()=>this.handleReaction(reaction, {
+                        user,
+                        action: enum_index.ReactionHandlerAction.REMOVE
+                    })));
             await this.bot.login(this.discordToken);
             this.logger.log('Bot is online!');
         } catch (error) {
@@ -67,7 +109,11 @@ class MeoCordApp {
         }
     }
     async registerCommands() {
-        const builders = [];
+        // Keyed by registered name: a command whose subcommands live in separate methods
+        // declares the same name more than once, and sending its builder twice makes
+        // Discord reject the whole payload. The first builder wins, and a second one that
+        // is not the same object is reported rather than silently dropped.
+        const buildersByName = new Map();
         for (const controllerClass of this.controllerClasses){
             const instance = this.getInstance(controllerClass);
             const commandMap = controller_decorator.getCommandMap(instance);
@@ -75,12 +121,20 @@ class MeoCordApp {
                 const commandMetadataArray = commandMap[commandName];
                 if (!Array.isArray(commandMetadataArray)) continue;
                 for (const { builder, type } of commandMetadataArray){
-                    if (type in enum_index.CommandType && builder) {
-                        builders.push(builder);
+                    if (!(type in enum_index.CommandType) || !builder) continue;
+                    const registeredName = commandNameOf(builder) ?? commandName;
+                    const existing = buildersByName.get(registeredName);
+                    if (existing === undefined) {
+                        buildersByName.set(registeredName, builder);
+                    } else if (existing !== builder) {
+                        this.logger.warn(`Command "${registeredName}" is built more than once; only the first builder is registered. ` + `Declare the builder on one @Command and give the others the plain CommandType.`);
                     }
                 }
             }
         }
+        const builders = [
+            ...buildersByName.values()
+        ];
         try {
             if (this.bot.application) {
                 await this.bot.application.commands.set(builders);
@@ -99,7 +153,7 @@ class MeoCordApp {
                 });
                 for (const builder of builders){
                     const json = typeof builder.toJSON === 'function' ? builder.toJSON() : builder;
-                    const typeName = json?.type === 1 ? 'SlashCommand' : json?.type === 2 ? 'UserContextMenu' : json?.type === 3 ? 'MessageContextMenu' : builder instanceof discord_js.SlashCommandBuilder ? 'SlashCommand' : 'Command';
+                    const typeName = json?.type === 1 ? 'SlashCommand' : json?.type === 2 ? 'UserContextMenu' : json?.type === 3 ? 'MessageContextMenu' : json?.type === 4 ? 'PrimaryEntryPoint' : builder instanceof discord_js.SlashCommandBuilder ? 'SlashCommand' : 'Command';
                     const name = json?.name || builder.name;
                     const subCommands = Array.isArray(json?.options) && json.options.length ? json.options.map((opt)=>opt.name).join(', ') : '';
                     table.push([
@@ -114,78 +168,219 @@ class MeoCordApp {
             this.logger.error('Error during command registration:', error);
         }
     }
-    async handleInteraction(interaction) {
+    getComponentRoutes() {
+        if (this.componentRoutes) return this.componentRoutes;
+        const routes = [];
         for (const controllerClass of this.controllerClasses){
-            const controllerInstance = this.getInstance(controllerClass);
-            const commandMap = controller_decorator.getCommandMap(controllerInstance);
+            const commandMap = controller_decorator.getCommandMap(this.getInstance(controllerClass));
             if (!commandMap) continue;
-            let commandMetadataArray = undefined;
-            let commandIdentifier = undefined;
-            if (interaction.isChatInputCommand() || interaction.isContextMenuCommand()) {
-                commandIdentifier = interaction.commandName;
-                commandMetadataArray = commandMap[commandIdentifier];
-            } else if (interaction.isButton() || interaction.isStringSelectMenu() || interaction.isModalSubmit()) {
-                commandIdentifier = interaction.customId;
-                const foundEntry = Object.entries(commandMap).find(([commandName, metaArray])=>{
-                    if (!Array.isArray(metaArray)) return false;
-                    return metaArray.some((meta)=>{
-                        if (!meta.regex || !commandIdentifier) return false;
-                        const match = meta.regex.exec(commandIdentifier);
-                        if (match?.groups) {
-                            interaction.dynamicParams = match.groups;
-                            return true;
-                        }
-                        return commandIdentifier === commandName;
+            for (const [pattern, metaArray] of Object.entries(commandMap)){
+                if (!Array.isArray(metaArray)) continue;
+                for (const meta of metaArray){
+                    if (meta.regex) routes.push({
+                        controllerClass,
+                        meta,
+                        pattern
                     });
-                });
-                if (foundEntry) {
-                    commandMetadataArray = foundEntry[1];
                 }
             }
-            if (commandMetadataArray && commandMetadataArray.length > 0) {
-                const commandMetadata = commandMetadataArray[0];
-                const { methodName, type } = commandMetadata;
+        }
+        routes.sort((a, b)=>(b.meta.specificity ?? 0) - (a.meta.specificity ?? 0));
+        this.reportAmbiguousRoutes(routes);
+        this.componentRoutes = routes;
+        return routes;
+    }
+    /**
+   * Warns rather than throws: an app whose patterns overlap boots and works today, and
+   * refusing to start would turn a latent mis-route into an outage on upgrade.
+   */ reportAmbiguousRoutes(routes) {
+        // Grouped by command type first: dispatch only considers routes whose component
+        // type matches the interaction, so a button and a select menu sharing a pattern
+        // are never in competition and reporting them would be a false alarm.
+        const byType = new Map();
+        for (const { meta, pattern } of routes){
+            const patterns = byType.get(meta.type) ?? [];
+            patterns.push(pattern);
+            byType.set(meta.type, patterns);
+        }
+        const collisions = [
+            ...byType.values()
+        ].flatMap((patterns)=>controller_decorator.findAmbiguousRoutes(patterns));
+        if (collisions.length === 0) return;
+        this.logger.warn(`${collisions.length} pattern pair(s) can match the same customId, so which one runs is decided by ` + `ranking rather than by the ids themselves:\n` + collisions.map(([left, right])=>`  "${left}"  vs  "${right}"`).join('\n') + `\nA parameter stops at "${controller_decorator.PARAM_SEPARATOR}", so separating these segments with it makes them distinct.`);
+    }
+    getAutocompleteRoutes() {
+        if (this.autocompleteRoutes) return this.autocompleteRoutes;
+        const routes = [];
+        for (const controllerClass of this.controllerClasses){
+            for (const meta of controller_decorator.getAutocompleteHandlers(this.getInstance(controllerClass))){
+                routes.push({
+                    controllerClass,
+                    meta
+                });
+            }
+        }
+        routes.sort((a, b)=>Number(Boolean(b.meta.optionName)) - Number(Boolean(a.meta.optionName)));
+        this.autocompleteRoutes = routes;
+        return routes;
+    }
+    /**
+   * Dispatches an interaction, and makes sure a failure anywhere in that still reaches
+   * the person who triggered it.
+   *
+   * {@link executeCommand} already reports what a handler throws, but everything
+   * *before* the handler can fail too — resolving a controller through the container
+   * is the common case — and a component that fails there would otherwise look dead
+   * with nothing said to the user and nothing in the log.
+   */ async handleInteraction(interaction) {
+        try {
+            await this.dispatchInteraction(interaction);
+        } catch (error) {
+            this.logger.error(`Error dispatching ${controller_decorator.describeInteraction(interaction)}:`, error);
+            // Autocomplete has no reply to fall back on; closing its window is the only
+            // thing that stops the client showing a loading state until it times out.
+            if (interaction.isAutocomplete()) {
+                await this.respondEmpty(interaction);
+                return;
+            }
+            await this.replyWithError(interaction, 'An error occurred while executing the command.');
+        }
+    }
+    async dispatchInteraction(interaction) {
+        // Autocomplete first, and on its own path: it is answered with `respond()` rather
+        // than a reply, it has no customId to route on, and the "Command not found!" reply
+        // the other paths end in cannot be sent to it at all.
+        if (interaction.isAutocomplete()) {
+            await this.handleAutocomplete(interaction);
+            return;
+        }
+        // Component interactions route on a pattern, so they go through the ranked table.
+        // Commands match their registered name exactly and cannot overlap.
+        if (controller_decorator.hasCustomId(interaction)) {
+            const customId = interaction.customId;
+            for (const { controllerClass, meta } of this.getComponentRoutes()){
+                // A button and a select menu may legitimately share a customId shape, so the
+                // pattern alone does not identify the handler -- the component type does.
+                if (!controller_decorator.matchesCommandType(meta.type, interaction)) continue;
+                const match = meta.regex.exec(customId);
+                if (!match) continue;
+                interaction.dynamicParams = match.groups ?? {};
+                await this.executeCommand(this.getInstance(controllerClass), meta, interaction, customId);
+                return;
+            }
+        }
+        // Paths are walked outside the controller loop so the full subcommand path always
+        // beats the bare command name, whatever order the controllers were registered in.
+        for (const path of this.resolveNameRoutes(interaction)){
+            for (const controllerClass of this.controllerClasses){
+                const controllerInstance = this.getInstance(controllerClass);
+                const commandMap = controller_decorator.getCommandMap(controllerInstance);
+                const commandMetadata = commandMap?.[path]?.find((meta)=>controller_decorator.matchesCommandType(meta.type, interaction));
+                if (!commandMetadata) continue;
+                await this.executeCommand(controllerInstance, commandMetadata, interaction, path);
+                return;
+            }
+        }
+        // Log what actually failed to match. The user's "Command not found!" says nothing
+        // about which id was unroutable, so a control that is emitted but never routed --
+        // a customId whose value broke its pattern, or a handler nobody wrote -- stays
+        // invisible until somebody reports the dead button.
+        this.logger.warn(`No handler matched ${controller_decorator.describeInteraction(interaction)}. Check that a @Command pattern is ` + `declared for it and that its controller is registered.`);
+        await this.replyWithError(interaction, 'Command not found!');
+    }
+    /**
+   * The names a command interaction can be handled under, most specific first.
+   *
+   * Empty for anything that is not a registered command, which is how a component
+   * whose customId matched no pattern falls through to the unmatched warning instead
+   * of being looked up under a name it does not have.
+   */ resolveNameRoutes(interaction) {
+        if (interaction.isChatInputCommand()) return controller_decorator.resolveCommandPaths(interaction);
+        if (interaction.isContextMenuCommand() || interaction.isPrimaryEntryPointCommand()) {
+            return [
+                interaction.commandName
+            ];
+        }
+        return [];
+    }
+    /**
+   * Answers an autocomplete interaction from the `@Autocomplete` handler that claims it.
+   *
+   * Discord closes the window after three seconds and shows a loading state until
+   * something arrives, so an unclaimed option is answered with an empty list rather
+   * than left to time out -- a visibly empty menu is a better failure than a stuck one,
+   * and the warning says which option is missing a handler.
+   */ async handleAutocomplete(interaction) {
+        const focusedName = controller_decorator.focusedOptionName(interaction);
+        for (const path of controller_decorator.resolveCommandPaths(interaction)){
+            for (const { controllerClass, meta } of this.getAutocompleteRoutes()){
+                if (meta.commandPath !== path) continue;
+                if (meta.optionName !== undefined && meta.optionName !== focusedName) continue;
                 try {
-                    if (type === enum_index.CommandType.SLASH && interaction.isChatInputCommand() || type === enum_index.CommandType.BUTTON && interaction.isButton() || type === enum_index.CommandType.SELECT_MENU && interaction.isStringSelectMenu() || type === enum_index.CommandType.CONTEXT_MENU && interaction.isUserContextMenuCommand() || type === enum_index.CommandType.CONTEXT_MENU && interaction.isMessageContextMenuCommand() || type === enum_index.CommandType.MODAL_SUBMIT && interaction.isModalSubmit()) {
-                        this.logger.log('[INTERACTION]', `[${enum_index.CommandType[type]}]`, `[${methodName}]`);
-                        let dynamicParams = {};
-                        if (interaction.isChatInputCommand() && interaction.options) {
-                            dynamicParams = interaction.options.data.reduce((acc, opt)=>{
-                                acc[opt.name] = opt.value;
-                                return acc;
-                            }, {});
-                        } else if (interaction.isButton() || interaction.isStringSelectMenu() || interaction.isModalSubmit()) {
-                            dynamicParams = interaction.dynamicParams || {};
-                        }
-                        await controllerInstance[methodName](interaction, dynamicParams);
-                        return;
-                    } else {
-                        this.logger.debug(type, methodName, enum_index.CommandType.BUTTON, interaction.isButton());
-                        this.logger.warn(`Interaction type mismatch for command "${commandIdentifier}". Interaction type: ${interaction.type}.`);
-                    }
+                    const controllerInstance = this.getInstance(controllerClass);
+                    this.logger.log('[AUTOCOMPLETE]', `[${path}]`, `[${meta.methodName}]`);
+                    await controllerInstance[meta.methodName](interaction, controller_decorator.resolveOptionParams(interaction));
                 } catch (error) {
-                    this.logger.error(`Error executing command "${commandIdentifier}":`, error);
-                    if (interaction.isRepliable()) {
-                        const embed = createErrorEmbed('An error occurred while executing the command.');
-                        await interaction.reply({
-                            embeds: [
-                                embed
-                            ],
-                            flags: discord_js.MessageFlagsBitField.Flags.Ephemeral
-                        });
-                    }
+                    this.logger.error(`Error handling ${controller_decorator.describeInteraction(interaction)}:`, error);
+                    await this.respondEmpty(interaction);
                 }
                 return;
             }
         }
-        if (interaction.isRepliable()) {
-            const embed = createErrorEmbed('Command not found!');
+        this.logger.warn(`No handler matched ${controller_decorator.describeInteraction(interaction)}. Declare an @Autocomplete handler for it, ` + `or drop setAutocomplete(true) from the option.`);
+        await this.respondEmpty(interaction);
+    }
+    /** Closes an autocomplete window that nothing else answered. */ async respondEmpty(interaction) {
+        if (interaction.responded) return;
+        try {
+            await interaction.respond([]);
+        } catch (error) {
+            // The three-second window may already have closed, which is not actionable.
+            this.logger.debug(`Could not close autocomplete window: ${String(error)}`);
+        }
+    }
+    /**
+   * Runs a resolved command, shared by both dispatch paths so a pattern-matched
+   * component and a named slash command behave identically once the route is chosen.
+   */ async executeCommand(controllerInstance, commandMetadata, interaction, commandIdentifier) {
+        const { methodName, type } = commandMetadata;
+        // No interaction-type check here: both callers pick the route with
+        // `matchesCommandType` before getting this far, and `@Command` re-checks the
+        // interaction on the way into the handler.
+        try {
+            this.logger.log('[INTERACTION]', `[${type}]`, `[${methodName}]`);
+            let dynamicParams = {};
+            if (interaction.isChatInputCommand()) {
+                dynamicParams = controller_decorator.resolveOptionParams(interaction);
+            } else if (controller_decorator.hasCustomId(interaction)) {
+                dynamicParams = interaction.dynamicParams ?? {};
+            }
+            await controllerInstance[methodName](interaction, dynamicParams);
+        } catch (error) {
+            this.logger.error(`Error executing command "${commandIdentifier}":`, error);
+            await this.replyWithError(interaction, 'An error occurred while executing the command.');
+        }
+    }
+    /**
+   * Tells the user something went wrong, if the interaction can still hear it.
+   *
+   * A handler that replies and *then* throws is the common shape of a failure, and
+   * replying twice throws in turn -- out of the catch block, where nothing is left to
+   * handle it. Whatever the interaction's state, reporting an error must not be able
+   * to become a second, worse one.
+   */ async replyWithError(interaction, message) {
+        if (!interaction.isRepliable() || interaction.replied || interaction.deferred) return;
+        try {
+            const embed = createErrorEmbed(message);
             await interaction.reply({
                 embeds: [
                     embed
                 ],
                 flags: discord_js.MessageFlagsBitField.Flags.Ephemeral
             });
+        } catch (error) {
+            // Unknown or already-acknowledged interaction; the user cannot be told anything.
+            this.logger.debug(`Could not deliver the error reply: ${String(error)}`);
         }
     }
     async handleMessage(message) {
@@ -217,7 +412,15 @@ class MeoCordApp {
         }
     }
     async handleReaction(reaction, { user, action }) {
-        await reaction.message.fetch();
+        // A reaction arrives for messages the bot may no longer be able to read -- deleted,
+        // or in a channel it lost access to -- and `fetch` rejects for all of them. That is
+        // an ordinary outcome rather than a fault, so the reaction is skipped quietly.
+        try {
+            await reaction.message.fetch();
+        } catch (error) {
+            this.logger.debug(`Skipping a reaction whose message could not be fetched: ${String(error)}`);
+            return;
+        }
         const relevantControllers = this.controllerClasses.filter((controllerClass)=>{
             const instance = this.getInstance(controllerClass);
             const reactionHandlers = controller_decorator.getReactionHandlers(instance);

package/dist/cjs/decorator/index.cjs

@@ -3,7 +3,7 @@
 require('reflect-metadata');
 var inversify = require('inversify');
 var metadataKey_enum = require('../_shared/metadata-key.enum-BzzvGUId.cjs');
-var controller_decorator = require('../_shared/controller.decorator-DX5lFlPZ.cjs');
+var controller_decorator = require('../_shared/controller.decorator-MUHA_A3z.cjs');
 var discord_js = require('discord.js');
 require('../enum/index.cjs');
 
@@ -246,10 +246,14 @@ export class ButtonInteractionGuard implements GuardInterface {
     };
 }
 
+exports.Autocomplete = controller_decorator.Autocomplete;
 exports.Command = controller_decorator.Command;
 exports.Controller = controller_decorator.Controller;
 exports.MessageHandler = controller_decorator.MessageHandler;
+exports.PARAM_SEPARATOR = controller_decorator.PARAM_SEPARATOR;
 exports.ReactionHandler = controller_decorator.ReactionHandler;
+exports.findAmbiguousRoutes = controller_decorator.findAmbiguousRoutes;
+exports.getAutocompleteHandlers = controller_decorator.getAutocompleteHandlers;
 exports.getCommandMap = controller_decorator.getCommandMap;
 exports.getMessageHandlers = controller_decorator.getMessageHandlers;
 exports.getReactionHandlers = controller_decorator.getReactionHandlers;

package/dist/cjs/enum/index.cjs

@@ -2,11 +2,24 @@
 
 var metadataKey_enum = require('../_shared/metadata-key.enum-BzzvGUId.cjs');
 
-var CommandType = /*#__PURE__*/ function(CommandType) {
-    CommandType["SLASH"] = "SLASH";
+/**
+ * The kinds of interaction a `@Command` method can be bound to.
+ *
+ * Each member names one Discord interaction shape rather than a family of them, so a
+ * handler's parameter type follows from its command type alone. That is why the four
+ * entity select menus are separate members instead of one `SELECT_MENU`: Discord sends
+ * them as distinct component types (5-8) carrying different resolved data, and
+ * collapsing them would leave the handler with a union it has to re-narrow by hand.
+ */ var CommandType = /*#__PURE__*/ function(CommandType) {
+    /** Chat input command, or one subcommand of it. */ CommandType["SLASH"] = "SLASH";
+    /** User or message context menu command. */ CommandType["CONTEXT_MENU"] = "CONTEXT_MENU";
+    /** Activity launch command (`ApplicationCommandType.PrimaryEntryPoint`). */ CommandType["PRIMARY_ENTRY_POINT"] = "PRIMARY_ENTRY_POINT";
     CommandType["BUTTON"] = "BUTTON";
-    CommandType["CONTEXT_MENU"] = "CONTEXT_MENU";
-    CommandType["SELECT_MENU"] = "SELECT_MENU";
+    /** String select menu — the one whose options the application defines itself. */ CommandType["SELECT_MENU"] = "SELECT_MENU";
+    CommandType["USER_SELECT_MENU"] = "USER_SELECT_MENU";
+    CommandType["ROLE_SELECT_MENU"] = "ROLE_SELECT_MENU";
+    CommandType["MENTIONABLE_SELECT_MENU"] = "MENTIONABLE_SELECT_MENU";
+    CommandType["CHANNEL_SELECT_MENU"] = "CHANNEL_SELECT_MENU";
     CommandType["MODAL_SUBMIT"] = "MODAL_SUBMIT";
     return CommandType;
 }({});

package/dist/cjs/testing/index.cjs

@@ -410,7 +410,9 @@ const TYPE_GUARD_METHODS = [
     'isMentionableSelectMenu',
     'isChannelSelectMenu',
     'isAnySelectMenu',
-    'isSelectMenu',
+    // `isSelectMenu` is intentionally absent: discord.js deprecated it in favour of
+    // `isStringSelectMenu`, and wiring it here would emit a deprecation warning on every
+    // mock that has it on its prototype.
     'isModalSubmit',
     'isAutocomplete',
     'isRepliable'
@@ -480,9 +482,11 @@ function findPrototypeMethod(instance, name) {
         instance.ephemeral = false;
         const alreadyReplied = ()=>new Error('The reply to this interaction has already been sent or deferred.');
         const notYetReplied = (method)=>new Error(`Cannot call ${method}() before replying or deferring.`);
+        // Only `flags` is read: the `ephemeral: true` reply option is deprecated in
+        // discord.js, and honouring it here would let a test pass against a call the
+        // library has stopped supporting.
         const hasEphemeralFlag = (options)=>{
             if (!options) return false;
-            if (options.ephemeral === true) return true;
             const { flags } = options;
             if (typeof flags === 'number') return (flags & 64) !== 0;
             if (typeof flags === 'bigint') return (flags & 64n) !== 0n;
@@ -523,6 +527,17 @@ function findPrototypeMethod(instance, name) {
             }));
         }
     }
+    // Autocomplete is not repliable, but it has a response of its own: Discord accepts
+    // one `respond()` per interaction and rejects the second. Without `responded` set
+    // here it would read as an auto-stubbed object -- truthy -- and any code that checks
+    // it before answering would decide the window was already closed.
+    if (instance.type === discord_js.InteractionType.ApplicationCommandAutocomplete) {
+        instance.responded = false;
+        stubs.set('respond', createMockFn(async ()=>{
+            if (instance.responded) throw new Error('The reply to this interaction has already been sent or deferred.');
+            instance.responded = true;
+        }));
+    }
     // Applied last so an explicit prop wins over the type fields and the reply
     // state machine. defineProperty rather than assignment for the same reason the
     // Proxy uses it: several of these shadow a getter-only prototype accessor.
@@ -802,7 +817,64 @@ function createMockMessage() {
  * interaction.options.getSubcommand()  // → 'notes'
  * interaction.options.getNumber('uid') // → 12345678
  * ```
- */ // `any` is the default rather than `CacheType` because TypeScript types a generic
+ */ /** The option type Discord would have sent for a given JavaScript value. */ function optionTypeOf(value) {
+    if (typeof value === 'boolean') return discord_js.ApplicationCommandOptionType.Boolean;
+    if (typeof value === 'number') return discord_js.ApplicationCommandOptionType.Number;
+    if (value instanceof discord_js.User) return discord_js.ApplicationCommandOptionType.User;
+    if (value instanceof discord_js.GuildMember) return discord_js.ApplicationCommandOptionType.User;
+    if (value instanceof discord_js.Role) return discord_js.ApplicationCommandOptionType.Role;
+    if (value instanceof discord_js.BaseChannel) return discord_js.ApplicationCommandOptionType.Channel;
+    if (value instanceof discord_js.Attachment) return discord_js.ApplicationCommandOptionType.Attachment;
+    if (typeof value === 'object' && value !== null) return discord_js.ApplicationCommandOptionType.Mentionable;
+    return discord_js.ApplicationCommandOptionType.String;
+}
+/**
+ * Shapes one supplied option the way the gateway sends it.
+ *
+ * An entity option arrives as a snowflake in `value` *and* as the resolved object on
+ * its own field, and code that reads only one of the two is exactly what this lets a
+ * test catch — so both are set.
+ */ function toOptionData(name, value) {
+    const type = optionTypeOf(value);
+    const isEntity = typeof value === 'object' && value !== null;
+    const option = {
+        name,
+        type,
+        value: isEntity ? value.id : value
+    };
+    if (value instanceof discord_js.User) option.user = value;
+    else if (value instanceof discord_js.GuildMember) option.member = value;
+    else if (value instanceof discord_js.Role) option.role = value;
+    else if (value instanceof discord_js.BaseChannel) option.channel = value;
+    else if (value instanceof discord_js.Attachment) option.attachment = value;
+    else if (isEntity) option.user = value;
+    return option;
+}
+/**
+ * Nests the supplied options under the subcommand path they were invoked through,
+ * matching the shape Discord sends rather than a flat list.
+ */ function buildOptionData(subcommandGroup, subcommand, values) {
+    const leaves = Object.entries(values).map(([name, value])=>toOptionData(name, value));
+    if (subcommand === null) return leaves;
+    const sub = {
+        name: subcommand,
+        type: discord_js.ApplicationCommandOptionType.Subcommand,
+        options: leaves
+    };
+    if (subcommandGroup === null) return [
+        sub
+    ];
+    return [
+        {
+            name: subcommandGroup,
+            type: discord_js.ApplicationCommandOptionType.SubcommandGroup,
+            options: [
+                sub
+            ]
+        }
+    ];
+}
+// `any` is the default rather than `CacheType` because TypeScript types a generic
 // class's `prototype` with `any` for its parameters, and createMockInteraction infers
 // T from exactly that — `createMockInteraction(ChatInputCommandInteraction)` produces
 // an interaction whose `options` is `CommandInteractionOptionResolver<any>`. Defaulting
@@ -810,7 +882,7 @@ function createMockMessage() {
 // the target rejects, and the resolver stops being assignable to the property it exists
 // to fill. Pass Cached explicitly when the interaction under test is pinned.
 function createChatInputOptions(opts = {}) {
-    const { subcommandGroup = null, subcommand = null, ...values } = opts;
+    const { subcommandGroup = null, subcommand = null, focused = null, ...values } = opts;
     function resolveOrThrow(name, value, required) {
         if (value === null) {
             if (required === true) throw new Error(`Option "${name}" is required but was not provided.`);
@@ -841,6 +913,18 @@ function createChatInputOptions(opts = {}) {
     base.getChannel = createMockFn(getObjectOption);
     base.getMember = createMockFn(getObjectOption);
     base.getMentionable = createMockFn(getObjectOption);
+    base.getFocused = createMockFn((getFull)=>{
+        if (focused === null) throw new Error('No focused option found.');
+        const option = toOptionData(focused, values[focused] ?? null);
+        return getFull === true ? {
+            ...option,
+            focused: true
+        } : option.value;
+    });
+    // `data` is what the framework reads to build a handler's params, and it is the one
+    // part of the resolver that is not a method — so it has to be materialised here
+    // rather than auto-stubbed, or every params assertion would see an empty record.
+    base.data = buildOptionData(subcommandGroup, subcommand, values);
     return stubDeep(base);
 }