github.com/skwair/harmony
Package harmony provides an interface to the Discord API (https://discord.com/developers/docs/intro). The first thing you do with Harmony is to create a Client. NewClient does just that by returning a new Client pre-configured with sain defaults which should work fine in most cases. However, should you need a more specific configuration, you can always tweak it with optional `ClientOption`s. See the documentation of NewClient and the ClientOption type for more information on how to do so. Once you have a Client, you can start interacting with the Discord API, but some methods (such as event handlers) won't be available until you connect to Discord's Gateway. You can do so by simply calling the Connect method of the Client: It is only when successfully connected to the Gateway that your bot will appear as online and your Client will be able to receive events and send messages. Harmony's HTTP API is organized by resource. A resource maps to a core concept in the Discord world, such as a User or a Channel. Here is the list of resources you can interact with: Every interaction you can have with a resource can be accessed via methods attached to it. For example, if you wish to send a message to a channel, first access to the desired channel resource, then send the message: Endpoints that do not fall into one of those resource (creating a Guild for example, or getting valid Voice Regions) are directly available on the Client. To receive messages, use the OnMessageCreate method and give it your handler. It will be called each time a message is sent to a channel your bot is in with the message as a parameter. To register handlers for other types of events, see Client.On* methods. Note that your handlers are called in their own goroutine, meaning whatever you do inside of them won't block future events. When connecting to Discord, a session state is created with initial data sent by Discord's Gateway. As events are received by the client, this state is constantly updated so it always have the newest data available. This session state acts as a cache to avoid making requests over the HTTP API each time. If you need to get information about the current user, you can simply query the current state like so: Because this state might become memory hungry for bots that are in a very large number of servers, you can fine-tune events you want to track with the WithGatewayIntents option. State can also be completely disabled using the WithStateTracking option while creating the harmony client.
Readme
Harmony is a peaceful Go module for interacting with Discord's API.
Although this package is usable, it still is under active development so please don't use it for anything other than experiments, yet.
Contents
Make sure you have a working Go installation, if not see this page first.
Then, install this package with the go get command:
go get github.com/skwair/harmony
Note that
go getwill always pull the latest version from the master branch before Go 1.11. With newer versions and Go modules enabled, the latest minor or patch release will be downloaded.go get github.com/skwair/harmony@major.minor.patchcan be used to download a specific version. See Go modules for more information.
package main
import (
"context"
"fmt"
"log"
"github.com/skwair/harmony"
)
func main() {
client, err := harmony.NewClient("your.bot.token")
if err != nil {
log.Fatal(err)
}
// Get information about the current user (the bot itself).
u, err := client.User("@me").Get(context.Background())
if err != nil {
log.Fatal(err)
}
fmt.Println(u)
}
For information about how to create bots and more examples on how to use this package, check out the examples directory and the tests.
For now, only some end to end tests are provided with this module. To run them, you will need a valid bot token and a valid Discord server ID. The bot attached to the token must be in the server with administrator permissions.
From a Discord client and with you main account, simply create a new server. Then, right click on the new server and get its ID.
Note that for the UI to have the
Copy IDoption when right clicking on the server, you will need to enable developer mode. You can find this option inUser settings > Appearance > Advanced > Developer Mode.
Create a bot (or use an existing one) and add it to the freshly created server.
See the example directory for information on how to create a bot and add it to a server.
Set HARMONY_TEST_BOT_TOKEN to the token of your bot and HARMONY_TEST_GUILD_ID to the ID of the server you created and simply run:
⚠️ For the tests to be reproducible, they will start by deleting ALL channels in the provided server. Please make sure to provide a server created ONLY for those tests. ⚠️
go test -v -race ./...
Step 1 and 2 must be done only once for initial setup. Once you have your bot token and the ID of your test server, you can run the tests as many times as you want.
Harmony exposes its API differently. It uses a resource-based approach which organizes methods by topic, greatly reducing the number of methods on the main Client type. The goal by doing this is to have a more friendly API which is easier to navigate.
Another key difference is in the "event handler" mechanism. Instead of having a single method that takes an interface{} as a parameter and guesses which event you registered a handler for based on its concrete type, this library provides a dedicated method for each event type, making it clear what signature your handler must have and ensuring it at compile time, not at runtime.
Each action that results in an entry in the audit log has a ...WithReason form, allowing to set a reason for the change (see the X-Audit-Log-Reason header documentation for more information).
Finally, this library has a full support of the context package, allowing the use of timeouts, deadlines and cancellation when interacting with Discord's API.
This project is licensed under the MIT License - see the LICENSE file for details.
Original logo by Renee French, dressed with the cool t-shirt by @HlneChd.
FAQs
Package harmony provides an interface to the Discord API (https://discord.com/developers/docs/intro). The first thing you do with Harmony is to create a Client. NewClient does just that by returning a new Client pre-configured with sain defaults which should work fine in most cases. However, should you need a more specific configuration, you can always tweak it with optional `ClientOption`s. See the documentation of NewClient and the ClientOption type for more information on how to do so. Once you have a Client, you can start interacting with the Discord API, but some methods (such as event handlers) won't be available until you connect to Discord's Gateway. You can do so by simply calling the Connect method of the Client: It is only when successfully connected to the Gateway that your bot will appear as online and your Client will be able to receive events and send messages. Harmony's HTTP API is organized by resource. A resource maps to a core concept in the Discord world, such as a User or a Channel. Here is the list of resources you can interact with: Every interaction you can have with a resource can be accessed via methods attached to it. For example, if you wish to send a message to a channel, first access to the desired channel resource, then send the message: Endpoints that do not fall into one of those resource (creating a Guild for example, or getting valid Voice Regions) are directly available on the Client. To receive messages, use the OnMessageCreate method and give it your handler. It will be called each time a message is sent to a channel your bot is in with the message as a parameter. To register handlers for other types of events, see Client.On* methods. Note that your handlers are called in their own goroutine, meaning whatever you do inside of them won't block future events. When connecting to Discord, a session state is created with initial data sent by Discord's Gateway. As events are received by the client, this state is constantly updated so it always have the newest data available. This session state acts as a cache to avoid making requests over the HTTP API each time. If you need to get information about the current user, you can simply query the current state like so: Because this state might become memory hungry for bots that are in a very large number of servers, you can fine-tune events you want to track with the WithGatewayIntents option. State can also be completely disabled using the WithStateTracking option while creating the harmony client.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Cyber extortion in the US and Canada hit record levels in 2023, with ransomware attacks surging and median ransom demands skyrocketing, though fewer companies are choosing to pay ransoms.
Security News
Ecma TC39 is meeting this week and has moved key ECMAScript proposals forward, advancing Deferred Import Evaluation, Error.isError(), RegExp Escaping, and Promise.try to the next stages.
Security News
Researchers have demonstrated that teams of LLM agents can exploit zero-day vulnerabilities with a 53% success rate, and the costs of using AI to do so are rapidly becoming more affordable than hiring a human penetration tester.