eventsub_framework

package module
v0.0.0-...-9c1dc95 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 22, 2023 License: MIT Imports: 15 Imported by: 0

README

twitch-eventsub-framework

A small framework for creating Twitch EventSub applications with an HTTP transport.

Note: At the moment, this library does not support the WebSocket transport.

Features

This package has two main features:

  1. A SubClient to subscribe to, unsubscribe to, and list subscriptions created with EventSub
  2. A SubHandler to handle webhook verification requests and dispatch webhook notifications

Examples

  1. See examples/sub_client/main.go for an example usage of creating a new webhook subscription.
  2. See examples/sub_handler/main.go for an example usage of receiving webhook notifications from Twitch.

Documentation

Index

Constants

View Source 
const (
	EventSubSubscriptionsEndpoint = "https://api.twitch.tv/helix/eventsub/subscriptions"
)

Variables

This section is empty.

Functions

func VerifyRequestSignature 

func VerifyRequestSignature(req *http.Request, body, secret []byte) (bool, error)

Types

type Credentials 

type Credentials interface {
	ClientID() (string, error)
	AppToken() (string, error)
}

Credentials represents a method of obtaining Twitch API client credentials

func NewStaticCredentials 

func NewStaticCredentials(clientID string, appToken string) Credentials

NewStaticCredentials creates a Credentials instance with a fixed ClientID string and AppToken string.

This Credentials implementation should only be used for development as the app token will eventually expire and API calls will subsequently fail.

type IDTracker 

type IDTracker interface {
	// AddAndCheckIfDuplicate returns if the ID is a duplicate and an error.
	AddAndCheckIfDuplicate(ctx context.Context, id string) (bool, error)
}

type MapTracker 

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

MapTracker uses an in-memory map to check if a notification ID is a duplicate.

func NewMapTracker 

func NewMapTracker() *MapTracker

NewMapTracker creates a new MapTracker instance which uses an in-memory map to check if a notification ID is a duplicate.

func (*MapTracker) AddAndCheckIfDuplicate 

func (m *MapTracker) AddAndCheckIfDuplicate(_ context.Context, id string) (bool, error)

type Status 

type Status string
const (
	StatusAny                  Status = ""
	StatusEnabled              Status = "enabled"
	StatusVerificationPending  Status = "webhook_callback_verification_pending"
	StatusVerificationFailed   Status = "webhook_callback_verification_failed"
	StatusFailuresExceeded     Status = "notification_failures_exceeded"
	StatusAuthorizationRevoked Status = "authorization_revoked"
	StatusModeratorRemoved     Status = "moderator_removed"
	StatusUserRemoved          Status = "user_removed"
	StatusVersionRemoved       Status = "version_removed"
)

type SubClient 

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

func NewSubClient 

func NewSubClient(credentials Credentials) *SubClient

NewSubClient creates a new SubClient with the given Credentials provider.

func NewSubClientHTTP 

func NewSubClientHTTP(credentials Credentials, client *http.Client) *SubClient

NewSubClientHTTP creates a new SubClient with the given Credentials provider and http.Client instance.

func (*SubClient) GetSubscriptions 

func (s *SubClient) GetSubscriptions(ctx context.Context, statusFilter Status) (*esb.RequestStatus, error)

GetSubscriptions returns all EventSub subscriptions. If statusFilter != StatusAny, it will apply the filter to the query.

func (*SubClient) Subscribe 

func (s *SubClient) Subscribe(ctx context.Context, srq *SubRequest) (*esb.RequestStatus, error)

Subscribe creates a new Webhook subscription.

func (*SubClient) Unsubscribe 

func (s *SubClient) Unsubscribe(ctx context.Context, subscriptionID string) error

Unsubscribe deletes a Webhook subscription by the subscription's ID.

type SubHandler 

