doc: update doc (#14)

* doc(Readme): update description * update the 'how to use' section * package: update description and keywords * Readme: fix typo
tguichaoua · Oct 17, 2021 · 53ea406 · 53ea406
1 parent b99b44d
commit 53ea406
Show file tree

Hide file tree

Showing 2 changed files with 135 additions and 39 deletions.
diff --git a/README.md b/README.md
@@ -6,11 +6,20 @@
      <a href="https://github.com/tguichaoua/djs-slash/blob/main/LICENSE" target="_blank">
         <img alt="License: MIT" src="https://img.shields.io/github/license/tguichaoua/djs-slash" />
     </a>
-    <img src="https://img.shields.io/badge/node-%3E%3D16.6.0-blue.svg" />
-    <img alt="Dependency discordjs" src="https://img.shields.io/npm/dependency-version/djs-slash/peer/discord.js" />
+    <a href="https://node.green/#ES2021">
+        <img src="https://img.shields.io/badge/node-%3E%3D16.6.0-blue.svg" />
+    </a>
+    <a href="https://www.npmjs.com/package/discord.js">
+        <img alt="Dependency discordjs" src="https://img.shields.io/npm/dependency-version/djs-slash/peer/discord.js" />
+    </a>
 </p>
 
-> A Slash Command handler for discord.js v13
+djs-slash is a command handler for discord.js v13 that provides an easy command definition with file.  
+
+**Features**:
+- type checking (with TypeScript)
+- slash command
+- context menu command
 
 ## Install
 
@@ -24,26 +33,90 @@ npm i djs-slash
 
 ## How to use
 
-Commands will be load at runtime from the `commands` folder. Files contains the command. Folder are used to create sub command and sub command group.
+Project architecture example
+```
+├ commands/                    (this folder contains all commands)
+| ├ slash/                     (slash command)
+| | ├ ping.ts
+| | └ cmd/
+| |   ├ subcommand.ts
+| |   └ subcommandgroup/
+| |     └ subcommand.ts
+| ├ user/                      (context menu commands on user)
+| | ├ hi.ts
+| | └ ban.ts
+| └ message/                   (context menu commands on message)
+|   ├ delete.ts
+|   └ repeat.ts
+└ index.ts
+```
 
-The name of the command is the name of the file (without the extension).
+### Load commands
+```ts
+const commands = SlashCommandManager.create({
+    commandFolder: './commands' // This is the path to the folder where command are stored relative to the entry point of the application (ie the index.ts file)
+});
 
+// If no parameter is provided, './commands' is used as default path
+const commands = SlashCommandManager.create();
 ```
-└ commands/
-  ├ ping.ts
-  └ cmd/
-    ├ subcommand.ts
-    └ subcommandgroup/
-      └ subcommand.ts
+
+
+### Full script example
+
+```ts
+import { Client, Intents } from "discord.js";
+import { SlashCommandManager } from "djs-slash";
+
+const GUILD_ID = '000000000000000000'
+const BOT_TOKEN = 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa';
+
+// Create the djs client
+const client = new Client({ intents: [Intents.FLAGS.GUILDS] });
+
+// Load all commands from ./commands/
+const commands = SlashCommandManager.create();
+
+client.once("ready", async (client) => {
+    // Registering commands on a guild
+    const guild = await client.guilds.fetch(GUILD_ID);
+    await guild.commands.set(commands.toApplicationCommandData());
+
+    // Registering commands globally
+    await client.application.commands.set(commands.toApplicationCommandData());
+});
+
+client.on("interactionCreate", async (interaction) => {
+    // Pass the interaction to the SlashCommandManager to execute the command
+    if (await commands.execute(interaction)) {
+        // The interaction trigger a command
+    } else {
+        // The interaction didn't trigger a command.
+        // Either the interaction is not a command interaction
+        // either it didn't correspond to a registred command.
+    }
+});
+
+(async () => {
+    await client.login(BOT_TOKEN);
+})();
 ```
 
-Will create the following commands:
+### Define a command
 
--   `/ping`
--   `/cmd subcommand`
--   `/cmd subcommandgroup subcommand`
+#### Slash command
+Slash command files must be placed in a sub-folder named `slash` inside the command folder.  
+The name of the file is the name of the command.  
+To create sub-command and sub-command group use folder. Folder name is the name of the command/group.
 
-### Command file
+ping example:
+```ts
+import { SlashCommand } from 'djs-slash';
+
+export default SlashCommand.define("Reply with 'pong'", {}, async (interaction) => {
+    await interaction.reply({ content: ':ping_pong: pong !', ephemeral: true });
+});
+```
 
 ```ts
 import { SlashCommand } from "djs-slash";
@@ -86,38 +159,59 @@ export default SlashCommand.define(
 );
 ```
 
-### index.ts
 
+`SlashCommand.define(description, options, callback)`  
+- `description` `string`: the description of the command.
+- `options` `{ defaultPermission, options }`
+    - [`defaultPermission`](https://discord.js.org/#/docs/main/stable/typedef/ApplicationCommandData) `boolean`: whether the command is enabled by default when the app is added to a guild.
+    - [`options`](https://discord.js.org/#/docs/main/stable/typedef/ApplicationCommandOptionData) `object`: the options of the command, key is the name of the options.
+        - `description` `string`: the description of the option.
+        - `required` `boolean`: whether the option is required.
+        - `type`: the type of the option.
+        - `choices`: the choices of the option for the user to pick from.
+        - `channelTypes`: when the option type is channel, the allowed types of channels that can be selected.
+- `callback` `(interaction, options) => void | Promise<void>`
+    - `interaction` [`CommandInteraction`](https://discord.js.org/#/docs/main/stable/class/CommandInteraction): the interaction object that trigger the command.
+    - `options` `object`: a key-value object where key is the name of the option and the value the value provided by the user.
+
+#### User command
+User command files must be placed in a sub-folder named `user` inside the command folder.  
+The name of the file is the name of the command.
+
+An user command example:
 ```ts
-import { Client, Intents } from "discord.js";
-import { SlashCommandManager } from "djs-slash";
+import { UserCommand } from 'djs-slash';
 
-// Create the djs client
-const client = new Client({ intents: [Intents.FLAGS.GUILDS] });
+export default UserCommand.define(async (interaction, user) => {
+    await interaction.reply({ content: `Hi, ${user}` });
+});
+```
+`UserCommand.define(callback)`  
+- `callback` `(interaction, user) => void | Promise<void>`
+    - `interaction` [`ContextMenuInteraction`](https://discord.js.org/#/docs/main/stable/class/ContextMenuInteraction): the interaction object that trigger the command.
+    - `user` [`User`](https://discord.js.org/#/docs/main/stable/class/User): the target of the command.
 
-// Load all commands from ./commands/
-const commands = SlashCommandManager.create();
 
-client.once("ready", async (client) => {
-    // Registering commands on a guild
-    const guild = await client.guilds.fetch("000000000000000000");
-    await guild.commands.set(commands.toApplicationCommandData());
+#### Message command
+Message command files must be placed in a sub-folder named `message` inside the command folder.  
+The name of the file is the name of the command.
 
-    // Registering commands globally
-    await client.application.commands.set(commands.toApplicationCommandData());
-});
+A message command example:
+```ts
+import { MessageCommand } from 'djs-slash';
 
-client.on("interactionCreate", async (interaction) => {
-    // If the interaction is a command, pass it to the SlashCommandManager to execute the command
-    if (interaction.isCommand()) await commands.execute(interaction);
+export default MessageCommand.define(async (interaction, message) => {
+    await interaction.reply({ content: message.content });
 });
-
-(async () => {
-    await client.login("BOT_TOKEN");
-})();
 ```
+`MessageCommand.define(callback)`  
+- `callback` `(interaction, message) => void | Promise<void>`
+    - `interaction` [`ContextMenuInteraction`](https://discord.js.org/#/docs/main/stable/class/ContextMenuInteraction): the interaction object that trigger the command.
+    - `user` [`Message`](https://discord.js.org/#/docs/main/stable/class/Message): the target of the command.
+
 
 ## Example Project
+Checkout the example project to learn more.
 
 To run the example project:
 

diff --git a/package.json b/package.json
@@ -1,7 +1,7 @@
 {
     "name": "djs-slash",
     "version": "0.1.0",
-    "description": "A Slash Command handler for discord.js v13",
+    "description": "An application command handler for discord.js v13",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "scripts": {
@@ -24,7 +24,9 @@
         "djs",
         "discord",
         "slash",
-        "command"
+        "command",
+        "context",
+        "menu"
     ],
     "author": {
         "name": "Tristan Guichaoua",