README.md

@@ -1,70 +1,17 @@
 # bolt
 
-TODO
-pre-1. Break up msg handler method its insane
-pre-2. Copy main into README
-1. Read through code and ensure I didn't miss anything
-2. do research on intents for 'admin' jobs
-3. comments and README updates, things have changed
-4. determine adjustments to timeouts and contexts and const vs options for it
-5. Figure out why the exiting printing is going after terminal exit
-
----
-
-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.
+A fast [discordgo](https://github.com/bwmarrin/discordgo) wrapper for bootstrapping Discord bots.
 
 ## Usage
-### Token
+### Prerequisites
 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.
-```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.
-```go
-func Delete() error
-```
-The Delete method will delete the message from the text channel
-
 ### Example
 ```go
 package main
 
 import (
+	"fmt"
 	"strings"
 	"time"
 
@@ -72,10 +19,26 @@ import (
 	_ "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() {
-	b, err := bolt.New(bolt.WithLogLevel(bolt.LogLevelAll),
-		bolt.WithMaxGoroutines(150),
-		bolt.WithPermissions(bolt.MessagePermissions, bolt.AdminPermissions))
+	b, err := bolt.New(bolt.WithLogLevel(bolt.LogLevelAll))
 
 	if err != nil {
 		panic(err)
@@ -83,33 +46,47 @@ func main() {
 
 	b.AddCommands(
 		bolt.Command{
-			Trigger: "test",
-			Payload: func(msg *bolt.Message, admin bolt.AdminToolBox) error {
-				return msg.Respond("hi")
+			Trigger: "ping",
+			Payload: func(c *bolt.Context) error {
+				return c.Respond("pong")
 			},
 		},
+		bolt.Command{
+			Trigger: "wait",
+			Payload: func(c *bolt.Context) error {
+				return c.Respond("okay")
+			},
+			Timeout: time.Second * 25,
+			Roles:   []string{"user"},
+		},
 		bolt.Command{
 			Trigger: "timeout",
-			Payload: func(msg *bolt.Message, tools bolt.AdminToolBox) error {
-				if len(msg.Mentions) > 0 {
-					err := tools.Timeout(msg.Mentions[0].ID, msg.ServerID, time.Now().Add(time.Minute*5))
-					if err != nil {
-						return err
+			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 msg.Respond("done")
+				return nil
 			},
 			Roles: []string{"admin"},
 		},
 	)
 
-	b.AddMessageHandler(func(msg *bolt.Message, tools bolt.AdminToolBox) error {
-		if strings.Contains(msg.Content, "swear word") {
-			return tools.Timeout(msg.Author.ID, msg.ServerID, time.Now().Add(time.Hour*1))
+	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 msg.Content == "im a menace in VC" {
-			return tools.Mute(msg.Author.ID, msg.ServerID)
+		if c.Message.Content == "im going to yell in VoiceChat" {
+			return c.Mute(c.Message.Author.ID)
 		}
 		return nil
 	})
@@ -120,8 +97,8 @@ func main() {
 	}
 }
 
-
 ```
 
 ## 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

@@ -25,6 +25,14 @@ const (
 	//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.IntentGuildMessageReactions
 )
 
 type bolt struct {
@@ -53,6 +61,7 @@ type Bolt interface {
 	//filtered methods
 	stop() error
 	msgEventHandler(s *dg.Session, msg *dg.MessageCreate)
+	mapEventToMsg(msg *dg.MessageCreate, channel *dg.Channel, server *dg.Guild) Message
 	handleCommand(msgEvent *Message, lg int) error
 	handleMessage(event *Message) error
 	createReply(content, message, channel, guild string) *dg.MessageSend
@@ -61,6 +70,7 @@ type Bolt interface {
 	timeoutCheck(msgID, channelID, guildID string, s *dg.Session, run Command) (bool, error)
 }
 
+// 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 {
@@ -73,16 +83,15 @@ func New(opts ...Option) (Bolt, error) {
 	}
 
 	b := &bolt{
-		Session:   bot,
-		commands:  make(map[string]Command, 0),
-		logLvl:    LogLevelAll,
-		indicator: DEFAULT_INDICATOR,
-		wg:        sync.WaitGroup{},
-		// admin:       false,
+		Session:     bot,
+		commands:    make(map[string]Command, 0),
+		logLvl:      LogLevelAll,
+		indicator:   DEFAULT_INDICATOR,
+		wg:          sync.WaitGroup{},
 		maxRoutines: DEFAULT_MAX_GOROUTINES,
 	}
 
-	//apply options
+	b.Identify.Intents = DEFAULT_INTENTS
 	for _, opt := range opts {
 		opt(b)
 	}
@@ -109,7 +118,7 @@ func (b *bolt) Start() error {
 	signal.Notify(sigChannel, os.Interrupt)
 	<-sigChannel
 
-	//move this to an option, maybe?
+	//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{}, 0)
@@ -129,8 +138,8 @@ func (b *bolt) Start() error {
 	return b.stop()
 }
 
-// AddCommands registers command handlers, any messages that begin with the command indicator will be forwarded
-// to a handler if the command string matches a trigger
+// 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
@@ -138,18 +147,22 @@ func (b *bolt) AddCommands(cmd ...Command) {
 }
 
 // AddMessageHandler registers the generic message handler, any messages that are not commands will be forwarded
-// to the Payload
+// to the handler
 func (b *bolt) AddMessageHandler(p Payload) {
 	b.msgHandlerf = p
 }
 
-// stop closes the websocket connection with Discord
+// stop closes the websocket connection to Discord
 func (b *bolt) stop() error {
 	return b.Close()
 }
 
 // msgEventHandler is a beefy boy that handles message logging, command parsing, and executing payload functions. It needs cleanup then
 // i'll worry about this comment
+
+// 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)
@@ -165,7 +178,7 @@ func (b *bolt) msgEventHandler(s *dg.Session, msg *dg.MessageCreate) {
 
 	//the bot will ignore it's own messages to prevent command loops
 	if msg.Author.ID == s.State.User.ID {
-		if b.logLvl != LogLevelErr && b.logLvl != LogLevelNone {
+		if b.logLvl != LogLevelErr {
 			log.Printf("< %s | %s | %s > %s\n", server.Name, channel.Name, msg.Author.Username, msg.Content)
 		}
 		return
@@ -175,7 +188,35 @@ func (b *bolt) msgEventHandler(s *dg.Session, msg *dg.MessageCreate) {
 		log.Printf("< %s | %s | %s > %s\n", server.Name, channel.Name, msg.Author.Username, msg.Content)
 	}
 
-	//this hsould be moved to a parseMessageEvent method
+	m := b.mapEventToMsg(msg, channel, server)
+	lg := len(b.indicator)
+	if msg.Content[:lg] == b.indicator {
+		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
+		})
+	}
+}
+
+// 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,
@@ -218,33 +259,10 @@ func (b *bolt) msgEventHandler(s *dg.Session, msg *dg.MessageCreate) {
 		m.Attachments = att
 	}
 
-	lg := len(b.indicator)
-	if msg.Content[:lg] == b.indicator {
-		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
-		})
-	}
+	return m
 }
 
-// handleMessage forwards the message data to the handler function, if one was set
+// 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{
@@ -256,31 +274,35 @@ func (b *bolt) handleMessage(event *Message) error {
 	return nil
 }
 
-// handleCommand maps the first word of the message to the command payload, if it exists. Checking the timeout
-// and role restrictions before forwarding the message to the Command Payload. If restrictions have not been met
-// a response is sent to the message
+// 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, maybe log or respond to author
+		return nil //command doesn't exist
 	}
 
-	//has command met its timeout requirements
+	//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.ServerID, msg.Author.Roles, b.Session, run)
 		if err != nil {
 			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 {
@@ -290,6 +312,7 @@ func (b *bolt) handleCommand(msg *Message, lg int) error {
 		}
 	}
 
+	//execute handler func with message context
 	err = run.Payload(&Context{
 		Message: msg,
 		bolt:    b,
@@ -304,7 +327,7 @@ func (b *bolt) handleCommand(msg *Message, lg int) error {
 	return nil
 }
 
-// basic wrapper function to create easy Discord responses
+// 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,
@@ -318,7 +341,8 @@ 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
+// 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 (
@@ -336,14 +360,18 @@ func (b *bolt) remainingTimeout(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
+
+// 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, there may be a better way to check for this UNION
-	//TODO: improve role search performance to support bigger lists
+	//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(guild, r)
@@ -358,14 +386,11 @@ func (b *bolt) roleCheck(guild string, roles []string, s *dg.Session, run Comman
 		}
 	}
 
-	//can't find role, don't run command
-	if !found {
-		return false, nil
-	}
-
-	return true, nil
+	return found, nil
 }
 
+// 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)
 	now := time.Now()

command.go

@@ -4,43 +4,18 @@ import (
 	"time"
 )
 
-// custom Discord commands
+// 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 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 the command
+	//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
 }
-
-// type adminToolbox struct {
-// 	*bolt
-// }
-// type AdminToolBox interface {
-// 	Timeout(userId, serverId string, duration time.Time) error
-// 	ClearTimeout(userId, serverId string) error
-// 	Mute(userId, serverId string) error
-// 	Unmute(userId, serverId string) error
-// }
-
-// func NewToolbox(b *bolt) AdminToolBox {
-// 	return &adminToolbox{
-// 		bolt: b,
-// 	}
-// }
-
-// func (a *adminToolbox) Timeout(userId, serverId string, duration time.Time) error {
-// 	return a.GuildMemberTimeout(serverId, userId, &duration)
-// }
-
-// func (a *adminToolbox) ClearTimeout(userId, serverId string) error {
-// 	return a.GuildMemberTimeout(serverId, userId, nil)
-// }
-
-// func (a *adminToolbox) Mute(userId, serverId string) error {
-// 	return a.GuildMemberMute(serverId, userId, true)
-// }
-
-// func (a *adminToolbox) Unmute(userId, serverId string) error {
-// 	return a.GuildMemberMute(serverId, userId, false)
-// }

message.go

@@ -8,14 +8,14 @@ import (
 )
 
 const (
-	// the max length allowed for basic messages
+	// 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 payload functions, any strings returned are sent as a response to the command
+// command and message payload function type
 type Payload func(c *Context) error
 
-// message attachment details
 type MessageAttachment struct {
 	ID           string
 	URL          string
@@ -28,31 +28,41 @@ type MessageAttachment struct {
 	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
-	ID          string              //message ID
-	Words       []string            //message data split on whitespaces
-	Content     string              //entire message data string
-	Channel     string              //name of channel message was sent in
-	ChannelID   string              //ID of channel message was sent in
-	Server      string              //name of guild message was sent in
-	ServerID    string              //ID of guild message was sent in
+	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
+	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 reaction to the message
+// 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))
 }
@@ -85,7 +95,7 @@ func (c *Context) Respond(res string) error {
 		return nil
 	}
 
-	//short enough message to send in one go
+	//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
@@ -96,18 +106,23 @@ 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

@@ -5,60 +5,44 @@ import (
 )
 
 type Option func(b *bolt)
-
 type LogLevel int
 
-type Permission dg.Intent
-
-type HandlerLevel 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
-	LogLevelNone LogLevel = iota //log nothing, let the handlers sort it out
-
-	msgPerms dg.Intent = dg.IntentGuilds |
-		dg.IntentGuildMembers |
-		dg.IntentGuildPresences |
-		dg.IntentMessageContent |
-		dg.IntentsGuildMessages |
-		dg.IntentGuildMessageReactions
-
-	MessagePermissions Permission = Permission(msgPerms)
-	AdminPermissions   Permission = 0 //fake
-	//we also need a ModeratorPermissions for banning, kicking, etc.
+	LogLevelAll LogLevel = iota //log all messages, and errors
+	LogLevelCmd LogLevel = iota //log only commands and responses, and errors
+	LogLevelErr LogLevel = iota //log only errors
 )
 
-func WithPermissions(perms ...Permission) Option {
+// 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 fullPerms dg.Intent
-		for _, p := range perms {
-			// if p == AdminPermissions {
-			// 	b.admin = true
-			// }
-			fullPerms |= dg.Intent(p)
+		var full dg.Intent
+		for _, i := range intents {
+			full |= i
 		}
 
-		//set intents
-		b.Identify.Intents = fullPerms
+		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
 	}
 }
 
-// sets the substring that must be present at the beginning of the message to indicate a command
+// 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) {
 		b.indicator = i
 	}
 }
 
-// sets the log level to determine how much bolt logs
+// WithLogLevel adjusts bolt logging verbosity
 func WithLogLevel(lvl LogLevel) Option {
 	return func(b *bolt) {
 		b.logLvl = lvl

reaction.go

@@ -1,9 +1,9 @@
 package bolt
 
-// built-in Discord reactions
 type Reaction string
 
-// a few easy-to-use emojis, Discordgo/Discord API requires them to be saved like this.
+// 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 = "👎"