gleam

README

gleam

A simple Go framework for building command-driven Twitch chat bots.

Usage

A full example can be found in example/main.go, but we will walk through the essentials here.

The first step is creating a new bot with gleam.NewBot. This method requires some options for authenticating with Twitch.

bot, err := gleam.NewBot(&gleam.BotOptions{
    Channel: "some channel",
    Username: "some username",
    Password: "some password",
})
if err != nil {
    log.Fatal("error creating new bot: ", err)
}

Note that you can make a bot password using this implicit grant flow implementation.

Once the bot's ready, the next step is handler registration using. Handler functions use a specific signature (func (m gleam.Message) gleam.Event) and are registered using the bot.AddHandler method.

bot.AddHandler("!timer", func(m gleam.Message) gleam.Event {
    // ... do some stuff
    return Event{ ... }
}

After we've added all our handlers, we go ahead and start the connection and listening process. Note that the Bot.Connect method is blocking and should be launched in a goroutine.

go bot.Connect()

Once we see a confirmation message in the browser tab and the program's logs, we know we're ready to start listening for events. There are two important channels to watch: bot.Events and bot.Errors.

for {
    select {
    case event := <-bot.Events:
        // ... handle events
    case error := <-bot.Errors:
        // ... handle errors
    }
}

Design

See DESIGN.md for implementation details.

Documentation

Index

• type Bot
  • func NewBot(opts *BotOptions) (*Bot, error)
  • func (b *Bot) AddHandler(trigger string, handler Handler)
  • func (b *Bot) Connect()
  • func (b Bot) Say(msg string)
• type BotOptions
• type Event
  • func (e Event) String() string
• type Handler
• type Message

Types

type Bot

type Bot struct {
	// Events is the channel where all events arrive after being handled by the
	// registered handlers.
	Events chan Event

	// Errors is the channel were all connection and post-connection errors are
	// sent for handling by the user.
	Errors chan error
	// contains filtered or unexported fields
}

Bot is an abstraction over Twitch IRC that facilitates the creation of command-driven chat bots.

func NewBot

func NewBot(opts *BotOptions) (*Bot, error)

NewBot sets up a Bot with the provided options and opens its channels.

func (*Bot) AddHandler

func (b *Bot) AddHandler(trigger string, handler Handler)

Add handler registers an event handler function on the bot's handler map.

func (*Bot) Connect

func (b *Bot) Connect()

Connect launches the OAuth flow and, if completed, connects to Twitch IRC and starts listening for messages, and should be launched in a goroutine.

func (Bot) Say

func (b Bot) Say(msg string)

type BotOptions

type BotOptions struct {
	Channel  string
	Username string
	Password string
}

BotOptions are the values needed for connecting the bot to a channel/user

type Event

type Event struct {
	// Type is an arbitrary string to describe the type of event.
	Type string

	// UserID is the ID of the user that issued the event.
	UserID string

	// Username is the username of the user that issued the event.
	Username string

	// Data is any additional data that needs to be attached to the event.
	Data any
}

Event abstracts a single event produced by a Handler after its defined trigger is detected by the IRC listener.

func (Event) String

func (e Event) String() string

String prints a human-friendly representation of the event.

type Handler

type Handler func(Message) Event

Handler is a function that takes an IRC message and produces an event.

type Message

type Message twitch.PrivateMessage

Message is a facade type over twitch.PrivateMessage so that users don't need to explicitly import the go-twitch-irc package when adding handlers.