README.md

karma-simple

A simple, lightweight and functional Discord utility/Bot used for awarding positive or negative "Karma" to any user/keyword.

Public Bot Direct Invite: https://bot.discord.io/karmabot [scroll to the bottom of this page for support!] We'd appreciate if you could also give us a vote on DiscordBots :)

Screenshot In Action

GIF: https://i.imgur.com/hqehZjR.gif

We make sure to keep up-to-date. Although this is a small bot, we still run the same CI and build tests (as shown above). Our buildfile test includes our autoinstaller script(s). The config we use for Travis is here for anyone curious.

Installation

The bot is built for Discord using discord.js v12.0.0-dev and - for ease of access, we are including an basic install script for macOS/Linux and Windows.

Requirements:

Node version v11+ (to check your node version, you can type node --version - to update Node, you can use nvm and nvm install latest or your package manager (like apt-get or yum) to update. Because we like to stay up-to-date with things, Node v11 is required with the latest always being ideal in production. The project will throw an error if Node is below v11

Git is also required.

MongoDB or any Enmap-capable v3.x.x database is required; more on this below. This is a requirement from v2.0.1 as we switched to Enmap with MongoDB as the provider. Feel free to bug me about this if you need help: .vlexar#0001 on Discord.

npm manages the packages we need, which are found in package.json and are always kept up-to-date. This project uses discord.js v12.0-dev and requires >=Node v11.x or Node v11.x -- built with npm (currently at 6.x.x at the time of this update)

• The above which are handled by npm and/or with our macOS/Linux installer script or Windows installer script.

• The script doesn't install MongoDB or any other database for you; but I'll hopefully get to writing a documentation about that/doing it for free on Atlas shortly. There's some information below.

---

Install

macOS/Linux: Installer Script

wget -qO- https://raw.githubusercontent.com/shikhir-arora/karma-simple/master/installer.sh | bash

You may need to run this with sudo depending on your permissions! (it is likely depending on how your configuration and setups are) In that case, you should add sudo in front of the wget and before the bash otherwise the sudo action will only be applied to the download of the installer.sh file itself.

We will have super seamless update scripts - in-fact if you use the installer all one needs to do to update is git pull and we will have a way for the Botowner to do that in Discord shortly!

You will need a MongoDB URL setup. This in for Enmap. More on this below.

Windows: Installer

• Download installer.bat link here and run/open with Administrator access

• This should install the Node modules and KarmaBot files.

• Do not use this to update the bot, which can be done with a simple git pull as it will delete your old Karma files! Only use it for the initial/fresh install.

• Git and Node are required; the script will error but there will be a link provided if Node/Git are not detected.

• You will need a MongoDB URL setup. This in for Enmap. More on this below.

While we are on the npm directory and the bot can indeed can be installed via. npm in a single-pass: npm install karma-simple - which manages everything, you must be aware of where it installs, as all users need to configure config.json which links in the project. Our install-script makes sure this folder structure is kept intact by installing to a temporary directory and deleting it after.

The manual instructions below are quite straightforward.

Standard manual instructions below:

---

• Manual instruction:

• Clone the repo -

git clone --recursive --depth 1 https://github.com/shikhir-arora/karma-simple.git 

• Change directories to karma-simple and once there, run npm install to install the packages needed.

• Continue below as normal to edit config.json

Enmap w/ MongoDB Configuration

As of v2.0.0, KarmaBot no longer uses node-localStorage to store Karma. Instead, we switched to Enmap with MongoDB as a provider enmap-mongo. You can use Mongo or any of the Enmap-capable 3.x providers. It's just a few lines of switching code; please contact me if you need help with this. The change allows us to add much more capability when wanted/needed, is faster and cleaner and uses a persistent enhanced-map data structure.

You will need to either setup MongoDB (or use another database supported by Enmap 3.x persistence) or simply use a service like Atlas which provides a basic, free tier that works fine for this project if you're not hosting thousands of servers. This doesn't need much resources at all, so almost any installation will work.

I'm not going to post a detailed guide on databases or MongoDB installation as they exist out there and getting it setup isn't too difficult. Once you have set up MongoDB, you'll simply need to edit the following in karma.js:

client.karmaStore = new Enmap({ provider: new EnmapMongo({
  name: `karmaStore`,
  dbName: `enmap`,
  url: 'mongodb+srv://karma:[email protected]/enmap'
})
})

This can be found at the top of the karma.js file. Don't change anything but the URL! MongoDB URL formats are usually in the form: mongodb://user:password@IP:PORT/name and we'll call ours enmap -- in our example (no, it's not a working database), we're using a Google Compute Cluster with Atlas, and that uses the newer drivers and supports DNS seedlisting. So, our URL looks a little different. In either case, you should simply edit the URL. Save this.

That's the only switch on the user end for Enmap/Mongo! Everything else is handled in the code.

Please don't hesitate to contact me (.vlexar#0001) on Discord if you need assistance with Mongo.

Configuration (for all users!)

You must edit the config.json.example file. Insert your bot token and change the prefix if you wish to.

Save the file as config.json when complete. This can be before or after the installer script.

Admin Configuration and Eval Command (for the owner of the bot!)

Administrators should pay attention to the following parameters in the config.json file:

• ownerID: The Discord ID of the owner. Not the user or username, but the full Snowflake ID. To get this, enable Developer Mode and right click your user. "Copy ID" will output your user ID.

• adminprefix: The prefix for administrators to use the Eval command. To disable this, ignore the 'ownerID' and leave it as is. This will disable the eval command.

• The eval command is for advanced users only. It allows one to run admin-tasks by evaluating JavaScript from within Discord. I won't go into it here, because if one must ask about it, they shouldn't mess with the eval command. If you know what it is, then this should be self-sufficient.

• There is a seperate command prefix for Eval for the botowner. For example, the default prefix is >k and the default prefix for admin-eval is >>k. To evaluate code, you must type the prefix with the keyword 'eval' - so >>k as the adminprefix means >>keval [stuff] is how one would use the eval command.

• Remember, the ownerID: field must be set correctly and you must use the proper adminprefix. The bot will only respond to the ownerID with the correct adminprefix.

• Will post to Gist for overflows (errors/outputs > 2000 characters) -- token is sanitized (redacted) from Eval outputs. You'll need to setup node-gist as described here to allow GitHub to post Gists as they aren't open anymore and need a token or OAuth2 grant. See - https://gitlab.com/shikhir-arora/node-gist/blob/master/README.md

Again, contact me on Discord if you need help with this!

Admin Console (Exec) Command

• Just like the Eval command, this should be used with caution and care - you can expose your root library and more.

• It allows you to access your console from within Discord. It will post to Gist if it cannot fit the 2000 character limit. Eval will also do the same. See the above eval info about setting the Gist stuff up, contact me if you need help - you get the drill 👌

• I won't say much about this as mentioned above; if you need to ask then it's probably better/safer to avoid using the Exec/Eval features! :-)

• Accessed through the same means as Eval (above); with the adminprefix, ownerID together -- so you use the same logic as above to access the Exec command. The only difference is "exec" vs. "eval"; both use the same pre-checks.

Note To Selfhosters (API Tokens)

This can be safely ignored by selfhosters.

• You'll notice some parts of the code which have to do with pushing the public bot stats see here and here - Namely the 'guildCreate' and 'guildDelete' as well as the regular 'ready' state will post using the two functions discordBotsOrg() and discordBotsPw()

• If you have a token for these websites or wish to get one, you can - the spots where the Auth token is needed is left blank here ('') -- but please do not use the same username/avatar to avoid confusion!

• The lack of a token in the code for the API portion can be safely ignored. It will simply fail to post the stats and catch that.

nit: ^ it's actually not exactly like this anymore but I'm too lazy to update these docs for axios - if you care, please contact me!

Getting a Bot Token and Invite Link

If you have done this before, then this should be pretty straightforward. If not, go visit https://discordapp.com/developers/applications/me/create to create an application. Name the application with something you want to name it and save it - then choose "generate a Bot user" afterwords and generate the token, client ID, etc.

If you plan to give your bot to other servers, check the "Public Bot" when generating it, so others can use your invite link. Otherwise, it will only work if (you) - the person who created the bot token - invites the bot.

Save your client ID and token. They are different things! :-)

