{"id":18021459,"url":"https://github.com/abskmj/gulel","last_synced_at":"2025-03-26T22:30:58.008Z","repository":{"id":38290304,"uuid":"281929900","full_name":"abskmj/gulel","owner":"abskmj","description":"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.","archived":false,"fork":false,"pushed_at":"2023-01-08T00:16:39.000Z","size":696,"stargazers_count":12,"open_issues_count":7,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-22T14:22:25.395Z","etag":null,"topics":["express","twitch","twitch-api","twitchdev","webhook"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/gulel","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/abskmj.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-07-23T11:12:44.000Z","updated_at":"2025-02-18T10:57:40.000Z","dependencies_parsed_at":"2023-02-08T03:45:51.995Z","dependency_job_id":null,"html_url":"https://github.com/abskmj/gulel","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abskmj%2Fgulel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abskmj%2Fgulel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abskmj%2Fgulel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abskmj%2Fgulel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/abskmj","download_url":"https://codeload.github.com/abskmj/gulel/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245747511,"owners_count":20665803,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["express","twitch","twitch-api","twitchdev","webhook"],"created_at":"2024-10-30T06:10:00.907Z","updated_at":"2025-03-26T22:30:57.708Z","avatar_url":"https://github.com/abskmj.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"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)\n\n# Gulel - Local Server for Twitch Webhooks\nGulel 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.\n\nIt handles most of the stuff automatically for you.\n- It creates the HTTP endpoints needed by Twitch.\n- It [verifies the payload received](https://dev.twitch.tv/docs/api/webhooks-guide/#webhooks-guide) on the HTTP endpoints.\n- It [creates the subscriptions](https://dev.twitch.tv/docs/api/webhooks-reference) by calling Twitch API.\n- It renews the subscriptions on expiry.\n- It stops the subscriptions by calling Twitch API when the server is shutting down.\n\n\u003e **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.\n\n# Installation\n```bash\nnpm install gulel\n```\n\n# Usage\nGulel is an express based application server with additional methods for handling Twitch Webhooks.\n\n## Importing the module\n```javascript\nconst gulel = require('gulel')\n```\n\n## Listening for a Webhook\n```javascript\ngulel.subscribe('/users/follows?first=1\u0026to_id=1337', (data) =\u003e { \n    // data passed from Twitch is available as an argument\n\n    console.log(data)\n\n    /*{\n      \"data\": [\n          {\n            \"from_id\": \"1336\",\n            \"from_name\": \"ebi\",\n            \"to_id\": \"1337\",\n            \"to_name\": \"oliver0823nagy\",\n            \"followed_at\": \"2017-08-22T22:55:24Z\"\n          }\n      ]\n    }*/\n})\n```\n\nThis creates a new route for the subscription on the express server. It starts listening for both `GET` \u0026 `POST` calls. `GET` method is needed by Twitch to confirm the subscription. `POST` method is to receive data from Twitch.\n\nEach subscription is automatically subscribed when the server starts and renewed around 1 minute before they expire. The default expiry is set at 1 hour.\n\n`/users/follows?first=1\u0026to_id=1337` is the topic to subscribe to. More topics are documented at [dev.twitch.tv](https://dev.twitch.tv/docs/api/webhooks-reference).\n \n\n## Starting the server\n```javascript\ngulel.start({\n  twitch: {\n    accessToken: '\u003caccess token\u003e',\n    clientId: '\u003cclient id\u003e'\n  },\n  server: {\n    port: 3000\n}, () =\u003e console.log('Gulel is listening for Twitch calls'))\n\n// Output\n// Gulel is listening at https://39697b582cd8.ngrok.io -\u003e http://localhost:3000\n```\n\nThis 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.\n\n## Shutting down the server gracefully\nType `quit` in the terminal where the server is running and press `enter`. This will also unsubscribe from any active subscriptions.\n\n```\nGulel is shutting down\nUnsubscribing from active subscriptions\n```\n\nAlso, `gulel.shutdown()` can be used to shut it down.\n\n## Examples\nFew examples are available in the [examples](./examples) directory.\n\n# Configuration\n## Twitch\n```\ntwitch.secret\n```\nThis secret will be used as `hub.secret` while creating subscriptions. If not configured, the application will generate one.\n\n```\ntwitch.lease\n```\nThis 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.\n\n```\ntwitch.accessToken\n```\nUser's Access Token for authenticating Twitch APIs. \n\n```\ntwitch.clientId\n```\nClient ID for the Twitch application.\n\n\u003e **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.\n\n## Server\n```\nserver.port\n```\nLocal port number where the server will listen on. Should be a number. Default is `3003`\n\n```\nserver.tunnel\n```\nIf `true`, ngrok service will be used. The default value is `true`\n\n```\nserver.baseUrl\n```\nIf set, the value will be used as the base URL for Twitch subscription callbacks.\n\n# Fixes \u0026 Improvements\nHead 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.\n\n# Sponsor\nIf you find the project interesting or helpful, please consider sponsoring it at [github.com](https://github.com/abskmj/gulel). \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabskmj%2Fgulel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabskmj%2Fgulel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabskmj%2Fgulel/lists"}