Utility Commands

Relevant source files

The following files were used as context for generating this wiki page:

• src/commands/utility/help.ts
• src/commands/bot/bot.ts
• src/commands/info/info.ts
• src/handlers/command.ts
• types/commands.d.ts
• src/commands/bot/sub/botstats.ts
• package.json

Utility commands in Amina provide essential, non-specialized functionality that enhances the user experience. These commands are not tied to a specific feature domain like moderation or economy but rather serve as general-purpose tools. They allow users to get help, retrieve information about the bot and the server, and perform other useful actions.

The primary utility commands are /help, /mina, and /info. The /help command provides an interactive menu for discovering other commands. The /mina command offers a suite of subcommands for getting bot-specific information like statistics, uptime, and version history. The /info command allows users to look up details about server entities like users, channels, and the guild itself.

Core Command Handling

All utility commands, being slash commands, are processed by the central handleSlashCommand function. This handler orchestrates the entire lifecycle of a command's execution, from initial validation to final response.

The process involves several key steps:

1. Command Retrieval: The handler looks up the command data from the client.slashCommands collection based on the command name.
2. Validations: It runs any custom validation callbacks defined in the command's configuration.
3. Permission Checks: It verifies that the user and the bot have the necessary permissions to execute the command. It also restricts developer-only commands.
4. Cooldown Management: It checks if the user is under a cooldown for the specific command and prevents execution if they are.
5. Execution: It defers the reply to avoid timeouts and then calls the command's interactionRun method, passing the interaction object and guild settings.
6. Error Handling: Any exceptions during execution are caught, logged to Honeybadger, and a generic error message is sent to the user.
7. Cooldown Application: After execution, a new cooldown is applied to the user for that command.

Sources: src/handlers/command.ts:19-150

This diagram illustrates the flow of the handleSlashCommand function.

Command Definition (CommandData)

Every command in the system is defined by a CommandData object. This structure standardizes how commands are configured, including their permissions, options, and execution logic.

Property	Type	Description
name	string	The name of the command.
description	string	A brief explanation of what the command does.
cooldown	number	The cooldown period in seconds between uses for a single user.
category	CommandCategory	The category the command belongs to (e.g., UTILITY, INFO).
botPermissions	PermissionResolvable[]	Permissions the bot requires to run the command.
userPermissions	PermissionResolvable[]	Permissions the user requires to run the command.
slashCommand	InteractionInfo	Configuration for the slash command, including enabled, ephemeral, and options.
interactionRun	function	The main function that executes when the command is called.

Sources: types/commands.d.ts:29-57

/help Command

The /help command is an interactive and paginated menu that allows users to explore all available commands. It can be used to view commands by category or to get detailed information about a specific command.

Sources: src/commands/utility/help.ts

Features

• Category Browser: Users can select a command category from a dropdown menu.
• Paginated Command List: For each category, commands are displayed in a paginated embed, with 5 commands per page.
• Specific Command Lookup: Users can get usage information for a single command by providing its name (e.g., /help command:ping).
• Permission-Aware: The category list automatically hides categories that the user does not have permission to access (e.g., Admin, Moderation, Developer).

Interaction Flow

The help menu is managed by a message component collector that listens for user interactions with the select menu and pagination buttons.

This sequence diagram shows a user interacting with the /help menu.

/mina Command

The /mina command serves as a central hub for retrieving information and statistics about the bot itself. It is structured with several subcommands, each providing a specific piece of information.

Sources: src/commands/bot/bot.ts

Subcommands

Subcommand	Description
invite	DMs the user a link to invite the bot to their server.
stats	Displays system statistics like CPU/memory usage, server count, and ping.
uptime	Shows how long the bot has been running since its last restart.
donate	Provides links to support the bot's development via Ko-fi, GitHub Sponsors, or Patreon.
docs	Provides a link to the bot's documentation website.
ping	Checks the bot's WebSocket latency to Discord.
changelog	Fetches and displays the latest updates from the project's CHANGELOG.md file on GitHub.

Sources: src/commands/bot/bot.ts:14-53

stats Subcommand

The stats subcommand provides a detailed overview of the bot's operational health and system resource usage. It gathers data from both the Node.js process and os modules.

• Bot Stats: Guilds, users, channels, and WebSocket ping.
• CPU Info: OS platform, architecture, core count, and process CPU usage.
• RAM Info: Memory usage for the bot process and the overall system.
• Version Info: The running Node.js version.

After displaying the stats, it asynchronously calls updateBotStats to save the latest statistics to the database, which can be used for a monitoring dashboard.

Sources: src/commands/bot/sub/botstats.ts:10-72

changelog Subcommand

This subcommand dynamically fetches the CHANGELOG.md file directly from the bot's GitHub repository using the @octokit/rest library. It authenticates with a GitHub token stored in secrets. The repository owner and name are parsed from the repository.url field in package.json. It then displays the content of the two most recent version blocks in an embed.

Sources: src/commands/bot/bot.ts:141-193, package.json:20-23

/info Command

The /info command is a versatile utility for retrieving detailed information about various Discord entities within the server.

Sources: src/commands/info/info.ts

Subcommands

Subcommand	Description
user	Displays a user's account information, roles, and join date.
channel	Shows details for a channel, such as its type, topic, and creation date.
guild	Provides server statistics, including owner, boost level, and features.
avatar	Displays a user's avatar in full resolution.
emoji	Shows details for a custom emoji, like its ID and creation date.
profile	Displays a user's custom bot profile.

Sources: src/commands/info/info.ts:17-74

Conclusion

The utility commands are a fundamental part of Amina's feature set. They provide users with the necessary tools to learn about the bot's capabilities (/help), monitor its status (/mina), and inspect their server environment (/info). The modular design, centered around the CommandData structure and a robust command handler, ensures that these commands are reliable, maintainable, and consistent with the rest of the bot's functionality.