CommandBot 3.1.0 (merging 3.1 branch)

CommandBot 3.1.0 - server-specific help message, more customization and JSDoc comments

README.md

@@ -2,10 +2,23 @@
 
 A Discord.js based framework that makes creating Discord bots with support for slash commands easy and fast.
 
-# Table of contents
+## Features
+
+-   Support for slash commands
+-   Intuitive usage
+-   Good customization
+-   Permission system
+-   Built-in help command
+-   Built-in information messages
+-   Automatic error catching
+-   Large documentation in README and using JSDoc
+-   Written in TypeScript
+
+## Table of contents
 
 -   [CommandBot](#commandbot)
--   [Table of contents](#table-of-contents)
+    -   [Features](#features)
+    -   [Table of contents](#table-of-contents)
 -   [Instalation](#installation)
     -   [System requirements](#system-requirements)
     -   [Creating a project](#creating-a-project)
@@ -298,26 +311,34 @@ There are 4 information messages:
 -   **PERMISSION** - "Insufficient permissions" message (sent when the caller doesn't have enough permissions)
 -   **NOT_FOUND** - "Command not found" message (sent when someone tries to call a command that does not exist)
 
-Each of these messages can be customized with these properties:
+Their configuration is stored in _messages.system_ property.
 
--   **enabled** - _boolean_ - enables or disables the message
--   **title** - _string_ - title of the message
+Each of these messages can be customized with these properties (\* - required):
+
+-   **enabled\*** - _boolean_ - enables or disables the message
+-   **title\*** - _string_ - title of the message
 -   **bottomText** - _string_ - text below the title (also known as description)
 -   **accentColor** - _ColorResolvable_ - embed color
+-   **displayDetails** - _boolean_ - whether to display additional informations
 -   **showTimestamp** - _boolean_ - whether to show date and time in the footer
 -   **footer** - _string_ - message footer
+-   **deleteTimeout** - _number_ - time (ms) after the message gets deleted
+
+There is also a global _deleteTimeout_ property (_messages.system.deleteTimeout_)
 
 ## Help message
 
-You can customize the help message with these properties:
+Its configuration is stored in _messages.help_ property.
 
--   **enabled** - _boolean_ - enables or disables the message
--   **title** - _string_ - title of the message
--   **bottomText** - _string_ - text below the title (also known as description)
--   **accentColor** - _ColorResolvable_ - embed color
--   **description** - _string_ - description shown in the message itself
--   **usage** - _string_ - usage displayed in the message itself
--   **visible** - _boolean_ - whether to show the help command in the list
+You can customize the help message with these properties (\* - required):
+
+-   **enabled\*** - _boolean_ - enables or disables the message
+-   **title\*** - _string_ - title of the message
+-   **bottomText\*** - _string_ - text below the title (also known as description)
+-   **accentColor\*** - _ColorResolvable_ - embed color
+-   **description\*** - _string_ - description shown in the message itself
+-   **usage\*** - _string_ - usage displayed in the message itself
+-   **visible\*** - _boolean_ - whether to show the help command in the list
 
 # Issues
 

index.ts

@@ -1,8 +1,34 @@
 import { Bot } from "./src/Bot.js";
 import { Command } from "./src/Command.js";
-import { ParameterResolvable, ParameterType } from "./src/types.js";
+import { InitOptions, CommandBuilder, CommandMessageStructure, HelpMessageParams, ParameterResolvable, ParameterType } from "./src/types.js";
+import { ObjectID, InputParameter, ParameterSchema, StringParameter, BooleanParameter, NumberParameter, ObjectParameter, Parameter } from "./src/Parameter.js";
+import { SystemMessageAppearance, SystemMessageData } from "./src/SystemMessage.js";
+import { PermissionsError, ParameterTypeError, MissingParameterError, OperationSuccess } from "./src/errors.js";
 import { MessageEmbed } from "discord.js";
-import { ObjectID, InputParameter } from "./src/Parameter.js";
 
 export default Bot;
-export { Bot, Command, MessageEmbed, ParameterResolvable, ParameterType, ObjectID, InputParameter };
+export {
+    Bot,
+    Command,
+    MessageEmbed,
+    InitOptions,
+    CommandBuilder,
+    CommandMessageStructure,
+    HelpMessageParams,
+    ParameterResolvable,
+    ParameterType,
+    ObjectID,
+    SystemMessageAppearance,
+    SystemMessageData,
+    ParameterSchema,
+    Parameter,
+    InputParameter,
+    StringParameter,
+    BooleanParameter,
+    NumberParameter,
+    ObjectParameter,
+    PermissionsError,
+    ParameterTypeError,
+    MissingParameterError,
+    OperationSuccess,
+};

package.json

@@ -1,6 +1,6 @@
 {
     "name": "commandbot",
-    "version": "3.0.0",
+    "version": "3.1.0",
     "description": "A framework that helps you create your own Discord bot easier.",
     "main": "dist/cjs/index.js",
     "module": "dist/mjs/index.js",

src/Bot.ts

@@ -16,27 +16,57 @@ export declare interface Bot {
     on(event: "ERROR", listener: (e: any) => void): this;
 }
 
+/**
+ * @class  Class that represents your bot instance
+ * @extends {EventEmitter}
+ * @exports
+ */
 export class Bot extends EventEmitter {
+    /**
+     * Bot name
+     * @type {string}
+     */
     name: string;
+    /**
+     * Discord.js {@link Client} instance
+     * @type {Client}
+     */
     client: Client;
+    /**
+     * Instance command manager
+     * @type {CommandManager}
+     */
     commands: CommandManager;
+    /**
+     * Discord bot token
+     * @type {string}
+     */
     token: string;
+    /**
+     * Discord API application ID
+     * @type {string}
+     */
     applicationId: string;
+    /**
+     * Built-in messages configuration
+     * @type {Object}
+     */
     messages: {
+        /**
+         * Help message configuration
+         * @type {HelpMessageParams}
+         */
         help: HelpMessageParams;
+        /**
+         * {@link SystemMessageManager} storing messages' configuration
+         * @type {SystemMessageManager}
+         */
         system: SystemMessageManager;
     };
 
     /**
-     * Bot instance initializer
      * @constructor
-     * @param {InitOptions} options - instance properties
-     * @param {string} options.name - name of your bot
-     * @param {string} options.prefix - prefix used to call commands
-     * @param {string} [options.argumentSeparator=','] - used to get parameters from message
-     * @param {ClientOptions} [options.clientOptions] - client options from Discord.js
-     * @param {string} options.token - bot token from Discord Developer Portal
-     * @param {string} options.applicationId - Discord application ID used to register slash commands
+     * @param {InitOptions} options - instance properties ({@link InitOptions})
      */
     constructor(options: InitOptions) {
         super();
@@ -80,10 +110,11 @@ export class Bot extends EventEmitter {
     }
 
     /**
+     * @method
      * Starts your Discord bot
      * @param {number} [port] - if specified, the app will create a http server that will be listening on the specified port
-     * @param {boolean} [register] - if true, the bot will register all slash commands in Discord API
-     * @returns *Promise<boolean>*
+     * @param {boolean} [register=true] - if *true* or *undefined*, the bot will register all slash commands in Discord API
+     * @returns {Promise<boolean>} whether this operation has been completed successfully
      */
     async start(port?: number, register?: boolean): Promise<boolean> {
         try {
@@ -208,8 +239,9 @@ export class Bot extends EventEmitter {
     }
 
     /**
-     * Registers commands in Discord API
-     * @returns *Promise<void>*
+     * @method
+     * Registers commands from {@link CommandManager} in Discord API
+     * @returns {Promise<void>}
      */
     async register(): Promise<void> {
         process.stdout.write("Registering commands... ");

src/Command.ts

@@ -5,18 +5,74 @@ import { OperationSuccess, PermissionsError } from "./errors.js";
 import { DefaultParameter, InputParameter, Parameter } from "./Parameter.js";
 
 //CLASSES
+/**
+ * @class Class that represents a command instance
+ * @exports
+ */
 export class Command {
+    /**
+     * Command name
+     * @type {string}
+     */
     name: string;
+    /**
+     * List of parameters that can passed to this command
+     * @type {Array} {@link Parameter}
+     */
     parameters: Parameter[];
+    /**
+     * List of different names that can be used to invoke a command (when using prefix interactions)
+     * @type {Array} *string*
+     */
     aliases?: string[];
+    /**
+     * Command description displayed in the help message (Default description: "No description")
+     * @type {string}
+     */
     description: string;
+    /**
+     * Command usage displayed in the help message
+     * @type {string}
+     */
     usage?: string;
+    /**
+     * Whether to check if a caller has all defined in *permissions* property permissions or at least one of them (doesn't apply to custom function permissions)
+     * @type {PermissionCheckTypes} "ALL" | "ANY"
+     */
     permissionCheck: PermissionCheckTypes;
+    /**
+     * Command permissions (if *undefined*, no permissions check will be performed)
+     * @type {PermissionResolvable}
+     * @type {Function} should return boolean value
+     */
     permissions?: Permissions | ((m?: Message | CommandInteraction) => boolean);
+    /**
+     * List of Discord guild (server) IDs in which this command can be used
+     * @type {Array} *string*
+     */
     guilds?: string[];
+    /**
+     * Whether this command is visible in the help message (default: true)
+     * @type {boolean}
+     */
     visible: boolean;
+    /**
+     * Whether this command should be registered as a slash command (default: true)
+     * @type {boolean}
+     */
     slash: boolean;
+    /**
+     * Whether to send a SUCCESS message if no other response is defined (default: true)
+     * @type {boolean}
+     */
     announceSuccess: boolean;
+    /**
+     * Command execution function (triggered when someone invokes the command)
+     * @type {Function}
+     * @param {Function} p - function to fetch input parameters' values
+     * @param {Message | CommandInteraction} i - interaction object
+     * @private
+     */
     private function: (
         params: (query: string, returnType?: "value" | "object") => ParameterResolvable | InputParameter | null,
         interaction?: Message | CommandInteraction
@@ -25,17 +81,7 @@ export class Command {
     /**
      * Command constructor
      * @constructor
-     * @param {CommandBuilder} options - all command properties
-     * @param {string} options.name - command name (used to trigger the command)
-     * @param {ParameterSchema} options.parameters - all parameters that can be passed with the command
-     * @param {string | string[]} [options.aliases] - other words that can trigger the command with prefix (not used in slash commands)
-     * @param {string} [options.description="No description"] - command description shown in the help message
-     * @param {string} [options.usage] - command usage description shown in the help message (usage message can be automatically generated using parameters)
-     * @param {PermissionCheckTypes} [options.permissionCheck='ANY'] - specifies if the caller has to have all of the specified permissions or any of that
-     * @param {PermissionResolvable} [options.permissions] - permissions needed to run the command
-     * @param {boolean} [options.visible=true] - show command in the help message (visible as a slash command)
-     * @param {boolean} [options.slash=true] - whether the command should be available as a slash command
-     * @param {Function} options.function - function that will trigger when the commands gets called
+     * @param {CommandBuilder} options - {@link CommandBuilder}
      */
     constructor(options: CommandBuilder) {
         this.name = options.name.split(" ").join("_");
@@ -65,10 +111,10 @@ export class Command {
     }
 
     /**
-     * Starts the command
-     * @param {Message | CommandInteraction} [interaction] - a *Message* or *CommandInteraction* object used to check caller's permissions. It will get passed to the execution function (specified in *function* property of command's constructor)
-     * @param {InputParameter[]} [cmdParams] - list of processed parameters passed in a Discord message
-     * @returns *Promise<void>*
+     * Invokes the command
+     * @param {Message | CommandInteraction} [interaction] - Used to check caller's permissions. It will get passed to the execution function (specified in *function* property of command's constructor)
+     * @param {InputParameter[]} [cmdParams] - list of processed parameters passed in a Discord interaction
+     * @returns {Promise<void>}
      */
     async start(interaction?: Message | CommandInteraction, cmdParams?: InputParameter[]): Promise<void> {
         const paramFindFn = function (query: string, returnType?: "value" | "object") {
@@ -124,7 +170,7 @@ export class Command {
     }
 
     /**
-     * Returns object that is ready to be registered in the Discord API
+     * Converts {@link Command} instance to object that is recognized by the Discord API
      * @returns {Object} object
      */
     toCommandObject() {
@@ -163,10 +209,6 @@ export class Command {
         };
     }
 
-    /**
-     * @param  {string|string[]} phrase?
-     * @returns string
-     */
     private static processPhrase(phrase?: string | string[]): string[] | undefined {
         if (Array.isArray(phrase)) {
             const buff = phrase.map((p) => {
@@ -187,9 +229,6 @@ export class Command {
         }
     }
 
-    /**
-     * @returns string
-     */
     private generateUsageFromArguments(): string {
         let usageTemplate: string = "";
         this.parameters &&