bolt/README.md

bolt

look into using retries and context's

also add mentioned users to struct so the ban functions can use them

also do we move towards message handler or focus on command handling, this will dictate the structure going forward with the bans, etc. started on msg handler but it doesn't make sense, the Adding of the handlers won't work with messages since the trigger is always blank. Might need a catch all one, but then that blacklists a command trigger, hmmmm

The nuts-and-bolts of Discord bots. Bolt is a wrapper for discordgo that provides quick and easy bootstrapping for simple Discord bots.

Usage

Token

Bolt requires a Discord bot token to run, the token must be set as an environment variable labeled "DISCORD_TOKEN"

Commands

Commands are represented by the command struct and contain all needed information for bolt to handle the command payload. Including the command timeout as well as the Roles allowed to run the command.

type Command struct {
	Trigger string        //command that triggers payload NOT including the indicator
	Payload Payload       //payload function to run when a command is detected
	Timeout time.Duration //the amount of time before command can be run again
	lastRun time.Time     //timestamp of last command run
	Roles   []string      //roles that can use command, if none are set anyone can run
}

Payload

Payload functions are executed when a command is detected

type Payload func(msg Message) error

Payload functions are given a Message argument containing the needed data for handling commands

type Message struct {
	Author      string   //username of message author
	ID          string   //discord ID of message author
	Words       []string //words from message split on whitespace
	Content     string   //entire message content
	Channel     string   //message channel
	Server      string   //message guild
	Attachments []MessageAttachment //message attachments
}

The Message struct also exposes some methods to support replying to, or acknowledging command messages

func (m *Message) React(emoji Reaction) error

The React method will react to the command message by adding the requested emoji as a reaction. Bolt comes with a few preset emoji's for easy handling but any valid emoji string can be passed.

func (m *Message) Respond(res string) error

The Respond method will send the value of res in response to the command message.

func Delete() error

The Delete method will delete the message from the text channel

Example

package main

import (
	"time"

	"code.jakeyoungdev.com/jake/bolt"
)

func main() {
	//bolt defaults the command indicator to '.' however that can be changed with the options
	//Example: bolt.New(bolt.WithIndicator('!')) would support commands like !ping
	b, err := bolt.New(bolt.WithLogLevel(bolt.LogLevelCmd))
	if err != nil {
		panic(err)
	}

	b.AddCommands(
		// basic ping pong command, .ping can be run at anytime by anyone and will reply "pong"
		bolt.Command{
			Trigger: "ping",
			Payload: func(msg bolt.Message) error {
				return msg.Respond("pong")
			},
		},
		// .react will add a +1 reaction to the command message, .react can be run by anyone at any rate
		bolt.Command{
			Trigger: "react",
			Payload: func(msg bolt.Message) error {
				return msg.React(bolt.ReactionThumbsUp)
			},
		},
		// .time responds with the current date/time, .time can be run once every 25 seconds by any role
		bolt.Command{
			Trigger: "time",
			Payload: func(msg bolt.Message) error {
				return msg.Respond(time.Now().String())
			},
			Timeout: time.Second * 25,
		},
		// .role command can be ran every 10 seconds by anyone with the admin role and will return the string "admin"
		bolt.Command{
			Trigger: "role",
			Payload: func(msg bolt.Message) error {
				return msg.Respond("admin")
			},
			Timeout: time.Second * 10,
			Roles:   []string{"admin"},
		},
	)

	//start is a blocking call that handles safe-shutdown, all configuration and setup should be done before calling Start()
	err = b.Start()
	if err != nil {
		panic(err)
	}
}

Development

bolt is in development at the moment and may break occasionally before a v1 release