Compare commits
No commits in common. "main" and "v0.3.1" have entirely different histories.
75
README.md
75
README.md
@ -1,49 +1,28 @@
|
||||
# bolt
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
## 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.
|
||||
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.
|
||||
```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
|
||||
Roles []string //roles that can use command, if none are set anyone can run the command
|
||||
}
|
||||
```
|
||||
|
||||
### Payload
|
||||
Payload functions are executed when a command is detected
|
||||
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.
|
||||
```go
|
||||
type Payload func(msg Message) error
|
||||
type Payload func(msg Message) (string, 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
|
||||
@ -53,57 +32,47 @@ 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, err := bolt.New(bolt.WithLogLevel(bolt.LogLevelCmd))
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
b := bolt.New(bolt.WithLogLevel(bolt.LogLevelCmd))
|
||||
|
||||
b.AddCommands(
|
||||
// basic ping pong command, .ping can be run at anytime by anyone and will reply "pong"
|
||||
// .ping can be run at any time by anyone and will respond with 'pong'
|
||||
bolt.Command{
|
||||
Trigger: "ping",
|
||||
Payload: func(msg bolt.Message) error {
|
||||
return msg.Respond("pong")
|
||||
Payload: func(msg bolt.Message) (string, error) {
|
||||
return "pong", nil //any strings returned will be sent in response to the Discord message
|
||||
},
|
||||
},
|
||||
// .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
|
||||
// .time can be run every 25 seconds by anyone and will respond with 'yer'
|
||||
bolt.Command{
|
||||
Trigger: "time",
|
||||
Payload: func(msg bolt.Message) error {
|
||||
return msg.Respond(time.Now().String())
|
||||
Payload: func(msg bolt.Message) (string, error) {
|
||||
return "yer", nil
|
||||
},
|
||||
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")
|
||||
// .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"},
|
||||
},
|
||||
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()
|
||||
err := b.Start()
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
109
bolt.go
109
bolt.go
@ -20,8 +20,7 @@ const (
|
||||
dg.IntentGuildMembers |
|
||||
dg.IntentGuildPresences |
|
||||
dg.IntentMessageContent |
|
||||
dg.IntentsGuildMessages |
|
||||
dg.IntentGuildMessageReactions
|
||||
dg.IntentsGuildMessages
|
||||
)
|
||||
|
||||
// basic bot structure containing discordgo connection as well as the command map
|
||||
@ -45,16 +44,20 @@ type Bolt interface {
|
||||
timeoutCheck(msg *dg.MessageCreate, s *dg.Session, run Command) (bool, error)
|
||||
}
|
||||
|
||||
// create a new bolt interface
|
||||
func New(opts ...Option) (Bolt, error) {
|
||||
// setup
|
||||
func init() {
|
||||
//validate environment variables
|
||||
_, check := os.LookupEnv(TOKEN_ENV_VAR)
|
||||
if !check {
|
||||
return nil, fmt.Errorf("environment variable %s must be set", TOKEN_ENV_VAR)
|
||||
log.Fatalf("the %s environment variable must be set", TOKEN_ENV_VAR)
|
||||
}
|
||||
}
|
||||
|
||||
// create a new bolt interface
|
||||
func New(opts ...Option) Bolt {
|
||||
bot, err := dg.New(fmt.Sprintf("Bot %s", os.Getenv(TOKEN_ENV_VAR)))
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("failed to create Discord session: %e", err)
|
||||
log.Fatal(err)
|
||||
}
|
||||
bot.Identify.Intents = BOT_INTENTS
|
||||
|
||||
@ -71,7 +74,7 @@ func New(opts ...Option) (Bolt, error) {
|
||||
opt(b)
|
||||
}
|
||||
|
||||
return b, nil
|
||||
return b
|
||||
}
|
||||
|
||||
// starts the bot, commands are added and the connection to Discord is opened, this is a BLOCKING
|
||||
@ -82,7 +85,7 @@ func (b *bolt) Start() error {
|
||||
|
||||
err := b.Open()
|
||||
if err != nil {
|
||||
return fmt.Errorf("failed to open websocket connection with Discord: %e", err)
|
||||
return err
|
||||
}
|
||||
|
||||
//safe shutdown handler
|
||||
@ -114,28 +117,19 @@ func (b *bolt) messageHandler(s *dg.Session, msg *dg.MessageCreate) {
|
||||
//get server information
|
||||
server, err := s.Guild(msg.GuildID)
|
||||
if err != nil {
|
||||
log.Printf("failed to get guild: %e\n", err)
|
||||
log.Println(err)
|
||||
return
|
||||
}
|
||||
channel, err := s.Channel(msg.ChannelID)
|
||||
if err != nil {
|
||||
log.Printf("failed to get channel from guild: %e\n", err)
|
||||
log.Println(err)
|
||||
return
|
||||
}
|
||||
|
||||
//if there is no content it is likely an image, gif, or sticker, updating message content for
|
||||
//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 = "[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 {
|
||||
//log command responses
|
||||
log.Printf("< %s | %s | %s > %s\n", server.Name, channel.Name, msg.Author.Username, msg.Content)
|
||||
}
|
||||
return
|
||||
msg.Content = "GIF/IMAGE"
|
||||
}
|
||||
|
||||
if b.logLvl == LogLevelAll {
|
||||
@ -143,6 +137,15 @@ 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 {
|
||||
@ -170,7 +173,7 @@ func (b *bolt) handleCommand(msg *dg.MessageCreate, s *dg.Session, server *dg.Gu
|
||||
//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)
|
||||
return err
|
||||
}
|
||||
if !tc {
|
||||
return nil
|
||||
@ -180,50 +183,34 @@ func (b *bolt) handleCommand(msg *dg.MessageCreate, s *dg.Session, server *dg.Gu
|
||||
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)
|
||||
return 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,
|
||||
})
|
||||
}
|
||||
|
||||
plMsg.Attachments = att
|
||||
}
|
||||
|
||||
//run command payload
|
||||
err = run.Payload(plMsg)
|
||||
res, err := run.Payload(Message{
|
||||
Author: msg.Author.Username,
|
||||
ID: msg.Author.ID,
|
||||
Words: words,
|
||||
Content: msg.Content,
|
||||
Channel: channel.Name,
|
||||
Server: server.Name,
|
||||
})
|
||||
|
||||
if err != nil {
|
||||
return fmt.Errorf("failed to execute payload function: %e", err)
|
||||
return err
|
||||
}
|
||||
|
||||
//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 {
|
||||
return err
|
||||
}
|
||||
}
|
||||
|
||||
//update run time
|
||||
@ -276,7 +263,7 @@ func (b *bolt) roleCheck(msg *dg.MessageCreate, s *dg.Session, run Command) (boo
|
||||
//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)
|
||||
return false, err
|
||||
}
|
||||
//does this role exist in command roles
|
||||
check := slices.Contains(run.Roles, n.Name)
|
||||
@ -291,7 +278,7 @@ func (b *bolt) roleCheck(msg *dg.MessageCreate, s *dg.Session, run Command) (boo
|
||||
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, err
|
||||
}
|
||||
return false, nil
|
||||
}
|
||||
@ -306,7 +293,7 @@ func (b *bolt) timeoutCheck(msg *dg.MessageCreate, s *dg.Session, run Command) (
|
||||
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, err
|
||||
}
|
||||
return false, nil
|
||||
}
|
||||
|
||||
16
command.go
16
command.go
@ -1,8 +1,6 @@
|
||||
package bolt
|
||||
|
||||
import (
|
||||
"time"
|
||||
)
|
||||
import "time"
|
||||
|
||||
// custom Discord commands
|
||||
type Command struct {
|
||||
@ -14,4 +12,14 @@ type Command struct {
|
||||
}
|
||||
|
||||
// command payload functions, any strings returned are sent as a response to the command
|
||||
type Payload func(msg Message) error
|
||||
type Payload func(msg Message) (string, error)
|
||||
|
||||
// message information passed to payload function
|
||||
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
|
||||
}
|
||||
|
||||
80
message.go
80
message.go
@ -1,80 +0,0 @@
|
||||
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
|
||||
}
|
||||
Loading…
x
Reference in New Issue
Block a user