emoji updates

- no fatal calls
- more descriptive errors

LICENSE

@@ -0,0 +1,19 @@
+Copyright 2025 jake
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,9 +1,110 @@
 # 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
-bolt is a wrapper for Discordgo to provide very quick and easy setup for simple Discord bots. The only code required to run bolt is 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.
+## 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 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 (
+	"time"
+
+	"code.jakeyoungdev.com/jake/bolt"
+)
+
+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, err := bolt.New(bolt.WithLogLevel(bolt.LogLevelCmd))
+	if err != nil {
+		panic(err)
+	}
+
+	b.AddCommands(
+		// 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) error {
+				return msg.Respond("pong")
+			},
+		},
+		// .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) error {
+				return msg.Respond(time.Now().String())
+			},
+			Timeout: time.Second * 25,
+		},
+		// .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) error {
+				return msg.Respond("admin")
+			},
+			Timeout: time.Second * 10,
+			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()
+	if err != nil {
+		panic(err)
+	}
+}
+
+```
 
 ## Development
-bolt is in heavy development at the moment and may break occasionally before a v1 release, it is currently in a testing phase and should not be used until tagged.
+bolt is in development at the moment and may break occasionally before a v1 release

bolt.go

@@ -4,7 +4,10 @@ import (
 	"fmt"
 	"log"
 	"os"
+	"os/signal"
+	"slices"
 	"strings"
+	"syscall"
 	"time"
 
 	dg "github.com/bwmarrin/discordgo"
@@ -13,73 +16,96 @@ import (
 const (
 	TOKEN_ENV_VAR = "DISCORD_TOKEN" //label for token environment variable
 
-	// BOT_INTENTS = dg.IntentsAllWithoutPrivileged |
-	// 	dg.IntentGuildMembers |
-	// 	dg.IntentGuildPresences |
-	// 	dg.IntentMessageContent |
-	// 	dg.IntentsGuildMessages
-
-	BOT_INTENTS = dg.IntentGuildMembers |
+	BOT_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
+	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 {
 	Start() error
-	Stop() error
-	AddCommands(cmd Command)
+	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
-}
-
-// 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)
-	}
+	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)
 }
 
 // create a new bolt interface
-func New() *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
 
-	return &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 = "."
+
+	//apply options to bolt
+	for _, opt := range opts {
+		opt(b)
+	}
+
+	return b, nil
 }
 
-// adds command handler and starts the bot
+// 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)
 
-	return b.Open()
+	err := b.Open()
+	if err != nil {
+		return fmt.Errorf("failed to open websocket connection with Discord: %e", err)
+	}
+
+	//safe shutdown handler
+	sigChannel := make(chan os.Signal, 1)
+	signal.Notify(sigChannel, syscall.SIGINT)
+	<-sigChannel
+
+	if err := b.stop(); err != nil {
+		return err
+	}
+
+	return nil
 }
 
 // stops the bot
-func (b *bolt) Stop() error {
+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
+		b.commands[c.Trigger] = c
 	}
 }
 
@@ -88,73 +114,122 @@ 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]"
 	}
 
-	//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 command responses
+			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 msg.Content[:1] == "." {
-		words := strings.Split(msg.Content, " ")
-		run, ok := b.Commands[words[0]]
-		if !ok {
-			return //command doesn't exist, maybe log or respond to author
-		}
-
-		//has command met its timeout requirements
-		if !time.Now().After(run.LastRun.Add(run.Timeout)) {
-			return //running too soon, maybe respond letting know time remaining
-		}
-
-		//run command payload
-		res, err := run.Payload(Message{
-			Author: Author{
-				Username: msg.Author.Username,
-				Roles:    msg.Member.Roles,
-			},
-			Words:   words,
-			Message: msg.Content,
-			Channel: channel.Name,
-			Server:  server.Name,
-		})
+	if b.logLvl == LogLevelAll {
+		//log message
+		log.Printf("< %s | %s | %s > %s\n", server.Name, channel.Name, msg.Author.Username, msg.Content)
+	}
 
+	//does the message have the command indicator
+	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 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 {
-				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 {
+	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:]]
+	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)
+	if err != nil {
+		return fmt.Errorf("failed to calculate timeout for %s\n%e", run.Trigger, err)
+	}
+	if !tc {
+		return nil
+	}
+
+	//does user have correct permissions
+	if run.Roles != nil {
+		check, err := b.roleCheck(msg, s, run)
+		if err != nil {
+			return fmt.Errorf("failed to perform permission checks for %s\n%e", run.Trigger, err)
+		}
+		if !check {
+			return nil
+		}
+	}
+
+	plMsg := Message{
+		Author:    msg.Author.Username,
+		ID:        msg.Author.ID,
+		msgID:     msg.ID,
+		Words:     words,
+		Content:   msg.Content,
+		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,
+			})
 		}
 
-		//update run time
-		run.LastRun = time.Now()
-		b.Commands[run.Trigger] = run
+		plMsg.Attachments = att
 	}
+
+	//run command payload
+	err = run.Payload(plMsg)
+	if err != nil {
+		return fmt.Errorf("failed to execute payload function: %e", err)
+	}
+
+	//update run time
+	run.lastRun = time.Now()
+	b.commands[run.Trigger] = run
+	return nil
 }
 
 // basic wrapper function to create easy Discord responses
@@ -170,3 +245,71 @@ func (b *bolt) createReply(content, message, channel, guild string) *dg.MessageS
 		Reference: details,
 	}
 }
+
+// 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 {
+	r := time.Until(timeout)
+	var (
+		timeLeft int
+		metric   string
+	)
+	timeLeft = int(r.Hours())
+	metric = "h"
+	if timeLeft < 1 {
+		timeLeft = int(r.Minutes())
+		metric = "m"
+		if timeLeft < 1 {
+			timeLeft = int(r.Seconds())
+			metric = "s"
+		}
+	}
+
+	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) {
+	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 {
+		//get role name from ID
+		n, err := s.State.Role(msg.GuildID, r)
+		if err != nil {
+			return false, fmt.Errorf("failed to get role from ID %s\n%e", msg.GuildID, err)
+		}
+		//does this role exist in command roles
+		check := slices.Contains(run.Roles, n.Name)
+		if check {
+			found = true
+			break
+		}
+	}
+
+	//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, fmt.Errorf("failed to send permission response: %e", err)
+		}
+		return false, nil
+	}
+
+	return true, 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) {
+	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)
+		if err != nil {
+			return false, fmt.Errorf("failed to send timeout response: %e", err)
+		}
+		return false, nil
+	}
+
+	return true, nil
+}

command.go

@@ -1,30 +1,17 @@
 package bolt
 
-import "time"
+import (
+	"time"
+)
 
+// custom Discord commands
 type Command struct {
-	Trigger string        //.command that triggers payload INCLUDING the '.'
+	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
+	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
 }
 
-// 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) (res string, err error)
-
-// contains the basic information needed for a message command
-type Message struct {
-	Author  Author
-	Words   []string //words from message split on whitespace
-	Message string   //entire message content
-	Channel string   //channel message was sent in
-	Server  string   //guild message was sent in
-}
-
-// username and roles of message authors
-type Author struct {
-	Username string
-	Roles    []string
-}
+// command payload functions, any strings returned are sent as a response to the command
+type Payload func(msg Message) error

message.go

@@ -0,0 +1,80 @@
+package bolt
+
+import "fmt"
+
+//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 = "🐉"
+)
+
+// 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

@@ -0,0 +1,25 @@
+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
+	}
+}