# EventSub Proxy (ESP)

ESP is a service provided by [`fdgt`](https://fdgt.dev) to allow third party [Twitch](https://dev.twitch.tv) developers to leverage Twitch's [EventSub system](https://dev.twitch.tv/docs/eventsub) in serverless applications.

## Connecting to ESP

The ESP service is currently running at `esp.fdgt.dev`. It is an SSL-only connection, so all `ws://` or `http://` connections will be upgraded to `wss://` or `https://`, respectively.

You can connect to the service by opening a new WebSocket connection to the URL. For example, in JavaScript:

const espSocket = new WebSocket('wss://esp.fdgt.dev')
espSocket.addEventListener('message', event => console.log(event))

## Handling Messages

ESP sends data over the socket as JSON strings. There are currently 2 messages that the service sends:

### `PING`
ESP sends pings every 30 seconds to ensure the connection is still live and in use. These messages take the form...

{ "action": "PING" }

After sending the ping, ESP will wait 5 seconds for a response. If no response is sent, the connection will be closed. To keep the connection open after receiving a ping, respond with a pong:

{ "action": "PONG" }

### `EVENT`
Events are sent when an EventSub action is triggered for a channel/event to which the connection has subscribed. These messages take the form...

{
  "action": "EVENT",
  "event": "channel.follow",
  "data": {
		"user_id": "1234",
		"user_login": "cool_user",
		"user_name": "Cool_User",
		"broadcaster_user_id": "1337",
		"broadcaster_user_login": "cooler_user",
		"broadcaster_user_name": "Cooler_User",
		"followed_at": "2020-07-15T18:16:11.17106713Z"
  },
}

Supported events:
- `channel.follow`
- `channel.raid`
- `channel.update`
- `stream.offline`
- `stream.online`
- `user.update`

## Subscribing to Events
Event subscriptions are initiated by sending a message in the form of...

{
	"action": "SUBSCRIBE",
	"channel": "thesmartpixel",
	"event": "channel.follow"
}

The `channel` key may be either a channel name _or_ a channel ID. The `event` key can be any EventSub subscription type (available here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types).

Subscriptions are all revoked when your connection is closed. Alternatively, you can unsubscribe from events with the `UNSUBSCRIBE` action:

{
	"action": "UNSUBSCRIBE",
	"channel": "thesmartpixel",
	"event": "channel.follow"
}

Omitting the `channel` key from your action will result in all subscriptions to `event` will be revoked, regardless of channel.

Likewise, omitting the `event` key will revoke all subscriptions for a channel.

Omitting both the `channel` and `event` keys will revoke all subscriptions for your connection.

## Caveats

ESP doesn't currently support any events that requires authorisation, which include the following:
- `channel.ban`
- `channel.charity_campaign.donate`
- `channel.channel_points_custom_reward.add`
- `channel.channel_points_custom_reward.update`
- `channel.channel_points_custom_reward.remove`
- `channel.channel_points_custom_reward_redemption.add`
- `channel.channel_points_custom_reward_redemption.update`
- `channel.cheer`
- `channel.goal.begin`
- `channel.goal.end`
- `channel.goal.progress`
- `channel.hype_train.begin`
- `channel.hype_train.end`
- `channel.hype_train.progress`
- `channel.moderator.add`
- `channel.moderator.remove`
- `channel.poll.begin`
- `channel.poll.end`
- `channel.poll.progress`
- `channel.prediction.begin`
- `channel.prediction.end`
- `channel.prediction.lock`
- `channel.prediction.progress`
- `channel.subscribe`
- `channel.subscription.end`
- `channel.subscription.gift`
- `channel.subscription.message`
- `channel.unban`

Additionally, ESP doesn't currently plan to support `drop.entitlement.grant`, `extension.bits_transaction.create`, `user.authorization.grant`, or `user.authorization.revoke`.