fixing pkg site docs

Reviewed-on: #8

.gitignore

@@ -25,3 +25,5 @@ go.work.sum
 # env file
 .env
 
+/cmd/*
+/cmd

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,108 @@
 # bolt
 
-Base Discord bot framework
+A fast [discordgo](https://github.com/bwmarrin/discordgo) wrapper for bootstrapping 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
+### Prerequisites
+Bolt requires a Discord bot token to run, the token must be set as an environment variable labeled "DISCORD_TOKEN"
+
+### Example
+```go
+package main
+
+import (
+	"fmt"
+	"strings"
+	"time"
+
+	"code.jakeyoungdev.com/jake/bolt"
+	_ "github.com/joho/godotenv/autoload"
+)
+
+/*
+A basic example of a bot with two commands and a general message handler for non-command messages. The bot uses a
+verbose log level which will log everything for debugging purposes, and registers Discord Intents for message and 
+admin related permissions. This allows the bot to parse messages, send them, delete them, etc. as well as timeout 
+and mute users.
+
+This example registers three commands:
+
+1. .ping - a basic ping/pong command that can be run by anyone at any time
+2. .wait - a dummy command that replies "okay" it can only be run by users with the "user" role and can only be ran 
+once every 25 seconds
+3. .timeout - a admin command that can only be run by users with an "admin" role, this command will timeout any mentioned 
+users for 5 minutes
+
+A message handler is also registered in this example, message handlers are used to handle messages that do not contain a 
+command. This enables auto-moderation from the bot without manual intervention. The example message handler does two arbitrary 
+things to demo functionality:
+
+1. Checks the message content for the phrase "swear word" and, if found, times the user out for 5 minutes
+2. Checks the message for the phrase "im going to yell in VoiceChat" and mutes the message author until Unmute is called on them
+*/
+
+func main() {
+	b, err := bolt.New()
+
+	if err != nil {
+		panic(err)
+	}
+
+	b.AddCommands(
+		bolt.Command{
+			Trigger: "ping",
+			Payload: func(c *bolt.Context) error {
+				return c.Respond("pong")
+			},
+		},
+		bolt.Command{
+			Trigger: "wait",
+			Payload: func(c *bolt.Context) error {
+				return c.Respond("okay")
+			},
+			Timeout: time.Second * 25,
+			Roles:   []string{"user"},
+		},
+		bolt.Command{
+			Trigger: "timeout",
+			Payload: func(c *bolt.Context) error {
+				if len(c.Message.Mentions) > 0 {
+					count := 0
+					for _, m := range c.Message.Mentions {
+						err := c.Timeout(m.ID, time.Now().Add(time.Minute*5))
+						if err != nil {
+							return err
+						}
+						count++
+					}
+
+					return c.Respond(fmt.Sprintf("timed out %d users\n", count))
+				}
+				return nil
+			},
+			Roles: []string{"admin"},
+		},
+	)
+
+	b.AddMessageHandler(func(c *bolt.Context) error {
+		if strings.Contains(c.Message.Content, "swear word") {
+			return c.Timeout(c.Message.Author.ID, time.Now().Add(time.Hour*1))
+		}
+
+		if c.Message.Content == "im going to yell in VoiceChat" {
+			return c.Mute(c.Message.Author.ID)
+		}
+		return nil
+	})
+
+	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 early development and may encounter breaking changes until a full v1 rollout, I will do my best to communicate
+these changes. Use a tagged version to avoid any surprises with live code in main

bolt.go

@@ -1,161 +1,311 @@
 package bolt
 
 import (
+	"context"
 	"fmt"
 	"log"
 	"os"
+	"os/signal"
+	"slices"
 	"strings"
+	"sync"
 	"time"
 
 	dg "github.com/bwmarrin/discordgo"
 )
 
 const (
-	TOKEN_ENV_VAR = "DISCORD_TOKEN" //label for token environment variable
+	//the name of the environment variable that should contain the token for the bot, it is
+	//required for bolt to run
+	TOKEN_ENV_VAR = "DISCORD_TOKEN"
 
-	// BOT_INTENTS = dg.IntentGuildMembers | //discord permissions for the bot
-	// 	dg.IntentGuildPresences |
-	// 	dg.IntentMessageContent
+	//bot default command indicator, if messages begin with this substring they are processed
+	//through the command handler instead of the generic message handler
+	DEFAULT_INDICATOR = "."
+	//max amount of concurrent goroutines that bolt can use for events. A lower amount
+	//may lower the resource usage of bolt but may cause a delay in event handling
+	DEFAULT_MAX_GOROUTINES = 250
 
-	BOT_INTENTS = dg.IntentsAllWithoutPrivileged |
+	//minimum intents for bots to function, intents can be changed with options
+	DEFAULT_INTENTS = dg.IntentGuilds |
 		dg.IntentGuildMembers |
 		dg.IntentGuildPresences |
-		dg.IntentMessageContent
+		dg.IntentMessageContent |
+		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
+type Bolt struct {
+	//discordgo internals
+	*dg.Session
+	//maps trigger phrase to command struct for instant lookup
+	commands map[string]Command
+	//used to detect whether a message is a command
+	indicator string
+	//verbosity of logs bolt outputs
+	logLvl LogLevel
+	//waitgroup for event routines
+	wg sync.WaitGroup
+	//pool is a buffered channel used as a semaphore for event handler routines, it is limited to
+	//only spawn maxRoutines to handle events
+	pool        chan struct{}
+	maxRoutines int
+	//generic message handler func
+	msgHandlerf Payload
 }
 
-type Bolt interface {
-	Start() error
-	Stop() error
-	AddCommands(cmd Command)
-	messageHandler(s *dg.Session, msg *dg.MessageCreate)
-	createReply(content, message, channel, guild string) *dg.MessageSend
-}
-
-// setup
-func init() {
-	//validate environment variables
+// New creates a new bolt instance and applies any supplied options
+func New(opts ...Option) (*Bolt, error) {
 	_, check := os.LookupEnv(TOKEN_ENV_VAR)
 	if !check {
-		log.Fatalf("the %s environment variable must be set", TOKEN_ENV_VAR)
+		return nil, fmt.Errorf("environment variable %s must be set", TOKEN_ENV_VAR)
 	}
-}
 
-// create a new bolt interface
-func New() *bolt {
 	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
+	b := &Bolt{
+		Session:     bot,
+		commands:    make(map[string]Command, 0),
+		logLvl:      LogLevelAll,
+		indicator:   DEFAULT_INDICATOR,
+		wg:          sync.WaitGroup{},
+		maxRoutines: DEFAULT_MAX_GOROUTINES,
+	}
 
-	return &bolt{
-		Session:  bot,
-		Commands: make(map[string]Command, 0),
+	b.Identify.Intents = DEFAULT_INTENTS
+	for _, opt := range opts {
+		opt(b)
+	}
+
+	//options can change max routine number, so create after
+	b.pool = make(chan struct{}, b.maxRoutines)
+
+	return b, nil
+}
+
+// Start applies the message event handler function to the bot and opens the initial websocket connection
+// with Discord. Start is a blocking call that also handles safe shutdown, on Interrupt, bolt will give
+// command routines a window to finish before closing the connection.
+func (b *Bolt) Start() error {
+	b.AddHandler(b.msgEventHandler)
+	err := b.Open()
+	if err != nil {
+		return fmt.Errorf("failed to open websocket connection with Discord: %e", err)
+	}
+
+	sigChannel := make(chan os.Signal, 1)
+	signal.Notify(sigChannel, os.Interrupt)
+	<-sigChannel
+
+	//give handler routines a 5 second window to finish processes before closing connection
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second*5)
+	defer cancel()
+	closeChan := make(chan struct{})
+	go func() {
+		b.wg.Wait()
+		close(closeChan)
+	}()
+
+	select {
+	case <-ctx.Done():
+		log.Println("shutdown timed out waiting for handlers to finish, some may have been incomplete")
+	case <-closeChan:
+	}
+
+	return b.stop()
+}
+
+// AddCommands registers command handlers. Any messages that begin with the command indicator will be forwarded
+// to the handler
+func (b *Bolt) AddCommands(cmd ...Command) {
+	for _, c := range cmd {
+		b.commands[c.Trigger] = c
 	}
 }
 
-// adds command handler and starts the bot
-func (b *bolt) Start() error {
-	//register commands and open connection
-	b.AddHandler(b.messageHandler)
-
-	return b.Open()
+// AddMessageHandler registers the generic message handler, any messages that are not commands will be forwarded
+// to the handler
+func (b *Bolt) AddMessageHandler(p Payload) {
+	b.msgHandlerf = p
 }
 
-// stops the bot
-func (b *bolt) Stop() error {
+// stop closes the websocket connection to Discord
+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
-	}
-}
-
-// handler function that parses message data and executes any command payloads
-func (b *bolt) messageHandler(s *dg.Session, msg *dg.MessageCreate) {
+// msgEventHandler handles the routing of messages to either the command or message handlers. If LogLvl is set, logging is handled here before
+// the event is mapped to the Message struct and forwarded to the handlers. Each message is handled in its own goroutine, the max allowed goroutines
+// is set as a default and can be altered using options for better performance.
+func (b *Bolt) msgEventHandler(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
-	//better logging and to avoid confusion
-	if len(msg.Content) == 0 {
-		msg.Content = "GIF/IMAGE"
-	}
-
-	//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 != LogLevelErr {
+			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
+	if b.logLvl == LogLevelAll {
+		log.Printf("< %s | %s | %s > %s\n", server.Name, channel.Name, msg.Author.Username, msg.Content)
+	}
+
+	m := b.mapEventToMsg(msg, channel, server)
+	lg := len(b.indicator)
+	if msg.Content[:lg] == b.indicator {
+		if b.logLvl == LogLevelCmd {
+			log.Printf("< %s | %s | %s > %s\n", m.Server, m.Channel, m.Author.Name, m.Content)
 		}
 
-		//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 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)
+		b.pool <- struct{}{} //'aquire' a routine
+		b.wg.Go(func() {
+			err := b.handleCommand(&m, lg)
 			if err != nil {
 				log.Println(err)
-				return
 			}
-		}
-
-		//update run time
-		run.LastRun = time.Now()
+			<-b.pool //release routine
+		})
+	} else {
+		b.pool <- struct{}{} //'aquire' a routine
+		b.wg.Go(func() {
+			err := b.handleMessage(&m)
+			if err != nil {
+				log.Println(err)
+			}
+			<-b.pool //release routine
+		})
 	}
 }
 
-// basic wrapper function to create easy Discord responses
-func (b *bolt) createReply(content, message, channel, guild string) *dg.MessageSend {
+// mapEventToMsg maps the Discord event message struct into bolt's user-friendly Message struct
+func (b *Bolt) mapEventToMsg(msg *dg.MessageCreate, channel *dg.Channel, server *dg.Guild) Message {
+	m := Message{
+		Author: Author{
+			Name:  msg.Author.Username,
+			ID:    msg.Author.ID,
+			Roles: msg.Member.Roles,
+		},
+		ID:        msg.ID,
+		Content:   msg.Content,
+		Channel:   channel.Name,
+		ChannelID: channel.ID,
+		Server:    server.Name,
+		ServerID:  server.ID,
+	}
+
+	w := strings.Fields(msg.Content)
+	if len(w) > 0 {
+		m.Words = w
+	}
+
+	if len(msg.Mentions) > 0 {
+		m.Mentions = msg.Mentions
+	}
+
+	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,
+			})
+		}
+
+		m.Attachments = att
+	}
+
+	return m
+}
+
+// handleMessage forwards the message data to the handler function, if one is set
+func (b *Bolt) handleMessage(event *Message) error {
+	if b.msgHandlerf != nil {
+		return b.msgHandlerf(&Context{
+			Message: event,
+			bolt:    b,
+		})
+	}
+
+	return nil
+}
+
+// handleCommand maps the first word of the message to the command payload, if it exists. It then forwards the message
+// data to the handler after checking the timeout and role restrictions. If restrictions have not been met a generic
+// response is sent to the message
+// TODO: accept a string for timeout/role rejection messages to allow customization
+func (b *Bolt) handleCommand(msg *Message, lg int) error {
+	run, ok := b.commands[msg.Words[0][lg:]]
+	if !ok {
+		return nil //command doesn't exist
+	}
+
+	//has command met its timeout requirements, if timeout has not expired a response is sent to the message
+	//from the timeoutCheck method
+	tc, err := b.timeoutCheck(msg.ID, msg.ChannelID, msg.ServerID, b.Session, run)
+	if err != nil {
+		return fmt.Errorf("failed to calculate timeout for %s\n%e", run.Trigger, err)
+	}
+	//method handles sending a response, so we do not need to send another here, simply return
+	if !tc {
+		return nil
+	}
+
+	//does user have correct permissions to run this command
+	if run.Roles != nil {
+		check, err := b.roleCheck(msg.ServerID, msg.Author.Roles, b.Session, run)
+		if err != nil {
+			return fmt.Errorf("failed to perform permission checks for %s\n%e", run.Trigger, err)
+		}
+		if !check {
+			//this alert should probably be moved into the roleCheck function to match the pattern of the timeoutCheck method
+			reply := b.createReply("you do not have permissions to run that command", msg.ID, msg.ChannelID, msg.ServerID)
+			_, err := b.Session.ChannelMessageSendComplex(msg.ChannelID, reply)
+			if err != nil {
+				return err
+			}
+			return nil
+		}
+	}
+
+	//execute handler func with message context
+	err = run.Payload(&Context{
+		Message: msg,
+		bolt:    b,
+	})
+	if err != nil {
+		return fmt.Errorf("encountered an error while handling command (%s): %e", msg.Words[0], err)
+	}
+
+	//update run time
+	run.lastRun = time.Now()
+	b.commands[run.Trigger] = run
+	return nil
+}
+
+// createReploy is a basic wrapper function to map message data to the actual MessageSend struct
+func (b *Bolt) createReply(content, message, channel, guild string) *dg.MessageSend {
 	details := &dg.MessageReference{
 		MessageID: message,
 		ChannelID: channel,
@@ -167,3 +317,68 @@ func (b *bolt) createReply(content, message, channel, guild string) *dg.MessageS
 		Reference: details,
 	}
 }
