TwitchChannel | twitch-channel

A small JavaScript library to listen to various events that can happen on a twitch channel (chat messages, raids, follows, subscriptions…).

This library acts as a layer on top of various twitch APIs (currently: IRC and EventSub) so you only have to interact with a single EventEmitter that emits uniform events.

The event objects are kept simple and without surprises.

NPM - GitHub

Example

import { TwitchChannel } from "twitch-channel";

const channel = new TwitchChannel({
  channel: "your_channel",
  clientId: "your_app_id",
  clientSecret: "your_app_secret",
});

channel.on("sub-gift-received", ({ gifterName, recipientName }) => {
  console.log(`${gifterName} just subgifted ${recipientName}`);
});
channel.on("log", ({ level, message, error }) => {
  console.log(`[${level}] ${message}`, error);
});

await channel.connect();

Connecting to sources

Depending on which config you provide, the lib will be able to emit many types of events.

Event	Always available	Moderator IRC bot	Broadcaster IRC bot	EventSub	Authorized EventSub
BanEvent		X			X
ChatEvent	X
CheerEvent	X
ClearChatEvent	X
EmotesOnlyEvent	X
FollowEvent				X
FollowersOnlyEvent	X
HostEvent			X
HostingEvent	X
HypeTrainBeginEvent					X
HypeTrainEndEvent					X
MessageDeletedEvent	X
RaidEvent	X
RewardRedeemEvent					X
SlowModeEvent	X
StreamBeginEvent				X
StreamChangeCategoryEvent				X
StreamChangeTitleEvent				X
StreamEndEvent				X
SubEvent	X
SubGiftReceivedEvent	X
SubGiftEvent					X
SubsOnlyEvent	X
TimeoutEvent		X			X

EventSub

EventSub is a system where twitch sends HTTPS requests to notify your server.

