Code logs are important things among developers. Since I'm not using github within my workspace this time around (bc I don't need it for hosting and I'm lazy), I'll be outlining the different versions of the bot with all changes made along the way here.
- 🐛 Bug: Bot doesn't reply to messages send in replies to others
- 📚 Libraries: Google authentication renewal
- ✨ Feature: Bot reacts to keywords,
@ everyonemessages (based on channel), attachments (also based on channel), and etc. - ✨ Feature: King oyster can now detect haikus (not perfect with syllable counting… it's just a bot afterall ;-; ). Just type a haiku and it'll jump at you if it detects it.
- ✨ Feature: Syllable counter (count syllables for any poem when prompted), to try out reply to a message and say
@King Oyster#0093 count syllables - ✨ Feature: Generate QR code, to try out use slash command or type
qr https://example.com SCALE COLOR-HEX BG-COLOR-HEX(you can leave anything after the link out of it if you want to) - ❌
Feature: Add new creative resources to King OysterBad Idea ❌ (would need constant updates) - ✨ Feature Update: Improve the inspirator, figured there's no use for the adverb in there. Use through
/inspirecommand or type@King Oyster#0093 give me some inspiration(keywords:inspire,inspiration)
- 🎩 Hosting: Improve memory & hosting
- ✨ Feature: Allow bot to welcome new members
- 🚔 Modding: Spam prevention features with bot. If the same user sends 10+ messages in the same minute, or sends a message that is detected as spam (15+ letters without a space will be detected as spam, ex: uhfkeskfksfnnksefnks), mute them for a minute. If they spam again, bot will mute again for double the time, and so on. Mute info will reset after every hour (meaning if they spam again the next hour, it'll be back to 1 minute mute and goes up from there)
- ✨ Feature: Creating reminders. Ask Oyster to remind you to do something at certain time, and it'll DM you or send a message inside the channel when the time comes.
- 🔧 Improvement: Allowed bot to notice poems in share channel (used to only react to posts with embeds)
- 🔧 Improvement: Allow user to view specific or next quote (extra parameter), and make it so that requesting new quote creates a new message rather than editing previous message (this is how it was at first but then I edited it to prevent spam and now I'm putting it back after watching recent user interactions)
- 🎩 Hosting: Migrate hosting to a micrcontroller device
- ✍️ Data: Save data from google sheets on separate file, to avoid losing data when API token requires refreshing
🔧 Improvements: Stop bot from reacting with 📜 on messages "detected" as literature anywhere outside the share channel, as it can mistake a lotta things for poems/ lit pieces.✅ DONE- ☠️ Oyster's Secret: Create Oyster's secret, one which no one would know of until the "time has come." Am I insane for adding this in? Yes. I'm a programmer after all.
- ✨ Feature: Allow King Oyster to nicely organize submissions into folders based on their genre, and even create separate threads with every submission posted or linked within (avoid attachments over 200 MB).
These documentations are written as of version V0.1.06 of King Oyster Bot, and are currently being updated with version V0.1.07.
TOC:
- Workspace
- Slash commands
- /report
USERNAMEREASONATTACHMENTS(optional) - /add-officer
USERNAME - /deadline_
- /requirements_
- /submit
TITLEAUTHORTYPEINFOSUBMISSIONLINK(optional) - /schedule_
- /officehours_
- /appointment
MONTHDATEHOURDESCRIPTION(optional) - /rules_
- /linkperm
LINK - /suggest
ACTIVITYINFO - /roll
MAX(optional) - /INSPIRE_
- /QUOTE
NUMBER(optional) - /QR-CODE
URLSCALE(optional)COLOR(optional)COLOR-BG(optional) - /REMIND-MEREMINDERMONTHDAYYEAR (optional)TIME (optional)PRIVATE (optional)
- /report
- Non-Slash Commands
- Custom Welcome Image (v0.1.07)
- Haiku Detection (v0.1.05)
- Count Syllables (v0.1.06)
- Reactions (v0.1.05+)
- Moderating
The directory is organized as follows:
Registers slash commands.
Run the following command once to register commands with a server:
node src/commands.js
Make sure to adjust the server ID in .env file.
See Slash Commands section for more info on slash commands.
The heart of King Oyster, the brain— this file contains main code for bot.
This file includes Google authentication, working with Google Drive & Spreadhseets (see renewing authentication token section), imports dependencies (see Node Packages), sets bot status, connects to quotes.txt file, listens to interactions and created messages.
Lists quotes to be used in index.js.
See /quote slash command.
A text file to save all reminders.
In the case that Oyster Bot restarts, all the reminders won't be lost since they'd be saved in this file.
TODO link reminders command here
Base for custom welcome image. Image below to the left is src/ welcome.png, and image to the right is an example of the base image being used to create a welcome message with a user's avatar, as a test. The image to the right is also saved as welcome-image.png within the directory, and adjusts accordingly based on each user.
See Custom Welcome Image section.
Note: The src/ welcome.wick is the Wick project file where I created the custom image, and can be opened with Wick Editor and edited from there.
Contains all secrets.
This file contains:
TOKEN: The bot token, aka the Oyster's password.GUILD_ID: The Discord server ID. Useful when registering slash commands with a new server.CLIENT_ID: Oyster's user ID, not very important and I probably don't use.DRIVE_API_KEY: Google Authentication API key.DRIVE_CLIENT_ID: Google authentication client ID.DRIVE_CLIENT_SECRET: Google authentication secret, aka the password for the authentication process.DRIVE_REDIRECT_URI: Redirecting URI to authentication link for handling API requestDRIVE_REFRESH_TOKEN: Authentication token. May need to refresh after updating bot. See src/index.jsDRIVE_FOLDER_ID: ID for google drive folder. We don't use this one really in the code– but might be useful in later versions. ID derived from directory url.DRIVE_FOLDER_ID_1: Writing submissions folder ID; derived from directory url.DRIVE_FOLDER_ID_2: Visual submissions folder ID; derived from directory url.DRIVE_FOLDER_ID_3: Audio submissions folder ID; derived from directory url.DRIVE_FOLDER_ID_4: Video submissions folder ID; derived from directory url.DRIVE_FOLDER_ID_5: Other submissions folder ID; derived from directory url.SPREADSHEET_ID: Spreadsheet file ID, used for information on room number, meeting times, office hours, deadline, etc. Derived from spreadsheet url.
package.json contains version number of dependencies, while package-lock.json includes more info on packages used, connecting back to node_modules directory, which includes all the packages used in the project.
Setting up NPM steps included in Setting up Workspace section.
See Node Packages section.
See Workspace to get an idea of how to setup the directory. This tutorial assumes that you have NPM v22+ and git installed on your device.
If not, you can follow this quick guide to install git and clone this respitory with this command
git clone https://github.com/Alani25/OysterBot.git
or you can manually download the files from this respitory (which would be a better option if you don't have expierence with git).
However, you will still need to install Node JS to use the DiscordJS library and other required packages.
An IDE (Integrated Development Environment, aka a code editor) would also be required to edit the code, in which case I would recommend VS Code.
After install the code, either using git clone or by manually installing the zip file and unzipping it, you should find these files inside of the version folder.
Note that the version used in this tutorial is v0.1.06, but you might be working off of a different version. If there are any other files or versions outside of the directory feel free to remove them.
Next step should be simple— first make sure your Node version is up to date by running
node --version
Node version v17+ is recommended.
Next, change directory into the version you would like to use. Would recommend doing a quick ls to view all version installed, in this tutorial we'll be going into V0.1.06 but I would recommend working with the latest version of the bot available. Same steps would apply for all versions.
cd V0.1.06
npm install
Preview in terminal:
Now if you've never touched a terminal before you might be confused. In which case, I would recommend you to install the VS Code IDE I mentioned earlier, and open the version folder there instead. After opening the bot folder there, you should find a terminal at the bottom.
If you don't see the terminal, move your cursor closer to the bottom of the editor, and try to drag up the terminal window.
You should be able to run npm install inside of the terminal window, without needing to change directory with cd V0.1.06 if you opened the version folder inside VS Code.
Your main code should be inside of the index.js file. You will also need to create a .env file, see the .env file section for an idea on what to include inside of the file.
Note: you will need to know how to aquire the different tokens that are used in the .env file in order to create your own.
If you're planning on updating King Oyster's code… well, first off hey there future C&K officers, I can't believe you're actually reading this!! And second off… you can either contact me for the files or see if I've left it behind for you somewhere, unless if you have expierence programming bots and would like to get them on your own, in which case head over to the Google authentication playground for developers, Google Cloud Console, both which I'll explain later on, Google Drive & Sheets (obviously) and the Discord Developer Portal.
For the Google Spreasheet, make sure to also use this Spreadsheet as reference. Most of everything else would rely on the code, and in which case if you are trying to update things I would hope that you understand some coding… if you don't, then god help you cause you'll sure be in for a lotta fun.
Back on topic, once you're all set with everything, you should be able to start the bot by running the command
node src/index.js
Alternatively, I'd like to also recommend running the bot with either nodemon while testing, or pm2 if you'd like to keep the bot alive 24/7 in the background of your computer. There are additional steps to that in the case that you'd want to keep the bot alive while the computer is sleeping, in which for I'd recommend using Amphetamine or a real bot hosting service if you're not a psycho, such as lunes. I will give you a warning though, when using a bot hosting service, the service providers might be within a different time zone, which could mess up dates and such. This is not always the case, but do watch out for that.
If you run the bot, and get something in the console that says
Error reading spreadsheet: invalid_grant
Google APIs won't work. In other words, google drive & spreadsheet connections won't happen…
plz visit https://developers.google.com/oauthplayground using approved google account and see codes inside of .env file
First thing you should do is thank me for the detailed warning. Next up, follow the steps given.
Head over to the OAuth 2.0 Playground, and under step 1, search for and check https://www.googleapis.com/auth/drive for Google Drive authentication (under Apps Script API V1 or Drive API v3), and https://www.googleapis.com/auth/spreadsheets.readonly for Speadsheets authentication (under Area120 Tables API v1alpha1 or Google Sheets API v4).
Second step, select the gear icon and make sure to add in your OAuth Client ID and Secret ID.
I cannot show these tokens publicly as they can be misused, but you can obtain them from the Google Cloud Console, which if you're a part of C&K then I recommend logging in through the C&K Gmail to obtain these codes without much trouble. If you're not, then I would recommend following this youtube tutorial to connect your bot to Google's APIs.
Lastly, select Authorize APIs
You would be prompted to log into a google account, and allowing certain permissions.
You should use the C&K google account, or an account that has been set up under Google Cloud Console.
Once you complete the process, you should find yourself on step 2 of the OAuth 2.0 Playground (if it skips to step 3, then click step 2).
Click Exchange authroization code for tokens, and then copy the refresh token. This is the token that you will define inside the .env file, under the variable name DRIVE_REFRESH_TOKEN.
And now, once you run the bot again, you should not see the invalid_grant error.
Node Packages are outside libraries imported into our code to assist with specific tasks. The libraries have been installed through NPM. You may run npm ls to get a list of all current node packages, or npm outdated to search for any outdated packages.
DiscordBot
├── [email protected] Creating HTTP requests
├── [email protected] Used for creating custom images.
├── [email protected] Main Discord bot library.
├── [email protected] Working with environmental variables.
├── [email protected] Fetching url contents (UNUSED PACKAGE?)
├── [email protected] Used for reading file within directory.
├── [email protected] Used for Google authentication & connecting to Google tools.
├── [email protected] Used for running commands at specific times.
├── [email protected] Assists with tracking file paths.
└── [email protected] Generate & work with QR codes.
Slash commands are a list of pre-defined commands that can be used to interact with the bot.
These commands can also come with different input parameters accordingly (see src/commands.js).
To start using commands, all you need to do is start typing a message with the character /, then you can select the command you wish to use.
The purpose of each command is listed below.
Report USERNAME for REASON, and optionally attach ATTACHMENTS as proof.
If the USERNAME (being reported) is an officer, then the bot will let the user know that they might've made a mistake.
Despite this, the report is still send. When a report is send, the bot will search for a channel with the name bot-reports. If this channel doesn't exist, the bot is smart enough to create it, while restricting access to it by regular members (allowing only officers to view it).
The report will include the USERNAME display name and user ID, along with the user's username, their REASON, and an ATTACHMENT if provided.
In the case that the user (sending the report) was an officer, then the USERNAME will be automatically muted for 10 minutes after the report is send.
Command to give the officer role to a member. User must be an officer to be able to use this command.
✅ If the user is an officer, then USERNAME will be assigned an officer role.
❌ If the user is NOT an officer, they will be notified that only officers are able to run this command.
This command will inform the user of the C&K magazine submissions deadline, along with a countdown.
Button interactions can lead user to submission requirements, or the submissions form.
Can be activated through chat messages by replying to or mentioning
@King Oyster#0093, using keywords:
deadline or submission AND EITHER time OR when
This command will inform the user of the C&K magazine submissions' requirements.
Button interactions can lead user to deadline, or the submissions form.
Can be activated through chat messages by replying to or mentioning
@King Oyster#0093, using keywords:
submission or requirements
Submit a piece to the magazine.
The SUBMISSION file will be sent to Google drive, along with other submissions (if Drive isn't working, see Renewing Authentication Token section).
Before being send into the drive, the submission will be sorted into different folders based on the chosen TYPE:
- Writing
- Visual
- Video
- Audio
- Other
The SUBMISSION file will also be renamed into the title of the piece, followed by an underscore and the default file name.
Nevertheless, in case our bot faces issues submitting the piece to the drive, and as a backup, Oyster automatically sends all submissions in a separate, private channel, called "bot-submissions." This will include the user's username, the piece's TITLE and AUTHOR (name published under), all hidden behind spoilers, along with the submission TYPE, extra INFO, a LINK if included, and obviously the SUBMISSION if attached.
It's unlikely that the bot would ever have issues with uploading the SUBMISSION, unless if the SUBMISSION is very large in size. To prevent issues, we stop the bot from sending an attachment of the SUBMISSION in the bot-submissions channel if it's over 200 MB in size! The bot would still attempt to upload the file to google drive, in which it should succeed but at a slower rate. This is a rare case in which we'd advise to use the LINK option to share your piece (and for SUBMISSION you can submit a simple thumbnail).
Note: If the bot-submissions channel doesn't exist, the bot is smart enough to create it and set permissions accordingly.
This command will inform the user of the meeting time and location of our regular C&K member meetings, along with the exact meeting time of the next meeting.
Can be activated through chat messages by replying to or mentioning
@King Oyster#0093, using keywords:
schedule or meet AND time or when or where
🐛 Note: Sometimes the hosting service could have a different timezone and mess up deadline times and such since I'm working with literal timestamps, which sucks. I'm currently hosting locally but that's an issue to look out for. Now I can see why most discord bots don't use timestamps, I guess I made more work for myself.
Get the location and time of our office hours for the semester.
This command connects to a Google spreadsheet, where officers can input their office hours times without needing to touch the code.
Same case for infortmation included in the deadline and schedule commands.
Can be activated through chat messages by replying to or mentioning
@King Oyster#0093, using keywords:
officehours or office hours or office-hours
Set an appointment to meet with an officer in MONTH, DATE, at HOUR. The appointment is then treated as a report, and will be send to the reports channel for an officer to check (see /REPORT ... command). Along with the user info and appointment time, the report will also include the DESCRIPTION. As a matter of fact, the bot response send privately to the user is identical to the report the officers recieve (see image below).
Command will help the user find the server rules.
The bot will also give the user the option to navigate to the Discord Guidelines or view MCC Policies with the click of a button.
Can be activated through chat messages by replying to or mentioning
@King Oyster#0093, using keywords:
rules
Request permission to post links.
This will send a report to the same bot-report channel used by the /report... and /appointment... commands.
The request will look as follows:
To accept, after reviewing the link, a mod, aka officer, can give the user a @link perm role.
This role will allow the user to post links without being stopped by the bot.
Please note that certain links, such as youtube and tenor urls (GIFs) are allowed without needing link perms (see allowedLinks array in code).
Suggest an ACTIVITY for us to do during our weekly member meetings, along with extra INFO on how the activity works.
Similar to report..., /appointment ..., and /linkperm ... commands, this command will send the suggestion as a report in the bot-reports channel in the format shown below.
Roll a dice and get a random number. Optionally, you can adjust the range of possible values from the roll by adjusting the MAX sides of the die.
Get a random adjective and noun to help spark some inspiration ✨
Don't like what you see? Click Sprinkle More Inspiration and King Oyster will edit the message to add more inspiration on top of what's already there.
Note: See getRandomInspiration(...) function in code, noun and adjective variables.
Can be activated through chat messages by replying to or mentioning
@King Oyster#0093, using keywords:
inspire or inspiration
Wanna feel some wisdom? Then get a random quote from a set of 40+ pre-selected quotes (saved in quotes.txt file, quotes are separated by three new lines).
If you choose to input a NUMBER then you'll get a quote that corresponds to that number rather than a random one.
Each generated quote is followed with three buttons. Two arrows to cycle through previous and next quote, and a Random Quote button, which gives you a new random quote in a new message.
Can be activated through chat messages by replying to or mentioning
@King Oyster#0093, using keywords:
quote
Have Oyster generate you a QR code that redirects to URL, along with a few optional inputs, such as SCALE of the QR code image (default: 20), and the COLOR of the QR code (HEX code recommended), and COLOR-BG for the QR code background (transparent by default).
See image below for an example of how QR code can be generated WITHOUT using the slash command, but rather by sending a text message.
Note: In the image above, I could've also included the COLOR-BG at the end, but chose not to so the background defaulted to transparent.
The slash command works the same way as the text command, except if you generate a QR code with the slash commands, the message is hidden and can only be viewed by you.
Can be activated through chat messages by sending a message that
STARTS WITHqr
Ask King Oyster to reminder you about REMINDER, in the given MONTH / DAY.
You can also optionally specify YEAR (optional) and TIME (optional).
You can also set PRIVATE (optional) to True to make Oyster send you a private reminder in your DMs.
Note: This slash command was added recently in v0.1.07, and is likely to be updated in later versions.
To make the bot feel more lively and noticed, we need it to react and interact with the community without being tasked to.
For this reason, I have added a set of interactions for the bot. Some of these interactions might still be considered commands, but most could happen unexpectedly.
King Oyster greets all new members with a welcome message, and the new user's avatar as part of a custom welcome image.
See src/ welcome.png file.
King Oyster automatically checks all send messages in search of a 5-7-5 syllables haiku pattern. If it finds a message that meets this critera, it'll reply with the following message:
Note: You don't need to send a massage with multiple lines for Oyster to find the haiku
Of course, the syllable counter method by King Oyster isn't perfect since it's only a bot. For us humans, it's as simple as counting how many times our chin drops when saying a word, but for a bot… well… it's more difficult to program the logic for that, so expect some flaws here and there. I'd say it's close to accurate but not fully there yet.
When asked to, King Oyster will count the syllables inside of a poem.
See image below for usage.
Keywords: count AND syllables
I was considering making a whole new section for this part but figured might as well keep it a part of this.
King Oyster will react to different messages based on keywords, name of the channel they're send, mentions, and such.
For example, if you say "important" in your message then king oyster will try to emphasize your message
Personally, I would advise against reading the rest of this section, as knowing when and what Oyster reacts to would ruin the magic, but I won't stop you if you're curious.
Enough blabber, here's a table—
| Emoji | ID | Keywords | CHANNEL KEYWORD | INCLUDES |
|---|---|---|---|---|
| 💚 | X | X | "announce" | @everyone |
| 💚 | X | "love" or "thank" AND "oyster" |
X | X |
| 💚 | X | "thank" | X | @King Oyster |
| X | "important" | X | X | |
| 📜 | X | X | X | *5+ LINES |
 |
1334234382772207696 | X | NOT "anounce" | @everyone |
|
1334234382772207696 | X | "share" | ATTACHMENT or *5+ LINES |
 |
1334609229599739976 | X | NOT "share" | ATTACHMENT |
 |
1334609056421249186 | "boba" | X | X |
 |
1334608848513798155 | "origami" | X | X |
 |
1334609780097945733 | "oops" OR "uhoh" | X | X |
📜 *5+ lines: check if message has 4+ line breaks, meant to help detect poems.
This is fun and all, but gotta remember that a main reason for Oyster's creation was to help in moderating the server in cases where the mods might not be online.
This section has been added in version v0.1.07.
If the same user sends 10+ messages in the same minute, or 15+ letters without a space will (ex: uhfkeskfksfnnksefnks), Oyster will mute them for a minute.
If they spam again, Oyster will mute again for 2 minutes, and the time will keep doubling. Mute info will reset after every hour (meaning if they spam again the next hour, it'll be back to 1 minute mute and goes up from there)
Note: King Oyster cannot mute users with equal or higher permissions than him. Meaning if I'm an admin, then Oyster cannot mute me. Of course, if I'm an admin, spamming is the least dangerous thing I could do 😅
If a user without an officer or link role attempts to post a link that is not a tenor (GIF) or youtube URL, then Oyster deletes the message immediately and sends a private message to the user, telling them to ask for permission before sharing a link in the club.
To allow someone to post links, you'll just need to give them the link perm, or a role in the server with the word "link" (make sure you don't have multiple link roles in the channel).
As long as someone has the link role, they should be able to post links without Oyster stopping them.
You can also edit the URLs that Oyster allows by defeault by editing the allowedLinks array inside of the src/ index.js file.