response and readme updates

- fixed example syntax
- framework now response on timeout skips
- framework will now alert of missing permissions

README.md

@@ -3,7 +3,67 @@
 Base Discord bot framework
 
 ## 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 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. 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 simply a discord bot token and a few lines of Go code, the below example creates a Discord bot and registers three commands: ".test", ".time", and ".role"
+```go
+package main
+
+import (
+	"log"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"code.jakeyoungdev.com/jake/bolt"
+	_ "github.com/joho/godotenv/autoload"
+)
+
+func main() {
+	b := bolt.New()
+
+	b.AddCommands(
+        // .test can be run at any time by anyone
+		bolt.Command{
+			Trigger: ".test",
+			Payload: func(msg bolt.Message) (res string, err error) {
+				return "nah", nil //any strings returned will be sent in response to the Discord message
+			},
+		},
+        // .time can be run every 25 seconds by anyone
+		bolt.Command{
+			Trigger: ".time",
+			Payload: func(msg bolt.Message) (res string, err error) {
+				return "yer", nil
+			},
+			Timeout: time.Second * 25,
+		},
+        // .role can be run every 10 seconds by anyone with the 'admin' role
+        bolt.Command{
+            Trigger: ".role",
+            Payload: func(msg bolt.Message) (res string, err error) {
+				return "hi", nil
+			},
+            Timeout: time.Second * 10,
+            Roles: []string{"admin"},
+        },
+	)
+
+	_ = b.Start()
+
+	//set up safe CTRL-C
+	sigChannel := make(chan os.Signal, 1)
+	signal.Notify(sigChannel, syscall.SIGINT)
+	log.Println("bot running")
+	<-sigChannel
+
+	if err := b.Stop(); 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.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"log"
 	"os"
+	"slices"
 	"strings"
 	"time"
 
@@ -13,14 +14,11 @@ 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.IntentGuildPresences |
-	// 	dg.IntentMessageContent
-
-	BOT_INTENTS = dg.IntentsAllWithoutPrivileged |
 		dg.IntentGuildMembers |
 		dg.IntentGuildPresences |
-		dg.IntentMessageContent
+		dg.IntentMessageContent |
+		dg.IntentsGuildMessages
 )
 
 // basic bot structure containing discordgo connection as well as the command map
@@ -35,6 +33,7 @@ type Bolt interface {
 	AddCommands(cmd Command)
 	messageHandler(s *dg.Session, msg *dg.MessageCreate)
 	createReply(content, message, channel, guild string) *dg.MessageSend
+	getRemainingTimeout(timeout time.Time) string
 }
 
 // setup
@@ -118,16 +117,45 @@ func (b *bolt) messageHandler(s *dg.Session, msg *dg.MessageCreate) {
 		}
 
 		//has command met its timeout requirements
-		if !time.Now().After(run.LastRun.Add(run.Timeout)) {
+		wait := run.LastRun.Add(run.Timeout)
-			return //running too soon, maybe respond letting know time remaining
+		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 {
+				log.Println(err)
+			}
+			return //running too soon
+		}
+
+		//does user have correct permissions
+		if run.Roles != nil {
+			var found bool
+			for _, r := range msg.Member.Roles {
+				n, err := s.State.Role(msg.GuildID, r)
+				if err != nil {
+					log.Println(err)
+					return
+				}
+				check := slices.Contains(run.Roles, n.Name)
+				if check {
+					found = true
+				}
+			}
+
+			//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 {
+					log.Println(err)
+				}
+				return
+			}
 		}
 
 		//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,
 			Channel: channel.Name,
@@ -151,6 +179,7 @@ func (b *bolt) messageHandler(s *dg.Session, msg *dg.MessageCreate) {
 
 		//update run time
 		run.LastRun = time.Now()
+		b.Commands[run.Trigger] = run
 	}
 }
 
@@ -167,3 +196,24 @@ 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)
+}

command.go

@@ -3,7 +3,7 @@ package bolt
 import "time"
 
 type Command struct {
-	Trigger string        //.command that triggers payload NOT including the '.'
+	Trigger string        //.command that triggers payload INCLUDING the '.'
 	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
@@ -16,15 +16,9 @@ type Payload func(msg Message) (res string, err 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
 	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
-}