README
¶
arikawa
A Golang library for the Discord API.
Library Highlights
- More modularity with components divided up into independent packages, such as the API client and the Websocket Gateway being fully independent.
- Clear separation of models: API and Gateway models are never mixed together so to not be confusing.
- Extend and intercept Gateway events, allowing for use cases such as reading deleted messages.
- Pluggable Gateway cache allows for custom caching implementations such as Redis, automatically falling back to the API if needed.
- Typed Snowflakes make it much harder to accidentally use the wrong ID (e.g. it is impossible to use a channel ID as a message ID).
- Working user account support, with much of them in ningen. Please do not use this for self-botting, as that is against Discord's ToS.
Examples
Commands (Hybrid)
commands-hybrid is an alternative variant of commands, where the program permits being hosted either as a Gateway-based daemon or as a web server using the Interactions Webhook API.
Both examples demonstrate adding interaction commands into the bot as well as an example of routing those commands to be executed.
Simple
Simple bot example without any state. All it does is logging messages sent into
the console. Run with BOT_TOKEN="TOKEN" go run .. This example only
demonstrates the most simple needs; in most cases, bots should use the state or
the bot router.
Note that Discord discourages use of bots that do not use the interactions API, meaning that this example should not be used for bots.
Undeleter
A slightly more complicated example. This bot uses a local state to cache everything, including messages. It detects when someone deletes a message, logging the content into the console.
This example demonstrates the PreHandler feature of the state library. PreHandler calls all handlers that are registered (separately from the session), calling them before the state is updated.
Note that Discord discourages use of bots that do not use the interactions API, meaning that this example should not be used for bots.
Bare Minimum Bot Example
The least amount of code recommended to have a bot that responds to a /ping.
package main
import (
"context"
"log"
"os"
"github.com/diamondburned/arikawa/v3/api"
"github.com/diamondburned/arikawa/v3/api/cmdroute"
"github.com/diamondburned/arikawa/v3/gateway"
"github.com/diamondburned/arikawa/v3/state"
"github.com/diamondburned/arikawa/v3/utils/json/option"
)
var commands = []api.CreateCommandData{{Name: "ping", Description: "Ping!"}}
func main() {
r := cmdroute.NewRouter()
r.AddFunc("ping", func(ctx context.Context, data cmdroute.CommandData) *api.InteractionResponseData {
return &api.InteractionResponseData{Content: option.NewNullableString("Pong!")}
})
s := state.New("Bot " + os.Getenv("BOT_TOKEN"))
s.AddInteractionHandler(r)
s.AddIntents(gateway.IntentGuilds)
if err := cmdroute.OverwriteCommands(s, commands); err != nil {
log.Fatalln("cannot update commands:", err)
}
if err := s.Connect(context.TODO()); err != nil {
log.Println("cannot connect:", err)
}
}
Testing
The package includes integration tests that require $BOT_TOKEN. To run these
tests, do:
export BOT_TOKEN="<BOT_TOKEN>"
go test -tags integration -race ./...
Documentation
¶
Overview ¶
Package arikawa contains a set of modular packages that allows you to make a Discord bot or any type of session (OAuth unsupported).
Session ¶
Package session is the most simple abstraction, which combines the API package and the Gateway websocket package together into one. This could be used for minimal bots that only use gateway events and such.
State ¶
Package state abstracts on top of session and provides a local cache of API calls and events. Bots that either don't need a command router or already has its own should use this package.
Bot ¶
Package bot abstracts on top of state and provides a command router based on Go code. This is similar to discord.py's API, only it's Go and there's no optional arguments (yet, although it could be worked around). Most bots are recommended to use this package, as it's the easiest way to make a bot.
Voice ¶
Package voice provides an abstraction on top of State and adds voice support. This allows bots to join voice channels and talk. The package uses an io.Writer approach rather than a channel, contrary to other Discord libraries.
Example ¶
package main
import (
"context"
"log"
"os"
"os/signal"
"github.com/diamondburned/arikawa/v3/gateway"
"github.com/diamondburned/arikawa/v3/state"
)
func main() {
s := state.New("Bot " + os.Getenv("DISCORD_TOKEN"))
s.AddIntents(gateway.IntentGuilds | gateway.IntentGuildMessages)
s.AddHandler(func(m *gateway.MessageCreateEvent) {
log.Printf("%s: %s", m.Author.Username, m.Content)
})
ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
defer cancel()
if err := s.Connect(ctx); err != nil {
log.Println("cannot open:", err)
}
}
Output:
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
0-examples
|
|
|
sharded
Package main demonstrates a bare simple bot without a state cache.
|
Package main demonstrates a bare simple bot without a state cache. |
|
simple
Package main demonstrates a bare simple bot without a state cache.
|
Package main demonstrates a bare simple bot without a state cache. |
|
undeleter
Package main demonstrates the PreHandler API of the State.
|
Package main demonstrates the PreHandler API of the State. |
|
Package api provides an interface to interact with the Discord REST API.
|
Package api provides an interface to interact with the Discord REST API. |
|
webhook
Package webhook provides means to interact with webhooks directly and not through the bot API.
|
Package webhook provides means to interact with webhooks directly and not through the bot API. |
|
Package discord provides common structures that the whole repository uses.
|
Package discord provides common structures that the whole repository uses. |
|
Package gateway handles the Discord gateway (or Websocket) connection, its events, and everything related to it.
|
Package gateway handles the Discord gateway (or Websocket) connection, its events, and everything related to it. |
|
internal
|
|
|
backoff
Package backoff provides an exponential-backoff implementation partially taken from jpillora/backoff.
|
Package backoff provides an exponential-backoff implementation partially taken from jpillora/backoff. |
|
moreatomic/syncmod
Package syncmod contains a clone of package sync's map.go file with unused methods removed and some tweaks with LoadOrStore.
|
Package syncmod contains a clone of package sync's map.go file with unused methods removed and some tweaks with LoadOrStore. |
|
zlib
Package zlib provides abstractions on top of compress/zlib to work with Discord's method of compressing websocket packets.
|
Package zlib provides abstractions on top of compress/zlib to work with Discord's method of compressing websocket packets. |
|
Package session abstracts around the REST API and the Gateway, managing both at once.
|
Package session abstracts around the REST API and the Gateway, managing both at once. |
|
Package state provides interfaces for a local or remote state, as well as abstractions around the REST API and Gateway events.
|
Package state provides interfaces for a local or remote state, as well as abstractions around the REST API and Gateway events. |
|
store
Package store contains interfaces of the state's storage and its implementations.
|
Package store contains interfaces of the state's storage and its implementations. |
|
store/defaultstore
Package defaultstore provides thread-safe store implementations that store state values in memory.
|
Package defaultstore provides thread-safe store implementations that store state values in memory. |
|
utils
|
|
|
bot/_example/advanced_bot
Package main demonstrates an advanced bot that uses the bot router library to make commands.
|
Package main demonstrates an advanced bot that uses the bot router library to make commands. |
|
bot/extras/infer
Package infer implements reflect functions that package bot uses.
|
Package infer implements reflect functions that package bot uses. |
|
handler
Package handler handles incoming Gateway events.
|
Package handler handles incoming Gateway events. |
|
httputil
Package httputil provides abstractions around the common needs of HTTP.
|
Package httputil provides abstractions around the common needs of HTTP. |
|
httputil/httpdriver
Package httpdriver provides interfaces and implementations of a simple HTTP client.
|
Package httpdriver provides interfaces and implementations of a simple HTTP client. |
|
json
Package json allows for different implementations of JSON serializing, as well as extra optional types needed.
|
Package json allows for different implementations of JSON serializing, as well as extra optional types needed. |
|
json/option
Package option provides the ability to create omittable primitives.
|
Package option provides the ability to create omittable primitives. |
|
ws
Package wsutil provides abstractions around the Websocket, including rate limits.
|
Package wsutil provides abstractions around the Websocket, including rate limits. |
|
ws/ophandler
Package ophandler provides an Op channel reader that redistributes the events into handlers.
|
Package ophandler provides an Op channel reader that redistributes the events into handlers. |
|
Package voice handles the Discord voice gateway and UDP connections.
|
Package voice handles the Discord voice gateway and UDP connections. |