{"id":31865457,"url":"https://github.com/stjohnjohnson/extralife-helper-bot","last_synced_at":"2025-10-12T19:20:09.896Z","repository":{"id":313045576,"uuid":"1049584418","full_name":"stjohnjohnson/extralife-helper-bot","owner":"stjohnjohnson","description":"Helper bot for automating some Discord and Twitch integrations (and maybe more?!)","archived":false,"fork":false,"pushed_at":"2025-10-01T04:10:28.000Z","size":484,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-09T14:44:14.829Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/stjohnjohnson.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-09-03T07:39:37.000Z","updated_at":"2025-09-30T15:36:31.000Z","dependencies_parsed_at":"2025-09-30T07:07:35.493Z","dependency_job_id":"963069b8-12fe-4987-a91c-604ca58b8da6","html_url":"https://github.com/stjohnjohnson/extralife-helper-bot","commit_stats":null,"previous_names":["stjohnjohnson/extralife-helper-bot"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/stjohnjohnson/extralife-helper-bot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stjohnjohnson%2Fextralife-helper-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stjohnjohnson%2Fextralife-helper-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stjohnjohnson%2Fextralife-helper-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stjohnjohnson%2Fextralife-helper-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stjohnjohnson","download_url":"https://codeload.github.com/stjohnjohnson/extralife-helper-bot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stjohnjohnson%2Fextralife-helper-bot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279012651,"owners_count":26085159,"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","status":"online","status_checked_at":"2025-10-12T02:00:06.719Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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-10-12T19:20:06.614Z","updated_at":"2025-10-12T19:20:09.875Z","avatar_url":"https://github.com/stjohnjohnson.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ExtraLife Helper Bot\n\nA unified helper bot for managing your ExtraLife 24 hour marathon stream, bridging between Discord and Twitch.\n\nThis bot combines the functionality of both Discord and Twitch bridges, allowing you to:\n- Post donation notifications to Discord channels and Twitch chat\n- Update Discord channel names with fundraising progress\n- Cross-platform commands that work on both Discord and Twitch (`!goal`, `!promote`)\n- Custom command responses that work across both platforms\n- Voice channel management for stream participants\n- Automatic Twitch game category updates based on Discord presence changes\n- Smart game matching with 5-level priority system\n- Automatic token refresh management for seamless operation\n- Run both services simultaneously or independently\n\n## Features\n\n### Discord Integration\n- **Donation Stream**: Posts new donations to a specified Discord channel\n- **Summary Updates**: Updates a Discord channel name to show total amount raised and percentage of goal\n- **Voice Channel Management**: `!promote` command to move users from waiting room to live chat\n- **Presence Monitoring**: Detects when monitored users change their game status\n\n### Twitch Integration\n- **Donation Announcements**: Posts new donations to Twitch chat with ExtraLife emotes\n- **Automatic Game Category Updates**: Changes Twitch channel game category when Discord user changes games\n- **Smart Game Matching**: Uses 5-level priority system to find best Twitch category matches\n- **Automatic Token Management**: Refreshes access tokens automatically using refresh tokens\n\n### Cross-Platform Features\n- **Game Update Bridge**: Detects Discord game status changes and automatically updates Twitch channel category with smart matching\n- **Cross-platform Commands**: `!goal` and `!promote` commands work from both Twitch and Discord\n- **Custom Commands**: Define your own bot commands that work across both platforms\n- **Real-time Updates**: Checks for new donations every 30 seconds\n\n## Configuration\n\nThe bot requires at least one service (Discord or Twitch) to be configured. Set the following environment variables:\n\n### Required (for both services)\n- `EXTRALIFE_PARTICIPANT_ID`: Your ExtraLife/DonorDrive participant ID\n\n### Discord Service (optional)\n- `DISCORD_TOKEN`: Your Discord bot token\n- `DISCORD_DONATION_CHANNEL`: Discord channel ID for posting donations\n- `DISCORD_SUMMARY_CHANNEL`: Discord channel ID for updating the name with progress\n\n### Discord Voice Channel Management (optional - for !promote command)\n- `DISCORD_WAITING_ROOM_CHANNEL`: Voice channel ID for users waiting to join stream\n- `DISCORD_LIVE_ROOM_CHANNEL`: Voice channel ID for live streaming participants\n\n### Admin Users (optional - for restricted commands)\n- `DISCORD_ADMIN_USERS`: Comma-separated list of Discord user IDs who can use admin commands\n- `TWITCH_ADMIN_USERS`: Comma-separated list of Twitch usernames who can use admin commands\n\n### Twitch Service (optional)\n- `TWITCH_USERNAME`: Your bot's Twitch username\n- `TWITCH_CHAT_OAUTH`: Bot OAuth token from [https://twitchapps.com/tmi/](https://twitchapps.com/tmi/)\n- `TWITCH_CHANNEL`: The Twitch channel name to join\n- `TWITCH_CLIENT_ID`: Your Twitch application client ID\n\n### Game Update Notifications (optional - requires both Discord and Twitch)\n- `DISCORD_GAME_UPDATE_USER_ID`: Discord user ID to monitor for game changes\n- `DISCORD_GAME_UPDATE_MESSAGE`: Custom message template (optional, default: \"Now playing {game}!\")\n- `TWITCH_CLIENT_SECRET`: Your Twitch application client secret (for automatic token refresh)\n- `TWITCH_REFRESH_TOKEN`: Refresh token for automatic access token management\n\n### Custom Command Responses (optional)\n- `CUSTOM_RESPONSES`: Define custom bot commands and their responses\n  - Format: `command1:\"response1\",command2:\"response2\"`\n  - Example: `donate:\"Check out https://donate.example.com\",discord:\"Join our Discord: https://discord.gg/example\"`\n  - Commands must start with a letter and contain only lowercase letters and numbers\n  - Cannot conflict with built-in commands (`goal`, `promote`)\n  - Commands are case-insensitive when used (e.g., `!DONATE` and `!donate` work the same)\n\n## Running\n\n### Docker (Recommended)\n\n```bash\n# Create a .env file with your configuration\ncp env.example .env\n# Edit .env with your settings\n\n# Run the bot\ndocker run --rm -it --env-file .env ghcr.io/stjohnjohnson/extralife-helper-bot:latest\n```\n\n### Local Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Create .env file with your configuration\ncp env.example .env\n\n# Run the bot\nnpm start\n\n# Run tests\nnpm test\n\n# Lint code\nnpm run lint\n```\n\n## Setup Instructions\n\n### Discord Bot Setup\n1. Create a new Discord application at https://discord.com/developers/applications\n2. Create a bot user and copy the token\n3. **Enable required intents** in the Bot settings:\n   - `Server Members Intent` - required for game update monitoring\n   - `Presence Intent` - required for game update monitoring\n   - `Message Content Intent` - required for command processing\n4. Invite the bot to your server with these permissions:\n   - `Send Messages` - for donation notifications and command responses\n   - `Manage Channels` - for updating summary channel name\n   - `Move Members` - for the `!promote` command (if using voice channel management)\n   - `View Channels` - for accessing configured channels\n5. Get the channel IDs by enabling Developer Mode in Discord and right-clicking channels\n6. **For voice management**: Set up waiting room and live room voice channel IDs in your environment\n\n### Twitch Bot Setup\n1. **Create a Twitch application** at https://dev.twitch.tv/console/apps\n2. **Copy your Client ID and Client Secret** from the application\n3. **Generate Chat OAuth token**:\n   - Use your bot account (can be separate from streamer)\n   - Get token from https://twitchapps.com/tmi/\n   - Set as `TWITCH_CHAT_OAUTH`\n\n4. **Set basic configuration**:\n   - `TWITCH_USERNAME`: Your bot's username (for chat)\n   - `TWITCH_CHANNEL`: Your streamer channel name (without # prefix)\n   - `TWITCH_CLIENT_ID`: Your application's client ID\n\n### Game Update Setup (optional)\n1. **Requires both Discord and Twitch services** to be configured\n2. **Get refresh token for automatic token management**:\n   - **Must use streamer/broadcaster account** (not bot account)\n   - Use [Twitch Token Generator](https://twitchtokengenerator.com/) with your Client ID\n   - Select `channel:manage:broadcast` scope\n   - Copy the **refresh token** (not the access token)\n   - Set as `TWITCH_REFRESH_TOKEN`\n3. **Set client secret**: Add `TWITCH_CLIENT_SECRET` from your Twitch application\n4. **Get the Discord user ID to monitor**:\n   - Enable Developer Mode in Discord settings\n   - Right-click the user's profile and select \"Copy User ID\"\n   - Set this as `DISCORD_GAME_UPDATE_USER_ID`\n5. **Note**: The Discord bot needs the \"Server Members Intent\" and \"Presence Intent\" enabled for presence monitoring\n6. **Customize the notification** (optional): Set `DISCORD_GAME_UPDATE_MESSAGE` (use `{game}` as placeholder)\n\n## Commands\n\n### Built-in Commands (work on both Discord and Twitch)\n- **`!goal`**: Shows current fundraising progress\n  ```\n  St. John Johnson has raised $1,250.00 out of $10,000.00 (13%)\n  ```\n\n- **`!promote`**: Moves all users from waiting room voice channel to live chat voice channel *(Admin only)*\n  ```\n  Promoted 3 member(s) to live chat!\n  ```\n  *Note: This command requires Discord voice channel management to be configured and admin permissions*\n\n### Custom Commands\nYou can create your own custom commands using the `CUSTOM_RESPONSES` environment variable. Custom commands:\n- Work on both Discord and Twitch\n- Are available to all users (not admin-restricted)\n- Are case-insensitive (`!donate` and `!DONATE` work the same)\n- Cannot override built-in commands\n\n**Examples:**\n- **`!donate`**: Custom donation link response\n  ```\n  Check out my donation page: https://donate.example.com\n  ```\n- **`!discord`**: Custom Discord invite response\n  ```\n  Join our community Discord: https://discord.gg/example\n  ```\n\n## Admin Commands\n\nSome commands are restricted to admin users only for security purposes. Admin users are configured via the `DISCORD_ADMIN_USERS` and `TWITCH_ADMIN_USERS` environment variables (see configuration section above).\n\n**Admin-only commands:**\n- `!promote` - Voice channel management (moves users from waiting room to live chat)\n\n**Admin Configuration Examples:**\n```bash\nDISCORD_ADMIN_USERS=123456789012345678,987654321098765432\nTWITCH_ADMIN_USERS=your_username,another_admin\n```\n\n**Getting Discord User IDs**: Enable Developer Mode in Discord settings, right-click your username, and select \"Copy User ID\".\n\n## Example Output\n\n### Discord\n```\nSt. John Johnson just donated $25.00 with the message \"Good luck with the marathon!\"!\n```\n\n### Twitch\n```\nExtraLife ExtraLife St. John Johnson just donated $25.00 with the message \"Good luck with the marathon!\"! ExtraLife ExtraLife\n```\n\n### Goal Command Response\n```\n!goal\nSt. John Johnson has raised $1,250.00 out of $10,000.00 (13%)\n```\n\n### Game Update Behavior\nWhen the monitored Discord user changes their game status:\n- **Game Start**: Twitch channel game category automatically updates to match the new game using smart matching\n- **Game Stop**: Twitch channel game category automatically updates to \"Just Chatting\"\n- **Game Switch**: Twitch channel game category updates from old game to new game\n- **Smart Matching**: Uses 5-priority system:\n  1. **Exact match** (case insensitive)\n  2. **Game starts with** Discord activity name\n  3. **Discord activity starts with** game name (abbreviations)\n  4. **Whole word match** within game name\n  5. **Fuzzy match** for partial matches\n- **Not Found**: If no suitable game category is found on Twitch, no change is made and a warning is logged\n- **Token Management**: Access tokens are automatically refreshed using refresh tokens when they expire\n\n**Note**: This feature requires both Discord and Twitch services to be fully configured, including `TWITCH_CLIENT_SECRET` and `TWITCH_REFRESH_TOKEN` for automatic token management.\n\n## Automatic Token Management\n\nThe bot automatically manages Twitch access tokens when game update notifications are configured:\n\n- **Automatic Refresh**: Access tokens are automatically refreshed before they expire (with 5-minute safety buffer)\n- **In-Memory Caching**: Tokens are cached in memory to minimize API calls\n- **Error Handling**: If token refresh fails, detailed error messages guide you to re-authorize\n- **No Manual Intervention**: Once properly configured with refresh token, the bot handles all token management\n\n**Important**: The `TWITCH_REFRESH_TOKEN` must be obtained using the **broadcaster/streamer account**, not the bot account, as it needs `channel:manage:broadcast` permissions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstjohnjohnson%2Fextralife-helper-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstjohnjohnson%2Fextralife-helper-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstjohnjohnson%2Fextralife-helper-bot/lists"}