@julanzw/ttoolbox-discordjs-framework 1.4.0 → 1.5.0

package/dist/classes/Command.class.js

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/no-unused-vars */
 import { SlashCommandBuilder, } from 'discord.js';
 import { safeReply } from '../utils/editAndReply.js';
 import { getPermissionsForLevel } from '../utils/permissions.js';

package/dist/classes/CommandManager.class.d.ts

@@ -1,36 +1,105 @@
-import { ChatInputCommandInteraction, Client, RESTPostAPIChatInputApplicationCommandsJSONBody } from 'discord.js';
+import { ChatInputCommandInteraction, Client, MessageContextMenuCommandInteraction, RESTPostAPIApplicationCommandsJSONBody, UserContextMenuCommandInteraction } from 'discord.js';
 import { ILogger } from '../types/logger.js';
 import { Command } from './Command.class.js';
 import { SubcommandGroup } from './SubcommandGroup.class.js';
 import { ErrorReporter } from '../utils/ErrorReporter.js';
+import { MessageContextMenuCommand } from './MessageContextMenuCommand.class.js';
+import { UserContextMenuCommand } from './UserContextMenuCommand.class.js';
+import { LoadCommandsOptions } from '../types/loadCommands.js';
 export declare class CommandManager {
     private commands;
+    private userContextMenuCommands;
+    private messageContextMenuCommands;
     protected logger?: ILogger;
     protected errorReporter?: ErrorReporter;
     /**
+     * Register commands (accepts single, array, or mixed types)
+     * @param command - Command(s) to register
+     * @example
+     * ```typescript
+     * // Single command
+     * commandManager.registerCommand(new PingCommand());
+     *
+     * // Array of commands
+     * commandManager.registerCommand([cmd1, cmd2, cmd3]);
+     *
+     * // Mixed types
+     * commandManager.registerCommand([
+     *   new PingCommand(),
+     *   new UserContextMenu(),
+     *   new SubcommandGroup(),
+     * ]);
+     * ```
+     */
+    registerCommand(command: Command | SubcommandGroup | UserContextMenuCommand | MessageContextMenuCommand | Array<Command | SubcommandGroup | UserContextMenuCommand | MessageContextMenuCommand | any>): void;
+    /**
+     * @experimental
+     * Automatically load and register all commands from a directory.
+     *
+     * This is a convenience wrapper around the loadCommands utility.
+     *
+     * @param dirPath - Absolute path to the directory containing commands
+     * @param options - Optional configuration
+     * @returns Number of commands successfully loaded
+     *
+     * @example
+     * ```typescript
+     * // Basic usage
+     * const count = await commandManager.loadFromDirectory('./src/commands');
+     * console.log(`Loaded ${count} commands`);
+     *
+     * // With options
+     * await commandManager.loadFromDirectory('./src/commands', {
+     *   verbose: true,
+     *   skipDirs: ['subcommands', 'test'],
+     * });
+     * ```
+     */
+    loadFromDirectory(dirPath: string, options?: LoadCommandsOptions): Promise<number>;
+    /**
+     * @deprecated Use `registerCommand()` instead
+     *
      * Register a single command or subcommand group
      */
     register(command: Command | SubcommandGroup): this;
     /**
+     * @deprecated Use `registerCommand()` with an array instead
+     *
      * Register multiple commands at once
      */
     registerMultiple(commands: Array<Command | SubcommandGroup>): this;
     /**
-     * Get a specific command by name
+     * Get a specific slash command by name
      */
     get(name: string): Command | SubcommandGroup | undefined;
     /**
-     * Get all registered commands
+     * Get a specific user context menu command by name
+     */
+    getUserContextMenu(name: string): UserContextMenuCommand | undefined;
+    /**
+     * Get a specific message context menu command by name
+     */
+    getMessageContextMenu(name: string): MessageContextMenuCommand | undefined;
+    /**
+     * Get all registered slash commands
      */
     getAll(): Array<Command | SubcommandGroup>;
     /**
-     * Get all commands sorted alphabetically by name
+     * Get all registered user context menu commands
+     */
+    getAllUserContextMenus(): UserContextMenuCommand[];
+    /**
+     * Get all registered message context menu commands
+     */
+    getAllMessageContextMenus(): MessageContextMenuCommand[];
+    /**
+     * Get all slash commands sorted alphabetically by name
      */
     getAllSorted(): Array<Command | SubcommandGroup>;
     /**
      * Convert all commands to Discord JSON format for registration
      */
-    toDiscordJSON(): RESTPostAPIChatInputApplicationCommandsJSONBody[];
+    toJSON(): RESTPostAPIApplicationCommandsJSONBody[];
     /**
      * Generate paginated help pages for display in help command
      * Returns a 2D array where each inner array is a page of command descriptions
@@ -48,25 +117,69 @@ export declare class CommandManager {
      */
     executeCommand(commandName: string, interaction: ChatInputCommandInteraction, client: Client): Promise<void>;
     /**
-     * Get total number of registered commands
+     * Execute a user context menu command.
+     */
+    executeUserContextMenu(commandName: string, interaction: UserContextMenuCommandInteraction, client: Client): Promise<void>;
+    /**
+     * Execute a message context menu command.
+     */
+    executeMessageContextMenu(commandName: string, interaction: MessageContextMenuCommandInteraction, client: Client): Promise<void>;
+    /**
+     * Get total number of registered slash commands
      */
     get size(): number;
     /**
-     * Check if a command exists
+     * Get total number of all registered commands
+     */
+    get totalSize(): number;
+    /**
+     * Check if a slash command exists
      */
     has(name: string): boolean;
     /**
-     * Remove a command (useful for hot-reloading in dev)
+     * Check if a user context menu command exists
+     */
+    hasUserContextMenu(name: string): boolean;
+    /**
+     * Check if a message context menu command exists
+     */
+    hasMessageContextMenu(name: string): boolean;
+    /**
+     * Check if any command (slash, user context, or message context) exists
+     */
+    hasAny(name: string): boolean;
+    /**
+     * Remove a slash command (useful for hot-reloading in dev)
      */
     unregister(name: string): boolean;
     /**
-     * Clear all commands
+     * Remove a user context menu command
+     */
+    unregisterUserContextMenu(name: string): boolean;
+    /**
+     * Remove a message context menu command
+     */
+    unregisterMessageContextMenu(name: string): boolean;
+    /**
+     * Clear all commands (slash commands, user context menus, and message context menus)
      */
     clear(): void;
     /**
-     * Get command names as an array
+     * Get slash command names as an array
      */
     getCommandNames(): string[];
+    /**
+     * Get user context menu command names as an array
+     */
+    getUserContextMenuNames(): string[];
+    /**
+     * Get message context menu command names as an array
+     */
+    getMessageContextMenuNames(): string[];
+    /**
+     * Get all command names (slash + context menus) as an array
+     */
+    getAllCommandNames(): string[];
     setLogger(logger: ILogger): this;
     /**
      * Set the error reporter for all commands

package/dist/classes/CommandManager.class.js

@@ -1,42 +1,148 @@
+import { Command } from './Command.class.js';
 import { SubcommandGroup } from './SubcommandGroup.class.js';
+import { MessageContextMenuCommand } from './MessageContextMenuCommand.class.js';
+import { UserContextMenuCommand } from './UserContextMenuCommand.class.js';
+import { loadCommands } from '../utils/loadCommands.js';
 export class CommandManager {
     constructor() {
         this.commands = new Map();
+        this.userContextMenuCommands = new Map();
+        this.messageContextMenuCommands = new Map();
     }
     /**
-     * Register a single command or subcommand group
+     * Register commands (accepts single, array, or mixed types)
+     * @param command - Command(s) to register
+     * @example
+     * ```typescript
+     * // Single command
+     * commandManager.registerCommand(new PingCommand());
+     *
+     * // Array of commands
+     * commandManager.registerCommand([cmd1, cmd2, cmd3]);
+     *
+     * // Mixed types
+     * commandManager.registerCommand([
+     *   new PingCommand(),
+     *   new UserContextMenu(),
+     *   new SubcommandGroup(),
+     * ]);
+     * ```
      */
-    register(command) {
-        if (this.logger) {
+    registerCommand(command) {
+        if (Array.isArray(command)) {
+            for (const cmd of command) {
+                this.registerCommand(cmd);
+            }
+            return;
+        }
+        if (this.logger && 'setLogger' in command) {
             command.setLogger(this.logger);
         }
-        if (this.errorReporter) {
+        if (this.errorReporter && 'setErrorReporter' in command) {
             command.setErrorReporter(this.errorReporter);
         }
-        this.commands.set(command.name, command);
+        if (command instanceof Command || command instanceof SubcommandGroup) {
+            this.commands.set(command.name, command);
+        }
+        else if (command instanceof UserContextMenuCommand) {
+            this.userContextMenuCommands.set(command.name, command);
+        }
+        else if (command instanceof MessageContextMenuCommand) {
+            this.messageContextMenuCommands.set(command.name, command);
+        }
+        else {
+            this.logger?.warn(`Attempted to register invalid command type: ${command?.constructor?.name || 'unknown'}`, 'command-manager');
+        }
+    }
+    /**
+     * @experimental
+     * Automatically load and register all commands from a directory.
+     *
+     * This is a convenience wrapper around the loadCommands utility.
+     *
+     * @param dirPath - Absolute path to the directory containing commands
+     * @param options - Optional configuration
+     * @returns Number of commands successfully loaded
+     *
+     * @example
+     * ```typescript
+     * // Basic usage
+     * const count = await commandManager.loadFromDirectory('./src/commands');
+     * console.log(`Loaded ${count} commands`);
+     *
+     * // With options
+     * await commandManager.loadFromDirectory('./src/commands', {
+     *   verbose: true,
+     *   skipDirs: ['subcommands', 'test'],
+     * });
+     * ```
+     */
+    async loadFromDirectory(dirPath, options = {}) {
+        const commands = await loadCommands(dirPath, options);
+        this.registerCommand(commands);
+        const validCount = commands.filter(cmd => cmd instanceof Command ||
+            cmd instanceof SubcommandGroup ||
+            cmd instanceof UserContextMenuCommand ||
+            cmd instanceof MessageContextMenuCommand).length;
+        this.logger?.info(`Auto-loaded ${validCount} commands from ${dirPath}`, 'command-manager');
+        return validCount;
+    }
+    /**
+     * @deprecated Use `registerCommand()` instead
+     *
+     * Register a single command or subcommand group
+     */
+    register(command) {
+        this.registerCommand(command);
         return this;
     }
     /**
+     * @deprecated Use `registerCommand()` with an array instead
+     *
      * Register multiple commands at once
      */
     registerMultiple(commands) {
-        commands.forEach((cmd) => this.register(cmd));
+        this.registerCommand(commands);
         return this;
     }
     /**
-     * Get a specific command by name
+     * Get a specific slash command by name
      */
     get(name) {
         return this.commands.get(name);
     }
     /**
-     * Get all registered commands
+     * Get a specific user context menu command by name
+     */
+    getUserContextMenu(name) {
+        return this.userContextMenuCommands.get(name);
+    }
+    /**
+     * Get a specific message context menu command by name
+     */
+    getMessageContextMenu(name) {
+        return this.messageContextMenuCommands.get(name);
+    }
+    /**
+     * Get all registered slash commands
      */
     getAll() {
         return Array.from(this.commands.values());
     }
     /**
-     * Get all commands sorted alphabetically by name
+     * Get all registered user context menu commands
+     */
+    getAllUserContextMenus() {
+        return Array.from(this.userContextMenuCommands.values());
+    }
+    /**
+     * Get all registered message context menu commands
+     */
+    getAllMessageContextMenus() {
+        return Array.from(this.messageContextMenuCommands.values());
+    }
+    /**
+     * Get all slash commands sorted alphabetically by name
      */
     getAllSorted() {
         return this.getAll().sort((a, b) => a.name.localeCompare(b.name));
@@ -44,13 +150,26 @@ export class CommandManager {
     /**
      * Convert all commands to Discord JSON format for registration
      */
-    toDiscordJSON() {
-        return this.getAll().map((cmd) => {
+    toJSON() {
+        const slashCommands = Array.from(this.commands.values()).map((cmd) => {
             if (process.env.ENV === 'dev') {
                 console.log(`Registering: ${cmd.name}`);
             }
             return cmd.toJSON();
         });
+        const userContextMenus = Array.from(this.userContextMenuCommands.values()).map((cmd) => {
+            if (process.env.ENV === 'dev') {
+                console.log(`Registering user context menu: ${cmd.name}`);
+            }
+            return cmd.toJSON();
+        });
+        const messageContextMenus = Array.from(this.messageContextMenuCommands.values()).map((cmd) => {
+            if (process.env.ENV === 'dev') {
+                console.log(`Registering message context menu: ${cmd.name}`);
+            }
+            return cmd.toJSON();
+        });
+        return [...slashCommands, ...userContextMenus, ...messageContextMenus];
     }
     /**
      * Generate paginated help pages for display in help command
@@ -112,41 +231,131 @@ export class CommandManager {
         await command.execute(interaction, client);
     }
     /**
-     * Get total number of registered commands
+     * Execute a user context menu command.
+     */
+    async executeUserContextMenu(commandName, interaction, client) {
+        const command = this.userContextMenuCommands.get(commandName);
+        if (!command) {
+            throw new Error(`User context menu command not found: ${commandName}`);
+        }
+        await command.execute(interaction, client);
+    }
+    /**
+     * Execute a message context menu command.
+     */
+    async executeMessageContextMenu(commandName, interaction, client) {
+        const command = this.messageContextMenuCommands.get(commandName);
+        if (!command) {
+            throw new Error(`Message context menu command not found: ${commandName}`);
+        }
+        await command.execute(interaction, client);
+    }
+    /**
+     * Get total number of registered slash commands
      */
     get size() {
         return this.commands.size;
     }
     /**
-     * Check if a command exists
+     * Get total number of all registered commands
+     */
+    get totalSize() {
+        return this.commands.size +
+            this.userContextMenuCommands.size +
+            this.messageContextMenuCommands.size;
+    }
+    /**
+     * Check if a slash command exists
      */
     has(name) {
         return this.commands.has(name);
     }
     /**
-     * Remove a command (useful for hot-reloading in dev)
+     * Check if a user context menu command exists
+     */
+    hasUserContextMenu(name) {
+        return this.userContextMenuCommands.has(name);
+    }
+    /**
+     * Check if a message context menu command exists
+     */
+    hasMessageContextMenu(name) {
+        return this.messageContextMenuCommands.has(name);
+    }
+    /**
+     * Check if any command (slash, user context, or message context) exists
+     */
+    hasAny(name) {
+        return this.commands.has(name) ||
+            this.userContextMenuCommands.has(name) ||
+            this.messageContextMenuCommands.has(name);
+    }
+    /**
+     * Remove a slash command (useful for hot-reloading in dev)
      */
     unregister(name) {
         return this.commands.delete(name);
     }
     /**
-     * Clear all commands
+     * Remove a user context menu command
+     */
+    unregisterUserContextMenu(name) {
+        return this.userContextMenuCommands.delete(name);
+    }
+    /**
+     * Remove a message context menu command
+     */
+    unregisterMessageContextMenu(name) {
+        return this.messageContextMenuCommands.delete(name);
+    }
+    /**
+     * Clear all commands (slash commands, user context menus, and message context menus)
      */
     clear() {
         this.commands.clear();
+        this.userContextMenuCommands.clear();
+        this.messageContextMenuCommands.clear();
     }
     /**
-     * Get command names as an array
+     * Get slash command names as an array
      */
     getCommandNames() {
         return Array.from(this.commands.keys());
     }
+    /**
+     * Get user context menu command names as an array
+     */
+    getUserContextMenuNames() {
+        return Array.from(this.userContextMenuCommands.keys());
+    }
+    /**
+     * Get message context menu command names as an array
+     */
+    getMessageContextMenuNames() {
+        return Array.from(this.messageContextMenuCommands.keys());
+    }
+    /**
+     * Get all command names (slash + context menus) as an array
+     */
+    getAllCommandNames() {
+        return [
+            ...this.getCommandNames(),
+            ...this.getUserContextMenuNames(),
+            ...this.getMessageContextMenuNames(),
+        ];
+    }
     setLogger(logger) {
         this.logger = logger;
         // Inject logger into all already-registered commands
         for (const command of this.commands.values()) {
             command.setLogger(logger);
         }
+        for (const command of this.userContextMenuCommands.values()) {
+            command.setLogger(logger);
+        }
+        for (const command of this.messageContextMenuCommands.values()) {
+            command.setLogger(logger);
+        }
         return this;
     }
     /**
@@ -157,6 +366,12 @@ export class CommandManager {
         for (const command of this.commands.values()) {
             command.setErrorReporter(reporter);
         }
+        for (const command of this.userContextMenuCommands.values()) {
+            command.setErrorReporter(reporter);
+        }
+        for (const command of this.messageContextMenuCommands.values()) {
+            command.setErrorReporter(reporter);
+        }
         return this;
     }
 }

package/dist/classes/MessageContextMenuCommand.class.d.ts

@@ -0,0 +1,79 @@
+import { MessageContextMenuCommandInteraction, Client } from 'discord.js';
+import type { ILogger } from '../types/logger.js';
+import type { ErrorReporter } from '../utils/ErrorReporter.js';
+import { PermissionLevel } from '../types/permission.js';
+/**
+ * Base class for Message Context Menu Commands.
+ *
+ * Message context menu commands appear when right-clicking on a message and
+ * selecting "Apps" in the context menu.
+ *
+ * @example
+ * ```typescript
+ * export class ReportMessageCommand extends MessageContextMenuCommand {
+ *   name = 'Report Message';
+ *   guildOnly = true;
+ *   permissionLevel = 'user' as const;
+ *
+ *   protected async run(interaction: MessageContextMenuCommandInteraction) {
+ *     const message = interaction.targetMessage;
+ *     await reportMessage(message);
+ *     await interaction.reply({ content: 'Message reported!', ephemeral: true });
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class MessageContextMenuCommand {
+    abstract name: string;
+    abstract guildOnly: boolean;
+    abstract permissionLevel: PermissionLevel;
+    protected logger?: ILogger;
+    protected errorReporter?: ErrorReporter;
+    /**
+     * The main execution method - implement your command logic here.
+     */
+    protected abstract run(interaction: MessageContextMenuCommandInteraction, client: Client): Promise<void>;
+    /**
+     * Optional: Called before command execution.
+     * Return false to stop execution.
+     */
+    protected beforeExecute?(interaction: MessageContextMenuCommandInteraction, client: Client): Promise<boolean | void>;
+    /**
+     * Optional: Called after successful command execution.
+     */
+    protected afterExecute?(interaction: MessageContextMenuCommandInteraction, client: Client): Promise<void>;
+    /**
+     * Optional: Called when command execution fails.
+     */
+    protected onError?(interaction: MessageContextMenuCommandInteraction, error: Error, client: Client): Promise<void>;
+    /**
+     * Set the logger for this command.
+     */
+    setLogger(logger: ILogger): void;
+    /**
+     * Set the error reporter for this command.
+     */
+    setErrorReporter(reporter: ErrorReporter): void;
+    /**
+     * Log a message using the configured logger.
+     */
+    protected log(message: string, level: string, scope: string, logToConsole?: boolean): void;
+    /**
+     * Validate the interaction (guild-only check).
+     */
+    protected validate(interaction: MessageContextMenuCommandInteraction): string | null;
+    /**
+     * Check if the user has permission to use this command.
+     * Override this method to implement custom permission logic.
+     */
+    protected hasPermission(interaction: MessageContextMenuCommandInteraction): Promise<boolean>;
+    /**
+     * Execute the command with validation and error handling.
+     */
+    execute(interaction: MessageContextMenuCommandInteraction, client: Client): Promise<void>;
+    private safeExecute;
+    /**
+     * Convert this command to Discord API JSON format.
+     */
+    toJSON(): import("discord.js").RESTPostAPIContextMenuApplicationCommandsJSONBody;
+}

package/dist/classes/MessageContextMenuCommand.class.js

@@ -0,0 +1,120 @@
+import { ContextMenuCommandBuilder, ApplicationCommandType, } from 'discord.js';
+import { safeReply } from '../utils/editAndReply.js';
+/**
+ * Base class for Message Context Menu Commands.
+ *
+ * Message context menu commands appear when right-clicking on a message and
+ * selecting "Apps" in the context menu.
+ *
+ * @example
+ * ```typescript
+ * export class ReportMessageCommand extends MessageContextMenuCommand {
+ *   name = 'Report Message';
+ *   guildOnly = true;
+ *   permissionLevel = 'user' as const;
+ *
+ *   protected async run(interaction: MessageContextMenuCommandInteraction) {
+ *     const message = interaction.targetMessage;
+ *     await reportMessage(message);
+ *     await interaction.reply({ content: 'Message reported!', ephemeral: true });
+ *   }
+ * }
+ * ```
+ */
+export class MessageContextMenuCommand {
+    /**
+     * Set the logger for this command.
+     */
+    setLogger(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Set the error reporter for this command.
+     */
+    setErrorReporter(reporter) {
+        this.errorReporter = reporter;
+    }
+    /**
+     * Log a message using the configured logger.
+     */
+    log(message, level, scope, logToConsole = false) {
+        this.logger?.log(message, level, scope, logToConsole);
+    }
+    /**
+     * Validate the interaction (guild-only check).
+     */
+    validate(interaction) {
+        if (this.guildOnly && !interaction.guildId) {
+            return 'This command can only be used in a server.';
+        }
+        return null;
+    }
+    /**
+     * Check if the user has permission to use this command.
+     * Override this method to implement custom permission logic.
+     */
+    async hasPermission(interaction) {
+        // Default: everyone has permission
+        return true;
+    }
+    /**
+     * Execute the command with validation and error handling.
+     */
+    async execute(interaction, client) {
+        await this.safeExecute(this.name, interaction, client, async () => {
+            const error = this.validate(interaction);
+            if (error)
+                return await safeReply(interaction, error, true);
+            if (!(await this.hasPermission(interaction))) {
+                return await safeReply(interaction, 'You do not have permission to use this command.', true);
+            }
+            if (this.beforeExecute) {
+                const shouldContinue = await this.beforeExecute(interaction, client);
+                if (shouldContinue === false)
+                    return;
+            }
+            try {
+                await this.run(interaction, client);
+                if (this.afterExecute) {
+                    await this.afterExecute(interaction, client);
+                }
+            }
+            catch (err) {
+                if (this.onError) {
+                    await this.onError(interaction, err, client);
+                }
+                throw err;
+            }
+        });
+    }
+    async safeExecute(commandName, interaction, client, fn) {
+        const scope = `${commandName}_EXECUTION`;
+        try {
+            await fn();
+            this.log(`${commandName} context menu command executed`, 'info', scope);
+        }
+        catch (err) {
+            this.log('An Error occurred: ' + err, 'error', scope, true);
+            if (this.errorReporter) {
+                await this.errorReporter.reportError(err, `Context Menu: ${commandName}`, {
+                    user: interaction.user.tag,
+                    userId: interaction.user.id,
+                    messageAuthor: interaction.targetMessage.author.tag,
+                    messageContent: interaction.targetMessage.content.slice(0, 100),
+                    guild: interaction.guild?.name,
+                    guildId: interaction.guildId,
+                });
+            }
+            return await safeReply(interaction, 'An unexpected error occurred.');
+        }
+    }
+    /**
+     * Convert this command to Discord API JSON format.
+     */
+    toJSON() {
+        return new ContextMenuCommandBuilder()
+            .setName(this.name)
+            .setType(ApplicationCommandType.Message)
+            .toJSON();
+    }
+}

package/dist/classes/UserContextMenuCommand.class.d.ts

@@ -0,0 +1,78 @@
+import { UserContextMenuCommandInteraction, Client } from 'discord.js';
+import type { ILogger } from '../types/logger.js';
+import type { ErrorReporter } from '../utils/ErrorReporter.js';
+import { PermissionLevel } from '../types/permission.js';
+/**
+ * Base class for User Context Menu Commands.
+ *
+ * User context menu commands appear when right-clicking on a user and
+ * selecting "Apps" in the context menu.
+ *
+ * @example
+ * ```typescript
+ * export class GetUserInfoCommand extends UserContextMenuCommand {
+ *   name = 'Get User Info';
+ *   guildOnly = false;
+ *   permissionLevel = 'user' as const;
+ *
+ *   protected async run(interaction: UserContextMenuCommandInteraction) {
+ *     const user = interaction.targetUser;
+ *     await interaction.reply(`User: ${user.tag}\nID: ${user.id}`);
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class UserContextMenuCommand {
+    abstract name: string;
+    abstract guildOnly: boolean;
+    abstract permissionLevel: PermissionLevel;
+    protected logger?: ILogger;
+    protected errorReporter?: ErrorReporter;
+    /**
+     * The main execution method - implement your command logic here.
+     */
+    protected abstract run(interaction: UserContextMenuCommandInteraction, client: Client): Promise<void>;
+    /**
+     * Optional: Called before command execution.
+     * Return false to stop execution.
+     */
+    protected beforeExecute?(interaction: UserContextMenuCommandInteraction, client: Client): Promise<boolean | void>;
+    /**
+     * Optional: Called after successful command execution.
+     */
+    protected afterExecute?(interaction: UserContextMenuCommandInteraction, client: Client): Promise<void>;
+    /**
+     * Optional: Called when command execution fails.
+     */
+    protected onError?(interaction: UserContextMenuCommandInteraction, error: Error, client: Client): Promise<void>;
+    /**
+     * Set the logger for this command.
+     */
+    setLogger(logger: ILogger): void;
+    /**
+     * Set the error reporter for this command.
+     */
+    setErrorReporter(reporter: ErrorReporter): void;
+    /**
+     * Log a message using the configured logger.
+     */
+    protected log(message: string, level: string, scope: string, logToConsole?: boolean): void;
+    /**
+     * Validate the interaction (guild-only check).
+     */
+    protected validate(interaction: UserContextMenuCommandInteraction): string | null;
+    /**
+     * Check if the user has permission to use this command.
+     * Override this method to implement custom permission logic.
+     */
+    protected hasPermission(interaction: UserContextMenuCommandInteraction): Promise<boolean>;
+    /**
+     * Execute the command with validation and error handling.
+     */
+    execute(interaction: UserContextMenuCommandInteraction, client: Client): Promise<void>;
+    private safeExecute;
+    /**
+     * Convert this command to Discord API JSON format.
+     */
+    toJSON(): import("discord.js").RESTPostAPIContextMenuApplicationCommandsJSONBody;
+}

package/dist/classes/UserContextMenuCommand.class.js

@@ -0,0 +1,119 @@
+import { ContextMenuCommandBuilder, ApplicationCommandType, } from 'discord.js';
+import { safeReply } from '../utils/editAndReply.js';
+/**
+ * Base class for User Context Menu Commands.
+ *
+ * User context menu commands appear when right-clicking on a user and
+ * selecting "Apps" in the context menu.
+ *
+ * @example
+ * ```typescript
+ * export class GetUserInfoCommand extends UserContextMenuCommand {
+ *   name = 'Get User Info';
+ *   guildOnly = false;
+ *   permissionLevel = 'user' as const;
+ *
+ *   protected async run(interaction: UserContextMenuCommandInteraction) {
+ *     const user = interaction.targetUser;
+ *     await interaction.reply(`User: ${user.tag}\nID: ${user.id}`);
+ *   }
+ * }
+ * ```
+ */
+export class UserContextMenuCommand {
+    /**
+     * Set the logger for this command.
+     */
+    setLogger(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Set the error reporter for this command.
+     */
+    setErrorReporter(reporter) {
+        this.errorReporter = reporter;
+    }
+    /**
+     * Log a message using the configured logger.
+     */
+    log(message, level, scope, logToConsole = false) {
+        this.logger?.log(message, level, scope, logToConsole);
+    }
+    /**
+     * Validate the interaction (guild-only check).
+     */
+    validate(interaction) {
+        if (this.guildOnly && !interaction.guildId) {
+            return 'This command can only be used in a server.';
+        }
+        return null;
+    }
+    /**
+     * Check if the user has permission to use this command.
+     * Override this method to implement custom permission logic.
+     */
+    async hasPermission(interaction) {
+        // Default: everyone has permission
+        return true;
+    }
+    /**
+     * Execute the command with validation and error handling.
+     */
+    async execute(interaction, client) {
+        await this.safeExecute(this.name, interaction, client, async () => {
+            const error = this.validate(interaction);
+            if (error)
+                return await safeReply(interaction, error, true);
+            if (!(await this.hasPermission(interaction))) {
+                return await safeReply(interaction, 'You do not have permission to use this command.', true);
+            }
+            if (this.beforeExecute) {
+                const shouldContinue = await this.beforeExecute(interaction, client);
+                if (shouldContinue === false)
+                    return;
+            }
+            try {
+                await this.run(interaction, client);
+                if (this.afterExecute) {
+                    await this.afterExecute(interaction, client);
+                }
+            }
+            catch (err) {
+                if (this.onError) {
+                    await this.onError(interaction, err, client);
+                }
+                throw err;
+            }
+        });
+    }
+    async safeExecute(commandName, interaction, client, fn) {
+        const scope = `${commandName}_EXECUTION`;
+        try {
+            await fn();
+            this.log(`${commandName} context menu command executed`, 'info', scope);
+        }
+        catch (err) {
+            this.log('An Error occurred: ' + err, 'error', scope, true);
+            if (this.errorReporter) {
+                await this.errorReporter.reportError(err, `Context Menu: ${commandName}`, {
+                    user: interaction.user.tag,
+                    userId: interaction.user.id,
+                    targetUser: interaction.targetUser.tag,
+                    targetUserId: interaction.targetUser.id,
+                    guild: interaction.guild?.name,
+                    guildId: interaction.guildId,
+                });
+            }
+            return await safeReply(interaction, 'An unexpected error occurred.');
+        }
+    }
+    /**
+     * Convert this command to Discord API JSON format.
+     */
+    toJSON() {
+        return new ContextMenuCommandBuilder()
+            .setName(this.name)
+            .setType(ApplicationCommandType.User)
+            .toJSON();
+    }
+}

package/dist/index.d.ts

@@ -3,21 +3,25 @@ export { SubcommandGroup } from './classes/SubcommandGroup.class.js';
 export { CommandManager } from './classes/CommandManager.class.js';
 export { DiscordHandler } from './classes/DiscordHandler.class.js';
 export { ModalManager } from './classes/ModalManager.class.js';
-export { PaginatedEmbed } from './utils/PaginatedEmbed.class.js';
+export { UserContextMenuCommand } from './classes/UserContextMenuCommand.class.js';
+export { MessageContextMenuCommand } from './classes/MessageContextMenuCommand.class.js';
 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 type { LoadCommandsOptions } from './types/loadCommands.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';
 export { safeReply, safeEdit } from './utils/editAndReply.js';
 export { formatDuration, formatDateToString, formatDateToYYYYMMDDHHMMSS, formatDateToDDMMYYYY, getDaySuffix, capitalizeFirst, } from './utils/formatting.js';
+export { loadCommands } from './utils/loadCommands.js';
 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 { PaginatedEmbed } from './utils/PaginatedEmbed.class.js';
 export { InteractionError } from './classes/InteractionError.class.js';

package/dist/index.js

@@ -4,17 +4,20 @@ export { SubcommandGroup } from './classes/SubcommandGroup.class.js';
 export { CommandManager } from './classes/CommandManager.class.js';
 export { DiscordHandler } from './classes/DiscordHandler.class.js';
 export { ModalManager } from './classes/ModalManager.class.js';
-export { PaginatedEmbed } from './utils/PaginatedEmbed.class.js';
+export { UserContextMenuCommand } from './classes/UserContextMenuCommand.class.js';
+export { MessageContextMenuCommand } from './classes/MessageContextMenuCommand.class.js';
 // Utilities
 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';
 export { safeReply, safeEdit } from './utils/editAndReply.js';
 export { formatDuration, formatDateToString, formatDateToYYYYMMDDHHMMSS, formatDateToDDMMYYYY, getDaySuffix, capitalizeFirst, } from './utils/formatting.js';
+export { loadCommands } from './utils/loadCommands.js';
 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 { PaginatedEmbed } from './utils/PaginatedEmbed.class.js';
 // Errors
 export { InteractionError } from './classes/InteractionError.class.js';

package/dist/types/loadCommands.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Options for loading commands from a directory
+ */
+export interface LoadCommandsOptions {
+    /**
+     * Whether to recursively search subdirectories (default: true)
+     */
+    recursive?: boolean;
+    /**
+     * Whether to log verbose output to console (default: false)
+     */
+    verbose?: boolean;
+    /**
+     * Directory names to skip (default: ['subcommands', 'utils', 'helpers', 'lib'])
+     * Case-insensitive partial matching
+     */
+    skipDirs?: string[];
+    /**
+     * File name patterns to skip (default: ['Helper', 'Util', '.test', '.spec'])
+     * Case-sensitive partial matching
+     */
+    skipFiles?: string[];
+    /**
+     * Custom filter function for fine-grained control (optional)
+     * Return true to include the file, false to skip
+     * Runs AFTER skipDirs and skipFiles checks
+     */
+    filter?: (filePath: string) => boolean;
+}

package/dist/types/loadCommands.js

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

package/dist/utils/editAndReply.d.ts

@@ -1,5 +1,5 @@
 import Stream from 'stream';
-import { ActionRowBuilder, APIAttachment, Attachment, AttachmentBuilder, AttachmentPayload, BufferResolvable, ButtonInteraction, ChannelSelectMenuInteraction, ChatInputCommandInteraction, EmbedBuilder, JSONEncodable, Message, ModalSubmitInteraction, StringSelectMenuInteraction } from 'discord.js';
+import { ActionRowBuilder, APIAttachment, Attachment, AttachmentBuilder, AttachmentPayload, BufferResolvable, ButtonInteraction, ChannelSelectMenuInteraction, ChatInputCommandInteraction, ContextMenuCommandInteraction, EmbedBuilder, JSONEncodable, Message, ModalSubmitInteraction, StringSelectMenuInteraction } from 'discord.js';
 /**
  * Safely replies to an interaction, handling deferred/replied states.
  *
@@ -23,7 +23,7 @@ import { ActionRowBuilder, APIAttachment, Attachment, AttachmentBuilder, Attachm
  * }
  * ```
  */
-export declare function safeReply(interaction: ChatInputCommandInteraction | ButtonInteraction | ModalSubmitInteraction | ChannelSelectMenuInteraction | StringSelectMenuInteraction, content: string, ephemeral?: boolean, embeds?: EmbedBuilder[], components?: ActionRowBuilder<any>[], files?: (BufferResolvable | Stream | JSONEncodable<APIAttachment> | Attachment | AttachmentBuilder | AttachmentPayload)[]): Promise<Message>;
+export declare function safeReply(interaction: ChatInputCommandInteraction | ButtonInteraction | ModalSubmitInteraction | ChannelSelectMenuInteraction | StringSelectMenuInteraction | ContextMenuCommandInteraction, content: string, ephemeral?: boolean, embeds?: EmbedBuilder[], components?: ActionRowBuilder<any>[], files?: (BufferResolvable | Stream | JSONEncodable<APIAttachment> | Attachment | AttachmentBuilder | AttachmentPayload)[]): Promise<Message>;
 /**
  * Safely edits an interaction reply.
  *

package/dist/utils/loadCommands.d.ts

@@ -0,0 +1,27 @@
+import { LoadCommandsOptions } from '../types/loadCommands';
+/**
+ * @experimental
+ * Automatically discover and load all commands from a directory.
+ *
+ * Returns an array of command instances that can be registered with CommandManager.
+ *
+ * @param dirPath - Absolute path to the directory containing commands
+ * @param options - Optional configuration
+ * @returns Array of command instances
+ *
+ * @example
+ * ```typescript
+ * import { loadCommands } from '@julanzw/ttoolbox-discordjs-framework';
+ *
+ * // Load all commands
+ * const commands = await loadCommands('./src/commands', { verbose: true });
+ *
+ * // Register them
+ * commandManager.registerCommand(commands);
+ *
+ * // Or filter/process them first
+ * const adminCommands = commands.filter(cmd => cmd.name.startsWith('admin'));
+ * commandManager.registerCommand(adminCommands);
+ * ```
+ */
+export declare function loadCommands(dirPath: string, options?: LoadCommandsOptions): Promise<any[]>;

package/dist/utils/loadCommands.js

@@ -0,0 +1,129 @@
+import { readdir, stat } from 'fs/promises';
+import { join, extname } from 'path';
+import { pathToFileURL } from 'url';
+/**
+ * @experimental
+ * Automatically discover and load all commands from a directory.
+ *
+ * Returns an array of command instances that can be registered with CommandManager.
+ *
+ * @param dirPath - Absolute path to the directory containing commands
+ * @param options - Optional configuration
+ * @returns Array of command instances
+ *
+ * @example
+ * ```typescript
+ * import { loadCommands } from '@julanzw/ttoolbox-discordjs-framework';
+ *
+ * // Load all commands
+ * const commands = await loadCommands('./src/commands', { verbose: true });
+ *
+ * // Register them
+ * commandManager.registerCommand(commands);
+ *
+ * // Or filter/process them first
+ * const adminCommands = commands.filter(cmd => cmd.name.startsWith('admin'));
+ * commandManager.registerCommand(adminCommands);
+ * ```
+ */
+export async function loadCommands(dirPath, options = {}) {
+    const { recursive = true, verbose = false, skipDirs = ['subcommands', 'utils', 'helpers', 'lib'], skipFiles = ['Helper', 'Util', '.test', '.spec'], filter, } = options;
+    const allCommands = [];
+    try {
+        const files = await getFilesRecursive(dirPath, recursive, skipDirs, skipFiles, filter);
+        if (verbose) {
+            console.log(`Found ${files.length} potential command files in ${dirPath}`);
+        }
+        for (const file of files) {
+            try {
+                const commands = await loadCommandsFromFile(file, verbose);
+                allCommands.push(...commands);
+            }
+            catch (err) {
+                if (verbose) {
+                    console.error(`⚠️ Failed to load ${file}: ${err.message}`);
+                }
+            }
+        }
+        if (verbose) {
+            console.log(`\n✅ Successfully loaded ${allCommands.length} commands`);
+        }
+        return allCommands;
+    }
+    catch (err) {
+        throw new Error(`Failed to load commands from ${dirPath}: ${err.message}`);
+    }
+}
+/**
+ * Recursively get all .js/.ts files from a directory with smart filtering
+ */
+async function getFilesRecursive(dirPath, recursive, skipDirs, skipFiles, customFilter) {
+    const files = [];
+    const entries = await readdir(dirPath);
+    for (const entry of entries) {
+        const fullPath = join(dirPath, entry);
+        const stats = await stat(fullPath);
+        if (stats.isDirectory()) {
+            if (skipDirs.some(skip => entry.toLowerCase().includes(skip.toLowerCase()))) {
+                continue;
+            }
+            if (recursive) {
+                const subFiles = await getFilesRecursive(fullPath, recursive, skipDirs, skipFiles, customFilter);
+                files.push(...subFiles);
+            }
+        }
+        else {
+            const ext = extname(entry);
+            if (ext !== '.js' && ext !== '.ts')
+                continue;
+            if (skipFiles.some(skip => entry.includes(skip)))
+                continue;
+            if (customFilter && !customFilter(fullPath))
+                continue;
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+/**
+ * Load all command exports from a single file
+ */
+async function loadCommandsFromFile(filePath, verbose) {
+    const commands = [];
+    const fileUrl = pathToFileURL(filePath).href;
+    const module = await import(fileUrl);
+    if (module.default) {
+        commands.push(module.default);
+        if (verbose) {
+            const type = getCommandType(module.default);
+            const name = module.default.name || 'unnamed';
+            console.log(`  ✓ ${type}: ${name}`);
+        }
+    }
+    for (const [exportName, exportValue] of Object.entries(module)) {
+        if (exportName === 'default')
+            continue;
+        commands.push(exportValue);
+        if (verbose) {
+            const type = getCommandType(exportValue);
+            const name = exportValue.name || exportName;
+            console.log(`  ✓ ${type}: ${name}`);
+        }
+    }
+    return commands;
+}
+/**
+ * Get a human-readable type name for a command
+ */
+function getCommandType(obj) {
+    const constructorName = obj?.constructor?.name;
+    if (constructorName?.includes('SubcommandGroup'))
+        return 'SubcommandGroup';
+    if (constructorName?.includes('UserContextMenu'))
+        return 'UserContextMenu';
+    if (constructorName?.includes('MessageContextMenu'))
+        return 'MessageContextMenu';
+    if (constructorName?.includes('Command'))
+        return 'Command';
+    return 'Unknown';
+}

package/package.json

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