@julanzw/ttoolbox-discordjs-framework 1.1.0 → 1.3.0

package/dist/index.d.ts

@@ -8,6 +8,8 @@ export type { PermissionLevel } from './types/permission.js';
 export type { Modal, ModalField } from './types/modal.js';
 export type { ButtonType } from './types/button.js';
 export type { ILogger } from './types/logger.js';
+export type { AnySelectMenuInteraction, ButtonHandler, SelectMenuHandler, ComponentConfig } from './types/component.js';
+export type { AutocompleteHandler } from './types/autocomplete.js';
 export { getPermissionsForLevel } from './utils/permissions.js';
 export { embedBuilder, createButton, createButtonsRow, createPaginationButtons, } from './utils/embeds.js';
 export { stringOption, integerOption, booleanOption, userOption, channelOption, roleOption, } from './utils/slashCommandOptions.js';
@@ -16,4 +18,6 @@ export { formatDuration, formatDateToString, formatDateToYYYYMMDDHHMMSS, formatD
 export { TIMES_MILISECONDS } from './utils/miliseconds.js';
 export { TToolboxLogger } from './utils/TToolboxLogger.class.js';
 export { ErrorReporter } from './utils/ErrorReporter.js';
+export { ComponentManager } from './utils/ComponentManager.class.js';
+export { AutocompleteManager } from './utils/AutocompleteManager.class.js';
 export { InteractionError } from './classes/InteractionError.class.js';

package/dist/index.js

@@ -14,5 +14,7 @@ export { formatDuration, formatDateToString, formatDateToYYYYMMDDHHMMSS, formatD
 export { TIMES_MILISECONDS } from './utils/miliseconds.js';
 export { TToolboxLogger } from './utils/TToolboxLogger.class.js';
 export { ErrorReporter } from './utils/ErrorReporter.js';
+export { ComponentManager } from './utils/ComponentManager.class.js';
+export { AutocompleteManager } from './utils/AutocompleteManager.class.js';
 // Errors
 export { InteractionError } from './classes/InteractionError.class.js';

package/dist/types/autocomplete.d.ts

@@ -0,0 +1,25 @@
+import { AutocompleteInteraction } from "discord.js";
+/**
+ * Handler function for autocomplete interactions.
+ *
+ * @param interaction - The autocomplete interaction
+ * @param focusedValue - The current value the user is typing
+ * @returns Array of choices to display (max 25)
+ *
+ * @example
+ * ```typescript
+ * async (interaction, focusedValue) => {
+ *   const feeds = await getFeeds(interaction.user.id);
+ *   return feeds
+ *     .filter(f => f.name.toLowerCase().includes(focusedValue.toLowerCase()))
+ *     .map(f => ({ name: f.name, value: f.name }));
+ * }
+ * ```
+ */
+export type AutocompleteHandler = (interaction: AutocompleteInteraction, focusedValue: string) => Promise<Array<{
+    name: string;
+    value: string;
+}>> | Array<{
+    name: string;
+    value: string;
+}>;

package/dist/types/autocomplete.js

@@ -0,0 +1 @@
+export {};

package/dist/types/component.d.ts

@@ -0,0 +1,22 @@
+import { StringSelectMenuInteraction, ChannelSelectMenuInteraction, RoleSelectMenuInteraction, UserSelectMenuInteraction, MentionableSelectMenuInteraction, ButtonInteraction } from "discord.js";
+/**
+ * Type for all select menu interactions
+ */
+export type AnySelectMenuInteraction = StringSelectMenuInteraction | ChannelSelectMenuInteraction | RoleSelectMenuInteraction | UserSelectMenuInteraction | MentionableSelectMenuInteraction;
+/**
+ * Handler function for button interactions
+ */
+export type ButtonHandler = (interaction: ButtonInteraction) => Promise<void>;
+/**
+ * Handler function for select menu interactions
+ */
+export type SelectMenuHandler = (interaction: AnySelectMenuInteraction) => Promise<void>;
+/**
+ * Configuration for a component handler
+ */
+export interface ComponentConfig {
+    /** Whether this component should be removed after being handled once */
+    ephemeral?: boolean;
+    /** Optional timeout in milliseconds after which the handler is removed */
+    timeout?: number;
+}

package/dist/types/component.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/AutocompleteManager.class.d.ts

@@ -0,0 +1,140 @@
+import { AutocompleteInteraction } from 'discord.js';
+import type { ILogger } from '../types/logger.js';
+import { AutocompleteHandler } from '../types/autocomplete.js';
+/**
+ * Manages autocomplete interactions for slash commands.
+ *
+ * Provides centralized registration and handling of autocomplete options.
+ * Supports per-command, per-option handlers with automatic filtering and
+ * Discord's 25-choice limit.
+ *
+ * @example
+ * ```typescript
+ * const autocompleteManager = new AutocompleteManager(logger);
+ *
+ * // Register autocomplete for a specific command option
+ * autocompleteManager.register('item', 'name', async (interaction, value) => {
+ *   const items = await prisma.item.findMany({
+ *     where: {
+ *       userId: interaction.user.id,
+ *       name: { contains: value },
+ *     },
+ *   });
+ *
+ *   return items.map(item => ({ name: item.name, value: item.name }));
+ * });
+ *
+ * // Handle autocomplete interactions
+ * client.on('interactionCreate', async (interaction) => {
+ *   if (interaction.isAutocomplete()) {
+ *     await autocompleteManager.handle(interaction);
+ *   }
+ * });
+ * ```
+ */
+export declare class AutocompleteManager {
+    private logger?;
+    private handlers;
+    constructor(logger?: ILogger | undefined);
+    /**
+     * Register an autocomplete handler for a command option.
+     *
+     * @param commandName - The name of the slash command
+     * @param optionName - The name of the option with autocomplete enabled
+     * @param handler - The handler function that returns choices
+     *
+     * @example
+     * ```typescript
+     * // Simple static choices
+     * autocompleteManager.register('config', 'setting', async () => {
+     *   return [
+     *     { name: 'Notifications', value: 'notifications' },
+     *     { name: 'Language', value: 'language' },
+     *     { name: 'Theme', value: 'theme' },
+     *   ];
+     * });
+     *
+     * // Dynamic choices from database
+     * autocompleteManager.register('item', 'name', async (interaction, value) => {
+     *   const items = await prisma.item.findMany({
+     *     where: {
+     *       userId: interaction.user.id,
+     *       name: { contains: value },
+     *     },
+     *     take: 25,
+     *   });
+     *
+     *   return items.map(item => ({ name: item.name, value: item.id }));
+     * });
+     *
+     * // With fuzzy search
+     * autocompleteManager.register('user', 'username', async (interaction, value) => {
+     *   const users = await searchUsers(value);
+     *   return users.map(u => ({ name: u.tag, value: u.id }));
+     * });
+     * ```
+     */
+    register(commandName: string, optionName: string, handler: AutocompleteHandler): void;
+    /**
+     * Handle an autocomplete interaction.
+     *
+     * Automatically calls the appropriate handler and responds with choices.
+     * Handles errors gracefully and enforces Discord's 25-choice limit.
+     *
+     * @param interaction - The autocomplete interaction to handle
+     *
+     * @example
+     * ```typescript
+     * client.on('interactionCreate', async (interaction) => {
+     *   if (interaction.isAutocomplete()) {
+     *     await autocompleteManager.handle(interaction);
+     *   }
+     * });
+     * ```
+     */
+    handle(interaction: AutocompleteInteraction): Promise<void>;
+    /**
+     * Unregister an autocomplete handler.
+     *
+     * @param commandName - The command name
+     * @param optionName - The option name
+     * @returns true if the handler was removed, false if it didn't exist
+     */
+    unregister(commandName: string, optionName: string): boolean;
+    /**
+     * Unregister all handlers for a command.
+     *
+     * @param commandName - The command name
+     * @returns true if any handlers were removed
+     */
+    unregisterCommand(commandName: string): boolean;
+    /**
+     * Check if a handler is registered for a command option.
+     *
+     * @param commandName - The command name
+     * @param optionName - The option name
+     * @returns true if a handler exists
+     */
+    has(commandName: string, optionName: string): boolean;
+    /**
+     * Get all registered command names.
+     */
+    getCommands(): string[];
+    /**
+     * Get all registered option names for a command.
+     *
+     * @param commandName - The command name
+     * @returns Array of option names, or empty array if command not found
+     */
+    getOptions(commandName: string): string[];
+    /**
+     * Clear all registered handlers.
+     *
+     * Useful for cleanup or testing.
+     */
+    clear(): void;
+    /**
+     * Get the total number of registered handlers across all commands.
+     */
+    get handlerCount(): number;
+}

package/dist/utils/AutocompleteManager.class.js

@@ -0,0 +1,200 @@
+/**
+ * Manages autocomplete interactions for slash commands.
+ *
+ * Provides centralized registration and handling of autocomplete options.
+ * Supports per-command, per-option handlers with automatic filtering and
+ * Discord's 25-choice limit.
+ *
+ * @example
+ * ```typescript
+ * const autocompleteManager = new AutocompleteManager(logger);
+ *
+ * // Register autocomplete for a specific command option
+ * autocompleteManager.register('item', 'name', async (interaction, value) => {
+ *   const items = await prisma.item.findMany({
+ *     where: {
+ *       userId: interaction.user.id,
+ *       name: { contains: value },
+ *     },
+ *   });
+ *
+ *   return items.map(item => ({ name: item.name, value: item.name }));
+ * });
+ *
+ * // Handle autocomplete interactions
+ * client.on('interactionCreate', async (interaction) => {
+ *   if (interaction.isAutocomplete()) {
+ *     await autocompleteManager.handle(interaction);
+ *   }
+ * });
+ * ```
+ */
+export class AutocompleteManager {
+    constructor(logger) {
+        this.logger = logger;
+        // Map structure: Map<commandName, Map<optionName, handler>>
+        this.handlers = new Map();
+    }
+    /**
+     * Register an autocomplete handler for a command option.
+     *
+     * @param commandName - The name of the slash command
+     * @param optionName - The name of the option with autocomplete enabled
+     * @param handler - The handler function that returns choices
+     *
+     * @example
+     * ```typescript
+     * // Simple static choices
+     * autocompleteManager.register('config', 'setting', async () => {
+     *   return [
+     *     { name: 'Notifications', value: 'notifications' },
+     *     { name: 'Language', value: 'language' },
+     *     { name: 'Theme', value: 'theme' },
+     *   ];
+     * });
+     *
+     * // Dynamic choices from database
+     * autocompleteManager.register('item', 'name', async (interaction, value) => {
+     *   const items = await prisma.item.findMany({
+     *     where: {
+     *       userId: interaction.user.id,
+     *       name: { contains: value },
+     *     },
+     *     take: 25,
+     *   });
+     *
+     *   return items.map(item => ({ name: item.name, value: item.id }));
+     * });
+     *
+     * // With fuzzy search
+     * autocompleteManager.register('user', 'username', async (interaction, value) => {
+     *   const users = await searchUsers(value);
+     *   return users.map(u => ({ name: u.tag, value: u.id }));
+     * });
+     * ```
+     */
+    register(commandName, optionName, handler) {
+        if (!this.handlers.has(commandName)) {
+            this.handlers.set(commandName, new Map());
+        }
+        this.handlers.get(commandName).set(optionName, handler);
+        this.logger?.info(`Registered autocomplete handler: ${commandName}.${optionName}`, 'autocomplete-manager');
+    }
+    /**
+     * Handle an autocomplete interaction.
+     *
+     * Automatically calls the appropriate handler and responds with choices.
+     * Handles errors gracefully and enforces Discord's 25-choice limit.
+     *
+     * @param interaction - The autocomplete interaction to handle
+     *
+     * @example
+     * ```typescript
+     * client.on('interactionCreate', async (interaction) => {
+     *   if (interaction.isAutocomplete()) {
+     *     await autocompleteManager.handle(interaction);
+     *   }
+     * });
+     * ```
+     */
+    async handle(interaction) {
+        const commandHandlers = this.handlers.get(interaction.commandName);
+        if (!commandHandlers) {
+            this.logger?.warn(`No autocomplete handlers for command: ${interaction.commandName}`, 'autocomplete-manager');
+            await interaction.respond([]);
+            return;
+        }
+        const focusedOption = interaction.options.getFocused(true);
+        const handler = commandHandlers.get(focusedOption.name);
+        if (!handler) {
+            this.logger?.warn(`No autocomplete handler for ${interaction.commandName}.${focusedOption.name}`, 'autocomplete-manager');
+            await interaction.respond([]);
+            return;
+        }
+        try {
+            const choices = await handler(interaction, focusedOption.value);
+            // Discord's 25-choice limit
+            const limitedChoices = choices.slice(0, 25);
+            if (choices.length > 25) {
+                this.logger?.warn(`Autocomplete handler for ${interaction.commandName}.${focusedOption.name} returned ${choices.length} choices, truncating to 25`, 'autocomplete-manager');
+            }
+            await interaction.respond(limitedChoices);
+        }
+        catch (err) {
+            this.logger?.error(`Error in autocomplete handler for ${interaction.commandName}.${focusedOption.name}: ${err.message}`, 'autocomplete-manager');
+            // Empty array on error to prevent interaction failure
+            await interaction.respond([]);
+        }
+    }
+    /**
+     * Unregister an autocomplete handler.
+     *
+     * @param commandName - The command name
+     * @param optionName - The option name
+     * @returns true if the handler was removed, false if it didn't exist
+     */
+    unregister(commandName, optionName) {
+        const commandHandlers = this.handlers.get(commandName);
+        if (!commandHandlers)
+            return false;
+        const removed = commandHandlers.delete(optionName);
+        if (commandHandlers.size === 0) {
+            this.handlers.delete(commandName);
+        }
+        return removed;
+    }
+    /**
+     * Unregister all handlers for a command.
+     *
+     * @param commandName - The command name
+     * @returns true if any handlers were removed
+     */
+    unregisterCommand(commandName) {
+        return this.handlers.delete(commandName);
+    }
+    /**
+     * Check if a handler is registered for a command option.
+     *
+     * @param commandName - The command name
+     * @param optionName - The option name
+     * @returns true if a handler exists
+     */
+    has(commandName, optionName) {
+        return this.handlers.get(commandName)?.has(optionName) || false;
+    }
+    /**
+     * Get all registered command names.
+     */
+    getCommands() {
+        return Array.from(this.handlers.keys());
+    }
+    /**
+     * Get all registered option names for a command.
+     *
+     * @param commandName - The command name
+     * @returns Array of option names, or empty array if command not found
+     */
+    getOptions(commandName) {
+        const commandHandlers = this.handlers.get(commandName);
+        return commandHandlers ? Array.from(commandHandlers.keys()) : [];
+    }
+    /**
+     * Clear all registered handlers.
+     *
+     * Useful for cleanup or testing.
+     */
+    clear() {
+        this.handlers.clear();
+        this.logger?.info('Cleared all autocomplete handlers', 'autocomplete-manager');
+    }
+    /**
+     * Get the total number of registered handlers across all commands.
+     */
+    get handlerCount() {
+        let count = 0;
+        for (const commandHandlers of this.handlers.values()) {
+            count += commandHandlers.size;
+        }
+        return count;
+    }
+}

package/dist/utils/ComponentManager.class.d.ts

@@ -0,0 +1,194 @@
+import { ButtonInteraction, AnySelectMenuInteraction } from 'discord.js';
+import type { ILogger } from '../types/logger.js';
+import { ButtonHandler, ComponentConfig, SelectMenuHandler } from '../types/component.js';
+/**
+ * Manages Discord component interactions (buttons and select menus).
+ *
+ * Provides centralized registration and handling of long living
+ * button clicks and select menu interactions.
+ *
+ * Supports dynamic custom IDs (e.g., "delete-feed:123"),
+ * ephemeral handlers (one-time use), and automatic cleanup.
+ *
+ * @example
+ * ```typescript
+ * const componentManager = new ComponentManager(logger);
+ *
+ * // Register a button handler
+ * componentManager.registerButton('delete-feed', async (interaction) => {
+ *   const feedId = interaction.customId.split(':')[1];
+ *   await deleteFeed(feedId);
+ *   await interaction.reply('Feed deleted!');
+ * });
+ *
+ * // Register a select menu handler
+ * componentManager.registerSelect('choose-feed-type', async (interaction) => {
+ *   const type = interaction.values[0];
+ *   await interaction.reply(`You selected: ${type}`);
+ * });
+ *
+ * // Handle interactions
+ * client.on('interactionCreate', async (interaction) => {
+ *   if (interaction.isButton()) {
+ *     await componentManager.handleButton(interaction);
+ *   }
+ *   if (interaction.isAnySelectMenu()) {
+ *     await componentManager.handleSelect(interaction);
+ *   }
+ * });
+ * ```
+ */
+export declare class ComponentManager {
+    private logger?;
+    private buttonHandlers;
+    private selectHandlers;
+    private timeouts;
+    constructor(logger?: ILogger | undefined);
+    /**
+     * Register a button click handler.
+     *
+     * Supports dynamic custom IDs - if the exact ID isn't found, attempts to match
+     * using the base ID (before the first colon).\
+     * This allows for buttons with dynamic suffixes like "global-delete:123".
+     *
+     * Its recommended to add a prefix like ```global-``` to the id to fully
+     * distingush it from other local component handlers.
+     *
+     * @param customId - The button's custom ID (or base ID for dynamic buttons)
+     * @param handler - Function to call when the button is clicked
+     * @param config - Optional configuration (ephemeral, timeout)
+     *
+     * @example
+     * ```typescript
+     * // Simple button
+     * componentManager.registerButton('global-refresh', async (interaction) => {
+     *   await interaction.reply('Refreshed!');
+     * });
+     *
+     * // Dynamic button (matches "global-delete:123", "global-delete:456", etc.)
+     * componentManager.registerButton('global-delete', async (interaction) => {
+     *   const id = interaction.customId.split(':')[1];
+     *   await deleteItem(id);
+     * });
+     *
+     * // Ephemeral button (one-time use)
+     * componentManager.registerButton('global-confirm', async (interaction) => {
+     *   await processConfirmation();
+     * }, { ephemeral: true });
+     *
+     * // Button with timeout (auto-remove after 5 minutes)
+     * componentManager.registerButton('global-temp-action', async (interaction) => {
+     *   await doTempAction();
+     * }, { timeout: 5 * 60 * 1000 });
+     * ```
+     */
+    registerButton(customId: string, handler: ButtonHandler, config?: ComponentConfig): void;
+    /**
+     * Register a select menu handler.
+     *
+     * Supports dynamic custom IDs - if the exact ID isn't found, attempts to match
+     * using the base ID (before the first colon).
+     *
+     * Its recommended to add a prefix like ```global-``` to the id to fully
+     * distingush it from other local component handlers.
+     *
+     * @param customId - The select menu's custom ID (or base ID for dynamic menus)
+     * @param handler - Function to call when a selection is made
+     * @param config - Optional configuration (ephemeral, timeout)
+     *
+     * @example
+     * ```typescript
+     * // String select menu
+     * componentManager.registerSelect('global-choose-type', async (interaction) => {
+     *   const selected = interaction.values[0];
+     *   await interaction.reply(`You chose: ${selected}`);
+     * });
+     *
+     * // Dynamic select menu
+     * componentManager.registerSelect('global-choose-item', async (interaction) => {
+     *   const itemId = interaction.customId.split(':')[1];
+     *   const selected = interaction.values;
+     *   await processSelection(itemId, selected);
+     * });
+     * ```
+     */
+    registerSelect(customId: string, handler: SelectMenuHandler, config?: ComponentConfig): void;
+    /**
+     * Handle a button interaction.
+     *
+     * Automatically matches dynamic IDs and removes ephemeral handlers after use.
+     *
+     * @param interaction - The button interaction to handle
+     * @throws {Error} If no handler is found for the button
+     */
+    handleButton(interaction: ButtonInteraction): Promise<void>;
+    /**
+     * Handle a select menu interaction.
+     *
+     * Automatically matches dynamic IDs and removes ephemeral handlers after use.
+     *
+     * @param interaction - The select menu interaction to handle
+     * @throws {Error} If no handler is found for the select menu
+     */
+    handleSelect(interaction: AnySelectMenuInteraction): Promise<void>;
+    /**
+     * Find a handler by custom ID, supporting dynamic IDs.
+     *
+     * First tries exact match, then tries base ID (before colon).
+     */
+    private findHandler;
+    /**
+     * Set up automatic removal timeout for a handler.
+     */
+    private setupTimeout;
+    /**
+     * Unregister a button handler.
+     *
+     * @param customId - The button's custom ID
+     * @returns true if the handler was removed, false if it didn't exist
+     */
+    unregisterButton(customId: string): boolean;
+    /**
+     * Unregister a select menu handler.
+     *
+     * @param customId - The select menu's custom ID
+     * @returns true if the handler was removed, false if it didn't exist
+     */
+    unregisterSelect(customId: string): boolean;
+    /**
+     * Check if a button handler is registered.
+     *
+     * @param customId - The button's custom ID
+     * @returns true if a handler exists (exact or base ID match)
+     */
+    hasButton(customId: string): boolean;
+    /**
+     * Check if a select menu handler is registered.
+     *
+     * @param customId - The select menu's custom ID
+     * @returns true if a handler exists (exact or base ID match)
+     */
+    hasSelect(customId: string): boolean;
+    /**
+     * Clear all registered handlers.
+     *
+     * Useful for cleanup during bot shutdown or testing.
+     */
+    clear(): void;
+    /**
+     * Get the total number of registered button handlers.
+     */
+    get buttonCount(): number;
+    /**
+     * Get the total number of registered select menu handlers.
+     */
+    get selectCount(): number;
+    /**
+     * Get all registered button IDs.
+     */
+    getButtonIds(): string[];
+    /**
+     * Get all registered select menu IDs.
+     */
+    getSelectIds(): string[];
+}

package/dist/utils/ComponentManager.class.js

@@ -0,0 +1,318 @@
+/**
+ * Manages Discord component interactions (buttons and select menus).
+ *
+ * Provides centralized registration and handling of long living
+ * button clicks and select menu interactions.
+ *
+ * Supports dynamic custom IDs (e.g., "delete-feed:123"),
+ * ephemeral handlers (one-time use), and automatic cleanup.
+ *
+ * @example
+ * ```typescript
+ * const componentManager = new ComponentManager(logger);
+ *
+ * // Register a button handler
+ * componentManager.registerButton('delete-feed', async (interaction) => {
+ *   const feedId = interaction.customId.split(':')[1];
+ *   await deleteFeed(feedId);
+ *   await interaction.reply('Feed deleted!');
+ * });
+ *
+ * // Register a select menu handler
+ * componentManager.registerSelect('choose-feed-type', async (interaction) => {
+ *   const type = interaction.values[0];
+ *   await interaction.reply(`You selected: ${type}`);
+ * });
+ *
+ * // Handle interactions
+ * client.on('interactionCreate', async (interaction) => {
+ *   if (interaction.isButton()) {
+ *     await componentManager.handleButton(interaction);
+ *   }
+ *   if (interaction.isAnySelectMenu()) {
+ *     await componentManager.handleSelect(interaction);
+ *   }
+ * });
+ * ```
+ */
+export class ComponentManager {
+    constructor(logger) {
+        this.logger = logger;
+        this.buttonHandlers = new Map();
+        this.selectHandlers = new Map();
+        this.timeouts = new Map();
+    }
+    /**
+     * Register a button click handler.
+     *
+     * Supports dynamic custom IDs - if the exact ID isn't found, attempts to match
+     * using the base ID (before the first colon).\
+     * This allows for buttons with dynamic suffixes like "global-delete:123".
+     *
+     * Its recommended to add a prefix like ```global-``` to the id to fully
+     * distingush it from other local component handlers.
+     *
+     * @param customId - The button's custom ID (or base ID for dynamic buttons)
+     * @param handler - Function to call when the button is clicked
+     * @param config - Optional configuration (ephemeral, timeout)
+     *
+     * @example
+     * ```typescript
+     * // Simple button
+     * componentManager.registerButton('global-refresh', async (interaction) => {
+     *   await interaction.reply('Refreshed!');
+     * });
+     *
+     * // Dynamic button (matches "global-delete:123", "global-delete:456", etc.)
+     * componentManager.registerButton('global-delete', async (interaction) => {
+     *   const id = interaction.customId.split(':')[1];
+     *   await deleteItem(id);
+     * });
+     *
+     * // Ephemeral button (one-time use)
+     * componentManager.registerButton('global-confirm', async (interaction) => {
+     *   await processConfirmation();
+     * }, { ephemeral: true });
+     *
+     * // Button with timeout (auto-remove after 5 minutes)
+     * componentManager.registerButton('global-temp-action', async (interaction) => {
+     *   await doTempAction();
+     * }, { timeout: 5 * 60 * 1000 });
+     * ```
+     */
+    registerButton(customId, handler, config = {}) {
+        this.buttonHandlers.set(customId, { handler, config });
+        // Set up auto-removal timeout if specified
+        if (config.timeout) {
+            this.setupTimeout('button', customId, config.timeout);
+        }
+        this.logger?.info(`Registered button handler: ${customId}${config.ephemeral ? ' (ephemeral)' : ''}${config.timeout ? ` (timeout: ${config.timeout}ms)` : ''}`, 'component-manager');
+    }
+    /**
+     * Register a select menu handler.
+     *
+     * Supports dynamic custom IDs - if the exact ID isn't found, attempts to match
+     * using the base ID (before the first colon).
+     *
+     * Its recommended to add a prefix like ```global-``` to the id to fully
+     * distingush it from other local component handlers.
+     *
+     * @param customId - The select menu's custom ID (or base ID for dynamic menus)
+     * @param handler - Function to call when a selection is made
+     * @param config - Optional configuration (ephemeral, timeout)
+     *
+     * @example
+     * ```typescript
+     * // String select menu
+     * componentManager.registerSelect('global-choose-type', async (interaction) => {
+     *   const selected = interaction.values[0];
+     *   await interaction.reply(`You chose: ${selected}`);
+     * });
+     *
+     * // Dynamic select menu
+     * componentManager.registerSelect('global-choose-item', async (interaction) => {
+     *   const itemId = interaction.customId.split(':')[1];
+     *   const selected = interaction.values;
+     *   await processSelection(itemId, selected);
+     * });
+     * ```
+     */
+    registerSelect(customId, handler, config = {}) {
+        this.selectHandlers.set(customId, { handler, config });
+        if (config.timeout) {
+            this.setupTimeout('select', customId, config.timeout);
+        }
+        this.logger?.info(`Registered select menu handler: ${customId}${config.ephemeral ? ' (ephemeral)' : ''}${config.timeout ? ` (timeout: ${config.timeout}ms)` : ''}`, 'component-manager');
+    }
+    /**
+     * Handle a button interaction.
+     *
+     * Automatically matches dynamic IDs and removes ephemeral handlers after use.
+     *
+     * @param interaction - The button interaction to handle
+     * @throws {Error} If no handler is found for the button
+     */
+    async handleButton(interaction) {
+        if (interaction.replied || interaction.deferred) {
+            this.logger?.warn(`Button ${interaction.customId} already handled, skipping`, 'component-manager');
+            return;
+        }
+        const entry = this.findHandler(this.buttonHandlers, interaction.customId);
+        if (!entry) {
+            throw new Error(`No handler registered for button: ${interaction.customId}`);
+        }
+        const { handler, config, matchedId } = entry;
+        try {
+            await handler(interaction);
+            // Remove ephemeral handlers after use
+            if (config.ephemeral) {
+                this.unregisterButton(matchedId);
+                this.logger?.info(`Removed ephemeral button handler: ${matchedId}`, 'component-manager');
+            }
+        }
+        catch (err) {
+            this.logger?.error(`Error handling button ${interaction.customId}: ${err.message}`, 'component-manager');
+            throw err;
+        }
+    }
+    /**
+     * Handle a select menu interaction.
+     *
+     * Automatically matches dynamic IDs and removes ephemeral handlers after use.
+     *
+     * @param interaction - The select menu interaction to handle
+     * @throws {Error} If no handler is found for the select menu
+     */
+    async handleSelect(interaction) {
+        if (interaction.replied || interaction.deferred) {
+            this.logger?.warn(`Select menu ${interaction.customId} already handled, skipping`, 'component-manager');
+            return;
+        }
+        const entry = this.findHandler(this.selectHandlers, interaction.customId);
+        if (!entry) {
+            throw new Error(`No handler registered for select menu: ${interaction.customId}`);
+        }
+        const { handler, config, matchedId } = entry;
+        try {
+            await handler(interaction);
+            if (config.ephemeral) {
+                this.unregisterSelect(matchedId);
+                this.logger?.info(`Removed ephemeral select menu handler: ${matchedId}`, 'component-manager');
+            }
+        }
+        catch (err) {
+            this.logger?.error(`Error handling select menu ${interaction.customId}: ${err.message}`, 'component-manager');
+            throw err;
+        }
+    }
+    /**
+     * Find a handler by custom ID, supporting dynamic IDs.
+     *
+     * First tries exact match, then tries base ID (before colon).
+     */
+    findHandler(map, customId) {
+        // Try exact match first
+        const exact = map.get(customId);
+        if (exact) {
+            return { ...exact, matchedId: customId };
+        }
+        // Try base ID (before colon) for dynamic IDs
+        const baseId = customId.split(':')[0];
+        const base = map.get(baseId);
+        if (base) {
+            return { ...base, matchedId: baseId };
+        }
+        return null;
+    }
+    /**
+     * Set up automatic removal timeout for a handler.
+     */
+    setupTimeout(type, customId, timeout) {
+        // Clear existing timeout if any
+        const existingTimeout = this.timeouts.get(`${type}:${customId}`);
+        if (existingTimeout) {
+            clearTimeout(existingTimeout);
+        }
+        // Set new timeout
+        const timeoutId = setTimeout(() => {
+            if (type === 'button') {
+                this.unregisterButton(customId);
+            }
+            else {
+                this.unregisterSelect(customId);
+            }
+            this.logger?.info(`Auto-removed ${type} handler after timeout: ${customId}`, 'component-manager');
+        }, timeout);
+        this.timeouts.set(`${type}:${customId}`, timeoutId);
+    }
+    /**
+     * Unregister a button handler.
+     *
+     * @param customId - The button's custom ID
+     * @returns true if the handler was removed, false if it didn't exist
+     */
+    unregisterButton(customId) {
+        const removed = this.buttonHandlers.delete(customId);
+        // Clear timeout if exists
+        const timeoutId = this.timeouts.get(`button:${customId}`);
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+            this.timeouts.delete(`button:${customId}`);
+        }
+        return removed;
+    }
+    /**
+     * Unregister a select menu handler.
+     *
+     * @param customId - The select menu's custom ID
+     * @returns true if the handler was removed, false if it didn't exist
+     */
+    unregisterSelect(customId) {
+        const removed = this.selectHandlers.delete(customId);
+        const timeoutId = this.timeouts.get(`select:${customId}`);
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+            this.timeouts.delete(`select:${customId}`);
+        }
+        return removed;
+    }
+    /**
+     * Check if a button handler is registered.
+     *
+     * @param customId - The button's custom ID
+     * @returns true if a handler exists (exact or base ID match)
+     */
+    hasButton(customId) {
+        return this.buttonHandlers.has(customId) ||
+            this.buttonHandlers.has(customId.split(':')[0]);
+    }
+    /**
+     * Check if a select menu handler is registered.
+     *
+     * @param customId - The select menu's custom ID
+     * @returns true if a handler exists (exact or base ID match)
+     */
+    hasSelect(customId) {
+        return this.selectHandlers.has(customId) ||
+            this.selectHandlers.has(customId.split(':')[0]);
+    }
+    /**
+     * Clear all registered handlers.
+     *
+     * Useful for cleanup during bot shutdown or testing.
+     */
+    clear() {
+        this.buttonHandlers.clear();
+        this.selectHandlers.clear();
+        // Clear all timeouts
+        for (const timeoutId of this.timeouts.values()) {
+            clearTimeout(timeoutId);
+        }
+        this.timeouts.clear();
+        this.logger?.info('Cleared all component handlers', 'component-manager');
+    }
+    /**
+     * Get the total number of registered button handlers.
+     */
+    get buttonCount() {
+        return this.buttonHandlers.size;
+    }
+    /**
+     * Get the total number of registered select menu handlers.
+     */
+    get selectCount() {
+        return this.selectHandlers.size;
+    }
+    /**
+     * Get all registered button IDs.
+     */
+    getButtonIds() {
+        return Array.from(this.buttonHandlers.keys());
+    }
+    /**
+     * Get all registered select menu IDs.
+     */
+    getSelectIds() {
+        return Array.from(this.selectHandlers.keys());
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@julanzw/ttoolbox-discordjs-framework",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "A Discord.js command framework with built-in handlers and utilities",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",