Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/abskmj/gulel
Gulel is an express based application server that manages Twitch Webhooks with minimal setup. It uses ngrok to make the local server reachable by Twitch servers.
https://github.com/abskmj/gulel
express twitch twitch-api twitchdev webhook
Last synced: 17 days ago
JSON representation
Gulel is an express based application server that manages Twitch Webhooks with minimal setup. It uses ngrok to make the local server reachable by Twitch servers.
- Host: GitHub
- URL: https://github.com/abskmj/gulel
- Owner: abskmj
- License: mit
- Created: 2020-07-23T11:12:44.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2023-01-08T00:16:39.000Z (almost 2 years ago)
- Last Synced: 2024-08-10T21:15:34.148Z (3 months ago)
- Topics: express, twitch, twitch-api, twitchdev, webhook
- Language: JavaScript
- Homepage: https://npmjs.com/package/gulel
- Size: 680 KB
- Stars: 11
- Watchers: 3
- Forks: 1
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
  
# Gulel - Local Server for Twitch Webhooks
Gulel is an [express](https://expressjs.com) based application server that manages [Twitch Webhooks](https://dev.twitch.tv/docs/api/guide#webhooks) with minimal setup. It uses [ngrok](https://ngrok.com/) to make the local server reachable by Twitch servers.
It handles most of the stuff automatically for you.
- It creates the HTTP endpoints needed by Twitch.
- It [verifies the payload received](https://dev.twitch.tv/docs/api/webhooks-guide/#webhooks-guide) on the HTTP endpoints.
- It [creates the subscriptions](https://dev.twitch.tv/docs/api/webhooks-reference) by calling Twitch API.
- It renews the subscriptions on expiry.
- It stops the subscriptions by calling Twitch API when the server is shutting down.
> **Note:** As of April 30, 2020, all Helix endpoints require OAuth and matching client IDs. See [this announcement](https://discuss.dev.twitch.tv/t/requiring-oauth-for-helix-twitch-api-endpoints/23916) for more details. Gulel is already compatible with the changes announced.
# Installation
```bash
npm install gulel
```
# Usage
Gulel is an express based application server with additional methods for handling Twitch Webhooks.
## Importing the module
```javascript
const gulel = require('gulel')
```
## Listening for a Webhook
```javascript
gulel.subscribe('/users/follows?first=1&to_id=1337', (data) => {
// data passed from Twitch is available as an argument
console.log(data)
/*{
"data": [
{
"from_id": "1336",
"from_name": "ebi",
"to_id": "1337",
"to_name": "oliver0823nagy",
"followed_at": "2017-08-22T22:55:24Z"
}
]
}*/
})
```
This creates a new route for the subscription on the express server. It starts listening for both `GET` & `POST` calls. `GET` method is needed by Twitch to confirm the subscription. `POST` method is to receive data from Twitch.
Each subscription is automatically subscribed when the server starts and renewed around 1 minute before they expire. The default expiry is set at 1 hour.
`/users/follows?first=1&to_id=1337` is the topic to subscribe to. More topics are documented at [dev.twitch.tv](https://dev.twitch.tv/docs/api/webhooks-reference).
## Starting the server
```javascript
gulel.start({
twitch: {
accessToken: '',
clientId: ''
},
server: {
port: 3000
}, () => console.log('Gulel is listening for Twitch calls'))
// Output
// Gulel is listening at https://39697b582cd8.ngrok.io -> http://localhost:3000
```
This starts the express server on a port configured with routes for the subscriptions mounted. The express server is also available on the internet as a subdomain for [`ngrok.io`](https://ngrok.com) and therefore, the local server is reachable for Twitch servers to send data.
## Shutting down the server gracefully
Type `quit` in the terminal where the server is running and press `enter`. This will also unsubscribe from any active subscriptions.
```
Gulel is shutting down
Unsubscribing from active subscriptions
```
Also, `gulel.shutdown()` can be used to shut it down.
## Examples
Few examples are available in the [examples](./examples) directory.
# Configuration
## Twitch
```
twitch.secret
```
This secret will be used as `hub.secret` while creating subscriptions. If not configured, the application will generate one.
```
twitch.lease
```
This value will be used as `lease_seconds` when subscribing to a Twitch event. Value is in seconds and default is `3600` i.e. an hour.
```
twitch.accessToken
```
User's Access Token for authenticating Twitch APIs.
```
twitch.clientId
```
Client ID for the Twitch application.
> **Tip!** If you want to try out the server without creating a Twitch application, you can use [an online token generator](https://twitchtokengenerator.com/) to get an access token and client id. This will also help you to get an access token with the scopes needed by some subscriptions.
## Server
```
server.port
```
Local port number where the server will listen on. Should be a number. Default is `3003`
```
server.tunnel
```
If `true`, ngrok service will be used. The default value is `true`
```
server.baseUrl
```
If set, the value will be used as the base URL for Twitch subscription callbacks.
# Fixes & Improvements
Head over to the issues tab at [github.com](https://github.com/abskmj/gulel/issues) to report a bug or suggest an improvement. Feel free to contribute to the code or documentation by creating a pull request.
# Sponsor
If you find the project interesting or helpful, please consider sponsoring it at [github.com](https://github.com/abskmj/gulel).