+
+// remainingTimeout calculates the amount of time left before a command can be run again. Returning a string
+// representing a readable version of the time left, example: 1h (1 hour)
+func (b *Bolt) remainingTimeout(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"
+		}
+	}
+
+	//provide a user-friendly time string to send back to the user
+	return fmt.Sprintf("%d%s", timeLeft, metric)
+}
+
+// checks if the author of msg has the correct role to run the requested command
+
+// roleCheck loops through the provided user role ID's grabs the role "name" and ensures the role is present
+// in the commands whitelist. If the role exists in the Command whitelist a true response is returned
+func (b *Bolt) roleCheck(guild string, roles []string, s *dg.Session, run Command) (bool, error) {
+	var found bool
+	//this needs a bit of love, looping through roles could get messy as server and role lists grow on big servers
+	//especially with the Role() call inside of the loop
+	for _, r := range roles {
+		//get role name from ID
+		n, err := s.State.Role(guild, r)
+		if err != nil {
+			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)
+		if check {
+			found = true
+			break
+		}
+	}
+
+	return found, nil
+}
+
+// timeoutCheck determines if a Command timeout has expired, if it hasn't expired a response is sent back to the message alerting the user
+// of the remaining time
+func (b *Bolt) timeoutCheck(msgID, channelID, guildID string, s *dg.Session, run Command) (bool, error) {
+	wait := run.lastRun.Add(run.Timeout)
+	now := time.Now()
+	if !now.After(wait) && !now.Equal(wait) {
+		reply := b.createReply(fmt.Sprintf("that command cannot be run for another %s", b.remainingTimeout(wait)), msgID, channelID, guildID)
+		_, err := s.ChannelMessageSendComplex(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,21 @@
 package bolt
 
-import "time"
+import (
+	"time"
+)
 
+// Command represents a bolt command in its entirety
 type Command struct {
-	Trigger string        //.command that triggers payload NOT 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
-	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)
-
-// 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
+	//the trigger phrase for the command, this field cannot include the command indicator. If the command is .ping
+	//Trigger should be "ping"
+	Trigger string
+	//handler function to run when command is detected
+	Payload Payload
+	//the amount of time that must pass before a command can be run again
+	Timeout time.Duration
+	//timestamp of last command run
+	lastRun time.Time
+	//the roles that are allowed to execute this command, the command author must have at least one of these roles
+	//in order to use the command
+	Roles []string
 }

go.mod

@@ -1,8 +1,11 @@
 module code.jakeyoungdev.com/jake/bolt
 
-go 1.24.0
+go 1.25.0
 
-require github.com/bwmarrin/discordgo v0.29.0
+require (
+	github.com/bwmarrin/discordgo v0.29.0
+	github.com/joho/godotenv v1.5.1
+)
 
 require (
 	github.com/gorilla/websocket v1.4.2 // indirect

go.sum

@@ -2,6 +2,8 @@ github.com/bwmarrin/discordgo v0.29.0 h1:FmWeXFaKUwrcL3Cx65c20bTRW+vOb6k8AnaP+Eg
 github.com/bwmarrin/discordgo v0.29.0/go.mod h1:NJZpH+1AfhIcyQsPeuBKsUtYrRnjkyu0kIVMCHkZtRY=
 github.com/gorilla/websocket v1.4.2 h1:+/TMaTYc4QFitKJxsQ7Yye35DkWvkdLcvGKqM+x0Ufc=
 github.com/gorilla/websocket v1.4.2/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
+github.com/joho/godotenv v1.5.1 h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0=
+github.com/joho/godotenv v1.5.1/go.mod h1:f4LDr5Voq0i2e/R5DDNOoa2zzDfwtkZa6DnEwAbqwq4=
 golang.org/x/crypto v0.0.0-20210421170649-83a5a9bb288b h1:7mWr3k41Qtv8XlltBkDkl8LoP3mpSgBW8BUoxtEdbXg=
 golang.org/x/crypto v0.0.0-20210421170649-83a5a9bb288b/go.mod h1:T9bdIzuCu7OtxOm1hfPfRQxPLYneinmdGuTeoZ9dtd4=
 golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=

message.go

@@ -0,0 +1,128 @@
+package bolt
+
+import (
+	"fmt"
+	"time"
+
+	dg "github.com/bwmarrin/discordgo"
+)
+
+const (
+	// the max length allowed for basic messages, if the message content exceeds this amount
+	// then messages are split unto chunks of max size
+	MSG_MAX_LENGTH = 2000
+)
+
+// command and message payload function type
+type Payload func(c *Context) error
+
+type MessageAttachment struct {
+	ID           string
+	URL          string
+	ProxyURL     string
+	Filename     string
+	ContentType  string
+	Width        int
+	Height       int
+	Size         int
+	DurationSecs float64
+}
+
+// Author contains basic information about message authors
+type Author struct {
+	Name  string
+	ID    string
+	Roles []string
+}
+
+// Message contains all needed data to handle message events
+type Message struct {
+	Author Author
+	//current message ID
+	ID string
+	//message content split on whitespace to allow for easy argument parsing with commands
+	Words []string
+	//entire message content unchanged
+	Content string
+	//channel message was sent in, name and ID
+	Channel   string
+	ChannelID string
+	//guild message was sent in, name and ID
+	Server   string
+	ServerID string
+	//message extras
+	Attachments []MessageAttachment //any attachments bound to the message
+	Mentions    []*dg.User          //users mention in the message with @
+}
+
+// Context is the struct passed to message and command handlers, it contains all needed message data as well as
+// some methods to make interaction with the message as easy as possible
+type Context struct {
+	Message *Message
+	bolt    *Bolt
+}
+
+// React applies the reaction to the message
+func (c *Context) React(emoji Reaction) error {
+	return c.bolt.MessageReactionAdd(c.Message.ChannelID, c.Message.ID, fmt.Sprint(emoji))
+}
+
+// Respond sends a response to the message, handling chunking if the message exceeds max length
+func (c *Context) Respond(res string) error {
+	if len(res) > MSG_MAX_LENGTH {
+		for len(res) > 0 {
+			//send full chunk size allowed by discord
+			sc := res[:MSG_MAX_LENGTH]
+			rep := c.bolt.createReply(sc, c.Message.ID, c.Message.ChannelID, c.Message.ServerID)
+			_, err := c.bolt.ChannelMessageSendComplex(c.Message.ChannelID, rep)
+			if err != nil {
+				return err
+			}
+			res = res[MSG_MAX_LENGTH:]
+
+			//if we have left than a full chunk send the rest and break the loop
+			if len(res) < MSG_MAX_LENGTH {
+				final := c.bolt.createReply(res, c.Message.ID, c.Message.ChannelID, c.Message.ServerID)
+				_, err := c.bolt.ChannelMessageSendComplex(c.Message.ChannelID, final)
+				if err != nil {
+					return err
+				}
+
+				break
+			}
+		}
+
+		return nil
+	}
+
+	//short enough message to send in one go, so ship it
+	rep := c.bolt.createReply(res, c.Message.ID, c.Message.ChannelID, c.Message.ServerID)
+	_, err := c.bolt.ChannelMessageSendComplex(c.Message.ChannelID, rep)
+	return err
+}
+
+// Delete removes the message from the current channel
+func (c *Context) Delete() error {
+	return c.bolt.ChannelMessageDelete(c.Message.ChannelID, c.Message.ID, nil)
+}
+
+// Timeout creates a user timeout for the supplied userID that lasts until duration is exceeded or the
+// timeout is cleared
+func (c *Context) Timeout(userId string, duration time.Time) error {
+	return c.bolt.GuildMemberTimeout(c.Message.ServerID, userId, &duration)
+}
+
+// ClearTimeout clears existing user timeouts, allowing them access again
+func (c *Context) ClearTimeout(userId string) error {
+	return c.bolt.GuildMemberTimeout(c.Message.ServerID, userId, nil)
+}
+
+// Mute handles muting a user from Voice Chat, this mute stays until it is Unmute()'d
+func (c *Context) Mute(userId string) error {
+	return c.bolt.GuildMemberMute(c.Message.ServerID, userId, true)
+}
+
+// Unmute removes a mute on the user, allowing them vc access again
+func (c *Context) Unmute(userId string) error {
+	return c.bolt.GuildMemberMute(c.Message.ServerID, userId, false)
+}

option.go

@@ -0,0 +1,50 @@
+package bolt
+
+import (
+	dg "github.com/bwmarrin/discordgo"
+)
+
+type Option func(b *Bolt)
+type LogLevel int
+
+const (
+	LogLevelAll LogLevel = iota //log all messages, and errors
+	LogLevelCmd LogLevel = iota //log only commands and responses, and errors
+	LogLevelErr LogLevel = iota //log only errors
+)
+
+// WithIntents provides an option to use custom intents for the bot. Bolt comes preconfigured with the basic
+// intents needed to run a bot but those are completely overwritten by any supplied here
+func WithIntents(intents ...dg.Intent) Option {
+	return func(b *Bolt) {
+		var full dg.Intent
+		for _, i := range intents {
+			full |= i
+		}
+
+		b.Identify.Intents = full
+	}
+}
+
+// WithMaxGoroutines limits the amount of handler routines the bot is able to spawn at the same time. A lower value
+// may cause higher latency but may reduce resources needed to run bolt
+func WithMaxGoroutines(max int) Option {
+	return func(b *Bolt) {
+		b.maxRoutines = max
+	}
+}
+
+// WithIndicator sets the substring that must be present at the beginning of a message to trigger a
+// command, for example "." or "!"
+func WithIndicator(i string) Option {
+	return func(b *Bolt) {
+		b.indicator = i
+	}
+}
+
+// WithLogLevel adjusts bolt logging verbosity
+func WithLogLevel(lvl LogLevel) Option {
+	return func(b *Bolt) {
+		b.logLvl = lvl
+	}
+}

reaction.go

@@ -0,0 +1,38 @@
+package bolt
+
+type Reaction string
+
+// a few easy-to-use emojis, Discordgo/Discord API requires them to be saved like this. Some appear "broken" but do not play friendly
+// when saved in-file
+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 = "🐉"
+)