Twitch Stream Notifications

[karaktaka]

Feature: Twitch Stream Notifications

Notify Discord channels when followed Twitch streamers go live or offline. Admins configure which streamers to follow and where notifications are posted.

Depends on: #100 (Phase 4 — Webhook Listener)

Note: Draft PR #109 exists with a WIP implementation. It runs EventSub webhooks inside the bot process, which conflicts with the architecture decision in #100 to handle webhooks in the web service. This feature should be re-implemented on top of #100's webhook infrastructure.

---

Phase 1 — Go-Live / Offline Notifications

How It Works

1. Admin configures: streamer name + Discord channel + optional custom message
2. Web service (Management Webinterface #100) receives Twitch EventSub webhooks for stream.online and stream.offline
3. Web service writes events to a shared DB table
4. Bot picks up new events and posts notifications to the configured Discord channels

Admin Commands

• /twitch notifications list [channel] [streamer] — List configured notifications (filterable)
• /twitch notifications create <streamer> [channel] [message] — Add a notification config (defaults to current channel)
• /twitch notifications delete <id> — Remove a notification config

Notification Behavior

• Go-live: Posts a message in the configured channel (custom message or default: "{streamer} is now live at https://twitch.tv/{streamer}")
• Offline: Posts "{streamer} is now offline." in the same channel
• Streamer data (display name, profile image) cached in-memory with 1-hour TTL

Twitch API Setup

• Uses Twitch API (twitchAPI library) for user lookups and EventSub subscription management
• EventSub subscriptions registered via the web service's public callback URL
• Config requires: client_id, client_secret (in config.yaml under twitch:)

---

Phase 2 — Extended Events (follow-up)

• Follower milestones — Notify when a streamer reaches follower goals
• Subscription events — Notify on new subs/resubs/gift subs
• Raid notifications — Notify when a streamer raids another channel
• Configurable per notification entry (admins pick which event types they want)

---

Data Model

Bot DB (existing from PR #109, needs minor adjustments)

• TwitchNotifications — guild, channel, streamer name, custom message, event types (Phase 2)

Web Service DB (new, part of #100 Phase 4)

• WebhookEvent — provider ("twitch"), event_type, payload (JSON), processed flag, created_at
• Bot polls for unprocessed events and marks them as handled

Technical Notes

• Cog in NerdyPy/modules/twitch.py
• Model in NerdyPy/models/twitch.py
• No EventSubWebhook inside the bot — all webhook reception handled by the web service (Management Webinterface #100)
• Bot registers EventSub subscriptions via Twitch API on startup (pointing callback URL to the web service)
• Bot consumes events from shared DB table (polling loop or event-driven)
• Streamer user cache: in-memory dict with TTL (same as PR WIP: F twitch addin #109's approach, works well)
• Admin commands gated with @checks.has_permissions(administrator=True)
• Uses send_hidden_message() for ephemeral responses
• Conditional module loading: only loads if twitch config section exists