en3sis / hans

An open-source, modular Discord bot template. Built with Discord.JS & TypeScript

🤖 Hans - Discord Bot

Hans is built with a modular architecture that makes it easy to add and remove functionality on the fly, empowering you to create a bot tailored to your community's needs.

Built with Discord.JS, TypeScript, and lots of ❤️

Invite to server

Bring Hans to your Discord server and start using his available features immediately here 🔗. It uses the latest hans:nightly image with the latest features.

The list of commands & plugins can be found here 🔗

Developing Hans

🪬 NOTE: Please consider opening an issue and PR for bugs, suggestions, or new features.

---

🔅 Prepare environment

Before running any command, run npm install && cp .env.template .env, and fill in all the env variables needed. To create your application, visit Discord's Developer Portal

🪬 IMPORTANT: A Supabase instance is needed for the bot to work. A free cluster should be more than enough (even for small bots & communities) for development.

Supabase Local Development.

Supabase is used for storing the bot's configs, guilds, and users.

You can work with supabase local, follow the instructions here 🔗. Once you run supabase start the local Supabase will be populated with the latest schema (have a look at the supabase/seed.template.sql file for more configuration)

More information related to working with Supabase local development can be found 📹 here 🔗

👩🏼‍💻 Development

Once the Prepare environment section is done, you can follow along with the development.

npm run dev

It will start a development server with ts-node and nodemon for live-reload. A bot Invite link will be displayed in the console.

Slash commands

All commands (under src/commands) are built with the Slash Command interaction.

🪬 IMPORTANT: before developing commands, make sure you invite the bot to your server and the entry in Supabase configs -> bot_guild_id is your guild_id.

All commands under the main folder are available globally (it will take a second to have them available) while the ones under bots-playground/ are guild-specific and are instantly deployed, use this folder for debugging & development purposes.

To deploy the commands: npm run slashDev or npm run slash in production.

---

🧪 Unit Tests

For testing, we use Mocha with TS.

All the tests are under the /tests directory. Right now they're none or a few, we should add more test coverage for command controllers.

npm run test

Will run all the tests.

---

🏗 Production

We have multiple environments for deploying your bot.

With Docker

You can either use the pre-built Docker image from DockerHub at en3sis/hans:latest or build your own locally using the command docker build -t en3sis/hans .

To run the container, use the command docker run --env-file .env --name hans -d --restart=always en3sis/hans:latest while making sure that the .env file is in the same directory as the command and contains all the necessary environment variables for the bot to function properly. You can also run it with docker-compose using the command docker-compose up -d --build bot.

Note: for M1 Macs, you'll need to use docker-compose build --build-arg M1=true before running the docker-compose up -d.

Locally

You can also run the bot locally using the following commands:

🪬 IMPORTANT: Follow the Prepare environment section.

npm run build

To generate the application's build.

npm start

It will run the bot with the production environment.

With Kubernetes (WIP)

💢 NOTE: This is a WIP, it's not fully tested yet, things are missing. Please feel free to contribute.

It's also possible to deploy the bot to a Kubernetes cluster, the necessary files are in the k8s folder.

Steps:

1. You'll need your K8S cluster, ofc ;P
2. Create the namespace kubectl apply -f k8s/namespace.yaml
3. Run cp k8s/secrets.template.yaml k8s/secrets.yaml, fill it up and apply the secrets kubectl apply -f k8s/secrets.yaml
4. Deploy the workload kubectl apply -f k8s/deployment.yaml

hans's Issues

[FEATURE] using winston.js as loger

📝 Is your feature request related to a problem? Please describe.

A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
NA

🧬 Describe the solution you'd like

A clear and concise description of what you want to happen.

Right now we have some console.log to catch HTTP requests errors and so.
We want a better way to handle those errors, one idea would be using having a look at Winston (or some other alternatives)

👩🏼‍💻 Additional context

Add any other context or screenshots about the feature request here.

It would be also nice to have some wrapper for debugging, for example, having logs that will only show on ISDEV=true

[BUG] messageUpdated event

📝 Describe the bug

A clear and concise description of what the bug is.
Not sure if there was a change in the API, but the messageUpdate:oldMessage response seems to always be undefined

🧬 To Reproduce

Steps to reproduce the behavior:

1. Start your bot.
2. Make sure your development guild has the MongoDB document for messageUpdate: true & messagesAlterations: { logChannelId: 'YOUR_CHANNEL' } set.
3. Send a message in any chat
4. Edit the message
5. If you console.log the oldMessage (src/events/messageUpdate.ts) it the content is undefined

🔅 Expected behavior

A clear and concise description of what you expected to happen.

It should show the old message content & author should be present, but they're null.

🌠 Screenshots

If applicable, add screenshots to help explain your problem.

👩🏼‍💻 Additional context

Add any other context about the problem here.

Not sure if there was a change in the bot permissions level.

[FEATURE] Disallow commands globally

📝 Is your feature request related to a problem? Please describe.

If we deploy a command with some bugs, we need to redeploy the bot in order to fix it.

🧬 Describe the solution you'd like

Add an array with disabled commands so we can do it from Hans configuration. In this case if something goes wrong, we have the force stop.

👩🏼‍💻 Additional context

Reduce time for `/events`

After adding the new plugin for /events, I notice that in servers with many events & users, the command is slow.

Possibles causes:

• https://github.com/en3sis/hans/blob/main/src/controllers/plugins/events.controller.ts#L11
• https://github.com/en3sis/hans/blob/main/src/controllers/plugins/events.controller.ts#L15

Since the participants are not part of the GuildScheduledEvent and we need to fetch them for each event, that seems to be a heavy computation, we might be able to improve this by further checks and exceptions.