There are better guides out there, but most who would use this kind of tool likely are fine with getting this part finished. But, here is a good guide from jagrosh - this page applies for getting a token and client ID

Once you do get the client ID and token, for the invite link, if you wish I have populated a pre-made form: https://discordapi.com/permissions.html#201673792 in which you can enter your bot client ID in and it will generate the proper invite link with permissions and the bot will be assigned a role that is the name of your Bot application upon joining the server (so if you call the bot KarmaBot, it will get a role called KarmaBot with the right permissions - if that link is used)

Run

Ensure you are in the karma-simple directory!

• To run, type node karma.js (may need elevated permissions) (if this is an issue, run with sudo or sudo -H)

• Please see the section below though -

• To keep this bot running in the console as a background task so it does not stop when the console process terminates/times out, use a process manager such as pm2 (highly recommended) or a terminal multiplexer like tmux

pm2 - Strongly Recommended

pm2 can be found here: https://github.com/Unitech/pm2

You can read their quick install instructions, it takes just a minute. Please make sure you run pm2 update if you have pm2 but haven't updated in a while. It is seamless.

Once installed, instead of using node karma.js we go/cd into our same karma-simple directory and can run:

pm2 start karma.js --name "somename" where you can edit somename to call your application.

RUNNING AS SYSTEMD Once we did all this with pm2, we can have it so it will restart on things like server reboots. For Linux, systemd manages the startup tasks. Once we started the bot, we can simply run pm2 startup systemd which will take your pm2 projects and run them in the systemd for autostartup on harder reboots.

