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>

README.md

@@ -1,56 +1,97 @@
 # 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
 package main
 
 import (
-	"log"
-	"os"
-	"os/signal"
-	"syscall"
 	"time"
 
 	"code.jakeyoungdev.com/jake/bolt"
-	_ "github.com/joho/godotenv/autoload"
 )
 
 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 := bolt.New(bolt.WithLogLevel(bolt.LogLevelCmd))
 
 	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{
 			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{
 			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,
 		},
-        // .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()

bolt.go

@@ -26,8 +26,9 @@ const (
 // 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
+	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
+	logLvl      LogLevel           //determines how much the bot logs
 }
 
 type Bolt interface {
@@ -62,13 +63,15 @@ func New(opts ...Option) Bolt {
 
 	b := &bolt{
 		Session:  bot,
-		Commands: make(map[string]Command, 0),
+		commands: make(map[string]Command, 0),
+		logLvl:   LogLevelAll,
 	}
 	//set default command indicator
 	b.indicator = "."
 
-	for _, o := range opts {
+	//apply options to bolt
-		o(b)
+	for _, opt := range opts {
+		opt(b)
 	}
 
 	return b
@@ -85,6 +88,7 @@ func (b *bolt) Start() error {
 		return err
 	}
 
+	//safe shutdown handler
 	sigChannel := make(chan os.Signal, 1)
 	signal.Notify(sigChannel, syscall.SIGINT)
 	<-sigChannel
@@ -104,7 +108,7 @@ func (b *bolt) stop() error {
 // adds commands to bot command map for use
 func (b *bolt) AddCommands(cmd ...Command) {
 	for _, c := range cmd {
-		b.Commands[c.Trigger] = c
+		b.commands[c.Trigger] = c
 	}
 }
 
@@ -122,17 +126,23 @@ func (b *bolt) messageHandler(s *dg.Session, msg *dg.MessageCreate) {
 		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
 	if len(msg.Content) == 0 {
-		msg.Content = "GIF/IMAGE"
+		msg.Content = "[Embedded Content]"
 	}
 
-	//log message
+	if b.logLvl == LogLevelAll {
-	log.Printf("< %s | %s | %s > %s\n", server.Name, channel.Name, msg.Author.Username, msg.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
 	if msg.Author.ID == s.State.User.ID {
+		if b.logLvl == LogLevelCmd {
+			//log commands
+			log.Printf("< %s | %s | %s > %s\n", server.Name, channel.Name, msg.Author.Username, msg.Content)
+		}
 		return
 	}
 
@@ -149,8 +159,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
 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, " ")
-	run, ok := b.Commands[words[0][lg:]]
+	run, ok := b.commands[words[0][lg:]]
 	if !ok {
 		return nil //command doesn't exist, maybe log or respond to author
 	}
@@ -175,31 +190,48 @@ func (b *bolt) handleCommand(msg *dg.MessageCreate, s *dg.Session, server *dg.Gu
 		}
 	}
 
-	//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,
+		serverID:  server.ID,
+		sesh:      b,
+	}
 
+	//check for file attachments
+	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,
+			})
+		}
+
+		plMsg.Attachments = att
+	}
+
+	//run command payload
+	err = run.Payload(plMsg)
 	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
-		}
-	}
-
 	//update run time
 	run.lastRun = time.Now()
-	b.Commands[run.Trigger] = run
+	b.commands[run.Trigger] = run
 	return nil
 }
 
@@ -241,7 +273,8 @@ func (b *bolt) getRemainingTimeout(timeout time.Time) string {
 // 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) {
 	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 {
 		//get role name from ID
 		n, err := s.State.Role(msg.GuildID, r)

command.go

@@ -1,24 +1,17 @@
 package bolt
 
-import "time"
+import (
+	"time"
+)
 
+// custom Discord commands
 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
+	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
+	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
-}

message.go

@@ -0,0 +1,57 @@
+package bolt
+
+import "fmt"
+
+//built-in Discord reactions
+type Reaction string
+
+const (
+	ReactionThumbsUp      Reaction = ":+1:"
+	ReactionThumbsDown    Reaction = ":-1:"
+	ReactionPointUp       Reaction = ":point_up:"
+	ReactionPointDown     Reaction = ":point_down:"
+	ReactionHotdog        Reaction = ":hotdog:"
+	ReactionGiraffe       Reaction = ":giraffe:"
+	ReactionWatermelon    Reaction = ":watermelon:"
+	ReactionNoPedestrians Reaction = ":no_pedestrian:"
+)
+
+// 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
+}

option.go

@@ -2,9 +2,24 @@ package 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
 func WithIndicator(i string) Option {
 	return func(b *bolt) {
 		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
+	}
+}