meocord 3.0.0 → 3.2.0

package/dist/esm/core/meocord.app.js

@@ -1,22 +1,66 @@
 import { SlashCommandBuilder, MessageFlagsBitField } from 'discord.js';
 import { Logger } from '../common/logger.js';
 import '../common/theme.js';
-import { getCommandMap, findAmbiguousRoutes, PARAM_SEPARATOR, getMessageHandlers, getReactionHandlers } from '../decorator/controller.decorator.js';
+import { getCommandMap, findAmbiguousRoutes, PARAM_SEPARATOR, getAutocompleteHandlers, getMessageHandlers, getReactionHandlers } from '../decorator/controller.decorator.js';
 import { sample } from 'lodash-es';
 import { createErrorEmbed } from '../util/embed.util.js';
+import { describeInteraction, hasCustomId, matchesCommandType, resolveCommandPaths, focusedOptionName, resolveOptionParams } from '../util/interaction.util.js';
 import { ReactionHandlerAction, CommandType } from '../enum/controller.enum.js';
 import CliTable3 from 'cli-table3';
 
-/** Identifies an unmatched interaction for the log, by whichever field would have routed it. */ function describeUnmatched(interaction) {
-    if (interaction.isChatInputCommand() || interaction.isContextMenuCommand()) {
-        return `command "${interaction.commandName}"`;
+/**
+ * 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;
     }
-    if (interaction.isButton() || interaction.isStringSelectMenu() || interaction.isModalSubmit()) {
-        return `customId "${interaction.customId}"`;
-    }
-    return `interaction type ${interaction.type}`;
 }
 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(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));
@@ -26,30 +70,20 @@ class MeoCordApp {
     async start() {
         try {
             this.logger.log('Starting bot...');
-            this.bot.on('clientReady', async ()=>{
-                this.activityInterval = setInterval(()=>{
-                    this.bot.user?.setActivity(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: ReactionHandlerAction.ADD
-                });
-            });
-            this.bot.on('messageReactionRemove', async (reaction, user)=>{
-                await this.handleReaction(reaction, {
-                    user,
-                    action: 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: ReactionHandlerAction.ADD
+                    })));
+            this.bot.on('messageReactionRemove', (reaction, user)=>this.runListener('messageReactionRemove', ()=>this.handleReaction(reaction, {
+                        user,
+                        action: ReactionHandlerAction.REMOVE
+                    })));
             await this.bot.login(this.discordToken);
             this.logger.log('Bot is online!');
         } catch (error) {
@@ -57,7 +91,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 = getCommandMap(instance);
@@ -65,12 +103,20 @@ class MeoCordApp {
                 const commandMetadataArray = commandMap[commandName];
                 if (!Array.isArray(commandMetadataArray)) continue;
                 for (const { builder, type } of commandMetadataArray){
-                    if (type in CommandType && builder) {
-                        builders.push(builder);
+                    if (!(type in 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);
@@ -89,7 +135,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 SlashCommandBuilder ? 'SlashCommand' : 'Command';
+                    const typeName = json?.type === 1 ? 'SlashCommand' : json?.type === 2 ? 'UserContextMenu' : json?.type === 3 ? 'MessageContextMenu' : json?.type === 4 ? 'PrimaryEntryPoint' : builder instanceof 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([
@@ -130,16 +176,74 @@ class MeoCordApp {
    * 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) {
-        const collisions = findAmbiguousRoutes(routes.map(({ pattern })=>pattern));
+        // 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)=>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 "${PARAM_SEPARATOR}", so separating these segments with it makes them distinct.`);
     }
-    async handleInteraction(interaction) {
+    getAutocompleteRoutes() {
+        if (this.autocompleteRoutes) return this.autocompleteRoutes;
+        const routes = [];
+        for (const controllerClass of this.controllerClasses){
+            for (const meta of 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 ${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.
-        // Slash and context-menu commands match their name exactly and cannot overlap.
-        if (interaction.isButton() || interaction.isStringSelectMenu() || interaction.isModalSubmit()) {
+        // Commands match their registered name exactly and cannot overlap.
+        if (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 (!matchesCommandType(meta.type, interaction)) continue;
                 const match = meta.regex.exec(customId);
                 if (!match) continue;
                 interaction.dynamicParams = match.groups ?? {};
@@ -147,19 +251,15 @@ class MeoCordApp {
                 return;
             }
         }
-        for (const controllerClass of this.controllerClasses){
-            const controllerInstance = this.getInstance(controllerClass);
-            const commandMap = getCommandMap(controllerInstance);
-            if (!commandMap) continue;
-            let commandMetadataArray = undefined;
-            let commandIdentifier = undefined;
-            if (interaction.isChatInputCommand() || interaction.isContextMenuCommand()) {
-                commandIdentifier = interaction.commandName;
-                commandMetadataArray = commandMap[commandIdentifier];
-            }
-            if (commandMetadataArray && commandMetadataArray.length > 0) {
-                const commandMetadata = commandMetadataArray[0];
-                await this.executeCommand(controllerInstance, commandMetadata, interaction, commandIdentifier);
+        // 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 = getCommandMap(controllerInstance);
+                const commandMetadata = commandMap?.[path]?.find((meta)=>matchesCommandType(meta.type, interaction));
+                if (!commandMetadata) continue;
+                await this.executeCommand(controllerInstance, commandMetadata, interaction, path);
                 return;
             }
         }
@@ -167,15 +267,58 @@ class MeoCordApp {
         // 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 ${describeUnmatched(interaction)}. Check that a @Command pattern is ` + `declared for it and that its controller is registered.`);
-        if (interaction.isRepliable()) {
-            const embed = createErrorEmbed('Command not found!');
-            await interaction.reply({
-                embeds: [
-                    embed
-                ],
-                flags: MessageFlagsBitField.Flags.Ephemeral
-            });
+        this.logger.warn(`No handler matched ${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 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 = focusedOptionName(interaction);
+        for (const path of resolveCommandPaths(interaction)){
+            for (const { controllerClass, meta } of this.getAutocompleteRoutes()){
+                if (meta.commandPath !== path) continue;
+                if (meta.optionName !== undefined && meta.optionName !== focusedName) continue;
+                try {
+                    const controllerInstance = this.getInstance(controllerClass);
+                    this.logger.log('[AUTOCOMPLETE]', `[${path}]`, `[${meta.methodName}]`);
+                    await controllerInstance[meta.methodName](interaction, resolveOptionParams(interaction));
+                } catch (error) {
+                    this.logger.error(`Error handling ${describeInteraction(interaction)}:`, error);
+                    await this.respondEmpty(interaction);
+                }
+                return;
+            }
+        }
+        this.logger.warn(`No handler matched ${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)}`);
         }
     }
     /**
@@ -183,33 +326,43 @@ class MeoCordApp {
    * 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 {
-            if (type === CommandType.SLASH && interaction.isChatInputCommand() || type === CommandType.BUTTON && interaction.isButton() || type === CommandType.SELECT_MENU && interaction.isStringSelectMenu() || type === CommandType.CONTEXT_MENU && interaction.isUserContextMenuCommand() || type === CommandType.CONTEXT_MENU && interaction.isMessageContextMenuCommand() || type === CommandType.MODAL_SUBMIT && interaction.isModalSubmit()) {
-                this.logger.log('[INTERACTION]', `[${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;
+            this.logger.log('[INTERACTION]', `[${type}]`, `[${methodName}]`);
+            let dynamicParams = {};
+            if (interaction.isChatInputCommand()) {
+                dynamicParams = resolveOptionParams(interaction);
+            } else if (hasCustomId(interaction)) {
+                dynamicParams = interaction.dynamicParams ?? {};
             }
-            this.logger.warn(`Interaction type mismatch for command "${commandIdentifier}". Interaction type: ${interaction.type}.`);
+            await controllerInstance[methodName](interaction, dynamicParams);
         } 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: MessageFlagsBitField.Flags.Ephemeral
-                });
-            }
+            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: 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) {
@@ -241,7 +394,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 = getReactionHandlers(instance);

package/dist/esm/decorator/controller.decorator.js

@@ -1,12 +1,13 @@
 import 'reflect-metadata';
 import { injectable } from 'inversify';
-import { ButtonInteraction, StringSelectMenuInteraction, ChatInputCommandInteraction, ContextMenuCommandInteraction, ModalSubmitInteraction } from 'discord.js';
 import { CommandType } from '../enum/controller.enum.js';
 import { MetadataKey } from '../enum/metadata-key.enum.js';
+import { matchesCommandType, isCustomIdRouted } from '../util/interaction.util.js';
 
 const COMMAND_METADATA_KEY = Symbol('commands');
 const MESSAGE_HANDLER_METADATA_KEY = Symbol('message_handlers');
 const REACTION_HANDLER_METADATA_KEY = Symbol('reaction_handlers');
+const AUTOCOMPLETE_METADATA_KEY = Symbol('autocomplete_handlers');
 /**
  * Decorator to register message handlers in the controller.
  *
@@ -138,8 +139,13 @@ const PLACEHOLDER_PATTERN = /\{(\w+)}/g;
 /**
  * Decorator to register command methods in a controller.
  *
- * @param commandName - The name or pattern of the command.
- * @param builderOrType - A command builder class or a command type from `CommandType`.
+ * @param commandName - What the command is addressed by. Commands registered with
+ *   Discord use their name, and a subcommand its full path — `settings notify email`,
+ *   parts separated by a space, the way Discord displays it. Components use a customId
+ *   pattern, where `{name}` captures one `/`-separated segment.
+ * @param builderOrType - A command builder class, or a `CommandType` for a handler that
+ *   registers nothing of its own: every component, and every subcommand of a command
+ *   whose builder already describes it.
  *
  * @example
  * ```typescript
@@ -148,9 +154,19 @@ const PLACEHOLDER_PATTERN = /\{(\w+)}/g;
  *   await interaction.reply('This is the help command!')
  * }
  *
- * @Command('stats-{id}', CommandType.BUTTON)
- * public async handleStats(message: ButtonInteraction, { id }) {
- *   await message.reply(`Fetching stats for ID: ${id}`);
+ * @Command('settings notify email', CommandType.SLASH)
+ * public async handleNotifyEmail(interaction: ChatInputCommandInteraction, { enabled }) {
+ *   await interaction.reply(`Email notifications ${enabled ? 'on' : 'off'}`)
+ * }
+ *
+ * @Command('stats/{id}', CommandType.BUTTON)
+ * public async handleStats(interaction: ButtonInteraction, { id }) {
+ *   await interaction.reply(`Fetching stats for ID: ${id}`);
+ * }
+ *
+ * @Command('assign/{taskId}', CommandType.USER_SELECT_MENU)
+ * public async handleAssign(interaction: UserSelectMenuInteraction, { taskId }) {
+ *   await interaction.reply(`Assigned ${interaction.users.size} user(s) to ${taskId}`)
  * }
  * ```
  */ function Command(commandName, builderOrType) {
@@ -161,8 +177,7 @@ const PLACEHOLDER_PATTERN = /\{(\w+)}/g;
         }
         // Wrap original method for interaction type validation
         _descriptor.value = function(interaction, params) {
-            const expectedInteraction = commandType === CommandType.BUTTON && interaction instanceof ButtonInteraction || commandType === CommandType.SELECT_MENU && interaction instanceof StringSelectMenuInteraction || commandType === CommandType.SLASH && interaction instanceof ChatInputCommandInteraction || commandType === CommandType.CONTEXT_MENU && interaction instanceof ContextMenuCommandInteraction || commandType === CommandType.MODAL_SUBMIT && interaction instanceof ModalSubmitInteraction;
-            if (!expectedInteraction) {
+            if (!matchesCommandType(commandType, interaction)) {
                 throw new Error(`Invalid interaction type passed to @Command for method: ${propertyKey}`);
             }
             return originalMethod.apply(this, [
@@ -188,7 +203,7 @@ const PLACEHOLDER_PATTERN = /\{(\w+)}/g;
         } else {
             commandType = builderOrType;
         }
-        if (commandType !== CommandType.SLASH && commandType !== CommandType.CONTEXT_MENU) {
+        if (isCustomIdRouted(commandType)) {
             const { regex: generatedRegex, params, specificity: patternSpecificity } = createRegexFromPattern(commandName);
             regex = generatedRegex;
             dynamicParams = params;
@@ -217,6 +232,54 @@ const PLACEHOLDER_PATTERN = /\{(\w+)}/g;
  */ function getCommandMap(controller) {
     return Reflect.getMetadata(COMMAND_METADATA_KEY, controller);
 }
+/**
+ * Decorator to register an autocomplete handler for a chat input command's option.
+ *
+ * Autocomplete is a separate interaction from the command it belongs to, and Discord
+ * sends it while the user is still typing. It is not a `@Command`: nothing is
+ * registered for it — the option's own `setAutocomplete(true)` is what turns it on —
+ * and it is answered with `interaction.respond()` rather than a reply. Leaving it
+ * unhandled is not silent to the user: the client shows a loading state until the
+ * three-second window closes.
+ *
+ * @param commandPath - The command to complete, e.g. `settings` or `settings notify email`
+ *   for a subcommand. Parts are separated by a single space, as Discord displays them.
+ * @param optionName - The option to complete. Omit to handle every option of the command,
+ *   branching on `interaction.options.getFocused(true)`.
+ *
+ * @example
+ * ```typescript
+ * @Autocomplete('search', 'query')
+ * async completeQuery(interaction: AutocompleteInteraction) {
+ *   const { value } = interaction.options.getFocused(true)
+ *   await interaction.respond(this.search(value).map(name => ({ name, value: name })))
+ * }
+ * ```
+ */ function Autocomplete(commandPath, optionName) {
+    return function(target, propertyKey, _descriptor) {
+        const handlers = Reflect.getMetadata(AUTOCOMPLETE_METADATA_KEY, target) || [];
+        handlers.push({
+            commandPath,
+            optionName,
+            methodName: propertyKey.toString()
+        });
+        Reflect.defineMetadata(AUTOCOMPLETE_METADATA_KEY, handlers, target);
+    };
+}
+/**
+ * Retrieves autocomplete handler metadata from a given controller.
+ *
+ * Handlers naming an option come first, so a command-wide handler acts as the fallback
+ * for options no specific handler claimed rather than shadowing them by declaration order.
+ *
+ * @param controller - The controller class instance.
+ * @returns The registered autocomplete handlers, most specific first.
+ */ function getAutocompleteHandlers(controller) {
+    const handlers = Reflect.getMetadata(AUTOCOMPLETE_METADATA_KEY, controller) || [];
+    return [
+        ...handlers
+    ].sort((a, b)=>Number(Boolean(b.optionName)) - Number(Boolean(a.optionName)));
+}
 /**
  * Decorator to mark a class as a controller that can later be registered to the App class `(app.ts)` using the `@MeoCord` decorator.
  *
@@ -275,4 +338,4 @@ const PLACEHOLDER_PATTERN = /\{(\w+)}/g;
     return collisions;
 }
 
-export { Command, Controller, MessageHandler, PARAM_SEPARATOR, ReactionHandler, findAmbiguousRoutes, getCommandMap, getMessageHandlers, getReactionHandlers };
+export { Autocomplete, Command, Controller, MessageHandler, PARAM_SEPARATOR, ReactionHandler, findAmbiguousRoutes, getAutocompleteHandlers, getCommandMap, getMessageHandlers, getReactionHandlers };

package/dist/esm/decorator/guard.decorator.js

@@ -99,7 +99,7 @@ export class ButtonInteractionGuard implements GuardInterface {
  * @example
  * ```typescript
  * // Method-level usage
- * @Command('profile-{id}', CommandType.BUTTON)
+ * @Command('profile/{id}', CommandType.BUTTON)
  * @UseGuard(
  *   { provide: RateLimiterGuard, params: { limit: 2, window: 3000 } },
  *   ButtonInteractionGuard

package/dist/esm/decorator/index.js

@@ -1,5 +1,5 @@
 export { Service } from './service.decorator.js';
 export { CommandBuilder } from './command-builder.decorator.js';
-export { Command, Controller, MessageHandler, PARAM_SEPARATOR, ReactionHandler, findAmbiguousRoutes, getCommandMap, getMessageHandlers, getReactionHandlers } from './controller.decorator.js';
+export { Autocomplete, Command, Controller, MessageHandler, PARAM_SEPARATOR, ReactionHandler, findAmbiguousRoutes, getAutocompleteHandlers, getCommandMap, getMessageHandlers, getReactionHandlers } from './controller.decorator.js';
 export { Guard, UseGuard } from './guard.decorator.js';
 export { MeoCord } from './app.decorator.js';

package/dist/esm/enum/controller.enum.js

@@ -6,17 +6,36 @@
     ControllerType["BUTTON"] = "button";
     ControllerType["MODAL_SUBMIT"] = "modal-submit";
     ControllerType["SELECT_MENU"] = "select-menu";
+    ControllerType["USER_SELECT_MENU"] = "user-select-menu";
+    ControllerType["ROLE_SELECT_MENU"] = "role-select-menu";
+    ControllerType["MENTIONABLE_SELECT_MENU"] = "mentionable-select-menu";
+    ControllerType["CHANNEL_SELECT_MENU"] = "channel-select-menu";
     ControllerType["REACTION"] = "reaction";
     ControllerType["MESSAGE"] = "message";
     ControllerType["SLASH"] = "slash";
+    ControllerType["AUTOCOMPLETE"] = "autocomplete";
     ControllerType["CONTEXT_MENU"] = "context-menu";
+    ControllerType["PRIMARY_ENTRY_POINT"] = "primary-entry-point";
     return ControllerType;
 }({});
-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;
 }({});