kylrs / gagbot.js

gagbot.js is a JavaScript implementation of GaGBot, a general-purpose, extensible bot for Discord servers.

gagbot.js

GaGBot is a utility bot for discord servers, written in JavaScript for Node.js

To get the latest stable release, check out the releases page.

Features

• Module Loader - GaGBot can dynamically load modules that define new commands and events, making implementing custom features a breeze! (r20.1.0)
• Permissions - Fine-tune access to custom commands with simple permission nodes per role. (r20.1.0)
• Greet Module - Send new users a welcome message when they join the server. (r20.2.0)
• Reaction Roles - Allow users to assign themselves specific roles by reacting to messages. (r20.2.0)

Upcoming Features

• Admin Module - Commands for managing the server, e.g. purging channels, muting users, and so on.
• Custom Logging - Keep track of server activity by choosing what events are logged, and where.
• Promotion Tracks - Allow users to earn roles, with ladders that they can climb automatically.

Got a good idea? Open an issue and start the discussion!

Alternatively, you could contribute to one of these features! Look for open issues that are awaiting your action.

Getting Started

Prerequisites

• Install git
• Install node, version 14.0.0 or later
• Install npm
• A MongoDB server.

Installation

1. Create a Discord Application and get a Bot Token
2. Invite the bot to your server.
3. Clone the repo or grab a stable release (recommended)
4. Install the bot

  cd /gagbot.js
  npm install

5. Create an environment variable named DISCORD_TOKEN, and set it to your bot's token.
   • If you're using the admin module, you should also supply the environment variables PASTEBIN_DEV_KEY, PASTEBIN_USER_NAME and PASTEBIN_USER_PASSWORD, containing your Pastebin API developer key, username and password respectively. This is especially necessary for large servers where the prune command may select inactive members in excess of the number the bot is able to list in a MessageEmbed.
6. Add your MongoDB connection string to an environment variable named MONGO_DB_URI.
7. Run the bot. If all goes well, you'll see the modules being loaded, followed by a message that your bot has logged in to Discord.

  node src/bot.js

7. You can test your bot using the ping command in your server chat, which is included in the core module. By default, you can either tag the bot to summon it, or use the prefix !.

8. Configure GaGBot!

Built With

• Node.js
• discord.js
• MongoDB

Versioning

We use MAJOR.MINOR.PATCH semantic versioning in two different flavours. One for versioning code, and the other for releases. For more information, visit the wiki.

The latest stable release is r20.1.0.

Contributors

• Kay [email protected] - Product Owner

License

This code is licensed under the ISC License - see LICENSE.md for details.

gagbot.js's Issues

Add new argument types

Description

This issue proposes the addition of new types for bot command arguments:

• Boolean - The strings true or false, parsed as JS boolean values
• User - A user's tag or ID, used to fetch that User object
• Role - The @, name or ID of a role, used to fetch that Role object
• Channel - The #, name or ID of a channel, used to fetch that Channel object
• Message - The ID of a message, used to fetch that Message object
• Emoji - The :name:, Unicode symbol or ID of an emoji, used to fetch that Emoji object

Why?

This feature would significantly increase the ease with which new commands can be implemented, as it removes the need for these objects to be parsed from raw argument strings.

Implementation Details

A collection of functions taking a Message (from which other entities can be fetched) and an input String. The function returns an (Object, String) tuple containing the parsed argument object and the remaining input after parsing. The function returns null if the type could not match the input string.

String and Number types should be re-implemented as part of the enactment of this change.

Purge lists exceed maximum embed size

Description

When the !purge command results in a list of names amounting to a message >6000 characters, the embed can't be sent, so fails silently.

Steps to Reproduce

Steps to reproduce the behaviour:

1. In a server with a large number of inactive users
2. !purge 1 day
3. No response, if enough members were selected for purging

Expected Behaviour

All members should be listed. This should be done via pagination, e.g.

...
User456 last seen 21:30 18/06/20 GMT
User789 last seen Never
And 12 more members...

React ⏩ to show unlisted members.

"Start" script is missing

Description

