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 |