discord-bot-shared 0.3.2 → 0.3.3

package/README.md

@@ -1 +1,138 @@
 # discord-bot-shared
+
+A module that makes creating discord.js bots a bit easier.
+
+## Installation/Usage
+
+```
+npm install discord-bot-shared
+```
+
+- This module expects a `BOT_TOKEN` and `CLIENT_ID` environment variable to login.
+  - By default, commands are registered globally. To register commands to a specific guild, you can optionally provide `GUILD_ID`.
+
+```
+// index.ts
+import login from 'discord-bot-shared'
+import { ClientOptions, GatewayIntentBits as Intents, Partials } from 'discord.js'
+
+const botIntents: ClientOptions = {
+  intents: [Intents.Guilds],
+  partials: [Partials.Reaction],
+}
+
+const bot = await login(botIntents, import.meta.url)
+
+export default bot
+```
+
+**You must have a directory names `events` and `commands` next to your `index.ts` (or wherever you are importing `login()` from).**
+
+```
+.
+└── src/
+    ├── events/
+    │   └── someEvent.ts
+    ├── commands/
+    │   └── someCommand.ts
+    └── index.ts
+```
+
+### Events
+
+This module registers your bot's events by `import`ing each file under your `events` directory. Events are registered as a side-effect of the import.
+
+```
+// guildMemberAdd.ts
+import bot from '../index.js'
+
+bot.on('guildMemberAdd', (member) => {
+  // do stuff
+})
+```
+
+### Commands
+
+Your commands are registered by `import`ing the default export of each command file.
+
+```
+// myCommand.ts
+import { Command } from 'discord-bot-shared'
+import { SlashCommandBuilder } from 'discord.js'
+
+const myCommand: Command = {
+  command: new SlashCommandBuilder()
+    .setName('my-command')
+    .setDescription('This command does stuff.') as SlashCommandBuilder,
+  run: (interaction) => {
+    // do stuff
+  },
+}
+
+export default myCommand
+```
+
+Your `run` function is passed the command interaction that initiated the command.
+
+### Exports
+
+The following functions and interfaces/types are exported by this module:
+
+```
+async function login(
+  botIntents: ClientOptions,
+  projectMetaURL: string,
+  interactionCheck?: InteractionCheck,
+): Promise<Client>
+```
+
+- `botIntents` is a discord.js `ClientOptions` object.
+- `projectMetaURL` should always be passed `import.meta.url`. This is used to find and register your events and commands.
+- Optionally provide an `interactionCheck` function that returns a boolean. This function is called right before trying to run a command. The command will only run if `interactionCheck` returns true.
+  - The `InteractionCheck` type is also exported by this module.
+
+---
+
+Returns an object that contains the guild and the following freshly fetched guild collections: `channels, emojis, members, roles`.
+
+```
+async function getGuildCache(baseGuild?: Guild)
+```
+
+- Optionally provide a Guild to retrieve the caches from. Otherwise, the first guild on the bot is used.
+- For example, a common pattern I use is something like this:
+
+```
+const { members } = await getGuildCache()
+// do stuff with members
+```
+
+---
+
+This interface defines the structure of your bot's commands. See above for an example of a command.
+
+```
+interface Command {
+  requiredRoles?: string[]
+  command: SlashCommandBuilder
+  run: (interaction: ChatInputCommandInteraction) => void | Promise<void>
+}
+```
+
+- Optionally provide `requiredRoles` string array. If the member initiating the command has _any_ of the roles provided in this array, they will be allowed to run the command.
+- **You may have to type cast your command `as SlashCommandBuilder` due to the way discord.js' `SlashCommandBuilder` works.**
+- `run` is the final function that will be called to run your command.
+
+---
+
+These are type guards that you will likely need to use.
+
+```
+function isTextChannel(channel: BaseChannel | APIPartialChannel): channel is TextChannel
+```
+
+```
+function isCategoryChannel(channel: BaseChannel): channel is CategoryChannel
+```
+
+- Almost every channel type in discord.js extends `BaseChannel`, so you should be able to pass in whatever channel you need to here.

package/dist/guildCache.d.ts

@@ -2,10 +2,10 @@ import { Client, Guild } from 'discord.js';
 declare function setBot(botClient: Client): void;
 declare function getGuildCache(baseGuild?: Guild): Promise<{
     guild: Guild;
-    channels: import("@discordjs/collection").Collection<string, import("discord.js").NonThreadGuildBasedChannel>;
-    emojis: import("@discordjs/collection").Collection<string, import("discord.js").GuildEmoji>;
-    members: import("@discordjs/collection").Collection<string, import("discord.js").GuildMember>;
-    roles: import("@discordjs/collection").Collection<string, import("discord.js").Role>;
+    channels: import("discord.js").Collection<string, import("discord.js").NonThreadGuildBasedChannel>;
+    emojis: import("discord.js").Collection<string, import("discord.js").GuildEmoji>;
+    members: import("discord.js").Collection<string, import("discord.js").GuildMember>;
+    roles: import("discord.js").Collection<string, import("discord.js").Role>;
 } | undefined>;
 export default getGuildCache;
 export { setBot };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "discord-bot-shared",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "type": "module",
   "description": "Modules for creating discord bots.",
   "repository": "github:adamhl8/discord-bot-shared",
@@ -18,26 +18,26 @@
     "lint": "eslint -f pretty --fix ."
   },
   "dependencies": {
-    "@discordjs/rest": "^1.0.0",
-    "discord-api-types": "^0.36.3",
-    "discord.js": "^14.0.3"
+    "@discordjs/rest": "^1.0.1",
+    "discord-api-types": "^0.37.1",
+    "discord.js": "^14.1.2"
   },
   "devDependencies": {
     "@types/eslint": "^8.4.5",
-    "@types/node": "^18.6.1",
-    "@types/prettier": "^2.6.3",
-    "@typescript-eslint/eslint-plugin": "^5.31.0",
-    "@typescript-eslint/parser": "^5.31.0",
-    "eslint": "^8.20.0",
+    "@types/node": "^18.6.5",
+    "@types/prettier": "^2.7.0",
+    "@typescript-eslint/eslint-plugin": "^5.33.0",
+    "@typescript-eslint/parser": "^5.33.0",
+    "eslint": "^8.21.0",
     "eslint-config-prettier": "^8.5.0",
     "eslint-formatter-pretty": "^4.1.0",
     "eslint-plugin-eslint-comments": "^3.2.0",
-    "eslint-plugin-sonarjs": "^0.14.0",
+    "eslint-plugin-sonarjs": "^0.15.0",
     "eslint-plugin-unicorn": "^43.0.2",
     "prettier": "^2.7.1",
-    "prettier-plugin-organize-imports": "^3.0.0",
-    "prettier-plugin-pkg": "^0.16.0",
-    "prettier-plugin-sh": "^0.12.6",
+    "prettier-plugin-organize-imports": "^3.0.3",
+    "prettier-plugin-pkg": "^0.16.1",
+    "prettier-plugin-sh": "^0.12.8",
     "typescript": "^4.7.4"
   }
 }