[FEATURE] `sentimentAnalysis` plugin

📝 Is your feature request related to a problem? Please describe.

We have the functionality, we just need to move it to the new plugin architecture.

🧬 Describe the solution you'd like

• It should trigger on messageCreate
• It should be part of the moderation category
• It should allow setting a channel where to send the analysis and inform of negative/positive messages

👩🏼‍💻 Additional context

[FEATURE ]Generic /config command for guild configuration

🧬 Details

Right now a user cannot enable plugins without editing the DB directly. This will be a multiple steps tasks.

Step 1 :
We need to create a slash command called /moderation.
Requirements:

• It should only be allowed to be used by the guild owner
• It should provide multiple options, preferably plugin specific (check /src/controllers/plugins)

Moderation plugins:

• sentimentAnalysis
• messagesAlterations

[FEATURE] Standup Plugin improvements

📝 Is your feature request related to a problem? Please describe.

I'm currently implementing a new plugin for Standups with limited functionality (Monday - Friday at a given hour, single channel)
This Issue is to have a follow-up and improve it.

🧬 Describe the solution you'd like

• Allow creating multiple standups per guild (metadata[{standups}])
• Command that shows all standups and an option to stop/remove a given standup.
• Move everything to it's command (/standup)? This might require thinking, maybe we can rework the plugins/commands functionality.

👩🏼‍💻 Additional context

[FEATURE] free use of `chatGpt` limits per server

📝 Is your feature request related to a problem? Please describe.

Right now only guilds labeled at premium can run the /ask command and without limit. Server admins can add their own api key.

🧬 Describe the solution you'd like

Besides the current functionality, we want to allow a ~50 commands per guild per day for free, above those usages, they'll have to add their own API key if more requests are needed.

• Show remaining usages on the response.
• Maybe we want an rpc that will reset the remaining commands every night at 00:00

[BUG] ThreadChannel

📝 Describe the bug

Adding a new channel object to the the threadChannels document doesn't seem to work

🧬 To Reproduce
Having multiple elements in the array's documents won't make all of them work, only the first one

🔅 Expected behavior
It should create a new thread in threadChannels[1].threadChannelId

🌠 Screenshots

👩🏼‍💻 Additional context

[FEATURE] Self role

📝 Is your feature request related to a problem? Please describe.

🧬 Describe the solution you'd like

1. Have a subcommand for /moderation related to user self role where an Admin can select multiple roles from server roles.
2. It should take @roles, channel, description where channel = channel for the message to be posted and description as message.content
3. Create a new message, having each role as a button.
4. This should be a new plugin called selfRoles

Notes: We need to figure out how and when we edit the message with the roles when we add/remove roles from the list.

👩🏼‍💻 Additional context

[FEATURE] `giveaway` plugin

📝 Is your feature request related to a problem? Please describe.
We want a solid giveaway system

🧬 Describe the solution you'd like

• new table for guilds-giveaways
• a new plugin and the command for it
• we should be able to specify title, description, ending date, allowed roles(?), active
• a button to join the giveaway
• functionality to randomly choose a participant when the event ends (this will require to get the cronjob on the bot or supabase side)
• when it finishes, maybe we can create a thread to the giveaway message where the winner is announced

Note: We add before a full-automated delivery system where we could set the reward (cd key for example) and it would be sent as DM to the winner. We could make use of the encrypt/decrypt functionality to store sensitive data if auto-delivery is enabled

👩🏼‍💻 Additional context

[FEATURE] introduce Mongoose / To be filled

📝 Is your feature request related to a problem? Please describe.

🧬 Describe the solution you'd like

👩🏼‍💻 Additional context

[FEATURE] Sharding

📝 Is your feature request related to a problem? Please describe.

Currently, Hans does not need sharding since it's way below the minimum requirement (guild presence) but if a forked bot requires it, Shading has to be implemented.

🧬 Describe the solution you'd like
Implement Shading: https://discordjs.guide/sharding/#sharding-file

[FEATURE] MongoDB -> Supabase

👩🏼‍💻 Additional context

While MongoDB works well, I want a more robust solution.
I was playing around with Supabase for a few days now and seems to fit perfectly.
I'll gradually move the core functionality then the Plugins section

[FEATURE] Reddit new messages notifications

📝 Is your feature request related to a problem? Please describe.
NA

🧬 Describe the solution you'd like

They're many cool subreddits whit excellent content, one of them being https://www.reddit.com/r/FreeGameFindings where people post free games.

New functionality scans the subreddit every n minutes and, If a new post makes it to new sections, notify it to a given channel.

AC:

Plugin part
As part of #15

• Should fetch the latest post
• A new database called Plugins with a collection reddit and the document with the data structure.
• Should check in the collection to see if it was already notified (in the document)
• Allow multiples guilds to subscribe to the same document
• Iterate over the list of subscribed guilds and send it to the channel

Command part
As part of #20
To enable it:

• Add a command to subscribe to a subreddit, it will create a new document in the collection (/reddit -> Subredit* -> ChannelId?* = required | ? = optional)
• It will create a new channel in the discord with some {title} where it will initialize the notifications
• It will re-post the latest post in the channel.

Document Template

{
  subReddit: 'javascript',
  description: 'The programming language of the web',
  latestPostId: 'foo_bar',
  subscribedGuilds: [
    {
      guildId: '123456789',
      channelId: '123456789',
    }
  ]
}

👩🏼‍💻 Additional context

[FEATURE] Plugins structure

📝 Is your feature request related to a problem? Please describe.

Right now the Plugin configuration works well but it can be improved.

🧬 Describe the solution you'd like

• Replicate the slashCommand folder structure and dynamic loading
• Stores plugins in their own table in Supabase, depending on #37