In order to make it work, your server must be reachable from the internet with HTTPS and a domain name (you may need a reverse proxy: this lib won't handle the TLS layer and will listen to HTTP requests only).

From here you have 2 choices:

Either you provide both OptionalConfig.callbackUrl and OptionalConfig.port, and the lib will start an http server that will listen to twitch's requests on the provided port.
Or, if you already have an Express-like server, you provide only OptionalConfig.callbackUrl and you call TwitchChannel.applyEventSubMiddleware on your server, and the lib will add a middleware to your server so it receives twitch's requests.

Some events require your client to be authorized by the channel's owner. To do that, you must create an OAuth flow where the user generates a token using your app's client id and containing the required scopes. Once the channel's owner have authorized your app, you don't need the resulting token.

The needed scopes are: channel:moderate channel:read:hype_train channel:read:redemptions channel:read:subscriptions.

Hierarchy

TwitchChannel

Index

Constructors

constructor

Methods

Constructors

constructor

new TwitchChannel(config: Config): TwitchChannel

Parameters
- config: Config
Returns TwitchChannel

Methods

applyEventSubMiddleware

applyEventSubMiddleware(app: unknown): void

Add a middleware to your Express server so it will receive EventSub notifications.

Must be called before TwitchChannel.connect.

See the EventSub paragraph in TwitchChannel.

Parameters
- app: unknown
Returns void

connect

connect(): Promise<void>

Connect to the IRC chat, subscribe to EventSub, start emitting events.

Returns Promise<void>

disconnect

disconnect(): Promise<void>

Disconnect from every source and stop emitting events.

Returns Promise<void>

on

on(event: "ban", handler: (param: BanEvent) => void): void
on(event: "chat", handler: (param: ChatEvent) => void): void
on(event: "cheer", handler: (param: CheerEvent) => void): void
on(event: "clear-chat", handler: (param: ClearChatEvent) => void): void
on(event: "emotes-only", handler: (param: EmotesOnlyEvent) => void): void
on(event: "follow", handler: (param: FollowEvent) => void): void
on(event: "followers-only", handler: (param: FollowersOnlyEvent) => void): void
on(event: "host", handler: (param: HostEvent) => void): void
on(event: "hosting", handler: (param: HostingEvent) => void): void
on(event: "hype-train-begin", handler: (param: HypeTrainBeginEvent) => void): void
on(event: "hype-train-end", handler: (param: HypeTrainEndEvent) => void): void
on(event: "message-deleted", handler: (param: MessageDeletedEvent) => void): void
on(event: "raid", handler: (param: RaidEvent) => void): void
on(event: "reward-redeem", handler: (param: RewardRedeemEvent) => void): void
on(event: "slow-mode", handler: (param: SlowModeEvent) => void): void
on(event: "stream-begin", handler: (param: StreamBeginEvent) => void): void
on(event: "stream-change-category", handler: (param: StreamChangeCategoryEvent) => void): void
on(event: "stream-change-title", handler: (param: StreamChangeTitleEvent) => void): void
on(event: "stream-end", handler: (param: StreamEndEvent) => void): void
on(event: "sub", handler: (param: SubEvent) => void): void
on(event: "sub-gift", handler: (param: SubGiftEvent) => void): void
on(event: "sub-gift-received", handler: (param: SubGiftReceivedEvent) => void): void
on(event: "subs-only", handler: (param: SubsOnlyEvent) => void): void
on(event: "timeout", handler: (param: TimeoutEvent) => void): void
on(event: "log", handler: (param: LogEvent) => void): void

Subscribe to an event type

Parameters
- event: "ban"
  
  the event to subscribe
- handler: (param: BanEvent) => void
  
  the handler
  - - (param: BanEvent): void
    - Parameters
      - param: BanEvent
      Returns void
Returns void
Subscribe to an event type

Parameters
- event: "chat"
  
  the event to subscribe
- handler: (param: ChatEvent) => void
  
  the handler
  - - (param: ChatEvent): void
    - Parameters
      - param: ChatEvent
      Returns void
Returns void
Subscribe to an event type

Parameters
- event: "cheer"
  
  the event to subscribe
- handler: (param: CheerEvent) => void
  
  the handler
  - - (param: CheerEvent): void
    - Parameters
      - param: CheerEvent
      Returns void
Returns void
Subscribe to an event type

Parameters
- event: "clear-chat"
  
  the event to subscribe
- handler: (param: ClearChatEvent) => void
  
  the handler
  - - (param: ClearChatEvent): void
    - Parameters
      - param: ClearChatEvent
      Returns void
Returns void
Subscribe to an event type

Parameters
- event: "emotes-only"
  
  the event to subscribe
- handler: (param: EmotesOnlyEvent) => void
  
  the handler
  - - (param: EmotesOnlyEvent): void
    - Parameters
      - param: EmotesOnlyEvent
      Returns void
Returns void
Subscribe to an event type

Parameters
- event: "follow"
  
  the event to subscribe
- handler: (param: FollowEvent) => void
  
  the handler
  - - (param: FollowEvent): void
    - Parameters
      - param: FollowEvent
      Returns void
Returns void
Subscribe to an event type

Parameters
- event: "followers-only"
  
  the event to subscribe
- handler: (param: FollowersOnlyEvent) => void
  
  the handler
  - - (param: FollowersOnlyEvent): void
    - Parameters
      - param: FollowersOnlyEvent
      Returns void
Returns void
Subscribe to an event type

Parameters
- event: "host"
  
  the event to subscribe
- handler: (param: HostEvent) => void
  
  the handler
  - - (param: HostEvent): void
    - Parameters
      - param: HostEvent
      Returns void
Returns void
Subscribe to an event type

Parameters
- event: "hosting"
  
  the event to subscribe
- handler: (param: HostingEvent) => void
  
  the handler
  - - (param: HostingEvent): void
    - Parameters
      - param: HostingEvent
      Returns void
Returns void
Subscribe to an event type

Parameters
- event: "hype-train-begin"
  
  the event to subscribe
- handler: (param: HypeTrainBeginEvent) => void
  
  the handler
  - - (param: HypeTrainBeginEvent): void
    - Parameters
      - param: HypeTrainBeginEvent
      Returns void
Returns void
Subscribe to an event type

Parameters
- event: "hype-train-end"
  
  the event to subscribe
- handler: (param: HypeTrainEndEvent) => void
  
  the handler
  - - (param: HypeTrainEndEvent): void
    - Parameters
      - param: HypeTrainEndEvent
      Returns void
Returns void
Subscribe to an event type

Parameters
- event: "message-deleted"
  
  the event to subscribe
- handler: (param: MessageDeletedEvent) => void
  
  the handler
  - - (param: MessageDeletedEvent): void
    - Parameters
      - param: MessageDeletedEvent
      Returns void
Returns void
Subscribe to an event type

Parameters
- event: "raid"
  
  the event to subscribe
- handler: (param: RaidEvent) => void
  
  the handler
  - - (param: RaidEvent): void
    - Parameters
      - param: RaidEvent
      Returns void
Returns void
Subscribe to an event type

Parameters
- event: "reward-redeem"
  
  the event to subscribe
- handler: (param: RewardRedeemEvent) => void
  
  the handler
  - - (param: RewardRedeemEvent): void
    - Parameters
      - param: RewardRedeemEvent
      Returns void
Returns void
Subscribe to an event type

Parameters
- event: "slow-mode"
  
  the event to subscribe
- handler: (param: SlowModeEvent) => void
  
  the handler
  - - (param: SlowModeEvent): void
    - Parameters
      - param: SlowModeEvent
      Returns void
Returns void
Subscribe to an event type

Parameters
- event: "stream-begin"
  
  the event to subscribe
- handler: (param: StreamBeginEvent) => void
  
  the handler
  - - (param: StreamBeginEvent): void
    - Parameters
      - param: StreamBeginEvent
      Returns void
Returns void
Subscribe to an event type

Parameters
- event: "stream-change-category"
  
  the event to subscribe
- handler: (param: StreamChangeCategoryEvent) => void
  
  the handler
  - - (param: StreamChangeCategoryEvent): void
    - Parameters
      - param: StreamChangeCategoryEvent
      Returns void
Returns void
Subscribe to an event type

Parameters
- event: "stream-change-title"
  
  the event to subscribe
- handler: (param: StreamChangeTitleEvent) => void
  
  the handler
  - - (param: StreamChangeTitleEvent): void
    - Parameters
      - param: StreamChangeTitleEvent
      Returns void
Returns void
Subscribe to an event type

Parameters
- event: "stream-end"
  
  the event to subscribe
- handler: (param: StreamEndEvent) => void
  
  the handler
  - - (param: StreamEndEvent): void
    - Parameters
      - param: StreamEndEvent
      Returns void
Returns void
Subscribe to an event type

Parameters
- event: "sub"
  
  the event to subscribe
- handler: (param: SubEvent) => void
  
  the handler
  - - (param: SubEvent): void
    - Parameters
      - param: SubEvent
      Returns void
Returns void
Subscribe to an event type

Parameters
- event: "sub-gift"
  
  the event to subscribe
- handler: (param: SubGiftEvent) => void
  
  the handler
  - - (param: SubGiftEvent): void
    - Parameters
      - param: SubGiftEvent
      Returns void
Returns void
Subscribe to an event type

Parameters
- event: "sub-gift-received"
  
  the event to subscribe
- handler: (param: SubGiftReceivedEvent) => void
  
  the handler
  - - (param: SubGiftReceivedEvent): void
    - Parameters
      - param: SubGiftReceivedEvent
      Returns void
Returns void
Subscribe to an event type

Parameters
- event: "subs-only"
  
  the event to subscribe
- handler: (param: SubsOnlyEvent) => void
  
  the handler
  - - (param: SubsOnlyEvent): void
    - Parameters
      - param: SubsOnlyEvent
      Returns void
Returns void
Subscribe to an event type

Parameters
- event: "timeout"
  
  the event to subscribe
- handler: (param: TimeoutEvent) => void
  
  the handler
  - - (param: TimeoutEvent): void
    - Parameters
      - param: TimeoutEvent
      Returns void
Returns void
Subscribe to an event type

Parameters
- event: "log"
  
  the event to subscribe
- handler: (param: LogEvent) => void
  
  the handler
  - - (param: LogEvent): void
    - Parameters
      - param: LogEvent
      Returns void
Returns void

Example

Connecting to sources

EventSub

Hierarchy

Index

Constructors

Methods

Constructors

constructor

Parameters

config: Config

Returns TwitchChannel

Methods

applyEventSubMiddleware

Parameters

app: unknown

Returns void

connect

Returns Promise<void>

disconnect

Returns Promise<void>

on

Parameters

event: "ban"

handler: (param: BanEvent) => void

Parameters

param: BanEvent

Returns void

Returns void

Parameters

event: "chat"

handler: (param: ChatEvent) => void

Parameters

param: ChatEvent

Returns void

Returns void

Parameters

event: "cheer"

handler: (param: CheerEvent) => void

Parameters

param: CheerEvent

Returns void

Returns void

Parameters

event: "clear-chat"

handler: (param: ClearChatEvent) => void

Parameters

param: ClearChatEvent

Returns void

Returns void

Parameters

event: "emotes-only"

handler: (param: EmotesOnlyEvent) => void

Parameters

param: EmotesOnlyEvent

Returns void

Returns void

Parameters

event: "follow"

handler: (param: FollowEvent) => void

Parameters

param: FollowEvent

Returns void

Returns void

Parameters

event: "followers-only"

handler: (param: FollowersOnlyEvent) => void

Parameters

param: FollowersOnlyEvent

Returns void

Returns void

Parameters

event: "host"

handler: (param: HostEvent) => void

Parameters

param: HostEvent

Returns void

Returns void

Parameters

event: "hosting"