helix

README

helix

This package contains code to interface with the Twitch Helix API to manage subscribe to chat messages in conduits, as well as code to manage the chat messages themselves.

Usage

Call helix.NewTwitchAPI with a valid clientID, OAuth token and bot user ID.
The twitch application of the clientID should have the user:read:chat, user:bot scopes for your bot user. And either the channel:bot scope, or moderator status for the channels you're trying to join.

Missing features

• Joining an existing conduit
• Conduits don't get deleted when all shards are disconnected.
• Sending messages to chat
• Handling any other chat message type than channel chat messages, such as whispers, follows, etc.
• Probably much more

Documentation

Index

• type AssignConduitTransportRequest
• type AssignConduitTransportResponse
• type ChannelMessage
  • func ParseChannelMessage(data []byte) (ChannelMessage, error)
• type ChannelMessageEvent
• type CreateConduitResponse
• type EventSubscribeCondition
• type EventSubscribeRequest
  • func GetChannelMessageSubscribeRequest(conduitID, channelID, userID string) *EventSubscribeRequest
• type EventSubscribeResponse
• type EventType
• type Subscription
• type Transport
• type TransportMethod
• type TransportShard
• type TransportUpdate
  • func (u *TransportUpdate) GetConduitTransportRequest(conduitID string, shardID string) *AssignConduitTransportRequest
• type TwitchAPI
  • func NewTwitchAPI(clientID, oauthToken, userID string) *TwitchAPI
  • func (t *TwitchAPI) AssignConduitTransport(request *AssignConduitTransportRequest) (*AssignConduitTransportResponse, error)
  • func (t *TwitchAPI) CreateConduit(shardCount int) (*CreateConduitResponse, error)
  • func (t *TwitchAPI) Do(method, url string, body io.Reader) (*http.Response, error)
  • func (t *TwitchAPI) EventSubscribe(request *EventSubscribeRequest) (*EventSubscribeResponse, error)
  • func (t *TwitchAPI) EventSubscribeChannelMessage(conduitID, channelID, userID string) (*EventSubscribeResponse, error)
  • func (t *TwitchAPI) UpdateOAuthToken(oauthToken string)

Types

type AssignConduitTransportRequest

type AssignConduitTransportRequest struct {
	ConduitID string           `json:"conduit_id"`
	Shards    []TransportShard `json:"shards"`
}

AssignConduitTransportRequest is the request body for assigning a transport to shards of a conduit

type AssignConduitTransportResponse

type AssignConduitTransportResponse struct {
	Data []TransportShard `json:"data"`
}

AssignConduitTransportResponse is the response the Twitch API returns when assigning a transport a conduit

type ChannelMessage

type ChannelMessage struct {
	Subscription Subscription        `json:"subscription"`
	Event        ChannelMessageEvent `json:"event"`
}

ChannelMessage is the structure of a chat message received through a conduit

func ParseChannelMessage

func ParseChannelMessage(data []byte) (ChannelMessage, error)

ParseChannelMessage parses a channel message from a slice of bytes

type ChannelMessageEvent

type ChannelMessageEvent struct {
	BroadcasterUserID    string `json:"broadcaster_user_id"`
	BroadcasterUserLogin string `json:"broadcaster_user_login"`
	BroadcasterUserName  string `json:"broadcaster_user_name"`
	ChatterUserID        string `json:"chatter_user_id"`
	ChatterUserLogin     string `json:"chatter_user_login"`
	ChatterUserName      string `json:"chatter_user_name"`
	MessageID            string `json:"message_id"`
	Message              struct {
		Text      string `json:"text"`
		Fragments []struct {
			Type string `json:"type"`
			Text string `json:"text"`
			// TODO: figure out types
			Cheermote interface{} `json:"cheermote"`
			Emote     interface{} `json:"emote"`
			Mention   interface{} `json:"mention"`
		} `json:"fragments"`
	} `json:"message"`
	Color  string `json:"color"`
	Badges []struct {
		SetID string `json:"set_id"`
		ID    string `json:"id"`
		Info  string `json:"info"`
	} `json:"badges"`
	MessageType string `json:"message_type"`
	// TODO: figure out types
	Cheer                       interface{} `json:"cheer"`
	Reply                       interface{} `json:"reply"`
	ChannelPointsCustomRewardID interface{} `json:"channel_points_custom_reward_id"`
}

ChannelMessageEvent is the structure for the event data of a chat message received through a conduit

type CreateConduitResponse

type CreateConduitResponse struct {
	Data []struct {
		ID         string `json:"id"`
		ShardCount int    `json:"shard_count"`
	} `json:"data"`
}

CreateConduitResponse is the response the Twitch API returns when creating a conduit

type EventSubscribeCondition

type EventSubscribeCondition struct {
	BroadcasterUserID string `json:"broadcaster_user_id"`
	ModeratorUserID   string `json:"moderator_user_id,omitempty"`
	UserID            string `json:"user_id,omitempty"`
}

EventSubscribeCondition contains the user data for the event subscription

type EventSubscribeRequest

type EventSubscribeRequest struct {
	Type      EventType               `json:"type"`
	Version   string                  `json:"version"`
	Condition EventSubscribeCondition `json:"condition"`
	Transport TransportUpdate         `json:"transport"`
}

EventSubscribeRequest is the request body for subscribing to an eventSub event

func GetChannelMessageSubscribeRequest

func GetChannelMessageSubscribeRequest(conduitID, channelID, userID string) *EventSubscribeRequest

