Augur-TS - Discord bot framework

Augur-TS is a fork of a Discord bot framework, utilizing the discord.js library.

Installation

npm install --save augurbot-ts discord.js

Getting Started - The Augur Client

Augur Client

Within your base file, require augurbot-ts and create a new instance of AugurClient:

const { AugurClient } = require("augurbot-ts");

const  client = new AugurClient(config, options?);

client.login();

The AugurClient will create the Discord Client, log it in using the token provided in config.token, listen for events, and process commands. Any gateway intents are automatically calculated based on config.events.

Processing Order:

0. Bot is logged in and ready, but ready event handlers are not triggered yet
1. The application ID is fetched
2. AugurOptions.delayStart is called
3. Modules are loaded (init > clockwork > events > commands > interactions > shared)
4. Augur is ready and triggers any ready event handlers

AugurClient Config

PROPERTY	TYPE	REQUIRED	DEFAULT	DESCRIPTION
events	ClientEvents[]	✓		An array of discord.js events to process, including messageCreate and messageUpdate, if your bot will be processing message commands. Gateway intents will be automatically calculated based on the events supplied. messageEdit has been created as an alternative to messageUpdate to address the problem of CDN link and pin updates.
ownerId	Snowflake	✓		The ID of the bot owner, used in the onlyOwner property in the command structure
prefix	string		!	A default prefix for commands
processDMs	boolean		true	Whether to process messages in DMs
getMessageContent	boolean		false	Whether to use the message content privileged intent
token	string			Your bot's Discord token to log in. If provided in the config object, it does not need to be passed to client.login(). If omitted, it must be passed to client.login().
...	any			Any other properties you wish to be able to access from your command modules may be added. They will not work with intellisense, so this avoid this if possible.

---

AugurClient Options (optional)

PROPERTY	TYPE	DESCRIPTION
clientOptions	ClientOptions	An object containing options to be passed to the new Client. Gateway intents are automatically calculated based on config.events. If you would like to override the calculated intents, provide your own intents as usual for Discord.js
modules	string	A directory, relative to the base file, containing any command modules you wish to automatically load.
errorHandler	Function (Error | string, Message | Interaction | string) => any	A function accepting an Error and one of Message, Interaction, or string as its arguments. This will replace the default error handling function.
parse	Function (Message) => Promise<ParsedMessage | null>	An asynchronous function accepting a Discord.Message as its argument, returning an object with command, suffix, and params properties. This will replace the default parsing function. (Useful in case different servers use different prefixes, for example. Awaited in the case of a database call). The function does not have to return a promise if you don't need it to.
commandExecution	Function (AugurCommand, Message, string[]) => Promise<AugurCommand.process() | void>	An asynchronous function accepting an AugurCommand, Message, and string[] (params). This replaces the default execution function and should call command.process(message, ...params)
interactionExecution	Function (AugurInteraction, Interaction) => Promise<AugurInteraction.process() | void>	An asynchronous function accepting an AugurInteraction and an Interaction. This replaces the default execution function and should call command.process(interaction)
delayStart	Function () => Promise<any>	An asynchronous function that delays module loading and the ready event.

AugurClient Properties

Properties of the AugurClient class:

• config: The config object passed to the AugurClient.
• augurOptions: The options object passed to the AugurClient upon initialization.
• applicationId: Your application's ID
• moduleManager: Holds all of the information for all loaded modules. Includes functions for loading/reloading/unloading modules.

AugurClient Methods

Methods of the AugurClient class:

• errorHandler: Error handling function.

• parse: Parse a message into its command name and suffix. Returns an object containing command (string), suffix (string), and params (string[])

• commandExecution: Handles command execution

• interactionExecution: Handles interaction execution

• delayStart: The function that was run when the bot started

• get<Type>Channel: This method has been introduced to help with getting the correct type of channel for intellisense. This can replace the traditional channels.cache.get() and returns a channel of the correct type. This can also provide actual type safety, as it will return null if the channel type is incorrect.

---

Create Commands & Events - Module File Structure

The basic file structure should look something like this

• 📄 index.js
• 📄 config.json (contains your AugurClient Config)
• 📁./modules (Also commonly called commands. The name doesn't matter, just make sure it's the same as the modules property in your AugurClient Options)
  • 📄 *.js (these are your AugurModule files)

The basic file structure for AugurModule files:

const  Augur = require("augurbot");

const  Module = new Augur.Module();


// Add commands, interactions, event handlers, etc. as necessary.

//Ex: Module.addCommand({...}).addCommand({...}).addEvent(...);


module.exports = Module;

In between, you can add one or more commands and event handlers, as well as a clockwork and unload function.

Module properties include:

• config: Contents of the config object loaded with the AugurClient.
• client: The Augur client which loaded the command module.
• commands: The commands in the module
• interactions: The interaction commands in the module
• clockwork: The clockwork set in the module
• init and unload: The initialized and unloaded data
• events: A collection of events in the module
• shared: A variable or function to be shared across multiple modules

All of the following methods are chainable:

Clockwork

