Update README.md

- avoiding confusion w long functions for naked returns

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,65 @@
 # bolt
 
-Base Discord bot framework
+Base library for 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.
+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.
+
+## 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.
+```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.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
+			},
+		},
+        // .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
+			},
+			Timeout: time.Second * 25,
+		},
+        // .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
+			},
+            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,23 +16,31 @@ import (
 const (
 	TOKEN_ENV_VAR = "DISCORD_TOKEN" //label for token environment variable
 
-	BOT_INTENTS = dg.IntentGuildMembers | //discord permissions for the bot
+	BOT_INTENTS = dg.IntentGuilds |
+		dg.IntentGuildMembers |
 		dg.IntentGuildPresences |
-		dg.IntentMessageContent
+		dg.IntentMessageContent |
+		dg.IntentsGuildMessages
 )
 
 // 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 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
+	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
@@ -42,30 +53,53 @@ func init() {
 }
 
 // create a new bolt interface
-func New() *bolt {
+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
 
-	return &bolt{
+	b := &bolt{
 		Session:  bot,
 		Commands: make(map[string]Command, 0),
 	}
+	//set default command indicator
+	b.indicator = "."
+
+	//apply options to bolt
+	for _, o := range opts {
+		o(b)
+	}
+
+	return b
 }
 
-// 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 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()
 }
 
@@ -104,34 +138,56 @@ func (b *bolt) messageHandler(s *dg.Session, msg *dg.MessageCreate) {
 		return
 	}
 
-	//does the message have the command indicator "."
+	//does the message have the command indicator
-	if msg.Content[:1] == "." {
+	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
+		}
+	}
+}
+
+// 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]]
+	run, ok := b.Commands[words[0][lg:]]
 	if !ok {
-			return //command doesn't exist, maybe log or respond to author
+		return nil //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)) {
+	tc, err := b.timeoutCheck(msg, s, run)
-			return //running too soon, maybe respond letting know time remaining
+	if err != nil {
+		return 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 err
+		}
+		if !check {
+			return nil
+		}
 	}
 
 	//run command payload
 	res, err := run.Payload(Message{
-			Author: Author{
+		Author:  msg.Author.Username,
-				Username: msg.Author.Username,
-				Roles:    msg.Member.Roles,
-			},
 		Words:   words,
-			Message: msg.Content,
+		Content: msg.Content,
 		Channel: channel.Name,
 		Server:  server.Name,
 	})
 
 	if err != nil {
-			log.Println(err)
+		return err
-			return
 	}
 
 	//if a reply is returned send back to Discord
@@ -139,14 +195,14 @@ func (b *bolt) messageHandler(s *dg.Session, msg *dg.MessageCreate) {
 		reply := b.createReply(res, msg.ID, msg.ChannelID, msg.GuildID)
 		_, err := s.ChannelMessageSendComplex(msg.ChannelID, reply)
 		if err != nil {
-				log.Println(err)
+			return err
-				return
 		}
 	}
 
 	//update run time
-		run.LastRun = time.Now()
+	run.lastRun = time.Now()
-	}
+	b.Commands[run.Trigger] = run
+	return nil
 }
 
 // basic wrapper function to create easy Discord responses
@@ -162,3 +218,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, 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, 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, err
+		}
+		return false, nil
+	}
+
+	return true, nil
+}

command.go

@@ -3,28 +3,22 @@ package bolt
 import "time"
 
 type Command struct {
-	Trigger string        //.command that triggers payload NOT 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
+	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) (res string, err error)
+type Payload func(msg Message) (string, error)
 
 // contains the basic information needed for a message command
 type Message struct {
-	Author  Author
+	Author  string   //username of message author
 	Words   []string //words from message split on whitespace
-	Message string   //entire message content
+	Content 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
-}

option.go

@@ -0,0 +1,10 @@
+package bolt
+
+type Option func(b *bolt)
+
+// 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
+	}
+}