12 Commits

Author SHA1 Message Date
8f9205fbf0 adding emojis 2025-07-15 19:06:44 -04:00
e1bae3edea adding more emojis 2025-07-10 15:36:25 -04:00
34fdf453c1 readme update 2025-07-10 14:36:21 -04:00
113c6927cb better errors
- no fatal calls
- more descriptive errors
2025-07-09 18:05:55 -04:00
90a17ded2b adding reaction support (#2)
- some rework of structure to allow for more puposeful response usage
- react and response now live on the message itself
- message structs split into own file
- readme updated to use new methods

Reviewed-on: #2
Co-authored-by: jake <jake.young.dev@gmail.com>
Co-committed-by: jake <jake.young.dev@gmail.com>
2025-07-09 20:11:12 +00:00
113fcbf2d1 adding author id to message struct 2025-06-25 19:12:34 -04:00
dd20b73b76 adding log level option (#1)
Reviewed-on: #1
Co-authored-by: jake <jake.young.dev@gmail.com>
Co-committed-by: jake <jake.young.dev@gmail.com>
2025-06-25 22:51:32 +00:00
5f72f58c74 readme update 2025-06-11 17:37:59 -04:00
2d70c450a9 merge fix 2025-06-08 02:27:46 -04:00
08ffade13d [chore] comments and function scope
- methods no longer exported if not used
- readme update
- comments updated
2025-06-08 02:26:06 -04:00
0b39a0996f Update README.md 2025-06-07 13:41:19 +00:00
9ffab89ebf adding TODO comments 2025-06-07 09:31:00 -04:00
5 changed files with 248 additions and 88 deletions

View File

@@ -1,64 +1,109 @@
# bolt # bolt
Base Discord bot framework The nuts-and-bolts of Discord bots. Bolt is a wrapper for [discordgo](https://github.com/bwmarrin/discordgo) that provides quick and easy bootstrapping for simple Discord bots.
## Introduction ## Usage
bolt is a wrapper for Discordgo to provide very quick and easy setup for simple Discord bots. The only code required to run bolt are the command handler functions, this provides developers with the ability to have text-based commands on a Discord server without all the bootstrapping and setup usually required. Any strings returned from the Payload function will be sent back to the Discord server as a reply to the command message. ### Token
Bolt requires a Discord bot token to run, the token must be set as an environment variable labeled "DISCORD_TOKEN"
## Basic Usage ### Commands
bolt allows developers to create a Discord bot with a discord bot token and a few lines of Go code, discord tokens must be set as an environment variable labeled DISCORD_TOKEN. The below example creates a Discord bot and registers three commands: ".ping", ".time", and ".role" the "." character is the default command indicator but that can be changed using the WithIndicator option. 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.
```go
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
```go
type Payload func(msg Message) error
```
Payload functions are given a Message argument containing the needed data for handling commands
```go
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
```go
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.
```go
func (m *Message) Respond(res string) error
```
The Respond method will send the value of <b>res</b> in response to the command message.
### Example
```go ```go
package main package main
import ( import (
"log"
"os"
"os/signal"
"syscall"
"time" "time"
"code.jakeyoungdev.com/jake/bolt" "code.jakeyoungdev.com/jake/bolt"
_ "github.com/joho/godotenv/autoload"
) )
func main() { func main() {
//bolt defaults the command indicator to '.' however that can be changed with the options //bolt defaults the command indicator to '.' however that can be changed with the options
//Example: bolt.New(bolt.WithIndicator('!')) would support commands like !ping //Example: bolt.New(bolt.WithIndicator('!')) would support commands like !ping
b := bolt.New() b, err := bolt.New(bolt.WithLogLevel(bolt.LogLevelCmd))
if err != nil {
panic(err)
}
b.AddCommands( b.AddCommands(
// .ping can be run at any time by anyone and will respond with 'pong' // basic ping pong command, .ping can be run at anytime by anyone and will reply "pong"
bolt.Command{ bolt.Command{
Trigger: "ping", Trigger: "ping",
Payload: func(msg bolt.Message) (string, error) { Payload: func(msg bolt.Message) error {
return "pong", nil //any strings returned will be sent in response to the Discord message return msg.Respond("pong")
}, },
}, },
// .time can be run every 25 seconds by anyone and will respond with 'yer' // .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{ bolt.Command{
Trigger: "time", Trigger: "time",
Payload: func(msg bolt.Message) (string, error) { Payload: func(msg bolt.Message) error {
return "yer", nil return msg.Respond(time.Now().String())
}, },
Timeout: time.Second * 25, Timeout: time.Second * 25,
}, },
// .role can be run every 10 seconds by anyone with the 'admin' role and will respond with 'hi' // .role command can be ran every 10 seconds by anyone with the admin role and will return the string "admin"
bolt.Command{ bolt.Command{
Trigger: "role", Trigger: "role",
Payload: func(msg bolt.Message) (string, error) { Payload: func(msg bolt.Message) error {
return "hi", nil return msg.Respond("admin")
}, },
Timeout: time.Second * 10, Timeout: time.Second * 10,
Roles: []string{"admin"}, Roles: []string{"admin"},
}, },
) )
//start is a blocking call that handles safe-shutdown, all configuration and setup should be done before calling Start() //start is a blocking call that handles safe-shutdown, all configuration and setup should be done before calling Start()
err := b.Start() err = b.Start()
if err != nil { if err != nil {
panic(err) panic(err)
} }
} }
``` ```
## Development ## Development

123
bolt.go
View File

@@ -26,8 +26,9 @@ const (
// basic bot structure containing discordgo connection as well as the command map // basic bot structure containing discordgo connection as well as the command map
type bolt struct { type bolt struct {
*dg.Session //holds discordgo internals *dg.Session //holds discordgo internals
Commands map[string]Command //maps trigger phrase to command struct for fast lookup commands map[string]Command //maps trigger phrase to command struct for fast lookup
indicator string //the indicator used to detect whether a message is a command indicator string //the indicator used to detect whether a message is a command
logLvl LogLevel //determines how much the bot logs
} }
type Bolt interface { type Bolt interface {
@@ -43,35 +44,33 @@ type Bolt interface {
timeoutCheck(msg *dg.MessageCreate, s *dg.Session, run Command) (bool, error) timeoutCheck(msg *dg.MessageCreate, s *dg.Session, run Command) (bool, error)
} }
// setup // create a new bolt interface
func init() { func New(opts ...Option) (Bolt, error) {
//validate environment variables
_, check := os.LookupEnv(TOKEN_ENV_VAR) _, check := os.LookupEnv(TOKEN_ENV_VAR)
if !check { if !check {
log.Fatalf("the %s environment variable must be set", TOKEN_ENV_VAR) return nil, fmt.Errorf("environment variable %s must be set", TOKEN_ENV_VAR)
} }
}
// create a new bolt interface
func New(opts ...Option) Bolt {
bot, err := dg.New(fmt.Sprintf("Bot %s", os.Getenv(TOKEN_ENV_VAR))) bot, err := dg.New(fmt.Sprintf("Bot %s", os.Getenv(TOKEN_ENV_VAR)))
if err != nil { if err != nil {
log.Fatal(err) return nil, fmt.Errorf("failed to create Discord session: %e", err)
} }
bot.Identify.Intents = BOT_INTENTS bot.Identify.Intents = BOT_INTENTS
b := &bolt{ b := &bolt{
Session: bot, Session: bot,
Commands: make(map[string]Command, 0), commands: make(map[string]Command, 0),
logLvl: LogLevelAll,
} }
//set default command indicator //set default command indicator
b.indicator = "." b.indicator = "."
for _, o := range opts { //apply options to bolt
o(b) for _, opt := range opts {
opt(b)
} }
return b return b, nil
} }
// starts the bot, commands are added and the connection to Discord is opened, this is a BLOCKING // starts the bot, commands are added and the connection to Discord is opened, this is a BLOCKING
@@ -82,9 +81,10 @@ func (b *bolt) Start() error {
err := b.Open() err := b.Open()
if err != nil { if err != nil {
return err return fmt.Errorf("failed to open websocket connection with Discord: %e", err)
} }
//safe shutdown handler
sigChannel := make(chan os.Signal, 1) sigChannel := make(chan os.Signal, 1)
signal.Notify(sigChannel, syscall.SIGINT) signal.Notify(sigChannel, syscall.SIGINT)
<-sigChannel <-sigChannel
@@ -104,7 +104,7 @@ func (b *bolt) stop() error {
// adds commands to bot command map for use // adds commands to bot command map for use
func (b *bolt) AddCommands(cmd ...Command) { func (b *bolt) AddCommands(cmd ...Command) {
for _, c := range cmd { for _, c := range cmd {
b.Commands[c.Trigger] = c b.commands[c.Trigger] = c
} }
} }
@@ -113,29 +113,35 @@ func (b *bolt) messageHandler(s *dg.Session, msg *dg.MessageCreate) {
//get server information //get server information
server, err := s.Guild(msg.GuildID) server, err := s.Guild(msg.GuildID)
if err != nil { if err != nil {
log.Println(err) log.Printf("failed to get guild: %e\n", err)
return return
} }
channel, err := s.Channel(msg.ChannelID) channel, err := s.Channel(msg.ChannelID)
if err != nil { if err != nil {
log.Println(err) log.Printf("failed to get channel from guild: %e\n", err)
return return
} }
//if there is no content it is likely an image or a GIF, updating message content for //if there is no content it is likely an image, gif, or sticker, updating message content for
//better logging and to avoid confusion //better logging and to avoid confusion
if len(msg.Content) == 0 { if len(msg.Content) == 0 {
msg.Content = "GIF/IMAGE" msg.Content = "[Embedded Content]"
} }
//log message
log.Printf("< %s | %s | %s > %s\n", server.Name, channel.Name, msg.Author.Username, msg.Content)
//the bot will ignore it's own messages to prevent command loops //the bot will ignore it's own messages to prevent command loops
if msg.Author.ID == s.State.User.ID { if msg.Author.ID == s.State.User.ID {
if b.logLvl == LogLevelCmd {
//log command responses
log.Printf("< %s | %s | %s > %s\n", server.Name, channel.Name, msg.Author.Username, msg.Content)
}
return return
} }
if b.logLvl == LogLevelAll {
//log message
log.Printf("< %s | %s | %s > %s\n", server.Name, channel.Name, msg.Author.Username, msg.Content)
}
//does the message have the command indicator //does the message have the command indicator
lg := len(b.indicator) lg := len(b.indicator)
if msg.Content[:lg] == b.indicator { if msg.Content[:lg] == b.indicator {
@@ -149,8 +155,13 @@ func (b *bolt) messageHandler(s *dg.Session, msg *dg.MessageCreate) {
// parses command from message and handles timeout checks, role checks, and command execution. All command responses are sent back to Discord // parses command from message and handles timeout checks, role checks, and command execution. All command responses are sent back to Discord
func (b *bolt) handleCommand(msg *dg.MessageCreate, s *dg.Session, server *dg.Guild, channel *dg.Channel, lg int) error { func (b *bolt) handleCommand(msg *dg.MessageCreate, s *dg.Session, server *dg.Guild, channel *dg.Channel, lg int) error {
if b.logLvl == LogLevelCmd {
//log commands
log.Printf("< %s | %s | %s > %s\n", server.Name, channel.Name, msg.Author.Username, msg.Content)
}
words := strings.Split(msg.Content, " ") words := strings.Split(msg.Content, " ")
run, ok := b.Commands[words[0][lg:]] run, ok := b.commands[words[0][lg:]]
if !ok { if !ok {
return nil //command doesn't exist, maybe log or respond to author return nil //command doesn't exist, maybe log or respond to author
} }
@@ -158,7 +169,7 @@ func (b *bolt) handleCommand(msg *dg.MessageCreate, s *dg.Session, server *dg.Gu
//has command met its timeout requirements //has command met its timeout requirements
tc, err := b.timeoutCheck(msg, s, run) tc, err := b.timeoutCheck(msg, s, run)
if err != nil { if err != nil {
return err return fmt.Errorf("failed to calculate timeout for %s\n%e", run.Trigger, err)
} }
if !tc { if !tc {
return nil return nil
@@ -168,38 +179,55 @@ func (b *bolt) handleCommand(msg *dg.MessageCreate, s *dg.Session, server *dg.Gu
if run.Roles != nil { if run.Roles != nil {
check, err := b.roleCheck(msg, s, run) check, err := b.roleCheck(msg, s, run)
if err != nil { if err != nil {
return err return fmt.Errorf("failed to perform permission checks for %s\n%e", run.Trigger, err)
} }
if !check { if !check {
return nil return nil
} }
} }
//run command payload plMsg := Message{
res, err := run.Payload(Message{ Author: msg.Author.Username,
Author: msg.Author.Username, ID: msg.Author.ID,
Words: words, msgID: msg.ID,
Content: msg.Content, Words: words,
Channel: channel.Name, Content: msg.Content,
Server: server.Name, Channel: channel.Name,
}) channelID: msg.ChannelID,
Server: server.Name,
if err != nil { serverID: server.ID,
return err sesh: b,
} }
//if a reply is returned send back to Discord //check for file attachments
if res != "" { if len(msg.Attachments) > 0 {
reply := b.createReply(res, msg.ID, msg.ChannelID, msg.GuildID) var att []MessageAttachment
_, err := s.ChannelMessageSendComplex(msg.ChannelID, reply) for _, a := range msg.Attachments {
if err != nil { att = append(att, MessageAttachment{
return err ID: a.ID,
URL: a.URL,
ProxyURL: a.ProxyURL,
Filename: a.Filename,
ContentType: a.ContentType,
Width: a.Width,
Height: a.Height,
Size: a.Size,
DurationSecs: a.DurationSecs,
})
} }
plMsg.Attachments = att
}
//run command payload
err = run.Payload(plMsg)
if err != nil {
return fmt.Errorf("failed to execute payload function: %e", err)
} }
//update run time //update run time
run.lastRun = time.Now() run.lastRun = time.Now()
b.Commands[run.Trigger] = run b.commands[run.Trigger] = run
return nil return nil
} }
@@ -241,12 +269,13 @@ func (b *bolt) getRemainingTimeout(timeout time.Time) string {
// checks if the author of msg has the correct role to run the requested command // checks if the author of msg has the correct role to run the requested command
func (b *bolt) roleCheck(msg *dg.MessageCreate, s *dg.Session, run Command) (bool, error) { func (b *bolt) roleCheck(msg *dg.MessageCreate, s *dg.Session, run Command) (bool, error) {
var found bool var found bool
//loop thru author roles //loop thru author roles, there may be a better way to check for this UNION
//TODO: improve role search performance to support bigger lists
for _, r := range msg.Member.Roles { for _, r := range msg.Member.Roles {
//get role name from ID //get role name from ID
n, err := s.State.Role(msg.GuildID, r) n, err := s.State.Role(msg.GuildID, r)
if err != nil { if err != nil {
return false, err return false, fmt.Errorf("failed to get role from ID %s\n%e", msg.GuildID, err)
} }
//does this role exist in command roles //does this role exist in command roles
check := slices.Contains(run.Roles, n.Name) check := slices.Contains(run.Roles, n.Name)
@@ -261,7 +290,7 @@ func (b *bolt) roleCheck(msg *dg.MessageCreate, s *dg.Session, run Command) (boo
reply := b.createReply("you do not have permissions to run that command", msg.ID, msg.ChannelID, msg.GuildID) reply := b.createReply("you do not have permissions to run that command", msg.ID, msg.ChannelID, msg.GuildID)
_, err := s.ChannelMessageSendComplex(msg.ChannelID, reply) _, err := s.ChannelMessageSendComplex(msg.ChannelID, reply)
if err != nil { if err != nil {
return false, err return false, fmt.Errorf("failed to send permission response: %e", err)
} }
return false, nil return false, nil
} }
@@ -276,7 +305,7 @@ func (b *bolt) timeoutCheck(msg *dg.MessageCreate, s *dg.Session, run Command) (
reply := b.createReply(fmt.Sprintf("that command cannot be run for another %s", b.getRemainingTimeout(wait)), msg.ID, msg.ChannelID, msg.GuildID) reply := b.createReply(fmt.Sprintf("that command cannot be run for another %s", b.getRemainingTimeout(wait)), msg.ID, msg.ChannelID, msg.GuildID)
_, err := s.ChannelMessageSendComplex(msg.ChannelID, reply) _, err := s.ChannelMessageSendComplex(msg.ChannelID, reply)
if err != nil { if err != nil {
return false, err return false, fmt.Errorf("failed to send timeout response: %e", err)
} }
return false, nil return false, nil
} }

View File

@@ -1,24 +1,17 @@
package bolt package bolt
import "time" import (
"time"
)
// custom Discord commands
type Command struct { type Command struct {
Trigger string //command that triggers payload NOT including the indicator Trigger string //command that triggers payload NOT including the indicator
Payload Payload //payload function to run when a command is detected Payload Payload //payload function to run when a command is detected
Timeout time.Duration //the amount of time before command can run again Timeout time.Duration //the amount of time before command can be run again
lastRun time.Time //timestamp of last command run lastRun time.Time //timestamp of last command run
Roles []string //roles that can use command Roles []string //roles that can use command, if none are set anyone can run the command
} }
// payload function type handling commands. The returned error is parsed and, if no error, // command payload functions, any strings returned are sent as a response to the command
// is detected then the response string (res) will be sent in response to the command message type Payload func(msg Message) error
type Payload func(msg Message) (string, error)
// contains the basic information needed for a message command
type Message struct {
Author string //username of message author
Words []string //words from message split on whitespace
Content string //entire message content
Channel string //channel message was sent in
Server string //guild message was sent in
}

78
message.go Normal file
View File

@@ -0,0 +1,78 @@
package bolt
import "fmt"
//built-in Discord reactions
type Reaction string
const (
ReactionThumbsUp Reaction = ":+1:"
ReactionThumbsDown Reaction = ":-1:"
ReactionHundred Reaction = ":100:"
ReactionHeart Reaction = ":heart:"
ReactionPinkHeart Reaction = ":pink_heart:"
ReactionOrangeHeart Reaction = ":orange_heart:"
ReactionYellowHeart Reaction = ":yellow_heart:"
ReactionGreenHeart Reaction = ":green_heart:"
ReactionBlueHeart Reaction = ":blue_heart:"
ReactionBlackHeart Reaction = ":black_heart:"
ReactionPointUp Reaction = ":point_up:"
ReactionPointDown Reaction = ":point_down:"
ReactionHotdog Reaction = ":hotdog:"
ReactionDog Reaction = ":dog:"
ReactionCat Reaction = ":cat:"
ReactionMonkey Reaction = ":monkey:"
ReactionGiraffe Reaction = ":giraffe:"
ReactionDuck Reaction = ":duck:"
ReactionGoose Reaction = ":goose:"
ReactionWatermelon Reaction = ":watermelon:"
ReactionHoney Reaction = ":honey_pot:"
ReactionSandwich Reaction = ":sandwich:"
ReactionPepper Reaction = ":hot_pepper:"
ReactionNoPedestrians Reaction = ":no_pedestrian:"
ReactionExclamation Reaction = ":exclamation:"
ReactionDoubleExclamation Reaction = ":bangbang:"
ReactionSkull Reaction = ":skull:"
ReactionSpeakingHead Reaction = ":speaking_head:"
ReactionGreenCheck Reaction = ":white_check_mark:"
)
// information about attachments to messages
type MessageAttachment struct {
ID string
URL string
ProxyURL string
Filename string
ContentType string
Width int
Height int
Size int
DurationSecs float64
}
// represents a Discord message
type Message struct {
Author string //username of message author
ID string //discord ID of message author
msgID string //id string of message
Words []string //words from message split on whitespace
Content string //entire message content
Channel string //message channel
channelID string //id of channel message was sent in
Server string //message guild
serverID string //id of guild message was sent in
Attachments []MessageAttachment
sesh *bolt
}
// applies reaction to message
func (m *Message) React(emoji Reaction) error {
return m.sesh.MessageReactionAdd(m.channelID, m.msgID, fmt.Sprint(emoji))
}
// sends the value of res in response to the message
func (m *Message) Respond(res string) error {
rep := m.sesh.createReply(res, m.msgID, m.channelID, m.serverID)
_, err := m.sesh.ChannelMessageSendComplex(m.channelID, rep)
return err
}

View File

@@ -2,9 +2,24 @@ package bolt
type Option func(b *bolt) type Option func(b *bolt)
type LogLevel int
const (
LogLevelAll LogLevel = iota //logs all messages, and errors
LogLevelCmd LogLevel = iota //log only commands and responses, and errors
LogLevelErr LogLevel = iota //logs only errors
)
// sets the substring that must be present at the beginning of the message to indicate a command // sets the substring that must be present at the beginning of the message to indicate a command
func WithIndicator(i string) Option { func WithIndicator(i string) Option {
return func(b *bolt) { return func(b *bolt) {
b.indicator = i b.indicator = i
} }
} }
// sets the log level to determine how much bolt logs
func WithLogLevel(lvl LogLevel) Option {
return func(b *bolt) {
b.logLvl = lvl
}
}