fixing pkg site docs

Reviewed-on: #8

.gitignore

@@ -25,3 +25,5 @@ go.work.sum
 # env file
 .env
 
+/cmd/*
+/cmd

README.md

@@ -1,65 +1,108 @@
 # bolt
 
-Base Discord bot framework
+A fast [discordgo](https://github.com/bwmarrin/discordgo) wrapper for bootstrapping Discord bots.
 
-## Introduction
-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.
+## Usage
+### Prerequisites
+Bolt requires a Discord bot token to run, the token must be set as an environment variable labeled "DISCORD_TOKEN"
 
-## Basic Usage
-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.
+### Example
 ```go
 package main
 
 import (
-	"log"
-	"os"
-	"os/signal"
-	"syscall"
+	"fmt"
+	"strings"
 	"time"
 
 	"code.jakeyoungdev.com/jake/bolt"
 	_ "github.com/joho/godotenv/autoload"
 )
 
+/*
+A basic example of a bot with two commands and a general message handler for non-command messages. The bot uses a
+verbose log level which will log everything for debugging purposes, and registers Discord Intents for message and 
+admin related permissions. This allows the bot to parse messages, send them, delete them, etc. as well as timeout 
+and mute users.
+
+This example registers three commands:
+
+1. .ping - a basic ping/pong command that can be run by anyone at any time
+2. .wait - a dummy command that replies "okay" it can only be run by users with the "user" role and can only be ran 
+once every 25 seconds
+3. .timeout - a admin command that can only be run by users with an "admin" role, this command will timeout any mentioned 
+users for 5 minutes
+
+A message handler is also registered in this example, message handlers are used to handle messages that do not contain a 
+command. This enables auto-moderation from the bot without manual intervention. The example message handler does two arbitrary 
+things to demo functionality:
+
+1. Checks the message content for the phrase "swear word" and, if found, times the user out for 5 minutes
+2. Checks the message for the phrase "im going to yell in VoiceChat" and mutes the message author until Unmute is called on them
+*/
+
 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 := bolt.New()
