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

OpenDevBot is a personal Twitch chatbot intended for a single broadcaster. It can join multiple chat channels, but some features use the first configured broadcaster or hard-coded channel details, so independent multi-channel operation is not currently supported.

(back to top)

Built With

• Twurple
• Express.js
• discord.js for Discord webhook notifications
• Node.js built-in SQLite for local persistence
• Electron for the desktop control room

(back to top)

Prerequisites

• Node.js 22.13 or newer, including npm, for running from source.
• A Twitch developer application and Twitch accounts for the desired integrations.
• Discord webhooks if Discord notifications are enabled.

Installation

1. Create a Twitch developer application and configure its OAuth redirect URL.

2. Clone the repo

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

3. Install NPM packages.

   npm install

4. Copy .env.example to .env and configure the required credentials and flags. Keep .env private.

(back to top)

Project UI Preview

Usage

electron:dev compiles the Electron app and starts it. The application uses Node's built-in SQLite support, so SQLite does not require a separate native package or C++ build tools. Existing SQLite databases remain compatible.

npm run electron:dev

Run npm install to install the application's other dependencies. Node's SQLite API is experimental in Node 22 and 24, so an experimental warning may appear.

Set ENABLE_CHAT=true and/or ENABLE_EVENTSUB=true to start those integrations. Unset values and false leave them disabled; other values are rejected with a warning. When stream online and offline events overlap, superseded notifications are skipped; already-started notifications finish before the next transition is announced.

Tests

Run npm test from the repository root. Tests are in __tests__/, with Electron tests in __tests__/electron/ and shared mock files in __mock__/. Some integration tests require localhost connections.

The glob and minimatch npm overrides upgrade affected development-tool dependencies across major versions to address their security advisories. Review and remove these overrides when upstream tools adopt patched versions. Nodemon is pinned to an unaffected release for the same reason. Jest's development-only deepmerge dependency has a separate low-severity advisory with no patched release; check npm audit for its current status.

The economy dashboard edits and deletes accounts by their database _id, using PUT and DELETE /api/v1/admin/economy/accounts/:accountId. Missing accounts return 404 rather than being created. The existing singular /account/:userId routes remain available for user-ID-based API clients.

Windows installer

On Windows x64, run npm run electron:package:win to build the unsigned NSIS installer in release/. The installer does not require Node.js to be installed on the target computer. The Windows CI job builds it, checks the archive for required assets and private data, installs it in an isolated CI directory, and smoke-tests the installed application.

After installation, create %APPDATA%\OpenDevBot\.env using .env.example as a reference and add your Twitch application credentials. Do not include your own .env or database in a distributable. Set the Twitch redirect URL to match the API port (the example redirect uses port 3001, so set PORT=3001 if using it). Restart the app after editing the file. The packaged app stores its SQLite database and logs in the same per-user application data directory and binds its local API to 127.0.0.1. Set ADMIN_API_TOKEN to protect its admin endpoints with a persistent token, or let Electron use an automatically generated private session token. The installer is not code-signed and may trigger Windows SmartScreen warnings.

Electron writes persistent application logs to the logs directory under its userData folder:

• opendevbot.log contains the application logger output.
• opendevbot-errors.log contains error-handler and logger error output.

Electron uses these per-user paths regardless of DEV_LOG_FILE, PROD_LOG_FILE, or ERROR_LOG_FILE in .env. The Logs window still shows recent entries from the current session.

The economy dashboard looks up Twitch usernames and caches them for five minutes, falling back to a saved name or the account ID if Twitch is unavailable. Account balances and admin actions continue to use the Twitch ID, so a username change does not create a new balance. The desktop dashboard and logs window use a bundled Vue runtime and do not require a CDN to load.

(back to top)

Admin token persistence & security

• Standalone server: Set ADMIN_API_TOKEN to use admin endpoints. If it is missing, those endpoints return 503; health and setup endpoints remain available.
• Electron: The local API requires authentication even without a configured token. Electron generates a fresh private session token and attaches it through its admin proxy; it is not saved or exposed to the renderer. A configured ADMIN_API_TOKEN takes precedence.
• 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 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 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)