meocord 3.0.0 → 3.1.0

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/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;
 }({});

package/dist/esm/testing/mock-interaction.js

@@ -1,6 +1,6 @@
 import 'reflect-metadata';
 import { createMockFn } from './mock-fn.js';
-import { InteractionType, ComponentType, ApplicationCommandType, CommandInteractionOptionResolver, GuildMessageManager, ThreadManager, DMMessageManager, MessageManager, ThreadMemberManager, Client, ApplicationCommandManager, UserManager, ChannelManager, GuildManager, ClientUser, Guild, GuildMemberManager, GuildChannelManager, RoleManager, GuildBanManager, Message, User, GuildMember, TextChannel, ThreadChannel, MessageMentions } from 'discord.js';
+import { InteractionType, ComponentType, ApplicationCommandType, CommandInteractionOptionResolver, GuildMessageManager, ThreadManager, DMMessageManager, MessageManager, ThreadMemberManager, Client, ApplicationCommandManager, UserManager, ChannelManager, GuildManager, ClientUser, Guild, GuildMemberManager, GuildChannelManager, RoleManager, GuildBanManager, Message, User, GuildMember, TextChannel, ThreadChannel, MessageMentions, ApplicationCommandOptionType, Role, BaseChannel, Attachment } from 'discord.js';
 
 // ---------------------------------------------------------------------------
 // stubDeep — Proxy that auto-creates a mock fn on any property access
