Moderation Suite

Relevant source files

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

• src/helpers/ModUtils/index.ts
• src/helpers/ModUtils/core.ts
• src/handlers/automod.ts
• src/commands/admin/automod/automod.ts
• src/commands/moderation/warnings.ts
• src/commands/moderation/purge.ts
• src/commands/moderation/timeout.ts
• src/commands/moderation/kick.ts
• src/commands/moderation/ban.ts

The Moderation Suite is a comprehensive set of tools designed to help server administrators and moderators maintain a safe and orderly environment. It combines manual moderation commands for direct intervention with a powerful automated moderation system (Automod) that proactively handles rule violations. The suite is built around a central ModUtils helper, which standardizes actions, permission checks, and logging across all moderation features.

This system ensures that all moderation actions, whether manual or automatic, are consistently applied, logged for auditing, and communicated to the relevant parties. It includes features for managing members (ban, kick, timeout), controlling chat content (purge), and tracking user behavior (warnings, strikes).

Core Architecture: ModUtils

The ModUtils module is the backbone of the moderation system, providing a unified API for performing moderation actions. It consists of a class and several exported functions that encapsulate the logic for interacting with the Discord API, checking permissions, and logging actions.

Sources: src/helpers/ModUtils/index.ts, src/helpers/ModUtils/core.ts

Key Components

• ModUtils Class: A wrapper class that provides static methods for all moderation actions. This is used for backward compatibility and organized access.
• Exported Functions: Individual functions for each action (e.g., banTarget, kickTarget, purgeMessages) are exported directly for modern usage.
• memberInteract: A crucial permission check function that determines if an issuer (moderator) can act upon a target based on role hierarchy. A server owner can always moderate, but otherwise, the issuer's highest role must be above the target's highest role.
• logModeration: A centralized function for logging all moderation actions. It sends a detailed embed to the configured log channel and saves a record to the database.

The following diagram illustrates the structure of the ModUtils module.

Moderation Logging Flow

Every significant moderation action is recorded. The logModeration function is responsible for this process.

1. Retrieves guild settings to find the logs_channel.
2. Constructs a MinaEmbed with a color corresponding to the action type (e.g., red for BAN, orange for KICK).
3. Populates the embed with details about the issuer, target, reason, and any action-specific data (like timeout duration or number of purged messages).
4. Saves the log to the database via addModLogToDb.
5. Sends the embed to the logs_channel if configured.
6. For punitive actions (BAN, KICK, TIMEOUT, etc.), it automatically adds a "red flag" to the target user's profile in the database via addFlagFromModAction.

This flow is depicted below:

Manual Moderation Commands

Users with appropriate permissions can execute slash commands to moderate users and chat. These commands all leverage the ModUtils helper to perform and log their actions.

Command	Description	Key Parameters
/ban	Bans a member from the server.	user, reason, duration
/kick	Kicks a member from the server.	user, reason
/timeout	Times out a member, preventing them from interacting.	user, duration, reason
/purge	Bulk deletes messages from a channel.	amount, type, user/token
/warnings list	Lists all warnings for a member.	user
/warnings clear	Clears all warnings for a member.	user

Sources: src/commands/moderation/ban.ts, src/commands/moderation/kick.ts, src/commands/moderation/timeout.ts, src/commands/moderation/purge.ts, src/commands/moderation/warnings.ts

Command Execution Flow

The sequence diagram below shows a typical flow for a manual moderation command, using /ban as an example.

Purge Command

The /purge command is unique in its variety of filters for deleting messages.

Purge Type	Argument	Description
ALL	-	Deletes all messages up to the specified amount.
ATTACHMENT	-	Deletes messages containing attachments.
BOT	-	Deletes messages from bots.
LINK	-	Deletes messages containing links.
TOKEN	token	Deletes messages containing a specific word or phrase.
USER	user	Deletes messages from a specific user.

Sources: src/commands/moderation/purge.ts:16-92, src/helpers/ModUtils/index.ts:98-106

Automated Moderation (Automod)

The Automod system automatically scans messages and applies moderation actions based on pre-configured rules. It is designed to be a first line of defense against spam and other unwanted content.

Sources: src/handlers/automod.ts, src/commands/admin/automod/automod.ts

Automod Processing Flow

1. Initial Check (shouldModerate): Before processing, Automod checks if moderation is appropriate. It ignores messages from members with KickMembers, BanMembers, or ManageGuild permissions, as well as messages in channels where the bot lacks ManageMessages permission.
2. Rule Evaluation: If a message passes the initial check, it is evaluated against a series of rules.
3. Strike Accumulation: For each rule violation, the system adds one or more "strikes" to a strikesTotal counter.
4. Action & Logging: If strikesTotal > 0, the user receives the calculated number of strikes, which are saved to their member profile in the database. A log is sent to the mod-log channel, and the user is notified via DM about the infraction and their new strike total.
5. Punishment: If the user's cumulative strikes meet or exceed the configured maximum (automod.strikes), a punishment is triggered via ModUtils.addModAction. The punishment type (TIMEOUT, KICK, or BAN) is configured via the /automod action command. After punishment, the user's strikes are reset to 0.

Automod Configuration

The Automod system is configured using the /automod command group.

Subcommand	Description
status	Displays the current Automod configuration.
strikes	Sets the number of strikes a user can receive before a punishment is issued.
action	Sets the punishment action (TIMEOUT, KICK, BAN) when max strikes are reached.
debug	Toggles whether Automod ignores messages from staff.
whitelistadd	Exempts a channel from all Automod checks.
whitelistremove	Removes a channel from the exemption whitelist.

Sources: src/commands/admin/automod/automod.ts:12-106

Conclusion

Amina's Moderation Suite provides a robust and flexible toolkit for server management. By centralizing core logic in ModUtils, it ensures consistency and auditability for all actions. The combination of direct, manual commands for immediate response and a configurable, strike-based Automod for proactive enforcement allows moderators to effectively maintain server health. The detailed logging and automatic user flagging system further enhance accountability and provide valuable history for future moderation decisions.