Merge pull request #14 from nakajimayoshi/contributing-docs

docs/refactor: add command & contributing docs, standardize makeEmbed

.github/CHANGELOG.md

@@ -1,5 +1,7 @@
 # May 2023
 - feat: (05/25/2023): Add new role handler, update gpt command, changelog
+- fix: (05/26/2023): Fix permissions loophole in 'roles' command
+- docs: (05/26/2023): Add contributing guide, update readme, changelog
 
 # March 2023
 - feat: (03/07/2023): Integrate slash command api & new cowsay command

.github/CONTRIBUTING.md

@@ -1,3 +1,139 @@
-# OWDDM Discord Bot 
+# Contributing Guide
 
-Thanks for your interest in making 
+Please reference the information below when contributing to this repository.
+
+## Welcome
+
+Welcome to the OWDDM bot repository. Thank you for your interest in contributing to the project. Full details and guidelines on how to ensure this project is managed are included below.
+
+## Helping others
+
+Please help other contributors to the project wherever you can, as people all start somewhere. If you require assistance or wish to provide assistance you can ask/answer questions in the [Discord Server](https://owddm.com/discord).
+
+## Prerequisites
+
+- [node](https://nodejs.org/) version >= 16.x
+
+## Ground Rules
+
+To ensure that commands are written professionally and clearly, please follow the guide below:
+
+- Use the proper name for third party services.
+- If you are using images within the command, please ensure that they are clear and easy to understand.
+- Refrain from using exclamation points unless it is a warning.
+- Ensure that the contents of the command are correct. If you are unsure if something is correct please speak to any volunteer, and they will be able to verify.
+- Ensure that grammar and spelling is correct.
+
+## Pull Request Process
+
+Reminder: When submitting a pull request, please ensure you target the `staging` branch.
+
+1. Fork the repository.
+2. Clone to your local system using your IDE of choice.
+3. Make a new branch from staging and name appropriately (e.g. feat: added database command, fix: typos fixed in README).
+4. Create/edit the command you are working on.
+5. Test your build locally.
+6. Create a PR to merge your changes into staging.
+
+Note: It may be beneficial to create a draft PR while working on your command. This will allow us to see who is working on what, and will enable the community to give active feedback on your work.
+
+## Pull Request Template
+
+You can find the pull request template [here](PULL_REQUEST_TEMPLATE.md).
+
+## Setting up the Bot
+
+1. Log into the Discord website and navigate to the [applications page](https://discord.com/developers/applications).
+2. Click `New Application`.
+3. Give your application a name.
+4. Navigate to the `Bot` tab and click `Add Bot`. You will have to confirm by clicking `Yes, do it!`.
+5. Click the `Copy` button underneath token. (Do not share this).
+6. Copy the `.env.example` file and rename it to `.env`.
+7. Inside the .env file, type `DISCORD_TOKEN=TOKEN` replacing TOKEN with what you copied in `step 6.`
+
+## Setting Up Privileged Gateway Intents
+
+Privileged Gateway Intents must now be enabled within the Discord Developer Portal in order for your bot to function. The steps below will explain how to enable them.
+
+1. Log into the Discord website and navigate to the [applications page](https://discord.com/developers/applications) and select your application. Then select `Bot` under `Settings`
+2. Scroll down to the Privileged Gateway Intents section and enable all the intents.
+
+### Inviting the Bot to Your Server
+
+1. Create a Discord server where you can test your bot.
+2. On the [applications page](https://discord.com/developers/applications), select your application and navigate to the `OAuth2` tab. Then select `bot` under the `scopes` section.
+3. Tick `Administrator` box under the `Bot Permissions` section.
+4. Click the `Copy` button and paste it into your search bar in the browser of choice, and invite it to your test server.
+
+## Running the Bot
+
+1. Run `npm install` to install the dependencies.
+2. Run `npm run dev` to start the development build.
+
+## Tokens
+
+Some commands may require additional tokens. If you would like to test them out on your bot, you must include the tokens inside your .env file. (E.g. working with the 'chat' command)
+
+## Adding a New Command
+
+>Please note, this will only show the basics of adding a command.
+
+1. Create a new file in the relevant folder within `src/commands/` and name it appropriately. `yourcommand.ts`.
+2. Create your command.
+3. Add it to `src/commands/index.ts`. You need to add the line `import { name } from './commandfolder/filename';`, replacing `name` with the `export const` from your command, `commandfolder` with the relevant folder your command has been placed within, and `filename` with the file name you created in `step 1` (Add this below the last command).
+4. Add changes to `.github/CHANGELOG.md` and add command to `.github/command-docs.md`.
+
+If you need help creating a command, you may find it useful to copy an existing command as a template, changing what you need.
+
+Please ensure that the command category is appropriate for the command. You can find what each category means in `src/lib/constants.ts`. For example, a command used for support would use the `SUPPORT` category.
+
+> ### Considerations
+>
+> - Choose user-friendly command names.
+> - Test your build locally before submitting as ready for review.
+
+## Modifying a Command
+
+1. All you need to do is open the command you wish to edit in `src/commands/` and edit what you need.
+2. Add changes to `.github/CHANGELOG.md` (and `.github/command-docs.md` if necessary).
+3. Commit and Push.
+
+## Example Slash Commands
+
+For commands that need to respond with a message (no complex logic), take a look at a command that is based on the `CommandDefinition` interface. This interface is specifically designed to minimize the effort of creating these types of commands.
+
+The basic structure of such a command looks similar to this example:
+
+```ts
+import { CommandDefinition } from '../../lib/command';
+import { CommandCategory } from '../../constants';
+import { makeEmbed } from '../../lib/embed';
+
+const genericCommandEmbed = makeEmbed({
+    title: 'Command Title',
+    description: 'A simple message that is returned when the command is executed.',
+    fields: [ // optional
+        {
+            name: 'field name',
+            value: 'value of field',
+            inline: false, // or true
+        }
+    ],
+    image: { url: 'URL to image to show' }, // optional
+});
+
+export const command: CommandDefinition = {
+    name: 'command',
+    description: 'A short description of the purpose of the command.',
+    category: CommandCategory.GENERAL,
+    interaction: async ({ interaction }) => {
+        await interaction.reply({ embeds: [genericCommandEmbed] });
+    },
+};
+```
+
+In the above example, you should change the following:
+
+- `const genericCommandEmbed`: Replace `Command` with a proper unique name for your command. Also update the `title` and `description`.
+- `export const command`: Replace `command` with the same proper unique name for your command. Also update the `name` of the command with the proper command and aliases.
+- `genericEmbed: genericCommandEmbed`: Replace `Command` with the same unique name for your command as in the actual `const genericCommandEmbed`.

.github/command-docs.md

@@ -0,0 +1,20 @@
+## Bot Commands
+
+### General
+
+| Command | Description           | 
+|:--------|:----------------------|
+| /chat   | Interact with chatgpt | 
+
+
+### Memes
+
+| Command | Description                               |
+|:--------|:------------------------------------------|
+| /cowsay | emulates the famous UNIX program 'cowsay' |
+
+### Moderation
+
+| Command | Description                                                                                         |
+|:--------|:----------------------------------------------------------------------------------------------------|
+| /roles  |                                                                                                     |

src/commands/general/chatgpt.ts

@@ -44,14 +44,14 @@ export const chatgpt: CommandDefinition = {
                 messages: [{role:'user', content: input}],
             });
 
-            const responseEmbed = new EmbedBuilder({
+            const responseEmbed = makeEmbed({
                 title: input,
                 description: response.data.choices[0].message?.content,
                 footer: {
-                    text: 'https://openai.com',
+                    text: 'Model provided by OpenAI',
                 }
             })
-            
+
             await interaction.followUp({embeds: [responseEmbed]});
 
         } catch (error) {

src/commands/moderation/role_assignment.ts

@@ -5,15 +5,15 @@ import {
     PermissionsBitField, Message,
 } from 'discord.js';
 import { client } from '../../index';
-import { CommandDefinition } from '../../lib';
+import {CommandDefinition, makeEmbed} from '../../lib';
 import { CommandCategory, ResponseType, techRoles, regionRoles } from '../../constants';
 
-export const regionEmbed = new EmbedBuilder({
+export const regionEmbed = makeEmbed({
     title: '🗾 Where in Japan are you based?',
     description: 'Select an item from the dropdown menu to select a region role'
 }).toJSON()
 
-export const techEmbed = new EmbedBuilder({
+export const techEmbed = makeEmbed({
     title: '💻 What technologies do you use?',
     description: 'Select an item from the dropdown menu to select a tech role'
 }).toJSON()

src/handlers/role.ts

@@ -1,4 +1,4 @@
-import Logger from '../lib';
+import Logger, {makeEmbed} from '../lib';
 import {
     ActionRowBuilder,
     EmbedBuilder,
@@ -9,7 +9,7 @@ import {
 import { regionEmbed, techEmbed, createMenu } from '../commands/moderation/role_assignment';
 import { regionRoles, techRoles, Channels } from '../constants';
 
-const errorEmbed = new EmbedBuilder({
+const errorEmbed = makeEmbed({
     title: 'Error',
     description: 'Please wait for the interaction to finish before re-selecting',
     color: Colors.Red,

src/lib/embed.ts

@@ -1,17 +1,10 @@
 import { EmbedBuilder, EmbedData, Colors } from 'discord.js';
 
 export function makeEmbed(embed: EmbedData): EmbedBuilder {
-	const embedBuilder = new EmbedBuilder()
-		.setColor(Colors.Purple)
-		.setTitle(embed.title!)
-		.setDescription(embed.description!)
-		.setURL(embed.url ?? '');
-
-	if(embed.image) {
-		embedBuilder.setImage(embed.image.url!);
-	}
-
-	return embedBuilder;
+	return new EmbedBuilder({
+		color: Colors.Purple,
+		...embed,
+	});
 }
 
 export function makeLines(lines: string[]): string {