@@ -140,7 +140,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'
@@ -210,9 +212,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;
@@ -253,6 +257,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 === 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.
@@ -532,7 +547,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 ApplicationCommandOptionType.Boolean;
+    if (typeof value === 'number') return ApplicationCommandOptionType.Number;
+    if (value instanceof User) return ApplicationCommandOptionType.User;
+    if (value instanceof GuildMember) return ApplicationCommandOptionType.User;
+    if (value instanceof Role) return ApplicationCommandOptionType.Role;
+    if (value instanceof BaseChannel) return ApplicationCommandOptionType.Channel;
+    if (value instanceof Attachment) return ApplicationCommandOptionType.Attachment;
+    if (typeof value === 'object' && value !== null) return ApplicationCommandOptionType.Mentionable;
+    return 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 User) option.user = value;
+    else if (value instanceof GuildMember) option.member = value;
+    else if (value instanceof Role) option.role = value;
+    else if (value instanceof BaseChannel) option.channel = value;
+    else if (value instanceof 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: ApplicationCommandOptionType.Subcommand,
+        options: leaves
+    };
+    if (subcommandGroup === null) return [
+        sub
+    ];
+    return [
+        {
+            name: subcommandGroup,
+            type: 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
@@ -540,7 +612,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.`);
@@ -571,6 +643,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);
 }
 

package/dist/esm/util/interaction.util.js

@@ -0,0 +1,174 @@
+import { ApplicationCommandOptionType, MessageComponentInteraction, ModalSubmitInteraction, ChannelSelectMenuInteraction, MentionableSelectMenuInteraction, RoleSelectMenuInteraction, UserSelectMenuInteraction, StringSelectMenuInteraction, ButtonInteraction, PrimaryEntryPointCommandInteraction, ContextMenuCommandInteraction, ChatInputCommandInteraction } from 'discord.js';
+import { CommandType } from '../enum/controller.enum.js';
+
+/**
+ * The discord.js class each command type is handled by.
+ *
+ * One table rather than a chain of `isButton() || isStringSelectMenu() || ...`: the
+ * registration guard in `@Command`, the dispatcher, and the type-level
+ * `CommandInteractionType` all have to agree on what a command type accepts, and a
+ * chain repeated in three files drifts the moment a fifth select menu appears. Adding
+ * a `CommandType` member without an entry here is a compile error, not a silent
+ * fall-through to "Command not found!".
+ */ const INTERACTION_MATCHERS = {
+    [CommandType.SLASH]: (interaction)=>interaction instanceof ChatInputCommandInteraction,
+    [CommandType.CONTEXT_MENU]: (interaction)=>interaction instanceof ContextMenuCommandInteraction,
+    [CommandType.PRIMARY_ENTRY_POINT]: (interaction)=>interaction instanceof PrimaryEntryPointCommandInteraction,
+    [CommandType.BUTTON]: (interaction)=>interaction instanceof ButtonInteraction,
+    [CommandType.SELECT_MENU]: (interaction)=>interaction instanceof StringSelectMenuInteraction,
+    [CommandType.USER_SELECT_MENU]: (interaction)=>interaction instanceof UserSelectMenuInteraction,
+    [CommandType.ROLE_SELECT_MENU]: (interaction)=>interaction instanceof RoleSelectMenuInteraction,
+    [CommandType.MENTIONABLE_SELECT_MENU]: (interaction)=>interaction instanceof MentionableSelectMenuInteraction,
+    [CommandType.CHANNEL_SELECT_MENU]: (interaction)=>interaction instanceof ChannelSelectMenuInteraction,
+    [CommandType.MODAL_SUBMIT]: (interaction)=>interaction instanceof ModalSubmitInteraction
+};
+/** Command types Discord identifies by a registered name rather than by a customId. */ const NAME_ROUTED_TYPES = new Set([
+    CommandType.SLASH,
+    CommandType.CONTEXT_MENU,
+    CommandType.PRIMARY_ENTRY_POINT
+]);
+/**
+ * Whether an interaction is the kind the given command type handles.
+ *
+ * @param type - The command type declared on `@Command`.
+ * @param interaction - The interaction being dispatched.
+ */ function matchesCommandType(type, interaction) {
+    const matches = INTERACTION_MATCHERS[type];
+    return matches !== undefined && matches(interaction);
+}
+/**
+ * Whether the command type is routed by matching a customId pattern.
+ *
+ * Components carry an application-defined customId and so are matched by pattern;
+ * commands carry a name Discord itself registered and are matched exactly.
+ *
+ * @param type - The command type declared on `@Command`.
+ */ function isCustomIdRouted(type) {
+    return !NAME_ROUTED_TYPES.has(type);
+}
+/**
+ * Whether an interaction carries a customId, and so can be routed by pattern.
+ *
+ * @param interaction - The interaction being dispatched.
+ */ function hasCustomId(interaction) {
+    return interaction instanceof MessageComponentInteraction || interaction instanceof ModalSubmitInteraction;
+}
+/** Separates a command from its subcommand group and subcommand in a route key. */ const COMMAND_PATH_SEPARATOR = ' ';
+/**
+ * The route keys a chat input interaction can be handled by, most specific first.
+ *
+ * Discord sends `/settings notify email` as one interaction named `settings`, so
+ * routing on `commandName` alone gives every subcommand of a command the same handler
+ * — and the framework would run whichever one was declared first. The full path is
+ * tried before the bare name so a command can either split its subcommands across
+ * methods or keep handling them in one, but never both by accident.
+ *
+ * A group is never dropped on the way down: `settings notify email` does not fall back
+ * to `settings email`, because a second group could declare its own `email` and the
+ * two would be indistinguishable.
+ *
+ * @param interaction - The chat input or autocomplete interaction being dispatched.
+ * @returns The keys to look up, most specific first.
+ */ function resolveCommandPaths(interaction) {
+    const { commandName } = interaction;
+    const options = interaction.options;
+    // Guarded rather than called directly: `options` is a stub on a hand-built test
+    // double, and an interaction whose command has no subcommands still has to route.
+    const group = typeof options?.getSubcommandGroup === 'function' ? options.getSubcommandGroup(false) : null;
+    const sub = typeof options?.getSubcommand === 'function' ? options.getSubcommand(false) : null;
+    const path = [
+        commandName,
+        group,
+        sub
+    ].filter((part)=>Boolean(part));
+    const full = path.join(COMMAND_PATH_SEPARATOR);
+    return full === commandName ? [
+        commandName
+    ] : [
+        full,
+        commandName
+    ];
+}
+/** Options that only wrap other options; their values live one level down. */ const NESTING_OPTION_TYPES = new Set([
+    ApplicationCommandOptionType.Subcommand,
+    ApplicationCommandOptionType.SubcommandGroup
+]);
+/**
+ * The value a handler should receive for one option.
+ *
+ * Discord sends entity options as a snowflake plus a `resolved` payload, and discord.js
+ * puts that payload on the option as `user`/`role`/`channel`/`attachment`. Passing
+ * `value` alone would hand the handler a bare id string for `@user`, forcing every
+ * handler to re-fetch what the gateway already delivered.
+ */ function resolveOptionValue(option) {
+    return option.attachment ?? option.channel ?? option.role ?? option.user ?? option.member ?? option.value;
+}
+/**
+ * Flattens a chat input interaction's options into the params record handlers receive.
+ *
+ * Subcommand and subcommand-group options are containers, not values — for
+ * `/settings notify email true` the top level holds only `notify`. Recursing past them
+ * means a subcommand handler sees `{ email: true }`, the same shape a flat command's
+ * handler sees.
+ *
+ * @param interaction - The chat input or autocomplete interaction being dispatched.
+ * @returns Each supplied option keyed by name, with entity options resolved.
+ */ function resolveOptionParams(interaction) {
+    const data = interaction.options?.data;
+    if (!Array.isArray(data)) return {};
+    const params = {};
+    const walk = (options)=>{
+        for (const option of options){
+            if (NESTING_OPTION_TYPES.has(option.type)) {
+                walk(option.options ?? []);
+                continue;
+            }
+            params[option.name] = resolveOptionValue(option);
+        }
+    };
+    walk(data);
+    return params;
+}
+/**
+ * The name of the option the user is currently typing, or `undefined`.
+ *
+ * `getFocused` throws when nothing is focused rather than returning null, and it is
+ * absent altogether on a hand-built test double. Neither is worth failing a dispatch
+ * over — an autocomplete with no focused option simply matches no option-specific
+ * handler.
+ *
+ * @param interaction - The autocomplete interaction being dispatched.
+ */ function focusedOptionName(interaction) {
+    if (typeof interaction.options?.getFocused !== 'function') return undefined;
+    try {
+        return interaction.options.getFocused(true)?.name;
+    } catch  {
+        return undefined;
+    }
+}
+/**
+ * Identifies an interaction in a log line, by whichever field would have routed it.
+ *
+ * @param interaction - The interaction that matched no handler.
+ */ function describeInteraction(interaction) {
+    // Captured before the narrowing below: the guards cover every member of the union,
+    // so by the fallback `interaction` is `never` and nothing can be read off it.
+    const { type } = interaction;
+    if (interaction.isAutocomplete()) {
+        const path = resolveCommandPaths(interaction)[0];
+        const focused = focusedOptionName(interaction);
+        return focused === undefined ? `autocomplete for "${path}"` : `autocomplete for "${path}" option "${focused}"`;
+    }
+    if (interaction.isChatInputCommand()) {
+        return `command "${resolveCommandPaths(interaction)[0]}"`;
+    }
+    if (interaction.isContextMenuCommand() || interaction.isPrimaryEntryPointCommand()) {
+        return `command "${interaction.commandName}"`;
+    }
+    if (hasCustomId(interaction)) {
+        return `customId "${interaction.customId}"`;
+    }
+    return `interaction type ${type}`;
+}
+
+export { COMMAND_PATH_SEPARATOR, describeInteraction, focusedOptionName, hasCustomId, isCustomIdRouted, matchesCommandType, resolveCommandPaths, resolveOptionParams };

package/dist/types/controller.enum-DYfhYaat.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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.
+ */
+declare enum CommandType {
+    /** Chat input command, or one subcommand of it. */
+    SLASH = "SLASH",
+    /** User or message context menu command. */
+    CONTEXT_MENU = "CONTEXT_MENU",
+    /** Activity launch command (`ApplicationCommandType.PrimaryEntryPoint`). */
+    PRIMARY_ENTRY_POINT = "PRIMARY_ENTRY_POINT",
+    BUTTON = "BUTTON",
+    /** String select menu — the one whose options the application defines itself. */
+    SELECT_MENU = "SELECT_MENU",
+    USER_SELECT_MENU = "USER_SELECT_MENU",
+    ROLE_SELECT_MENU = "ROLE_SELECT_MENU",
+    MENTIONABLE_SELECT_MENU = "MENTIONABLE_SELECT_MENU",
+    CHANNEL_SELECT_MENU = "CHANNEL_SELECT_MENU",
+    MODAL_SUBMIT = "MODAL_SUBMIT"
+}
+/**
+ * Enum representing actions that can be performed on a message reaction.
+ */
+declare enum ReactionHandlerAction {
+    /** Reaction added to a message. */
+    ADD = "ADD",
+    /** Reaction removed from a message. */
+    REMOVE = "REMOVE"
+}
+
+export { CommandType as C, ReactionHandlerAction as R };

package/dist/types/core/index.d.ts

@@ -19,6 +19,31 @@ declare class MeoCordApp {
     private activityInterval;
     private controllerInstancesCache;
     constructor(controllerClasses: (new (...args: any[]) => any)[], container: Container, discordClient: Client, discordToken: string, activities?: ActivityOptions[] | undefined);
+    /**
+     * 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.
+     */
+    private runListener;
+    /**
+     * 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.
+     */
+    private updateActivity;
     private getInstance;
     start(): Promise<void>;
     registerCommands(): Promise<void>;
@@ -38,12 +63,60 @@ declare class MeoCordApp {
      * refusing to start would turn a latent mis-route into an outage on upgrade.
      */
     private reportAmbiguousRoutes;
+    /**
+     * Every `@Autocomplete` handler, ordered so an option-specific handler is found
+     * before a command-wide one.
+     *
+     * Cached alongside the component table: autocomplete fires on every keystroke, and
+     * rebuilding the list per keystroke would put reflection on the hottest path the
+     * framework has.
+     */
+    private autocompleteRoutes?;
+    private getAutocompleteRoutes;
+    /**
+     * 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.
+     */
     private handleInteraction;
+    private dispatchInteraction;
+    /**
+     * 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.
+     */
+    private resolveNameRoutes;
+    /**
+     * 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.
+     */
+    private handleAutocomplete;
+    /** Closes an autocomplete window that nothing else answered. */
+    private respondEmpty;
     /**
      * 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.
      */
     private executeCommand;
+    /**
+     * 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.
+     */
+    private replyWithError;
     private handleMessage;
     private handleReaction;
     private gracefulShutdown;