Information

The framework is built on top of the discord.js rewrite. A Discord server is always referred to as a Guild internally, as that's what the API calls them.

First steps

The first thing you'll want to do is instantiate the Bot class, specifying at minimum the properties name and version. To add information to the built-in about command, also add the about property. For update checking, specify updateURL.
Example:

const graf = require('discord-graf');

const version = '1.0.0';
const bot = new graf.Bot({
    name: 'SomeBot',
    version: version,
    about: `**SomeBot** v${version} created by Some Guy.`,
    updateURL: 'https://raw.githubusercontent.com/SomeGuy/some-bot/master/package.json'
});

Then, you'll need to register your modules and commands to the bot, and create the client.
Example (with command classes):

const SomeCommand = require('./commands/general/some-command');
const SomeOtherCommand = require('./commands/general/some-other-command');
const YetAnotherCommand = require('./commands/some-mod/another-command');

const client = bot
    .registerDefaults()
    .registerModules([
        ['general', 'General'],
        ['something', 'Some module']
    ])
    .registerCommands([
        SomeCommand,
        SomeOtherCommand,
        YetAnotherCommand
    ])
.createClient();

That's it! You now have a fully-functioning bot.

Commands

There are two ways to make a command; using the command builder, or making your own class. Using classes is generally preferred and cleaner. Regardless of the method used to make your command, you will need an object of command information. At minimum, the command info must contain the name, module, memberName, and description properties. See the list of all command options. If a command name or alias has hyphens (-) in it, the framework will automatically add aliases for de-hyphenated ones.

Classes

All commands extend the base Command class. They must all override the constructor and run method. They may also optionally override the hasPermission method.

Example command:

const graf = require('discord-graf');

module.exports = class AddNumbersCommand extends graf.Command {
    constructor(bot) {
        super(bot, {
            name: 'add-numbers',
            aliases: ['add', 'add-nums'],
            module: 'math',
            memberName: 'add',
            description: 'Adds numbers together.',
            usage: 'add-numbers <number> [number2] [number3...]',
            details: 'This is an incredibly useful command that finds the sum of numbers. This command is the envy of all other commands.',
            examples: ['add-numbers 42 1337'],
            argsType: 'multiple'
        });
    }

    run(message, args) {
        if(!args[0]) throw new graf.CommandFormatError(this, message.guild);
        const total = args.reduce((prev, arg) => prev + parseFloat(arg), 0);
        return Promise.resolve(`Sum: ${total}`);
    }
}

Builder

The command builder allows you to make and register commands with the bot with a fluent interface.

To use the builder, just call bot.buildCommand() to get a builder. Call .info() on the builder to set the command information before anything else. Call .run() to set the command's run method. Optionally call .hasPermission() to set the command's hasPermission method. Note that using arrow functions will not allow you to access the command via this, so use regular functions instead. Finally, call .register() to register the command to the bot.

Example command:

const graf = require('discord-graf');

bot.buildCommand()
    .info({
        name: 'add-numbers',
        aliases: ['add', 'add-nums'],
        module: 'math',
        memberName: 'add',
        description: 'Adds numbers together.',
        usage: 'add-numbers <number> [number2] [number3...]',
        details: 'This is an incredibly useful command that finds the sum of numbers. This command is the envy of all other commands.',
        examples: ['add-numbers 42 1337'],
        argsType: 'multiple'
    })
    .run(function run(message, args) {
        if(!args[0]) throw new graf.CommandFormatError(this, message.guild);
        const total = args.reduce((prev, arg) => prev + parseFloat(arg), 0);
        return Promise.resolve(`Sum: ${total}`);
    })
.register();

Permissions

Every bot has an instance of BotPermissions as bot.permissions that contains handy methods for checking the permissions of a user on a server. There are three permissions:

• Owner (isOwner): Only the owner of the bot has this permission, and they have it in every server.
• Administrator (isAdmin): A user has this permission if they are the bot owner, or if they have a role on the server with the "Administrate" permission.
• Moderator (isMod): A user has this permission if they are the bot owner, they are an admin, or they have one of the moderator roles assigned. If there are no moderator roles set in the server, then the "Manage messages" permission on any of their roles will make them a moderator instead.

Guild storage

The GuildStorage class allows you to create storages that associate data with guilds. You can either directly instantiate the base GuildStorage class, or extend it. There are three built-in storages that every bot has an instance of:

• AllowedChannelStorage as bot.storage.allowedChannels
• ModRoleStorage as bot.storage.modRoles
• SettingStorage as bot.storage.settings

You probably will never need to use the first two, as they are used primarily by built-in commands/functionality. The SettingStorage, however, could prove to be very useful for your bot. It's essentially a key-value store that is associated with guilds, so you can store simple per-guild settings with it.

It is not recommended to use the storages to store large amounts of data or user-generated content. Use SQLite or some other database for that.

Utilities

Every bot has an instance of BotUtil as bot.util. This contains several handy methods:

• usage creates command usage strings to send in messages
• nbsp converts all spaces in a string into non-breaking spaces
• disambiguation creates disambiguation strings to send in messages (for when you find multiple matches from user input, and need a specific one)
• paginate paginates an array of items, and returns info about the pagination
• search searches an array of items and finds matches
• split splits a string into multiple strings that will fit within Discord's 2,000 character limit