_The Permission Command

The PermissionCommand class is a parent class most of our commands extend to get special role and channel permission functionality.

A command that extends the PermissionCommand class gets the following perks:

• command locked behind the admin or staff role
• command locked behind the admin console channel
• BotGuildModel object available for command code
• command locked for dm only
• the message used to call the command is deleted

If non of these perks will be useful to you, we recommend you not extend this class and create your command extending the default Command class.

The Class Itself

The PermissionCommand class extends the Command class like any other command would.

The Constructor

Its constructor requires the client and command info, however, there is a third parameter, special for PermissionCommand. This third parameter is the permission information.

     /**
     * Our custom command information for validation
     * @typedef {Object} CommandPermissionInfo
     * @property {string} role - the role this command can be run by, one of FLAGS
     * @property {string} channel - the channel where this command can be run, one of FLAGS
     * @property {string} roleMessage - the message to be sent for an incorrect role
     * @property {string} channelMessage - the message to be sent for an incorrect channel
     * @property {Boolean} dmOnly - true if this command can only be used on a DM
     */

If no information is given, then the command will have no permission requirements.

The run function.

The run function is overwritten, like any other command class, however, before running the command code, it makes the permission checks, and will not run the code if the checks are not successful.

Once all checks are successful, the runCommand function is activated.

The runCommand function

The runCommand function is the function that must be overwriten by the programmer. It will be called by the PermissionCommand class if the command is called and the permission checks are successful.

An advantage of working with this class and the runCommand, is that the runCommand passes the BotGuildModel object as the first argument. This removes the necessity of instantiating the object when being used for the command. There are no efficiency issues involved since the BotGuildModel object is used during permission checks.

     /**
     * Required class by children, will throw error if not implemented!
     * @param {BotGuildModel} botGuild
     * @param {CommandoMessage} message
     * @param {Object} args
     * @param {Boolean} fromPattern
     * @param {Promise<*>} result
     * @abstract
     * @protected
     */
    runCommand(botGuild, message, args, fromPattern, result) {
        throw new Error('You need to implement the runCommand method!');
    }

Static FLAGS for CommandPermissionInfo

The role and channel arguments of the CommandPermissionInfo must be one of the static FLAGS values. These static values are the botGuildlModel map names for channel and role IDs.

/**
 * String permission flags used for command permissions.
 * * ADMIN_ROLE : only admins can use this command
 * * STAFF_ROLE : staff and admin can use this command
 * * ADMIN_CONSOLE : can only be used in the admin console
 * @enum {String}
 */
PermissionCommand.FLAGS = {
    ADMIN_ROLE: 'adminRole',
    STAFF_ROLE: 'staffRole',
    ADMIN_CONSOLE: 'adminConsole',
};

Usage

A great example to look at is the ChangePreFix command.
This command extends the PermissionCommand.
class ChangePreFix extends PermissionCommand{...}

It then calls super() on its constructor and passes permission information.

    constructor(client) {
        super(client, {
            name: 'change-prefix',
            group: 'a_utility',
            memberName: 'change guild prefix',
            description: 'Change the prefix used in this guild by the bot.',
            guildOnly: true,
        }, {
            role: PermissionCommand.FLAGS.STAFF_ROLE,
        });
    }

It then overwrites the runCommand function and receives the botGuild object as its first argument.

    /**
     * @param {BotGuildModel} botGuild 
     * @param {Message} message 
     */
    async runCommand(botGuild, message) {...}