pm2 unstartup [platform]                    disable and clear auto startup    
pm2 startup [platform]                      setup script for pm2 at boot   

where [platform]=systemd,upstart,launchd,rcd   # one of these, with most Linux it is just systemd

(this step was optional re: systemd, but it is a good step to take and only is a few seconds to enable as pm2 will automate the config)

---

Usage

Add/Subtract Karma

This is a simple Discord karma app. Simply put, to add karma, append any keyword (user ID, name, or anything, even emotes) with a ++

To subtract, append the keyword with --

Only the last two ++ or -- count, so doing keyword+++++++++ or @user--------+++---- will result in keyword gaining one regular karma and @user losing one in this example. That is, the messages are cleaned before counting.

So, assuming the prefix is >k here, one can simply type:

user123++ (will add (+1) Karma to user123) or user123-- (will subtract (-1) Karma to user123) and the bot will display the following in a random color embed:

[KARMA] user123 has X Karma! To lookup later use >k and type >k user123

(where X can be positive or negative Karma count)

• Searches ARE case sensitive, so giving karma to a keyword "test" is different from "Test" (to change this, see comment in karma.js and change .trim(); to .trim().toLowerCase();)

• These values are stored in the specified folder (default "karmafiles") as binary files containing the current int karma count (positive or negative).

You can also add karma for an emoticon, :emoticonname: ++/-- if you wish; this will work as well and is stored correctly. Can be useful for specific emoticons (such as custom ones in your server)

NOTE: Because of this, if you add a user's karma with @username vs. username, it will be two different keywords to the karma counter. That is intended. It is not limited for users. Karma can be awarded to anyone, or any keyword, or even an emoji :-)

Lookup Karma

You can lookup karma by simply typing the following:

{PREFIX} {KEYWORD} where PREFIX is setup in config.json for example, >k will set the prefix to >k and keyword is simply the lookup term.

Example: >k string in the above example would return:

@user, string has X Karma!

Ratelimiting

• Ratelimiting is enabled to prevent spam. This is done with the Ratelimiter.js we have. It will just prevent spamming Karma. We allow users to give Karma to themselves, we are agnostic here! If you did something and think you should reward yourself for it, well...who are we to judge, I guess? Anyway, nothing exciting about 'abusing' it and the Ratelimiter just works to prevent spam by making it longer and longer before a user can add new Karma. (i.e. similar to the ratelimits on Discord's servers by design) -- this is not 'visible' to the user, but of course the simple code is in Ratelimiter.js - tl;dr -> if you spam a lot to KarmaBot, your user is added to a countdown which removes one entry every 3 seconds. If you accumulate more than two entries - which means ~6 seconds - the bot won't respond until the timer removes enough so you are below two [remember, it removes one entry every three seconds by default] This only affects KarmaBot, and it won't send any message or notification - rather just not respond.

Blacklist / Misc.

• By default, anyone can use Karma. This is how the vast majority of users end up using it, and it is also out of simplicity. It was also the idea to enable cross-guild Karma with a seamless user experience. As of v1.0.5, however, there is a blacklist feature which is per-guild - this requires a user with Manage Role permissions (at the minimum) to create a role called NoKarma (case-sensitive) and assign it to any user(s) - this will block the user from adding/subtracting Karma. They will get a message reply back and the bot will react with a red-circle icon to indiciate that they should talk to a mod in the server. They will be able to lookup Karma, so you can make, for example, an admin-only points system where mods have access to give Karma but users can only look up Karma. Makes a lot more sense this way and has been that way on the public bot for a while.

• We do have a stats command, which can be accessed by typing @KarmaBot stats - all of this is on the help menu as well (in-guild, @KarmaBot help) Note that the bot does not accept user-commands through DM, except for stats :-) This shows some real-time stats about the server/bot.

• If you ping the bot `@KarmaBot‘ with nothing else it'll respond with some how-to, since users often do that. (:

Support

You can reach me .vlexar#0001 (User ID: 243902693666455553) pretty easily on my Discord server: https://invite.gg/ec or feel free to always open a GitHub issue: https://github.com/shikhir-arora/karma-simple/issues or open an issue/pull-request if need be.

For users of the public KarmaBot - typing @KarmaBot help will bring up a quick and easy help menu with support/invite links and basic usage info, commands, blacklist info, etc.

Direct invite link for the public bot: https://bot.discord.io/karmabot

---

License

This project is freely distributed under The Creative Commons CC0 1.0 Universal and we give full freedom to anyone who wishes to use this little bot! You are not obligated to link back to this repo in any way. This is a stronger worded, arguably more open than The Unlicense and this project has no restrictions (and no liability from myself) - this has not changed.