The function passed to the .setClockwork() method should return an interval which will continue to run in the background. The interval is cleared and reloaded when the module is reloaded. Note that the clockwork function is run after the initialization function, and after the bot is ready.

Module.setClockwork((client) => {
    return setInterval(() => {
        checkXP(client)
    }, 60_000);
});

Commands

The .addCommand() method defines a new message based command.

Module.addCommand({
    name: "ping",
    onlyOwner: true,
    process: (msg) => {
        msg.reply("Pong!")
    }
})
// !ping -> Pong!

PROPERTY	TYPE	REQUIRED	DEFAULT	DESCRIPTION
name	string	✓		A string for the name of the command
process	Function (Message, ...string[]) => void	✓		The function to run when the command is invoked.
aliases	string[]			An array of strings that can be used as alternates to the command name
syntax	string			A description of command syntax
description	string			A short overview of the command
info	string			A longer description of the command's usage
category	string		{ The AugurModule filename }	The name of the category the command belongs in. Helpful for sorting/categorizing in things like help commands.
permissions	Function (Message) => boolean			Used to validate if the command should be run based off of the message that triggered the command
userPermissions	PermissionResolveable[]			Used to check if the member using the command has the right server permissions
options	Object			An object of custom options that the developer may wish to use (e.g. in parsing messages)
hidden	boolean		false	A helper for hiding commands in your help functions
enabled	boolean		true	If set to false, the command will never run
parseParams	boolean		false	If set to true, the command suffix will be split by " " before passing the parameters to the process function.
onlyOwner	boolean		false	If set to true, only the user with the ID provided under ownerId in AugurClient Config will be able to run the command
onlyGuild	boolean		false	If set to true, the command will only be run if called in a server. This also changes the type of Message to be a guild message.
onlyDm	boolean		false	If set to true, the command will only be run if called in a DM with the bot. This also changes the type of Message to be a DM message.

Interactions

Interaction slash commands and contexts have to be registered with the Discord API before their first use, or after changes. Augurbot does not handle this. This is the script that Icarus, the main bot that uses this framework, uses to register it's commands.

The .addInteraction() method defines an interaction.

Module.addInteraction({
    id: snowflakes.commands.slashPing,
    name: "ping",
    process: (interaction) => {
        interaction.reply(`${msg.author} you've been pinged!`);
    }
});
// /ping -> @author you've been pinged!

PROPERTY	TYPE	REQUIRED	DEFAULT	DESCRIPTION
type	string			Sets the type of interaction the command should expect. Only used for type checking and intellisense, and does not provide any actual safety.
id	string	✓		The interaction ID for the interaction command
process	Function (Interaction) => void	✓		The function to run when the command is invoked. The type can change to be more specific, depending on the type property.
name	string			The name of the command
syntax	string			A description of command syntax
description	string			A short overview of the command
info	string			A longer description of the command's usage
category	string		{ The AugurModule filename }	The name of the category the command belongs in. Helpful for sorting/categorizing.
permissions	Function (Interaction) => Boolean			Used to validate if the command should be run based off of the message or user that triggered the command. Typing is also changed by the type property.
userPermissions	PermissionResolveable[]			Used to check if the member using the command has the right server permissions
options	Object			An object of custom options that the developer may wish to use (e.g. in execution)
hidden	boolean		false	A helper for hiding commands in your help functions
enabled	boolean		true	If set to false, the command will never run
onlyOwner	boolean		false	If set to true, only the user with the ID provided under ownerId in AugurClient Config will be able to run the command
onlyGuild	boolean		false	If set to true, the command will only be run if called in a server. Sets the type of interaction to be in a guild on top of the provided type.
onlyDm	boolean		false	If set to true, the command will only be run if called in a DM with the bot

Events

The .addEvent() method adds an event handler for the various Discord.js events. For convenience, an additional messageEdit event has been included that only triggers when message content is edited, rather than any other type of message update.

Keep in mind that there are certain quirks with how events are handled. They are described in the function documentation.

Module.addEvent("messageCreate", (msg) => {
    if (msg.content.toLowerCase().startsWith("i'm")) {
        return msg.reply(`Hi ${msg.author}, I'm AugurBot!`)
    }
});
// I'm bobby -> Hi @Bobby, I'm AugurBot!

Initialization

The .setInit(data) method accepts a function to run on module initialization. The data parameter will have a null value on the first run, and will contain the returned by the function defined with the .setUnload() method on subsequent reloads of the module. This function is run after the bot is ready.

Module.setInit((data) => {
    if (data) cachedInfo = data;
    else cachedInfo = await fetchInfo();
});

Unloading

The function passed to the .setUnload() method will be run when unloading or reloading the module.

Module.setUnload(() => {
    return cachedInfo;
});

Sharing Functions/Variables Between Files

// module_1.js

const func = (update) => console.log(update)
const foo = "bar"
Module.setShared({ func, foo });

// module_2.js
Module.addCommand({
    name: "remoteupdate",
    process: (msg) => {
        const shared = msg.client.moduleManager.shared.get("module_1.js")
        shared?.func("Here's your update of the day!")
        console.log(shared?.foo)
    }
})

(ps: do client.debug = true to get more info when event and command handlers are run)