1
0
Fork 0
mirror of https://github.com/diamondburned/arikawa.git synced 2024-12-12 08:25:10 +00:00
A Golang library and framework for the Discord API.
Go to file
2022-08-23 13:37:10 -07:00
.github Fixed FUNDING.yml 2020-12-11 16:50:47 -08:00
0-examples examples: Add commands-hybrid 2022-08-22 23:45:07 -07:00
api webhook: Add missing Content-Type for Pong 2022-08-22 14:43:49 -07:00
discord discord: Fix json tag for Guild.MFA 2022-08-22 14:43:29 -07:00
gateway gateway: Add IsPending for GuildMemberUpdateEvent 2022-08-22 14:43:29 -07:00
internal discord: ContainerComponents.Unmarshal for number types 2022-08-20 09:39:24 -07:00
session webhook: Add session+state helpers 2022-08-22 02:18:54 -07:00
state state: Finish comments for NewAPIOnlyState 2022-08-22 23:12:08 -07:00
utils Revert "ws: Add LastAcknowledgedBeat" 2022-04-12 10:55:42 -07:00
voice Revert "ws: Add LastAcknowledgedBeat" 2022-04-12 10:55:42 -07:00
.build.yml gateway: Refactor for a better concurrent API 2021-12-14 13:49:34 -08:00
.editorconfig
.gitlab-ci.yml CI: Update dismock 2021-09-23 22:28:02 -07:00
arikawa.go bot: Fix previous breaking change 2021-09-22 10:56:40 -07:00
go.mod discord: Refactor interactions and components 2021-11-12 11:38:36 -08:00
go.sum *: Update go dependencies 2021-11-09 14:49:18 -08:00
LICENSE Changed LICENSE. 2020-04-13 19:09:24 -07:00
README.md README: Add commands-hybrid, minor tweaks 2022-08-23 13:37:10 -07:00

arikawa

 Pipeline Status  Report Card      Godoc Reference  Examples         Discord Gophers  Hime Arikawa

A Golang library for the Discord API.

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.

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.

Bare Minimum Messaging Example

The least amount of code recommended to have a bot that logs all messages to console.

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("BOT_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 connect:", err)
	}
}

Where is package bot?

Package bot has now been deprecated after Discord's decision to eventually deprecate regular message events as means of commanding bots. We've decided to move the old bot package into utils/ to signify that it should no longer be used.

Moving bot into utils/ will allow us to eventually rewrite the whole package to use slash commands without worrying about breaking the old (v2) API, which is great, because almost nothing translates well from the previous design to slash commands.

Comparison: Why not discordgo?

Discordgo is great. It's the first library that I used when I was learning Go. Though there are some things that I disagree on. Here are some ways that this library is different:

  • Better package structure: this library divides the Discord library up into smaller packages.
  • Cleaner API/Gateway structure separation: this library separates fields that would only appear in Gateway events, so to not cause confusion.
  • Automatic un-pagination: this library automatically un-paginates endpoints that would otherwise not return everything fully.
  • Flexible underlying abstractions: this library allows plugging in different JSON and Websocket implementations, as well as direct access to the HTTP client.
  • Flexible API abstractions: because packages are separated, the developer could choose to use a lower level package (such as gateway) or a higher level package (such as state).
  • Pre-handlers in the state: this allows the developers to access items from the state storage before they're removed.
  • Pluggable state storages: although only having a default state storage in the library, it is abstracted with an interface, making it possible to implement a custom remote or local state storage.
  • REST-updated state: this library will call the REST API if it can't find things in the state, which is useful for keeping it updated.
  • No code generation: just so the library is a lot easier to maintain.

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 ./...