GetChannelMessageSubscribeRequest returns an EventSubscribeRequest for subscribing to chat events in the given channel, as the given user

type EventSubscribeResponse

type EventSubscribeResponse struct {
	Data []struct {
		ID        string                  `json:"id"`
		Status    string                  `json:"status"`
		Type      EventType               `json:"type"`
		Version   string                  `json:"version"`
		Condition EventSubscribeCondition `json:"condition"`
		CreatedAt string                  `json:"created_at"`
		Transport TransportUpdate         `json:"transport"`
		Cost      int                     `json:"cost"`
	}
	Total        int `json:"total"`
	MaxTotalCost int `json:"max_total_cost"`
	TotalCost    int `json:"total_cost"`
}

EventSubscribeResponse is the response the Twitch API returns when subscribing to an eventSub event

type EventType

type EventType string

EventType is the type of event that the conduit/subscription is for

const (
	// EventTypeNull is an empty event type, and therefore the default value of EventType
	EventTypeNull EventType = ""
	//EventTypeChannelMessage is a chat message
	EventTypeChannelMessage EventType = "channel.chat.message"
)

type Subscription

type Subscription struct {
	ID        string    `json:"id"`
	Status    string    `json:"status"`
	Type      EventType `json:"type"`
	Version   string    `json:"version"`
	Condition struct {
		BroadcasterUserID string `json:"broadcaster_user_id"`
		UserID            string `json:"user_id"`
	} `json:"condition"`
	Transport struct {
		Method    string `json:"method"`
		SessionID string `json:"session_id"`
	} `json:"transport"`
	CreatedAt string `json:"created_at"`
	Cost      int    `json:"cost"`
}

Subscription is the structure for subscription data of a message received through a conduit

type Transport

type Transport interface {
	// Init initializes the transport
	Init() error
	// Close closes the transport
	Close()
	// Ready returns the ready channel, which is closed when the transport is ready to be used.
	// Reading from the channel, after calling Init, will block until the transport is ready.
	Ready() chan struct{}
	// GetTransportUpdate returns a TransportUpdate used to update the conduit
	GetTransportUpdate() *TransportUpdate
	// OnChannelMessage sets a callback to be called when a channel message is received, is not executed in gorourines. It is the responsibility of the caller to handle concurrency.
	OnChannelMessage(func(message ChannelMessage))
}

Transport is used to manage websocket & webhook conduits as a single interface

type TransportMethod

type TransportMethod string

TransportMethod is the method of transport used by the conduit/subscription

const (
	TransportMethodWebhook   TransportMethod = "webhook"
	TransportMethodWebsocket TransportMethod = "websocket"
	TransportMethodConduit   TransportMethod = "conduit"
)

type TransportShard

type TransportShard struct {
	ID        string          `json:"id"`
	Status    string          `json:"status,omitempty"`
	Transport TransportUpdate `json:"transport"`
}

TransportShard is a shard of a conduit

type TransportUpdate

type TransportUpdate struct {
	Method    TransportMethod `json:"method"`
	Callback  string          `json:"callback,omitempty"`
	ConduitID string          `json:"conduit_id,omitempty"`
	SessionID string          `json:"session_id,omitempty"`
	Secret    string          `json:"secret,omitempty"`
}

TransportUpdate contains the data of the transport for a conduit shard

func (*TransportUpdate) GetConduitTransportRequest

func (u *TransportUpdate) GetConduitTransportRequest(conduitID string, shardID string) *AssignConduitTransportRequest

GetConduitTransportRequest returns an AssignConduitTransportRequest for assigning a transport to a conduit using TwitchAPI.AssignConduitTransport

type TwitchAPI

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

TwitchAPI is a struct used to interact with the Twitch helix API

func NewTwitchAPI

func NewTwitchAPI(clientID, oauthToken, userID string) *TwitchAPI

NewTwitchAPI returns a new instance of the TwitchAPI configured with the given clientID, oauthToken, and userID

func (*TwitchAPI) AssignConduitTransport

func (t *TwitchAPI) AssignConduitTransport(request *AssignConduitTransportRequest) (*AssignConduitTransportResponse, error)

AssignConduitTransport sends a request to the Twitch API to assign a transport to shards of a conduit

func (*TwitchAPI) CreateConduit

func (t *TwitchAPI) CreateConduit(shardCount int) (*CreateConduitResponse, error)

CreateConduit sends a request to the Twitch API to create a conduit with the given shard count

func (*TwitchAPI) Do

func (t *TwitchAPI) Do(method, url string, body io.Reader) (*http.Response, error)

Do send a request to the given URL with the given method & body, adding authorization headers

func (*TwitchAPI) EventSubscribe

func (t *TwitchAPI) EventSubscribe(request *EventSubscribeRequest) (*EventSubscribeResponse, error)

EventSubscribe sends a request to the Twitch API to subscribe to an eventSub event

func (*TwitchAPI) EventSubscribeChannelMessage

func (t *TwitchAPI) EventSubscribeChannelMessage(conduitID, channelID, userID string) (*EventSubscribeResponse, error)

EventSubscribeChannelMessage subscribes to chat events in the given channel, as the given user. This is more or less the equivalent of JOIN in IRC.

func (*TwitchAPI) UpdateOAuthToken

func (t *TwitchAPI) UpdateOAuthToken(oauthToken string)

UpdateOAuthToken updates the oauth token used by the TwitchAPI, used when the token expires