salamander

README

Salamander

[!WARNING] In development. May contain bugs.

[!CAUTION] This project is not stable. Breaking changes may happen at any time without prior notice.

A Discord API wrapper for Go designed for selfbot usage.

[!IMPORTANT] Legal Disclaimer: Selfbots violate Discord's Terms of Service. Use at your own risk. We are not responsible for any consequences including account termination, bans, or any other actions taken by Discord. By using this library, you acknowledge and accept all risks involved.

Features

• ✅ Gateway support
• 🚧 REST API (in progress)
• 📊 Estimated REST coverage: ~26-30% (approx.; measured from current implemented endpoints/operations)

Requirements

• Go 1.25+

Installation

go get github.com/goland-express/salamander

Quick Start

package main

import (
 "context"
 "log"
 "log/slog"
 "os"
 "os/signal"

 "github.com/goland-express/salamander"
 "github.com/goland-express/salamander/events"
 "github.com/goland-express/salamander/gateway"
)

func main() {
 token := "YOUR_TOKEN_HERE"
 
 logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
  Level: slog.LevelInfo,
 }))

 client := salamander.New(token,
  gateway.WithLogger(logger),
  gateway.WithCompression(gateway.CompressionZstd),
 )

 salamander.OnTyped(client, func(e *events.MessageCreate) {
  if e.Content == "!ping" {
   logger.Info("pong!")
  }
 })

 salamander.OnTyped(client, func(e *events.Ready) {
  logger.Info("bot ready", "session_id", e.SessionID)
 })

 ctx := context.Background()
 if err := client.Connect(ctx); err != nil {
  log.Fatal(err)
 }

 stop := make(chan os.Signal, 1)
 signal.Notify(stop, os.Interrupt)
 <-stop

 logger.Info("shutting down...")
 if err := client.Close(ctx); err != nil {
  logger.Error("error closing client", "error", err)
 }
}

salamander.OnTyped(client, handler) is the compile-time safe listener API. On(any) is still available for dynamic handler registration.

Examples

• _examples/ping: basic gateway event listening (!ping log)
• _examples/reply_ping: message listener + REST reply (!ping -> pong!)
• _examples/health: connection health monitoring (latency/sequence/ack timestamps)
• _examples/rest_session: REST session persistence + channel fetch

Documentation

Contributing

Pull requests are welcome. For major changes, open an issue first to discuss what you want to change.

License

MIT

Documentation

Index

• func OnTyped[T any](c *Client, handler func(T)) func()
• type Client
  • func New(token string, opts ...any) *Client
  • func (c *Client) Cache() cache.Cache
  • func (c *Client) Close(ctx context.Context) error
  • func (c *Client) Connect(ctx context.Context) error
  • func (c *Client) Gateway() *gateway.Gateway
  • func (c *Client) Health() gateway.GatewayHealth
  • func (c *Client) On(handler any) func()
  • func (c *Client) Rest() *rest.Client
  • func (c *Client) SetPresence(ctx context.Context, opts ...gateway.PresenceOpt) error
• type Option
  • func WithCache(opts ...cache.Option) Option

Functions

func OnTyped

func OnTyped[T any](c *Client, handler func(T)) func()

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

func New

func New(token string, opts ...any) *Client

func (*Client) Cache

func (c *Client) Cache() cache.Cache

func (*Client) Close

func (c *Client) Close(ctx context.Context) error

func (*Client) Connect

func (c *Client) Connect(ctx context.Context) error

func (*Client) Gateway

func (c *Client) Gateway() *gateway.Gateway

func (*Client) Health

func (c *Client) Health() gateway.GatewayHealth

func (*Client) On

func (c *Client) On(handler any) func()

func (*Client) Rest

func (c *Client) Rest() *rest.Client

func (*Client) SetPresence

func (c *Client) SetPresence(ctx context.Context, opts ...gateway.PresenceOpt) error

type Option

type Option func(*Client)

func WithCache

func WithCache(opts ...cache.Option) Option