# gulel

> Gulel is an express based application server that manages Twitch Webhooks with minimal setup

Latest version **1.2.2** (published 2022-01-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install gulel
pnpm add gulel
yarn add gulel
bun add gulel
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.2 |
| Published | 2022-01-21 |
| First published | 2020-07-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 5 |
| Unpacked size | 16.2 KB |
| Known vulnerabilities | 0 (+24 in 2 direct dependencies) |
| Install scripts | no |
| GitHub stars | 13 |
| Author | abskmj@gmail.com |
| Maintainers | abskmj |
| Keywords | twitch, webhooks, express, server |

## Links

- npm: https://www.npmjs.com/package/gulel
- Repository: https://github.com/abskmj/gulel
- Issues: https://github.com/abskmj/gulel/issues
- npm.io page: https://npm.io/package/gulel

## Dependencies (5)

- [axios](https://npm.io/package/axios.md) ^0.25.0
- [ngrok](https://npm.io/package/ngrok.md) ^4.3.0
- [morgan](https://npm.io/package/morgan.md) ^1.10.0
- [express](https://npm.io/package/express.md) ^4.17.2
- [body-parser](https://npm.io/package/body-parser.md) ^1.19.1

## Recent versions

- 1.2.2 (latest) — 2022-01-21
- 1.2.1 — 2021-05-12
- 1.2.0 — 2020-08-15
- 1.1.0 — 2020-08-08
- 1.0.0 — 2020-07-23

## README

![npm (scoped)](https://img.shields.io/npm/v/gulel?label=NPM) ![NPM](https://img.shields.io/npm/l/gulel?label=License) ![npm](https://img.shields.io/npm/dt/gulel?label=Downloads)

# 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: '<access token>',
    clientId: '<client id>'
  },
  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).

---
_Source: https://npm.io/package/gulel · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
