OpenDevBot

Twitch Chatbot
· Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About The Project

a personal chat bot for my twitch channel, will make it usable on other channels at some point, im only a beginner coder but as i learn how to code better i will add more features to the bot, currently working on features that can be checked out in the Roadmap Section of this readme.

(back to top)

Built With

• Twurple
• Express.js
• guilded.js Basics, just for discord Embeds for webhooks

(back to top)

Prerequisites

This is an example of how to list things you need to use the software and how to install them.

• npm

  npm install npm@latest -g

• node
  Node

• Code Editor[Optional Choices] NOTE: i do not know how to setup the project with Atom so everything is based on VS Code
  VS Code
  Atom
  

Installation

1. Create a Twitch Dev Application Twitch Developer Application, you will need access to a discord bot aswell, for webhooks

2. Clone the repo

   git clone https://github.com/skullgaming31/OpenDevBot.git

3. Install NPM packages

   npm install

4. Fill out the .env with all nessasary Information, check .env.example for whats needed

(back to top)

Usage

electron:dev will build the electron app and start it

npm run electron:dev

(back to top)

Admin token persistence & security

• Env var: ALLOW_PERSIST_ADMIN_TOKEN (default: not set / false). Set to true only for local/dev use when you explicitly want the admin token written to the repository .env file.
• Production: Persistence is disabled when ENVIRONMENT is prod — do not enable persistence in production. Tokens persisted to disk are sensitive and should never be stored in shared or committed files.
• How it works: The app accepts admin credentials via the x-admin-token header or the admin_token cookie only (query parameters are no longer accepted). Sensitive comparisons use a timing-safe compare to reduce attack surface.
• Recommended workflow: For local setup prefer manual, ephemeral methods: set process.env.ADMIN_API_TOKEN in your shell, or use the admin setup endpoint with ALLOW_PERSIST_ADMIN_TOKEN=true in a safe local .env copy. After testing, unset or rotate the token.
• If compromised: Rotate the token immediately and remove it from any persisted .env files.

Examples (local/dev only):

# temporary in-process (preferred for local testing)
setx ADMIN_API_TOKEN "your-token-value"

# OR to opt-in to persistence for the setup endpoint (dev only)
# add to your local .env: ALLOW_PERSIST_ADMIN_TOKEN=true

(back to top)

Roadmap

• Connected auth to account
• Connected ChatClient
• connected to PubSub(Dont Use Anymore)
• connected to EventSub with websockets
• add commands
  • commands load from there own .ts file
  • convert followage/accountage to years,months,day,hours,minutes,seconds
  • convert uptime to display days,hours,minutes,seconds(24 hour streams)
• add word detection to send commands without prefix
• create channelPoints with userToken to modify the channel points with commands [Hard Coded ChannelPoints]
• Advanced Lurk Command
• Timer Command
• Counters
• Quotes System?
• Viewer Watch Time?
• Virtual Currency System
  • duel
  • dig
  • Heist
  • Gamble
• Que/delay webhooks being sent to avoid being rate limited by the Discord API

Today (2025-10-13)

• Added comprehensive unit tests covering:
  • authProvider token preloading and chat-provider registration fallbacks.
  • OAuth callback token exchange and persistence (/api/v1/auth/twitch/callback).
  • Chat helper getUsernamesFromDatabase() behavior for success and failure.
• Improved OAuth callback logging and normalization of returned scopes (code path exercised by tests).
• Implemented a dedicated chat auth provider and fallbacks to ensure the bot account is registered for the chat intent (dev-only forced mapping remains as a temporary workaround).
• Added debug logging around chat message parsing and command handling to aid diagnosis of why commands may not run.
• Started refactor to defer EventSub subscription registration until the websocket session is ready and added scaffolding for restart/retry logic (work in progress).

Notes: these changes include tests and mocks so the project can run unit tests without external Twitch or MongoDB services. See CHANGELOG.md for a detailed list of edits made on this date.

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature)
3. Commit your Changes (git commit -m 'describe your feature')
4. Push to the Branch (git push origin feature)
5. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Contact

📫 How to reach me:

canadiendragon
Email

Other Projects: Projects

(back to top)

Acknowledgments

• Twurple Twitch Library

(back to top)

Running in Docker (Production)

Follow these steps to run OpenDevBot in production inside Docker. The compose file will start a MongoDB service and build the bot image from the repository.

1. Copy the example env file and fill in secrets:

cp .env.prod.example .env.prod
# Edit .env.prod and fill in values (TWITCH_CLIENT_ID, etc.)

2- Build and start the services:

docker compose up --build -d

3- Logs:

docker compose logs -f opendevbot

Notes:

• The compose file sets MONGO_URI to mongodb://mongo:27017/opendevbot for the bot container.
• Make sure to provide TWITCH_CLIENT_ID, TWITCH_CLIENT_SECRET, and the bot OAuth token in .env.prod.
• For a managed deployment, consider using secrets, a Docker registry for the built image, and external MongoDB.