The "npm start" command fails due to the script being missing from the config file. Running "node src/bot.js" successfully starts the bot, however.

Steps to Reproduce

Steps to reproduce the behaviour:

1. Navigate to the install directory in Command Prompt or other shell
2. Send command npm start

Expected Behaviour

The bot should have started.

Context

Evidence:
If applicable, include any screenshots or error messages to help explain your problem.

Environment (please complete the following information):
npm ERR! missing script: start

Some emojis aren't parsed correctly as command arguments

Description

Some complex emojis, such as flags, aren't parsed fully by the emoji parsing function, causing the parser to think that additional arguments have been passed in the command call.

Steps to Reproduce

Steps to reproduce the behaviour:

1. Call the command !rrset add Test :flag_eu: @<some_role>
2. A 'Too many arguments!' error will be thrown by GaGBOT in the chat channel where the command was called.

Implement basic permissions management for bot commands

Description

Command definitions should allow an optional field permission, which takes a string representing the required permission node. Permission strings should represent a tree structure; that is, a root node admin may have the child nodes admin.purge, admin.ban, etc, which may in turn have their own child nodes.

Permissions should be able to be assigned at a Role, User, and Channel level, and can either be set to true or false. Which entities are assigned which roles should be persistent, using the NeDB datastore.

Why?

Permissions are essential for building a usable discord bot. Allowing any user to use any command in any channel is a recipe for disaster. This feature will enable granular control over which of the bot's features can be used by which users, and where.

Implementation Details

• Add commands to the Core module for manipulating permissions nodes. Assignments should persist in the datastore.
  • !perm set <entity:Role|User|Channel> <node:String> <allow:Boolean> - Assign a permission node to an entity.
  • !perm list <entity:Role|User|Channel>[ <node:String>] - List all permissions assigned to an entity. If a node is specified, list assignment of this node and child nodes.
• Check permissions before command execution - exact details to be established.
• Add permissions nodes for existing commands
• Allow a permissions.js in module folders defining permissions nodes and their defaults.

Prerequisites

• #2 Refactor Command-related code.
• #3 Implement Role, User and Channel command argument types.

Refactor command-related code

Description

This issue proposes the simplification of command-related code, and the implementation of a better, more object-oriented solution to command loading and parsing.

Why?

The current code for loading and parsing commands makes use of a number of "-er" classes, e.g. CommandLoader, CommandParser. Such classes tend to behave simply as collections of functionality, rather than definitions for proper objects.

Implementation Details

A single Command class that serves two functions:

• As a template for commands defined within modules, e.g.

class PingCommand extends Command {
    constructor(client) {
        super(client);
    }

    execute(message, args) {
        ping    
    }
}

• To contain static functions relating to commands in general, not just specific instances, e.g. a getCommand(msg: Message) method that identified a command by checking for a prefix and a valid command name, and returning the name of the command to be executed, if any.

GaGBot throws `No such command` when using commands from other bots.

Description

When using commands from other bots, e.g. !d from Disboard, gagbot sends an error saying No such command 'd', instead of failing silently.

Steps to Reproduce

1. Type a command from any other bot in the chat.

Expected Behaviour

GaGBot should fail silently, ignoring the command.

`logging` module reports a message edit when an embed is added to a message containing a link (e.g an image)

Description

When a user posts a message containing a link, discord attaches an embed to the message to show the content of a link, e.g. an image, GIF or website preview. If logging is enabled for message events, this action is logged as an edit, even though there has been no change to the message content.

Steps to Reproduce

Steps to reproduce the behaviour:

1. Enable message logging with the command !log set #some-channel message
2. Send a message containing a link in a channel that the bot can read.
3. In #some-channel, an edit has been logged.

Expected Behaviour

This should not be logged as a message edit.

Context

Evidence:

Add voice channel membership tracking

Description

The bot should send a message in a specified channel when users join a voice channel, when they disconnect from voice, and if they change status (get muted/silenced, moved to AFK, and so on).

Why?

This is a useful admin tool to monitor voice activity and prevent trolling/griefing in the channels.

Implementation Details

