Merge pull request 'new/message-deletes' (#5) from new/message-deletes into main

Reviewed-on: #5

README.md

@@ -1,28 +1,53 @@
 # bolt
 
-The nuts and bolts of a Discord bots. Bolt is a wrapper for [discordgo](https://github.com/bwmarrin/discordgo) that provides very quick bootstrapping for simple Discord bots. 
+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.
 
 ## Usage
 ### Token
 Bolt requires a Discord bot token to run, the token must be set as an environment variable labeled "DISCORD_TOKEN"
 
 ### Commands
-Commands are represented by the Command struct. Any roles in the Command struct can run the command, if the Roles field is empty anyone can run the command.
+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 the command
+	Roles   []string      //roles that can use command, if none are set anyone can run
 }
 ```
 
 ### Payload
-Payload functions are executed when a command is detected, if no errors are returned and the returned string is not empty, then the returned string is sent in reply to the command message.
+Payload functions are executed when a command is detected
 ```go
-type Payload func(msg Message) (string, error)
+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
@@ -32,35 +57,44 @@ import (
 	"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(bolt.WithLogLevel(bolt.LogLevelCmd))
+	b, err := bolt.New(bolt.WithLogLevel(bolt.LogLevelCmd))
+	if err != nil {
+		panic(err)
+	}
 
 	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{
 			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,
 			Roles:   []string{"admin"},
@@ -68,11 +102,12 @@ func main() {
 	)
 
 	//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 {
 		panic(err)
 	}
 }
+
 ```
 
 ## Development

bolt.go

@@ -20,7 +20,8 @@ const (
 		dg.IntentGuildMembers |
 		dg.IntentGuildPresences |
 		dg.IntentMessageContent |
-		dg.IntentsGuildMessages
+		dg.IntentsGuildMessages |
+		dg.IntentGuildMessageReactions
 )
 
 // basic bot structure containing discordgo connection as well as the command map
@@ -37,27 +38,23 @@ type Bolt interface {
 	//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
+	handleCommand(msgEvent *MessageCreateEvent, s *dg.Session, 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)
+	roleCheck(guild string, roles []string, s *dg.Session, run Command) (bool, error)
-	timeoutCheck(msg *dg.MessageCreate, s *dg.Session, run Command) (bool, error)
+	timeoutCheck(msgID, channelID, guildID string, s *dg.Session, run Command) (bool, error)
-}
-
-// setup
-func init() {
-	//validate environment variables
-	_, check := os.LookupEnv(TOKEN_ENV_VAR)
-	if !check {
-		log.Fatalf("the %s environment variable must be set", TOKEN_ENV_VAR)
-	}
 }
 
 // create a new bolt interface
-func New(opts ...Option) Bolt {
+func New(opts ...Option) (Bolt, error) {
+	_, check := os.LookupEnv(TOKEN_ENV_VAR)
+	if !check {
+		return nil, fmt.Errorf("environment variable %s must be set", TOKEN_ENV_VAR)
+	}
+
 	bot, err := dg.New(fmt.Sprintf("Bot %s", os.Getenv(TOKEN_ENV_VAR)))
 	if err != nil {
-		log.Fatal(err)
+		return nil, fmt.Errorf("failed to create Discord session: %e", err)
 	}
 	bot.Identify.Intents = BOT_INTENTS
 
@@ -69,23 +66,23 @@ func New(opts ...Option) Bolt {
 	//set default command indicator
 	b.indicator = "."
 
-	//apply options to bolt
+	//apply options
 	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 call
-// call that handles safe shutdown of the bot
+// that handles safe shutdown of the bot
 func (b *bolt) Start() error {
 	//register commands and open connection
 	b.AddHandler(b.messageHandler)
 
 	err := b.Open()
 	if err != nil {
-		return err
+		return fmt.Errorf("failed to open websocket connection with Discord: %e", err)
 	}
 
 	//safe shutdown handler
@@ -112,24 +109,34 @@ func (b *bolt) AddCommands(cmd ...Command) {
 	}
 }
 
-// handler function that parses message data and executes any command payloads
+// handler function that parses message data, handles logging the message based on logLevel, and executes
+// the payload function in a goroutine
 func (b *bolt) messageHandler(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
+	//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]"
+	}
+
+	//the bot will ignore it's own messages to prevent command loops
+	if msg.Author.ID == s.State.User.ID {
+		if b.logLvl == LogLevelCmd || b.logLvl == LogLevelAll {
+			//log command responses
+			log.Printf("< %s | %s | %s > %s\n", server.Name, channel.Name, msg.Author.Username, msg.Content)
+		}
+		return
 	}
 
 	if b.logLvl == LogLevelAll {
@@ -137,43 +144,47 @@ func (b *bolt) messageHandler(s *dg.Session, msg *dg.MessageCreate) {
 		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
-	}
-
 	//does the message have the command indicator
 	lg := len(b.indicator)
 	if msg.Content[:lg] == b.indicator {
-		err := b.handleCommand(msg, s, server, channel, lg)
+		mCreate := &MessageCreateEvent{
+			AuthorUsername: msg.Author.Username,
+			AuthorID:       msg.Author.ID,
+			AuthorRoles:    msg.Member.Roles,
+			MsgID:          msg.ID,
+			Msg:            msg.Content,
+			MsgChanID:      msg.ChannelID,
+			MsgGuildID:     msg.GuildID,
+			MsgAttachments: msg.Attachments,
+		}
+
+		if b.logLvl == LogLevelCmd {
+			//log commands
+			log.Printf("< %s | %s | %s > %s\n", mCreate.MsgGuildName, mCreate.MsgChanName, mCreate.AuthorUsername, mCreate.Msg)
+		}
+
+		//handled in its own goroutine to allow for async commands
+		go func() {
+			err := b.handleCommand(mCreate, s, lg)
 			if err != nil {
 				log.Println(err)
-			return
 			}
+		}()
 	}
 }
 
 // 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(msgEvent *MessageCreateEvent, s *dg.Session, lg int) error {
-	if b.logLvl == LogLevelCmd {
+	words := strings.Split(msgEvent.Msg, " ")
-		//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:]]
 	if !ok {
 		return nil //command doesn't exist, maybe log or respond to author
 	}
 
 	//has command met its timeout requirements
-	tc, err := b.timeoutCheck(msg, s, run)
+	tc, err := b.timeoutCheck(msgEvent.MsgID, msgEvent.MsgChanID, msgEvent.MsgGuildID, s, run)
 	if err != nil {
-		return err
+		return fmt.Errorf("failed to calculate timeout for %s\n%e", run.Trigger, err)
 	}
 	if !tc {
 		return nil
@@ -181,35 +192,58 @@ func (b *bolt) handleCommand(msg *dg.MessageCreate, s *dg.Session, server *dg.Gu
 
 	//does user have correct permissions
 	if run.Roles != nil {
-		check, err := b.roleCheck(msg, s, run)
+		check, err := b.roleCheck(msgEvent.MsgGuildID, msgEvent.AuthorRoles, s, run)
+		if err != nil {
+			return fmt.Errorf("failed to perform permission checks for %s\n%e", run.Trigger, err)
+		}
+		if !check {
+			reply := b.createReply("you do not have permissions to run that command", msgEvent.MsgID, msgEvent.MsgChanID, msgEvent.MsgGuildID)
+			_, err := s.ChannelMessageSendComplex(msgEvent.MsgChanID, reply)
 			if err != nil {
 				return err
 			}
-		if !check {
 			return nil
 		}
 	}
 
-	//run command payload
+	//populate message struct exposed to client
-	res, err := run.Payload(Message{
+	plMsg := Message{
-		Author:  msg.Author.Username,
+		Author:    msgEvent.AuthorUsername,
+		ID:        msgEvent.AuthorID,
+		msgID:     msgEvent.MsgID,
 		Words:     words,
-		Content: msg.Content,
+		Content:   msgEvent.Msg,
-		Channel: channel.Name,
+		Channel:   msgEvent.MsgChanName,
-		Server:  server.Name,
+		channelID: msgEvent.MsgChanID,
+		Server:    msgEvent.MsgGuildName,
+		serverID:  msgEvent.MsgGuildID,
+		sesh:      b,
+	}
+
+	//check for file attachments
+	if len(msgEvent.MsgAttachments) > 0 {
+		var att []MessageAttachment
+		for _, a := range msgEvent.MsgAttachments {
+			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,
 			})
-
-	if err != nil {
-		return err
 		}
 
-	//if a reply is returned send back to Discord
+		plMsg.Attachments = att
-	if res != "" {
-		reply := b.createReply(res, msg.ID, msg.ChannelID, msg.GuildID)
-		_, err := s.ChannelMessageSendComplex(msg.ChannelID, reply)
-		if err != nil {
-			return err
 	}
+
+	//run command payload
+	err = run.Payload(plMsg)
+	if err != nil {
+		return fmt.Errorf("failed to execute payload function: %e", err)
 	}
 
 	//update run time
@@ -254,15 +288,15 @@ 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) {
+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
-	for _, r := range msg.Member.Roles {
+	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)
@@ -272,13 +306,8 @@ 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
+	//can't find role, don't run command
 	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
 	}
 
@@ -286,13 +315,13 @@ func (b *bolt) roleCheck(msg *dg.MessageCreate, s *dg.Session, run Command) (boo
 }
 
 // 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) {
+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)
+		reply := b.createReply(fmt.Sprintf("that command cannot be run for another %s", b.getRemainingTimeout(wait)), msgID, channelID, guildID)
-		_, err := s.ChannelMessageSendComplex(msg.ChannelID, reply)
+		_, 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,6 +1,8 @@
 package bolt
 
-import "time"
+import (
+	"time"
+)
 
 // custom Discord commands
 type Command struct {
@@ -12,13 +14,4 @@ type Command struct {
 }
 
 // command payload functions, any strings returned are sent as a response to the command
-type Payload func(msg Message) (string, error)
+type Payload func(msg Message) error
-
-// message information passed to payload function
-type Message struct {
-	Author  string   //username of message author
-	Words   []string //words from message split on whitespace
-	Content string   //entire message content
-	Channel string   //message channel
-	Server  string   //message guild
-}

message.go

@@ -0,0 +1,68 @@
+package bolt
+
+import (
+	"fmt"
+
+	dg "github.com/bwmarrin/discordgo"
+)
+
+// the message struct is passed to the command payload providing basic
+// message information and needed methods
+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 response to 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
+}
+
+// deletes the message from the channel
+func (m *Message) Delete() error {
+	return m.sesh.ChannelMessageDelete(m.channelID, m.msgID, nil)
+}
+
+// this struct has all of the needed information from the messageCreate event so that
+// commands can be run asynchronously. Passing the messageCreate to payloads can block routines
+type MessageCreateEvent struct {
+	AuthorUsername string
+	AuthorID       string
+	AuthorRoles    []string
+	MsgID          string
+	Msg            string
+	MsgChanID      string
+	MsgChanName    string
+	MsgGuildID     string
+	MsgGuildName   string
+	MsgAttachments []*dg.MessageAttachment
+}
+
+// message attachment details
+type MessageAttachment struct {
+	ID           string
+	URL          string
+	ProxyURL     string
+	Filename     string
+	ContentType  string
+	Width        int
+	Height       int
+	Size         int
+	DurationSecs float64
+}

reaction.go

@@ -0,0 +1,38 @@
+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.
+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 = "🐉"
+)