solaire-discord

Solaire

A simple framework with an intuitive interface for creating Discord bots using Node.

import Discord from 'discord.js';
import { Solaire } from "solaire-discord";

const client = new Discord.Client({
  intents: [ Discord.Intents.FLAGS.GUILDS, Discord.Intents.FLAGS.GUILD_MESSAGES ]
});

const bot = Solaire.create({
  discordClient: client,
  token: process.env.TOKEN,
  commandPrelude: "!",
  commands: {
    // In a Discord channel...
    // > !ban @someUser being mean
    "ban <user:GuildMember> <...reason>": {
      execute({ args, message }) {
        // args.user: Discord.js::GuildMember(someUser)
        // args.offense: ["being", "mean"]
        message.channel.send(`Banning ${args.user.displayName} for ${args.reason.join(' ')}!`;
      },
    },
  },
});

bot.start();

Discord.js

Solaire interacts heavily with Discord.js, and many of the objects exposed from the Solaire API will be directly from Discord.js.

---

Example Bot

Install · Example Config · Defining Commands · Command Configuration · Events

---

Install

npm install solaire-discord

Config

Property	Required	Type	Desc
discordClient	Yes	Discord.js::Client	A Discord.js Client object. This client must have the GUILD_MESSAGES intent enabled for Solaire to work properly.
token	Yes	string	Your bot's Discord token (see https://discord.com/developers/docs/intro)
commandPrelude	No	string	The string that must precede a command's name in a Discord message for the command to be invoked. Common values are !, ?, ;;, but any string would technically work.
commandCooldown	No	number	The amount of time in milliseconds that a command is un-invokable after being used. This cooldown is per-command.
commands	Yes	Record<string, CommandConfiguration>	See Defining commands and Command configuration

Defining commands

In Solaire, bot commands are defined using a definition string that resembles how you would actually use the command in Discord. For example, a command that is used like !ban @someAnnoyingUser being mean, would be defined using the string ban <user:GuildMember> [...reason].

This string, along with associated configuration for the command, is passed in via your Solaire config's commands property.

   const bot = Solaire.create({
    ...
    commands: {
      'ban <user:GuildMember> <...reason>': {
        ...
      }
    }
  })

Command Name & Aliases

A command's name is defined as the first word in your command definition string

ban <user>
^------ "ban" is the command's name

You can define aliases for a command by appending the command's name with |<alias>, e.g.

ban|b|banMember <user>
^---- "ban is the command's name, but "b" and "banMember" can also be used to invoke the command

Command Arguments

After your command's name, you can define any number of arguments that can be passed into your command.

Required Arguments

Required arguments are denoted in the definition string by being wrapped in <>, e.g.

ban <user>
      ^---- "user" is a required argument for the "ban" command

Optional Arguments

Optional arguments are denoted by being wrapped in [], e.g.

ban <user> [reason]
             ^---- "reason" is an optional argument

When an optional argument is defined, the remaining arguments in the command must also be optional.

ban [reason> <user>
               ^----- INVALID - since "reason" is optional, all arguments after it must also be optional           

Rest Arguments

A "rest" argument is an arg whose value is defined as all remaining words in a message. They are denoted by the arg's name being preceded with .... e.g.

ban <user> [reason]
> !ban @someAnnoyingUser being mean
                          ^----- "reason" arg has value "being"
                          
ban <user> [...reason]
> !ban @someAnnoyingUser being mean
                          ^----- "reason" arg has value "being mean"

A rest argument must be the last argument of a command. When accessing the argument in your execute, guard, etc. functions, the value of the argument will be an array.

Argument Types

An argument's value can be constrained by defining an explicit type for that argument, denoted in the command definition string by appending the argument's name with :<argType>, e.g.

ban <user:GuildMember>
           ^---- "user" arg value must be parseable into a "GuildMember" type

Defining an argument type has a few benefits

• It validates that the passed in value is valid
• It automatically parses the argument and fits it to its type, transforming the value to a more convenient data type for use when processing and executing the command
• It provides documentation for how our command is supposed to be used

The available argument types are:

Argument Type	Validation	Resolved JS Type
Int	Validates using parseInt	Number
Float	Validates using parseFloat	Number
GuildMember	Validates that ID passed in resolves to a member of the message's server	Discord.js::GuildMember
Date	Validates using new Date()	Date

Command Configuration

Command Execute Function

When your command is invoked, the command's execute function gets called.

   const bot = Solaire.create({
    ...
    commandPrelude: '!',
    commands: {
      'ban <user:GuildMember> [...reason]': {
        async execute({ args, message }) {
         // message: Discord.js::Message
         // args.user: Discord.js::GuildMember
         // args.reason: string[]
         
         const fullReason = args.reason.join(' ');

         message.channel.send(`Banning ${args.user.displayName} for ${fullReason}`;

         user.ban({ reason: fullReason })
        }
      }
    }
  })

> !ban @someAnnoyingUser mean
< Banning Some Annoying User for mean

The payload that gets passed into the execute function contains the following properties

Property	Type	Desc
args	Record<string, any>	The arguments passed into the command
message	Discord.js::Message	The message that triggered the command

Command Authorization

You can restrict which users can invoke a command by defining a guard function for a command.

   const bot = Solaire.create({
    ...
    commandPrelude: '!',
    commands: {
      'ban <user:GuildMember> [...reason]': {
        async execute({ args, message }) {...},
        async guard({ error, ok, message, args}) {
          if(!message.member.roles.cache.some(r => r.name.toLowerCase() === 'admin'){
            error('Member must be an admin');
          } else {
            ok();
          }
        }
      }
    }
  })

The payload provided to the guard function is the same as the one given to the execute function, with the addition of two new callback properties ok and error. If a guard function is provided, the command will be exected only if guard calls the ok function, and the error function is not called. If neither is called, the command will default closed and not execute.

Command Prelude

It is heavily suggested that you assign a commandPrelude to your bot, which is the string that is required at the start of any command invocation. Otherwise, Solaire has to process every single message for the possibility that it's invoking a command. It's also just nan extremely common practice for chat bots.

   const bot = Solaire.create({
    ...
    // To invoke a command in chat, the message has to start with '!'
    // e.g. ❌  ban @someUser being mean WON'T work
    //      ✅ !ban @someUser being mean WILL work
    commandPrelude: '!',
    commands: {
      'ban <user> <reason>': {
        ...
      }
    }
   })

> !ban @someAnnoyingUser mean

> !ban @someAnnoyingUser being mean
< Banning Some Annoying User for being mean

Events

The Solaire class extends EventEmitter, and emits events that you can listen to.

commandInvokedEnd

This event gets emitted after a bot command is invoked and Solaire has finished processing the invocation. The object that is passed to the listener has the following properties

Property	Type	Desc
success	boolean	Whether or not the command executed successfully
command	Command	The Command that was invoked
message	Discord.js::Message	The message that invoked the command
error	CommandInvocationError	See command-invocation-error.ts for all possible values