type SubHandler struct {

	// Challenge handler function.
	// Returns whether the subscription should be accepted.
	VerifyChallenge func(h *esb.ResponseHeaders, chal *esb.SubscriptionChallenge) bool

	// IDTracker used to deduplicate notifications
	IDTracker               IDTracker
	OnDuplicateNotification func(h *esb.ResponseHeaders)
	OnRawEvent              func(h *esb.ResponseHeaders, event json.RawMessage)

	HandleChannelUpdate func(h *esb.ResponseHeaders, event *esb.EventChannelUpdate)
	HandleChannelFollow func(h *esb.ResponseHeaders, event *esb.EventChannelFollow)
	HandleUserUpdate    func(h *esb.ResponseHeaders, event *esb.EventUserUpdate)

	HandleChannelSubscribe           func(h *esb.ResponseHeaders, event *esb.EventChannelSubscribe)
	HandleChannelSubscriptionEnd     func(h *esb.ResponseHeaders, event *esb.EventChannelSubscriptionEnd)
	HandleChannelSubscriptionGift    func(h *esb.ResponseHeaders, event *esb.EventChannelSubscriptionGift)
	HandleChannelSubscriptionMessage func(h *esb.ResponseHeaders, event *esb.EventChannelSubscriptionMessage)
	HandleChannelCheer               func(h *esb.ResponseHeaders, event *esb.EventChannelCheer)
	HandleChannelRaid                func(h *esb.ResponseHeaders, event *esb.EventChannelRaid)

	HandleChannelBan             func(h *esb.ResponseHeaders, event *esb.EventChannelBan)
	HandleChannelUnban           func(h *esb.ResponseHeaders, event *esb.EventChannelUnban)
	HandleChannelModeratorAdd    func(h *esb.ResponseHeaders, event *esb.EventChannelModeratorAdd)
	HandleChannelModeratorRemove func(h *esb.ResponseHeaders, event *esb.EventChannelModeratorRemove)

	HandleChannelPointsRewardAdd              func(h *esb.ResponseHeaders, event *esb.EventChannelPointsRewardAdd)
	HandleChannelPointsRewardUpdate           func(h *esb.ResponseHeaders, event *esb.EventChannelPointsRewardUpdate)
	HandleChannelPointsRewardRemove           func(h *esb.ResponseHeaders, event *esb.EventChannelPointsRewardRemove)
	HandleChannelPointsRewardRedemptionAdd    func(h *esb.ResponseHeaders, event *esb.EventChannelPointsRewardRedemptionAdd)
	HandleChannelPointsRewardRedemptionUpdate func(h *esb.ResponseHeaders, event *esb.EventChannelPointsRewardRedemptionUpdate)

	HandleChannelPollBegin    func(h *esb.ResponseHeaders, event *esb.EventChannelPollBegin)
	HandleChannelPollProgress func(h *esb.ResponseHeaders, event *esb.EventChannelPollProgress)
	HandleChannelPollEnd      func(h *esb.ResponseHeaders, event *esb.EventChannelPollEnd)

	HandleChannelPredictionBegin    func(h *esb.ResponseHeaders, event *esb.EventChannelPredictionBegin)
	HandleChannelPredictionProgress func(h *esb.ResponseHeaders, event *esb.EventChannelPredictionProgress)
	HandleChannelPredictionLock     func(h *esb.ResponseHeaders, event *esb.EventChannelPredictionLock)
	HandleChannelPredictionEnd      func(h *esb.ResponseHeaders, event *esb.EventChannelPredictionEnd)

	HandleDropEntitlementGrant           func(h *esb.ResponseHeaders, event *esb.EventDropEntitlementGrant)
	HandleExtensionBitsTransactionCreate func(h *esb.ResponseHeaders, event *esb.EventBitsTransactionCreate)

	HandleGoalBegin    func(h *esb.ResponseHeaders, event *esb.EventGoals)
	HandleGoalProgress func(h *esb.ResponseHeaders, event *esb.EventGoals)
	HandleGoalEnd      func(h *esb.ResponseHeaders, event *esb.EventGoals)

	HandleHypeTrainBegin    func(h *esb.ResponseHeaders, event *esb.EventHypeTrainBegin)
	HandleHypeTrainProgress func(h *esb.ResponseHeaders, event *esb.EventHypeTrainProgress)
	HandleHypeTrainEnd      func(h *esb.ResponseHeaders, event *esb.EventHypeTrainEnd)

	HandleStreamOnline  func(h *esb.ResponseHeaders, event *esb.EventStreamOnline)
	HandleStreamOffline func(h *esb.ResponseHeaders, event *esb.EventStreamOffline)

	HandleUserAuthorizationGrant  func(h *esb.ResponseHeaders, event *esb.EventUserAuthorizationGrant)
	HandleUserAuthorizationRevoke func(h *esb.ResponseHeaders, event *esb.EventUserAuthorizationRevoke)
	// contains filtered or unexported fields
}

SubHandler implements http.Handler to receive Twitch webhook notifications.

SubHandler handles both verification of new subscriptions and dispatching of event notifications. To handle a specific event, set the corresponding HandleXXX struct field. When a notification is received and validated, the handler function will be invoked in a new goroutine.

func NewSubHandler 

func NewSubHandler(doSignatureVerification bool, secret []byte) *SubHandler

func (*SubHandler) ServeHTTP 

func (s *SubHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

type SubRequest 

type SubRequest struct {
	// The type of event being subscribed to.
	Type string
	// The parameters under which the event will be fired.
	Condition interface{}
	// The Webhook HTTP callback address.
	Callback string
	// The HMAC secret used to verify the event data.
	Secret string
	// The subscription type version.
	Version string
}

type TwitchError 

type TwitchError struct {
	ErrorText string `json:"error"`
	Status    int    `json:"status"`
	Message   string `json:"message"`
}

TwitchError describes an error from the Twitch API.

For example: 

{
  "error": "Unauthorized",
  "status": 401,
  "message": "Invalid OAuth token"
}

func (*TwitchError) Error 

func (t *TwitchError) Error() string

Source Files

View all Source files

Directories

Path Synopsis
examples
sub_client
sub_handler

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.