+	b, err := bolt.New()
+
+	if err != nil {
+		panic(err)
+	}
 
 	b.AddCommands(
-        // .ping can be run at any time by anyone and will respond with 'pong'
 		bolt.Command{
 			Trigger: "ping",
-			Payload: func(msg bolt.Message) (string, error) {
-				return "pong", nil //any strings returned will be sent in response to the Discord message
+			Payload: func(c *bolt.Context) error {
+				return c.Respond("pong")
 			},
 		},
-        // .time can be run every 25 seconds by anyone and will respond with 'yer'
 		bolt.Command{
-			Trigger: "time",
-			Payload: func(msg bolt.Message) (string, error) {
-				return "yer", nil
+			Trigger: "wait",
+			Payload: func(c *bolt.Context) error {
+				return c.Respond("okay")
 			},
 			Timeout: time.Second * 25,
+			Roles:   []string{"user"},
 		},
-        // .role can be run every 10 seconds by anyone with the 'admin' role and will respond with 'hi'
-        bolt.Command{
-            Trigger: "role",
-            Payload: func(msg bolt.Message) (string, error) {
-				return "hi", nil
+		bolt.Command{
+			Trigger: "timeout",
+			Payload: func(c *bolt.Context) error {
+				if len(c.Message.Mentions) > 0 {
+					count := 0
+					for _, m := range c.Message.Mentions {
+						err := c.Timeout(m.ID, time.Now().Add(time.Minute*5))
+						if err != nil {
+							return err
+						}
+						count++
+					}
+
+					return c.Respond(fmt.Sprintf("timed out %d users\n", count))
+				}
+				return nil
 			},
-            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()
-	err := b.Start()
+	b.AddMessageHandler(func(c *bolt.Context) error {
+		if strings.Contains(c.Message.Content, "swear word") {
+			return c.Timeout(c.Message.Author.ID, time.Now().Add(time.Hour*1))
+		}
+
+		if c.Message.Content == "im going to yell in VoiceChat" {
+			return c.Mute(c.Message.Author.ID)
+		}
+		return nil
+	})
+
+	err = b.Start()
 	if err != nil {
 		panic(err)
 	}
 }
+
 ```
 
 ## Development
-bolt is in development at the moment and may break occasionally before a v1 release
+bolt is in early development and may encounter breaking changes until a full v1 rollout, I will do my best to communicate
+these changes. Use a tagged version to avoid any surprises with live code in main

bolt.go

@@ -1,210 +1,311 @@
 package bolt
 
 import (
+	"context"
 	"fmt"
 	"log"
 	"os"
 	"os/signal"
 	"slices"
 	"strings"
-	"syscall"
+	"sync"
 	"time"
 
 	dg "github.com/bwmarrin/discordgo"
 )
 
 const (
-	TOKEN_ENV_VAR = "DISCORD_TOKEN" //label for token environment variable
+	//the name of the environment variable that should contain the token for the bot, it is
+	//required for bolt to run
+	TOKEN_ENV_VAR = "DISCORD_TOKEN"
 
-	BOT_INTENTS = dg.IntentGuilds |
+	//bot default command indicator, if messages begin with this substring they are processed
+	//through the command handler instead of the generic message handler
+	DEFAULT_INDICATOR = "."
+	//max amount of concurrent goroutines that bolt can use for events. A lower amount
+	//may lower the resource usage of bolt but may cause a delay in event handling
+	DEFAULT_MAX_GOROUTINES = 250
+
+	//minimum intents for bots to function, intents can be changed with options
+	DEFAULT_INTENTS = dg.IntentGuilds |
 		dg.IntentGuildMembers |
 		dg.IntentGuildPresences |
 		dg.IntentMessageContent |
-		dg.IntentsGuildMessages
+		dg.IntentsGuildMessages |
+		dg.IntentGuildMessageReactions
 )
 
-// basic bot structure containing discordgo connection as well as the command map
-type bolt struct {
-	*dg.Session                    //holds discordgo internals
-	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
+type Bolt struct {
+	//discordgo internals
+	*dg.Session
+	//maps trigger phrase to command struct for instant lookup
+	commands map[string]Command
+	//used to detect whether a message is a command
+	indicator string
+	//verbosity of logs bolt outputs
+	logLvl LogLevel
+	//waitgroup for event routines
+	wg sync.WaitGroup
+	//pool is a buffered channel used as a semaphore for event handler routines, it is limited to
+	//only spawn maxRoutines to handle events
+	pool        chan struct{}
+	maxRoutines int
+	//generic message handler func
+	msgHandlerf Payload
 }
 
-type Bolt interface {
-	Start() error
-	AddCommands(cmd ...Command)
-	//filtered methods
-	stop() error
-	messageHandler(s *dg.Session, msg *dg.MessageCreate)
-	handleCommand(msg *dg.MessageCreate, s *dg.Session, server *dg.Guild, channel *dg.Channel, lg int) error
-	createReply(content, message, channel, guild string) *dg.MessageSend
-	getRemainingTimeout(timeout time.Time) string
-	roleCheck(msg *dg.MessageCreate, s *dg.Session, run Command) (bool, error)
-	timeoutCheck(msg *dg.MessageCreate, s *dg.Session, run Command) (bool, error)
-}
-
-// setup
-func init() {
-	//validate environment variables
+// New creates a new bolt instance and applies any supplied options
+func New(opts ...Option) (*Bolt, error) {
 	_, check := os.LookupEnv(TOKEN_ENV_VAR)
 	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)))
 	if err != nil {
-		log.Fatal(err)
-	}
-	bot.Identify.Intents = BOT_INTENTS
-
-	b := &bolt{
-		Session:  bot,
-		Commands: make(map[string]Command, 0),
-	}
-	//set default command indicator
-	b.indicator = "."
-
-	for _, o := range opts {
-		o(b)
+		return nil, fmt.Errorf("failed to create Discord session: %e", err)
 	}
 
-	return b
+	b := &Bolt{
+		Session:     bot,
+		commands:    make(map[string]Command, 0),
+		logLvl:      LogLevelAll,
+		indicator:   DEFAULT_INDICATOR,
+		wg:          sync.WaitGroup{},
+		maxRoutines: DEFAULT_MAX_GOROUTINES,
+	}
+
+	b.Identify.Intents = DEFAULT_INTENTS
+	for _, opt := range opts {
+		opt(b)
+	}
+
+	//options can change max routine number, so create after
+	b.pool = make(chan struct{}, b.maxRoutines)
+
+	return b, nil
 }
 
-// starts the bot, commands are added and the connection to Discord is opened, this is a BLOCKING
-// call that handles safe shutdown of the bot
-func (b *bolt) Start() error {
-	//register commands and open connection
-	b.AddHandler(b.messageHandler)
-
+// Start applies the message event handler function to the bot and opens the initial websocket connection
+// with Discord. Start is a blocking call that also handles safe shutdown, on Interrupt, bolt will give
+// command routines a window to finish before closing the connection.
+func (b *Bolt) Start() error {
+	b.AddHandler(b.msgEventHandler)
 	err := b.Open()
 	if err != nil {
-		return err
+		return fmt.Errorf("failed to open websocket connection with Discord: %e", err)
 	}
 
 	sigChannel := make(chan os.Signal, 1)
-	signal.Notify(sigChannel, syscall.SIGINT)
+	signal.Notify(sigChannel, os.Interrupt)
 	<-sigChannel
 
-	if err := b.stop(); err != nil {
-		return err
+	//give handler routines a 5 second window to finish processes before closing connection
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second*5)
+	defer cancel()
+	closeChan := make(chan struct{})
+	go func() {
+		b.wg.Wait()
+		close(closeChan)
+	}()
+
+	select {
+	case <-ctx.Done():
+		log.Println("shutdown timed out waiting for handlers to finish, some may have been incomplete")
+	case <-closeChan:
 	}
 
-	return nil
+	return b.stop()
 }
 
-// stops the bot
-func (b *bolt) stop() error {
+// AddCommands registers command handlers. Any messages that begin with the command indicator will be forwarded
+// to the handler
+func (b *Bolt) AddCommands(cmd ...Command) {
+	for _, c := range cmd {
+		b.commands[c.Trigger] = c
+	}
+}
+
+// AddMessageHandler registers the generic message handler, any messages that are not commands will be forwarded
+// to the handler
+func (b *Bolt) AddMessageHandler(p Payload) {
+	b.msgHandlerf = p
+}
+
+// stop closes the websocket connection to Discord
+func (b *Bolt) stop() error {
 	return b.Close()
 }
 
-// adds commands to bot command map for use
-func (b *bolt) AddCommands(cmd ...Command) {
-	for _, c := range cmd {
-		b.Commands[c.Trigger] = c
-	}
-}
-
-// handler function that parses message data and executes any command payloads
-func (b *bolt) messageHandler(s *dg.Session, msg *dg.MessageCreate) {
+// msgEventHandler handles the routing of messages to either the command or message handlers. If LogLvl is set, logging is handled here before
+// the event is mapped to the Message struct and forwarded to the handlers. Each message is handled in its own goroutine, the max allowed goroutines
+// is set as a default and can be altered using options for better performance.
+func (b *Bolt) msgEventHandler(s *dg.Session, msg *dg.MessageCreate) {
 	//get server information
 	server, err := s.Guild(msg.GuildID)
 	if err != nil {
-		log.Println(err)
+		log.Printf("failed to get guild: %e\n", err)
 		return
 	}
 	channel, err := s.Channel(msg.ChannelID)
 	if err != nil {
-		log.Println(err)
+		log.Printf("failed to get channel from guild: %e\n", err)
 		return
 	}
 
-	//if there is no content it is likely an image or a GIF, updating message content for
-	//better logging and to avoid confusion
-	if len(msg.Content) == 0 {
-		msg.Content = "GIF/IMAGE"
-	}
-
-	//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
 	if msg.Author.ID == s.State.User.ID {
+		if b.logLvl != LogLevelErr {
+			log.Printf("< %s | %s | %s > %s\n", server.Name, channel.Name, msg.Author.Username, msg.Content)
+		}
 		return
 	}
 
-	//does the message have the command indicator
+	if b.logLvl == LogLevelAll {
+		log.Printf("< %s | %s | %s > %s\n", server.Name, channel.Name, msg.Author.Username, msg.Content)
+	}
+
+	m := b.mapEventToMsg(msg, channel, server)
 	lg := len(b.indicator)
 	if msg.Content[:lg] == b.indicator {
-		err := b.handleCommand(msg, s, server, channel, lg)
-		if err != nil {
-			log.Println(err)
-			return
+		if b.logLvl == LogLevelCmd {
+			log.Printf("< %s | %s | %s > %s\n", m.Server, m.Channel, m.Author.Name, m.Content)
 		}
+
+		b.pool <- struct{}{} //'aquire' a routine
+		b.wg.Go(func() {
+			err := b.handleCommand(&m, lg)
+			if err != nil {
+				log.Println(err)
+			}
+			<-b.pool //release routine
+		})
+	} else {
+		b.pool <- struct{}{} //'aquire' a routine
+		b.wg.Go(func() {
+			err := b.handleMessage(&m)
+			if err != nil {
+				log.Println(err)
+			}
+			<-b.pool //release routine
+		})
 	}
 }
 
-// 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 {
-	words := strings.Split(msg.Content, " ")
-	run, ok := b.Commands[words[0][lg:]]
-	if !ok {
-		return nil //command doesn't exist, maybe log or respond to author
+// mapEventToMsg maps the Discord event message struct into bolt's user-friendly Message struct
+func (b *Bolt) mapEventToMsg(msg *dg.MessageCreate, channel *dg.Channel, server *dg.Guild) Message {
+	m := Message{
+		Author: Author{
+			Name:  msg.Author.Username,
+			ID:    msg.Author.ID,
+			Roles: msg.Member.Roles,
+		},
+		ID:        msg.ID,
+		Content:   msg.Content,
+		Channel:   channel.Name,
+		ChannelID: channel.ID,
+		Server:    server.Name,
+		ServerID:  server.ID,
 	}
 
-	//has command met its timeout requirements
-	tc, err := b.timeoutCheck(msg, s, run)
-	if err != nil {
-		return err
+	w := strings.Fields(msg.Content)
+	if len(w) > 0 {
+		m.Words = w
 	}
+
+	if len(msg.Mentions) > 0 {
+		m.Mentions = msg.Mentions
+	}
+
+	if len(msg.Attachments) > 0 {
+		var att []MessageAttachment
+		for _, a := range msg.Attachments {
+			att = append(att, MessageAttachment{
+				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,
+			})
+		}
+
+		m.Attachments = att
+	}
+
+	return m
+}
+
+// handleMessage forwards the message data to the handler function, if one is set
+func (b *Bolt) handleMessage(event *Message) error {
+	if b.msgHandlerf != nil {
+		return b.msgHandlerf(&Context{
+			Message: event,
+			bolt:    b,
+		})
+	}
+
+	return nil
+}
+
+// handleCommand maps the first word of the message to the command payload, if it exists. It then forwards the message
+// data to the handler after checking the timeout and role restrictions. If restrictions have not been met a generic
+// response is sent to the message
+// TODO: accept a string for timeout/role rejection messages to allow customization
+func (b *Bolt) handleCommand(msg *Message, lg int) error {
+	run, ok := b.commands[msg.Words[0][lg:]]
+	if !ok {
+		return nil //command doesn't exist
+	}
+
+	//has command met its timeout requirements, if timeout has not expired a response is sent to the message
+	//from the timeoutCheck method
+	tc, err := b.timeoutCheck(msg.ID, msg.ChannelID, msg.ServerID, b.Session, run)
+	if err != nil {
+		return fmt.Errorf("failed to calculate timeout for %s\n%e", run.Trigger, err)
+	}
+	//method handles sending a response, so we do not need to send another here, simply return
 	if !tc {
 		return nil
 	}
 
-	//does user have correct permissions
+	//does user have correct permissions to run this command
 	if run.Roles != nil {
-		check, err := b.roleCheck(msg, s, run)
+		check, err := b.roleCheck(msg.ServerID, msg.Author.Roles, b.Session, run)
 		if err != nil {
-			return err
+			return fmt.Errorf("failed to perform permission checks for %s\n%e", run.Trigger, err)
 		}
 		if !check {
+			//this alert should probably be moved into the roleCheck function to match the pattern of the timeoutCheck method
+			reply := b.createReply("you do not have permissions to run that command", msg.ID, msg.ChannelID, msg.ServerID)
+			_, err := b.Session.ChannelMessageSendComplex(msg.ChannelID, reply)
+			if err != nil {
+				return err
+			}
 			return nil
 		}
 	}
 
-	//run command payload
-	res, err := run.Payload(Message{
-		Author:  msg.Author.Username,
-		Words:   words,
-		Content: msg.Content,
-		Channel: channel.Name,
-		Server:  server.Name,
+	//execute handler func with message context
+	err = run.Payload(&Context{
+		Message: msg,
+		bolt:    b,
 	})
-
 	if err != nil {
-		return err
-	}
-
-	//if a reply is returned send back to Discord
-	if res != "" {
-		reply := b.createReply(res, msg.ID, msg.ChannelID, msg.GuildID)
-		_, err := s.ChannelMessageSendComplex(msg.ChannelID, reply)
-		if err != nil {
-			return err
-		}
+		return fmt.Errorf("encountered an error while handling command (%s): %e", msg.Words[0], err)
 	}
 
 	//update run time
 	run.lastRun = time.Now()
-	b.Commands[run.Trigger] = run
+	b.commands[run.Trigger] = run
 	return nil
 }
 
-// basic wrapper function to create easy Discord responses
-func (b *bolt) createReply(content, message, channel, guild string) *dg.MessageSend {
+// createReploy is a basic wrapper function to map message data to the actual MessageSend struct
+func (b *Bolt) createReply(content, message, channel, guild string) *dg.MessageSend {
 	details := &dg.MessageReference{
 		MessageID: message,
 		ChannelID: channel,
@@ -217,8 +318,9 @@ func (b *bolt) createReply(content, message, channel, guild string) *dg.MessageS
 	}
 }
 
-// used to calculate the remaining time left in a timeout and returning it in a human-readable format
-func (b *bolt) getRemainingTimeout(timeout time.Time) string {
+// remainingTimeout calculates the amount of time left before a command can be run again. Returning a string
+// representing a readable version of the time left, example: 1h (1 hour)
+func (b *Bolt) remainingTimeout(timeout time.Time) string {
 	r := time.Until(timeout)
 	var (
 		timeLeft int
@@ -235,18 +337,23 @@ func (b *bolt) getRemainingTimeout(timeout time.Time) string {
 		}
 	}
 
+	//provide a user-friendly time string to send back to the user
 	return fmt.Sprintf("%d%s", timeLeft, metric)
 }
 
 // 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) {
+
+// roleCheck loops through the provided user role ID's grabs the role "name" and ensures the role is present
+// in the commands whitelist. If the role exists in the Command whitelist a true response is returned
+func (b *Bolt) roleCheck(guild string, roles []string, s *dg.Session, run Command) (bool, error) {
 	var found bool
-	//loop thru author roles
-	for _, r := range msg.Member.Roles {
+	//this needs a bit of love, looping through roles could get messy as server and role lists grow on big servers
+	//especially with the Role() call inside of the loop
+	for _, r := range roles {
 		//get role name from ID
-		n, err := s.State.Role(msg.GuildID, r)
+		n, err := s.State.Role(guild, r)
 		if err != nil {
-			return false, err
+			return false, fmt.Errorf("failed to get role from ID %s\n%e", guild, err)
 		}
 		//does this role exist in command roles
 		check := slices.Contains(run.Roles, n.Name)
@@ -256,27 +363,19 @@ func (b *bolt) roleCheck(msg *dg.MessageCreate, s *dg.Session, run Command) (boo
 		}
 	}
 
-	//can't find role, don't run command, alert user of missing permissions
-	if !found {
-		reply := b.createReply("you do not have permissions to run that command", msg.ID, msg.ChannelID, msg.GuildID)
-		_, err := s.ChannelMessageSendComplex(msg.ChannelID, reply)
-		if err != nil {
-			return false, err
-		}
-		return false, nil
-	}
-
-	return true, nil
+	return found, nil
 }
 
-// check if the command timeout has been met, responding with remaining time if timeout has not been met yet.
-func (b *bolt) timeoutCheck(msg *dg.MessageCreate, s *dg.Session, run Command) (bool, error) {
+// timeoutCheck determines if a Command timeout has expired, if it hasn't expired a response is sent back to the message alerting the user
+// of the remaining time
+func (b *Bolt) timeoutCheck(msgID, channelID, guildID string, s *dg.Session, run Command) (bool, error) {
 	wait := run.lastRun.Add(run.Timeout)
-	if !time.Now().After(wait) {
-		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)
+	now := time.Now()
+	if !now.After(wait) && !now.Equal(wait) {
+		reply := b.createReply(fmt.Sprintf("that command cannot be run for another %s", b.remainingTimeout(wait)), msgID, channelID, guildID)
+		_, err := s.ChannelMessageSendComplex(channelID, reply)
 		if err != nil {
-			return false, err
+			return false, fmt.Errorf("failed to send timeout response: %e", err)
 		}
 		return false, nil
 	}

command.go

@@ -1,24 +1,21 @@
 package bolt
 
-import "time"
+import (
+	"time"
+)
 
+// Command represents a bolt command in its entirety
 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 run again
-	lastRun time.Time     //timestamp of last command run
-	Roles   []string      //roles that can use command
-}
-
-// payload function type handling commands. The returned error is parsed and, if no error,
-// is detected then the response string (res) will be sent in response to the command message
-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
+	//the trigger phrase for the command, this field cannot include the command indicator. If the command is .ping
+	//Trigger should be "ping"
+	Trigger string
+	//handler function to run when command is detected
+	Payload Payload
+	//the amount of time that must pass before a command can be run again
+	Timeout time.Duration
+	//timestamp of last command run
+	lastRun time.Time
+	//the roles that are allowed to execute this command, the command author must have at least one of these roles
+	//in order to use the command
+	Roles []string
 }

go.mod

@@ -1,8 +1,11 @@
 module code.jakeyoungdev.com/jake/bolt
 
-go 1.24.0
+go 1.25.0
 
-require github.com/bwmarrin/discordgo v0.29.0
+require (
+	github.com/bwmarrin/discordgo v0.29.0
+	github.com/joho/godotenv v1.5.1
+)
 
 require (
 	github.com/gorilla/websocket v1.4.2 // indirect

go.sum

@@ -2,6 +2,8 @@ github.com/bwmarrin/discordgo v0.29.0 h1:FmWeXFaKUwrcL3Cx65c20bTRW+vOb6k8AnaP+Eg
 github.com/bwmarrin/discordgo v0.29.0/go.mod h1:NJZpH+1AfhIcyQsPeuBKsUtYrRnjkyu0kIVMCHkZtRY=
 github.com/gorilla/websocket v1.4.2 h1:+/TMaTYc4QFitKJxsQ7Yye35DkWvkdLcvGKqM+x0Ufc=
 github.com/gorilla/websocket v1.4.2/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
+github.com/joho/godotenv v1.5.1 h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0=
+github.com/joho/godotenv v1.5.1/go.mod h1:f4LDr5Voq0i2e/R5DDNOoa2zzDfwtkZa6DnEwAbqwq4=
 golang.org/x/crypto v0.0.0-20210421170649-83a5a9bb288b h1:7mWr3k41Qtv8XlltBkDkl8LoP3mpSgBW8BUoxtEdbXg=
 golang.org/x/crypto v0.0.0-20210421170649-83a5a9bb288b/go.mod h1:T9bdIzuCu7OtxOm1hfPfRQxPLYneinmdGuTeoZ9dtd4=
 golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=

message.go

@@ -0,0 +1,128 @@
+package bolt
+
+import (
+	"fmt"
+	"time"
+
+	dg "github.com/bwmarrin/discordgo"
+)
+
+const (
+	// the max length allowed for basic messages, if the message content exceeds this amount
+	// then messages are split unto chunks of max size
+	MSG_MAX_LENGTH = 2000
+)
+
+// command and message payload function type
+type Payload func(c *Context) error
+
+type MessageAttachment struct {
+	ID           string
+	URL          string
+	ProxyURL     string
+	Filename     string
+	ContentType  string
+	Width        int
+	Height       int
+	Size         int
+	DurationSecs float64
+}
+
+// Author contains basic information about message authors
+type Author struct {
+	Name  string
+	ID    string
+	Roles []string
+}
+
+// Message contains all needed data to handle message events
+type Message struct {
+	Author Author
+	//current message ID
+	ID string
+	//message content split on whitespace to allow for easy argument parsing with commands
+	Words []string
+	//entire message content unchanged
+	Content string
+	//channel message was sent in, name and ID
+	Channel   string
+	ChannelID string
+	//guild message was sent in, name and ID
+	Server   string
+	ServerID string
+	//message extras
+	Attachments []MessageAttachment //any attachments bound to the message
+	Mentions    []*dg.User          //users mention in the message with @
+}
+
+// Context is the struct passed to message and command handlers, it contains all needed message data as well as
+// some methods to make interaction with the message as easy as possible
+type Context struct {
+	Message *Message
+	bolt    *Bolt
+}
+
+// React applies the reaction to the message
+func (c *Context) React(emoji Reaction) error {
+	return c.bolt.MessageReactionAdd(c.Message.ChannelID, c.Message.ID, fmt.Sprint(emoji))
+}
+
+// Respond sends a response to the message, handling chunking if the message exceeds max length
+func (c *Context) Respond(res string) error {
+	if len(res) > MSG_MAX_LENGTH {
+		for len(res) > 0 {
+			//send full chunk size allowed by discord
+			sc := res[:MSG_MAX_LENGTH]
+			rep := c.bolt.createReply(sc, c.Message.ID, c.Message.ChannelID, c.Message.ServerID)
+			_, err := c.bolt.ChannelMessageSendComplex(c.Message.ChannelID, rep)
+			if err != nil {
+				return err
+			}
+			res = res[MSG_MAX_LENGTH:]
+
+			//if we have left than a full chunk send the rest and break the loop
+			if len(res) < MSG_MAX_LENGTH {
+				final := c.bolt.createReply(res, c.Message.ID, c.Message.ChannelID, c.Message.ServerID)
+				_, err := c.bolt.ChannelMessageSendComplex(c.Message.ChannelID, final)
+				if err != nil {
+					return err
+				}
+
+				break
+			}
+		}
+
+		return nil
+	}
+
+	//short enough message to send in one go, so ship it
+	rep := c.bolt.createReply(res, c.Message.ID, c.Message.ChannelID, c.Message.ServerID)
+	_, err := c.bolt.ChannelMessageSendComplex(c.Message.ChannelID, rep)
+	return err
+}
+
+// Delete removes the message from the current channel
+func (c *Context) Delete() error {
+	return c.bolt.ChannelMessageDelete(c.Message.ChannelID, c.Message.ID, nil)
+}
+
+// Timeout creates a user timeout for the supplied userID that lasts until duration is exceeded or the
+// timeout is cleared
+func (c *Context) Timeout(userId string, duration time.Time) error {
+	return c.bolt.GuildMemberTimeout(c.Message.ServerID, userId, &duration)
+}
+
+// ClearTimeout clears existing user timeouts, allowing them access again
+func (c *Context) ClearTimeout(userId string) error {
+	return c.bolt.GuildMemberTimeout(c.Message.ServerID, userId, nil)
+}
+
+// Mute handles muting a user from Voice Chat, this mute stays until it is Unmute()'d
+func (c *Context) Mute(userId string) error {
+	return c.bolt.GuildMemberMute(c.Message.ServerID, userId, true)
+}
+
+// Unmute removes a mute on the user, allowing them vc access again
+func (c *Context) Unmute(userId string) error {
+	return c.bolt.GuildMemberMute(c.Message.ServerID, userId, false)
+}

option.go

@@ -1,10 +1,50 @@
 package bolt
 
-type Option func(b *bolt)
+import (
+	dg "github.com/bwmarrin/discordgo"
+)
 
-// sets the substring that must be present at the beginning of the message to indicate a command
+type Option func(b *Bolt)
+type LogLevel int
+
+const (
+	LogLevelAll LogLevel = iota //log all messages, and errors
+	LogLevelCmd LogLevel = iota //log only commands and responses, and errors
+	LogLevelErr LogLevel = iota //log only errors
+)
+
+// WithIntents provides an option to use custom intents for the bot. Bolt comes preconfigured with the basic
+// intents needed to run a bot but those are completely overwritten by any supplied here
+func WithIntents(intents ...dg.Intent) Option {
+	return func(b *Bolt) {
+		var full dg.Intent
+		for _, i := range intents {
+			full |= i
+		}
+
+		b.Identify.Intents = full
+	}
+}
+
+// WithMaxGoroutines limits the amount of handler routines the bot is able to spawn at the same time. A lower value
+// may cause higher latency but may reduce resources needed to run bolt
+func WithMaxGoroutines(max int) Option {
+	return func(b *Bolt) {
+		b.maxRoutines = max
+	}
+}
+
+// WithIndicator sets the substring that must be present at the beginning of a message to trigger a
+// command, for example "." or "!"
 func WithIndicator(i string) Option {
-	return func(b *bolt) {
+	return func(b *Bolt) {
 		b.indicator = i
 	}
 }
+
+// WithLogLevel adjusts bolt logging verbosity
+func WithLogLevel(lvl LogLevel) Option {
+	return func(b *Bolt) {
+		b.logLvl = lvl
+	}
+}

reaction.go

@@ -0,0 +1,38 @@
+package bolt
+
+type Reaction string
+
+// a few easy-to-use emojis, Discordgo/Discord API requires them to be saved like this. Some appear "broken" but do not play friendly
+// when saved in-file
+const (
+	ReactionThumbsUp          Reaction = "👍"
+	ReactionThumbsDown        Reaction = "👎"
+	ReactionHundred           Reaction = "💯"
+	ReactionHeart             Reaction = "❤️"
+	ReactionPinkHeart         Reaction = "🩷"
+	ReactionOrangeHeart       Reaction = "🧡"
+	ReactionYellowHeart       Reaction = "💛"
+	ReactionGreenHeart        Reaction = "💚"
+	ReactionBlueHeart         Reaction = "💙"
+	ReactionBlackHeart        Reaction = "🖤"
+	ReactionPointUp           Reaction = "☝️"
+	ReactionPointDown         Reaction = "👇"
+	ReactionHotdog            Reaction = "🌭"
+	ReactionDog               Reaction = "🐶"
+	ReactionCat               Reaction = "🐱"
+	ReactionMonkey            Reaction = "🐒"
+	ReactionGiraffe           Reaction = "🦒"
+	ReactionDuck              Reaction = "🦆"
+	ReactionGoose             Reaction = "🪿"
+	ReactionWatermelon        Reaction = "🍉"
+	ReactionHoney             Reaction = "🍯"
+	ReactionSandwich          Reaction = "🥪"
+	ReactionPepper            Reaction = "🌶️"
+	ReactionNoPedestrians     Reaction = "🚷"
+	ReactionExclamation       Reaction = "❗"
+	ReactionDoubleExclamation Reaction = "‼️"
+	ReactionSkull             Reaction = "💀"
+	ReactionSpeakingHead      Reaction = "🗣️"
+	ReactionGreenCheck        Reaction = "✅"
+	ReactionDragon            Reaction = "🐉"
+)