It is unclear how other bots treat this functionality, if they do at all.
Only one new command would be required, perhaps with modifiers to disable some messages for changing status other than joining and leaving.

e.g. !voicetracking # <enable/disable> <statuschanges show/hide (default to show)>

The messages in the tracking channel could be treated as embeds like the welcome message, and would just show who has joined and when, ideally with a timestamp for ease of use.

User#0000 joined General at 12:34:56
01/01/2020

User#0000 left General at 12:34:56
01/01/2020

Include voice activity when populating prune list

Description

The most recent activity of a user, used to decide whether a user should be pruned or not, should include voice activity.

Why?

Users who are active in voice channels, but not necessarily text channels, shouldn't be pruned for inactivity.

Implementation Details

Bump the member's activity timestamp on voiceStateUpdate events.

Add user promotion functions

Description

A simple !promote function that moves users up a role ladder and associated settings.

Why?

This would enable simple access restrictions to sensitive channels and permissions like sending images, joining voice channels, etc. It would also allow for a pseudo-punishment of a disruptive user without having to mute, kick or ban them.

Implementation Details

Suggested commands:

• promote <user:User> - Move the user up the ladder one role
• demote <user:User> - Move the user down the ladder one role
• promoset add <role:Role> <level:Number> - Add a new role to the promotion list at the specified rank and shift other roles down (with 1 being the highest, and any number >= the number of roles being the lowest; default to 1)
• promoset update <role:Role> <level:Number> - Move the role up or down the list to the specified rank
• promoset remove <role:Role> - Remove the role from the list and shift other roles up
• promoset list - Show the list of promotion roles in order of rank

Add an Admin module for server management

Description

A module that adds commands such as kick, ban and purge, which enable server administrators to perform management tasks.

Why?

Server management commands are fairly essential for a general purpose discord bot.

Implementation Details

The following commands should be implemented:

• kick <user:User> - Kick a user from the server.
• ban <user:User> <reason:String> - Ban a user from the server.
• unban <user:User> - Unban a user.
• tempban <user:User> <duration:Number> - Ban a user for duration hours.
• purge <count:Number>[ <channel:Channel>] - Delete the most recent count commands from the current channel, or the channel specified.
• mute <user:User> - Instantly delete any messages sent by the user until they are unmuted.
• unmute <user:User> - Stop muting the specified user.
• tempmute <user:User> <duration:Number> - Mute a user for duration hours.
• warn <user:User> <reason:String> - Send a DM to a user anonymously warning them of an infraction of the server rules.

Add a Reaction Roles module

Description

A module that adds commands to create "reaction roles". That is, adding reacts to messages that, when clicked by a user, grant them a certain role.

Why?

Reaction roles are a staple of many moderation bots, and are generally a really useful feature.

Implementation Details:

New commands:

• rrbind <roleset:str> <channel> <message:id> - Start using a role set as reaction roles for a given message.
• rrunbind <roleset:str> - Detach the role set from the bound message.
• rrset add <roleset:str> <react:emoji> <role> - Add an emoji to a role set, which when selected will grant the given role. The role set will be created if it doesn't exist.
• rrset delete <roleset:str> <react:emoji> - Remove an emoji from a role set.
• rrset clear <roleset:str> - Remove all emojis from a role set.
• rrset update <roleset:str> <react:emoji> <role> - Change the role granted by an existing emoji in the set.
• rrset togglex <roleset:str> -Toggle whether the roles in the set are mutually exclusive or not (initially false).

Permission node for all commands will be under gagbot:reactionroles. All commands' permissions will default to false.

While a message posses at least one reaction role, users may not react with emojis that aren't already on the message.

An emoji may not be added to a role set more than once, but each may be added to more than one role set.

Kicks/bans recorded as "user left" in the log

Description

The logging records "user#0000 left the server" if a user is banned or kicked.

Steps to Reproduce

Steps to reproduce the behaviour:

1. Kick someone
2. Look at the log

Expected Behaviour

Logging should either make clear that a user was kicked in the log, or use more ambiguous language if this cannot be reliably tracked (e.g. "user#0000 is no longer in the server").

Environment (please complete the following information):

• gagbot.js as of revision #43