abstracto/abstracto-application/documentation/src/main/docs/asciidoc/modules/moderation.adoc

=== Moderation

Feature key: `moderation`

==== Post targets
`banLog`:: target of the log message containing information about the ban for both `ban` and `banId`. Will still ban if not setup.
`kickLog`:: target of the log message containing information about the kick. Will still kick if not setup.

==== Feature modes
`banLogging`:: if enabled, log bans to the post target `banLog`. Enabled by default.
`kickLogging`:: if enabled, log bans to the post target `kickLog`. Enabled by default.

==== Commands
Ban a member::
* Usage: `ban <member> [reason]`
* Description:
Bans the given given `member` with the given optional `reason`. This sends a logging message to the `banLog` post target.
Banning this way does not delete old messages of the member on the server. If the `reason` is not provided, a default reason is used.
* Example: `ban @Member bad` in order to ban `Member` with the reason `bad` (the @Member is a user mention)
* Required bot permission: `BAN_MEMBERS`
Ban a user by ID::
* Usage: `banId <userId> [reason]`
* Description: Bans the `user` by his id with the optional `reason`. . This command can be used in case the user is not part of the server anymore.
This will also send a log message to `banLog` and not delete old messages.
* Example: `banId 1234 bad` in order to ban the user with ID `1234` with the reason `bad`
* Required bot permission: `BAN_MEMBERS`
Kick a member::
* Usage: `kick <member> [reason]`
* Description: Kicks the `member` from the guild with the given `reason`. If the `reason` is not provided, a default reason is used.
* Example: `kick @Member bad` in order to kick `Member` with the reason `bad` (the @Member is a user mention)
* Required bot permission: `KICK_MEMBERS`
Change the slow mode in a channel::
* Usage: `slowmode <duration> [channel]`
* Description: This command sets the slow mode in the `channel` to the given `duration`. This command uses duration parsing. The `channel` is optional and if none is provided, the current channel is used.
* Example: `slowMode 1h2m3s #general` in order to set the slow mode in channel `general` to 1 hour 2 minutes and 3 seconds (the #general is a user mention)
Purging messages in a channel::
* Usage: `purge <messageCount> [member]`
* Description: Deletes the last `messageCount` messages in the current channel. If a `member` is provided as parameter, only the messages by this member
will be deleted. The deletion of this messages will *not* be logged by the logging mechanism. The messages to be deleted need to be from within the last 2 weeks, but there is no limit on how much messages can be deleted besides that.
While the command is ongoing, a status update message will be shown indicating how far the command is. This message will be deleted after the command is done.

=== Warning

This feature can be used to warn specific users if they did something not allowed by the rules.

Feature key: `warnings`

==== Post targets
`warnLog`:: target of the log message containing information about a created warn, only used if feature mode `warnLogging` is enabled.
`decayLog`:: will be used when all the warnings are decayed by `decayAllWarnings` and feature mode `warnDecayLogging` is enabled.

==== Feature modes
`warnLogging`:: if enabled, each warn is logged to the post target `warnLog`. Enabled by default.
`automaticWarnDecayLogging`:: if enabled, warn decays by `decayAllWarnings` are logged to the post target `decayLog`. Enabled by default.


==== Commands
Warn a user::
* Usage: `warn <member> [reason]`
* Description: Warns the `member` with the given `reason` or a default one, if none is provided. This command sends a log message to the `warnLog` post
target and notifies the member about the warn.
* Example: `warn @Member bad` in order to warn `Member` with the reason `bad` (the @Member is a user mention)
Listing the warnings of users::
* Usage: `warnings [member]`
* Description: If no `member` is provided displays all the warnings on the server. If a `member` is provided, will only display the warnings of the user.
This uses a paginated output, which means multiple pages in case there are more warnings to display. This will also display the date the warning was decayed if applicable.
Showing your warnings::
* Usage: `myWarnings`
* Description: Displays the amount of warnings of the user executing on the server. This will show both active and total warnings.
Decaying all warnings regardless of the date::
* Usage: `decayAllWarnings`
* Description: This will cause all warnings of this server which are not decayed yet to be decayed instantly.
Deleting a warning::
* Usage: `deleteWarning <warnId>`
* Description: Deletes the warning identified by `warnId` completely from the database.


=== Automatic warn decay

This feature enables warnings to be decayed after a configurable amount of days. This feature directly depends on the feature `warnings`.

Feature key: `warnDecay`

==== Relevant system configuration
`decayDays` The amount of days after which a warning gets decayed. Default: 90

==== Post targets
`decayLog`:: target of the log message containing the information in case a warning is decayed.

==== Feature modes
`automaticWarnDecayLogging`:: if enabled, automatic warn decays are logged to the `decayLog` post target. Enabled by default.

==== Commands
Decaying all warnings if necessary::
* Usage: `decayWarnings`
* Description: Triggers the decay of the warnings instantly, which means, every not decayed warning on this server older than the configured amount of days will be decayed and the decay will be logged.

=== Muting

This feature provides the capability to mute users, which effectively means it applies a role which prevents them from sending messages and speaking in voice chat.
The role used to mute member will not be created and needs to be provided. There is no validation if the provided role actually mutes members.
If the user leaves the guild and rejoins, the mute role will be re-applied.

Feature key `muting`

==== Post targets
`muteLog`:: target of log message containing the information in case a member was muted and when the mute ended automatically.

==== Feature modes
`muteLogging`:: if enabled, each mute is to be logged to the post target `muteLog`. Enabled by default.
`unMuteLogging`:: if enabled, each un mute which happens 'naturally' (after the defined time period is over) will be logged to the `muteLog` post target. Enabled by default.
`manualUnMuteLogging`:: if enabled, each un mute which happens via the command `unmute` will be logged to the `muteLog` post target. Enabled by default.


==== Commands
Muting a user::
* Usage: `mute <member> <duration> [reason]`
* Description: Applies the mute role to the given `member` for the given `duration`. If `reason` is not provided, a default reason will be used for logging in the `muteLog` post target.  This will automatically
un-mute the user after the duration has passed. If the un-mute happens automatically, this will also be logged in the `muteLog` post target.
This command sends a notification to the user about the mute and kicks the user from the voice channel, if any.
* Example: `mute @Member 1h2m3s bad` in order to mute the member `Member` for 1 hour 2 minutes and 3 seconds with the reason `bad` (the @Member is a user mention)
Un-Muting a user::
* Usage: `unMute <member>`
* Description: Removes the mute role from the given member. This does *not* log the un-mute.
Configuring which role to use for muting::
* Usage: `setMuteRole <role>`
* Description: Sets the  `role` to be used as the role when applying a mute. This role needs to be muting, which means, if you want it to be effective, this role needs to deny `MESSAGE_WRITE`. Abstracto does not validate nor require the role to actually mute.
Only *one* role can be used as a mute role.

=== Logging

This feature provides a range of utilities to monitor the server.
The logging includes:

Feature key `logging`

==== Post targets
`deleteLog`:: target for the messages containing information about a deleted message.
`editLog`:: target for the messages containing information about an edited message.
`joinLog`:: target for the messages containing information about an user joining the server.
`leaveLog`:: target or the messages containing information about an user leaving the server.

Deleted message logging:: When a message is deleted, the content of the message and the possible attachments of said message will be logged.
Edited message logging:: When a message is edited, the previous content of the message and the new content of the message will be logged.
This does not work if the message was sent before the bot was started.
Member joining logging:: When a member joins the guild, a message indicating this is send.
Member leaving logging:: When a member leaves the guild, a message indicating this is send.


=== User notes

Feature key `userNotes`

This feature provides the ability to store specific notes for members in the database. These notes can then be retrieved and deleted and consist of only text.

==== Commands
Creating a user note::
* Usage: `userNote <user> <text>`
* Description: Creates a single user note for the specified user.

Deleting a user note::
* Usage: `deleteNote <id>`
* Description: Deletes the user note identified by its ID. The ID can be retrieved by the command `userNotes`.

Retrieving user notes::
* Usage: `userNotes [user]`
* Description: If `user` is not provided, this will list the user notes of the whole server, if `user` is provided, this will only list user notes from this particular `user`.

=== Invite filter

Feature key `inviteFilter`

This feature provides the ability to automatically delete invites not allowed on the server. These illegal invites can be tracked in a specific feature mode, in order to analyze if allowing them would make sense.
Another feature mode can send a notification to a post target in case an invite link has been deleted.

==== Post targets
`inviteDeleteLog`:: target for notifications about deleted invite links - if the feature mode `filterNotifications` is enabled.


==== Feature modes
`trackUses`:: if enabled, each filtered invite will be tracked in the database. Disabled by default.
`filterNotifications`:: if enabled, sends a notification to the `inviteDeleteLog` post target in case a message was deleted because of an invite. This notification contains the detected invite link(s), the author and a link to where the message was. Enabled by default.

==== Commands
Allowing an invite::
* Usage: `allowInvite <invite>`
* Description: Adds the `invite` to the list of invites, which are allowed on the server. The `invite` can either be the full invite URL or only the last part. If the invite is already allowed, this command will do nothing.

Disallowing an invite::
* Usage: `disAllowInvite <invite>`
* Description: Removes the `invite` from the list of invites, which are allowed on the server. The `invite` can either be the full invite URL or only the last part. In case the given invite is not allowed, this command will throw an error.

Showing the tracked filtered invites::
* Usage: `showTrackedInviteLinks [amount]`
* Description: Shows the invites which were used and deleted on the server ordered by the amount of times they were deleted. The `amount` can be used to define how many invite links to display. The default is the top 5.
* Mode Restriction: This command is only available when the feature mode `trackUses` is enabled.

Remove all or individual invites from the tracked filtered invites::
* Usage: `removeTrackedInviteLinks [invite]`
* Description: Removes the stored statistic for the given `invite`. In case `invite` is not given, it will delete all tracked filtered invites from the server.
* Mode Restriction: This command is only available when the feature mode `trackUses` is enabled.