{"id":29040657,"url":"https://github.com/pushchain/push-showrunners-framework","last_synced_at":"2025-06-26T14:36:35.439Z","repository":{"id":103176437,"uuid":"488532738","full_name":"pushchain/push-showrunners-framework","owner":"pushchain","description":"The PUSH Showrunners handles the channels created and maintaned by us. It also shows how easy it is to interact with the protocol to build highly customized notifications for your dApp, smart contracts or even centralized services.","archived":false,"fork":false,"pushed_at":"2025-06-04T11:06:22.000Z","size":1047,"stargazers_count":16,"open_issues_count":9,"forks_count":14,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-06-23T13:54:09.397Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pushchain.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-05-04T09:48:01.000Z","updated_at":"2025-04-09T10:21:26.000Z","dependencies_parsed_at":"2024-03-27T05:26:53.205Z","dependency_job_id":"20d414d7-5598-40e7-9768-82f128769f1f","html_url":"https://github.com/pushchain/push-showrunners-framework","commit_stats":null,"previous_names":["push-protocol/push-showrunners-framework","ethereum-push-notification-service/push-showrunners-framework","pushchain/push-showrunners-framework"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pushchain/push-showrunners-framework","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pushchain%2Fpush-showrunners-framework","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pushchain%2Fpush-showrunners-framework/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pushchain%2Fpush-showrunners-framework/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pushchain%2Fpush-showrunners-framework/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pushchain","download_url":"https://codeload.github.com/pushchain/push-showrunners-framework/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pushchain%2Fpush-showrunners-framework/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262085898,"owners_count":23256540,"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":[],"created_at":"2025-06-26T14:36:32.003Z","updated_at":"2025-06-26T14:36:35.414Z","avatar_url":"https://github.com/pushchain.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n    \u003ca href=\"https://push.org/#gh-light-mode-only\"\u003e\n    \u003cimg width='20%' height='10%' src=\"https://res.cloudinary.com/drdjegqln/image/upload/v1686227557/Push-Logo-Standard-Dark_xap7z5.png\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://push.org/#gh-dark-mode-only\"\u003e\n    \u003cimg width='20%' height='10%' src=\"https://res.cloudinary.com/drdjegqln/image/upload/v1686227558/Push-Logo-Standard-White_dlvapc.png\"\u003e\n    \u003c/a\u003e\n\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n  \u003ci align=\"center\"\u003ePush Protocol is a web3 communication network, enabling cross-chain notifications, messaging, video, and NFT chat for dapps, wallets, and services.🚀\u003c/i\u003e\n\u003c/p\u003e\n\n\u003ch4 align=\"center\"\u003e\n\n  \u003ca href=\"https://discord.gg/pushprotocol\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/discord-7289da.svg?style=flat-square\" alt=\"discord\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://twitter.com/pushprotocol\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/twitter-18a1d6.svg?style=flat-square\" alt=\"twitter\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.youtube.com/@pushprotocol\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/youtube-d95652.svg?style=flat-square\u0026\" alt=\"youtube\"\u003e\n  \u003c/a\u003e\n\u003c/h4\u003e\n\n\n# PUSH Showrunners (Server)\n\nThe showrunners framework is a scaffold that developers can use to build out notifications for their use cases. Showrunners framework provides the tools and helpers required for constructing the payload and sending the notification using the Push protocol infrastructure. \n\n---\n\n## Installation and Set Up Guide\n\n- Install docker \n- Clone the repo\n``` \ngit clone https://github.com/push-protocol/push-showrunners-framework\n```\n- To make it easier to use, we will be using Docker. You can initialize it using the code below code , but if looking for a manual setup then [Refer this](#external-services).\n```\ndocker-compose up\n```\n- Open the root folder in another terminal and enter\n```\nyarn install\n```\n```\nyarn start\n```\n\n### To exit \n- To stop running the showrunners server, press ```Ctrl + C```\n- To stop running the docker, press ```Ctrl + C``` and enter\n```docker-compose down```\n\n---\n## Channel Structure \nBefore we dive into an example ,Let's understand the requirements for the folder structure inside the src/showrunners folder and how you can use them to quickly refine / debug / deploy your channels.\n\nEach folder inside ```src/showrunners``` is treated as their own channel. Showrunners is designed to be a plug and play solution for your channel which means that each of the folders designated filenames are used to add-on various functionalities.\n\n1. channelChannel.js [.ts] (Mandatory)\n    - Example: helloWorldChannel.js\n    - This file contains all the logic functions of your channel, it can for instance have a way to poll all opted in users of your channel and based on certain conditions that are met, fire notifications out.\n1. channelKeys.json (Mandatory)\n    - Example: helloWorldKeys.json\n    - This file contains all your private keys that you either belong to the channel you created or have authorized the wallets to send notification on your channel's behalf.\n1. channelRoutes.js [.ts]\n    - Example: helloWorldRoutes.js\n    - This file contains the routes that you will enable to ensure you are able to manually trigger notification or any other logic points in your channelChannel.js [.ts]\n    - You will ideally use the route of this files in postman to trigger logic functions / test them out. \n1. channelJobs.js [.ts]\n    - Example: helloWorldJobs.js\n    - This file contains your cron jobs to trigger logic points in your channelChannel.js [.ts]\n    - The file is based on node-schedule and can handle a wide variety of automated cron jobs to enable sending wide array of notifications based on triggers.\n1. channelAWSSNS.js[.ts]\n    - Example: helloWorldAWSSNS.ts\n    - This file contains the webhook helpers and handle the logic points for consuming a webhook.\n    - This file is based on AWS-SNS and can handle the variety of logics for consuming webhook to enable sending wide array of notifications based on webhook triggers.\n\n---\n\n## Examples :\n\nNow lets have a quick tour into example and understand How to actually run a Showrunner framework over a demo HelloWorld channel\n\n[Hello World Example](https://docs.push.org/developers/developer-tooling/showrunners-framework/hello-world-channel)\n\nFor more examples [Refer this](https://github.com/push-protocol/push-showrunners-framework/tree/main/src/sample_showrunners).\n\n---\n\n## Technical Details\n\n\u003c!-- Following definitions are used in the rest of the spec to refer to a particular category or service.\n| Term | Description\n| ------------- | ------------- |\n| Showrunners | Showrunners are Channels on PUSH protocol notification protocol that are created and maintained by us | --\u003e\n\n\u003c!-- ### Tech Specs\n\nThe Showrunners run on node.js server and are modularized on the ideas and architecture of [Bulletproof NodeJS](https://github.com/santiq/bulletproof-nodejs), the essential features in the architeture are as follows:\n\n- **config** defines all the necessary configuration\n- **Jobs** is used to handle waking up different channels for various purpose. Very useful in sending notifications from channel at a specific interval\n- **dbListener** can be used to listen to and trigger functions on DB changes, we have left the interpretation and an example over there for whoever wants to use them\n- **showrunners** are the actual channels and contain logic which is required for them to construct notification according to their use cases\n- **middlewares and routes** will probably not be active on your production server but are given to test the channel in development mode. for example: triggering functions using postman or similar service and seeing the response\n- **database** the architecture has been changed from MongoDB to mysql to show how easy it is to have either of the database if required\n\n### Credits\n\n- [Bulletproof NodeJS](https://github.com/santiq/bulletproof-nodejs) --\u003e\n\n## External Services\n\nWe would need external services of:\n\n- [Mongodb](https://www.mongodb.com/) - Primary Database : [Installation](https://docs.mongodb.com/manual/installation/) We would be using Mongodb Atlas\n- [Redis](https://www.mongodb.com/) - Internal Cache : [Installation](https://redis.io/topics/quickstart)\n- [Mongodb Atlas](https://www.mongodb.com/cloud/atlas)\n\nFor local ease of development, we make use of [Docker](https://docs.docker.com/get-docker/).\n\n---\n\n## Contributing\n\nPush Protocol is an open source Project. We firmly believe in a completely transparent development process and value any contributions. We would love to have you as a member of the community, whether you are assisting us in bug fixes, suggesting new features, enhancing our documentation, or simply spreading the word. \n\n- Bug Report: Please create a bug report if you encounter any errors or problems while utilising the Push Protocol.\n- Feature Request: Please submit a feature request if you have an idea or discover a capability that would make development simpler and more reliable.\n- Documentation Request: If you're reading the Push documentation and believe that we're missing something, please create a docs request.\n\nNot sure where to start? Join our discord and we will help you get started!\n\n\n\u003ca href=\"https://discord.gg/pushprotocol\" title=\"Join Our Community\"\u003e\u003cimg src=\"https://www.freepnglogos.com/uploads/discord-logo-png/playerunknown-battlegrounds-bgparty-15.png\" width=\"200\" alt=\"Discord\" /\u003e\u003c/a\u003e\n\n---\n\n## License\nCheck out our License \u003ca href='https://github.com/push-protocol/push-showrunners-framework/blob/main/license-v1.md'\u003eHERE \u003c/a\u003e\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpushchain%2Fpush-showrunners-framework","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpushchain%2Fpush-showrunners-framework","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpushchain%2Fpush-showrunners-framework/lists"}