Twitch — Live-Benachrichtigungen

GrumpyTwitch beobachtet Twitch-Streamer und postet automatisch eine Ankündigung, sobald sie live gehen.

---

Aktivierung

In configs/config.yml:

addons:
  twitch: true   # Standard: true (aktiv sobald der Bot startet)

twitchClientId: ""      # Twitch-App Client-ID (dev.twitch.tv) — nötig für Live-Erkennung
twitchClientSecret: ""  # Twitch-App Client-Secret — nötig für Live-Erkennung

Zugangsdaten erforderlich — im Unterschied zu YouTube! Twitch bietet keinen anonymen Weg, den Live-Status eines Streamers abzufragen. Ohne twitchClientId/twitchClientSecret bleiben /twitch add, /twitch remove und /twitch list voll nutzbar (reine Datenbankverwaltung), aber der eigentliche Live-Poller macht nichts — es werden schlicht keine Live-Checks durchgeführt. Beim Bot-Start zeigt das Setup-Status-Banner den Zustand klar an:

twitch: 🟡 enabled (no credentials — inactive)

Sobald beide Felder gesetzt sind und der Bot neu gestartet wurde, wechselt der Status auf 🟢 enabled.

Twitch-App registrieren

1. Auf dev.twitch.tv/console/apps einloggen (kostenloser Twitch-Account reicht) und eine neue App anlegen.
2. Nach dem Anlegen die Client-ID kopieren und ein neues Client Secret generieren.
3. Beide Werte in configs/config.yml als twitchClientId / twitchClientSecret eintragen.
4. Bot neu starten.

Die OAuth-Redirect-URL beim Anlegen der App spielt keine Rolle — GrumpyCore nutzt ausschließlich den App Access Token über den client_credentials-Flow (kein User-Login, keine Redirect nötig).

---

Konfigurationsdatei

Es gibt keine configs/modules/twitch.yml. Das Modul hat keine eigenen einstellbaren Werte in einer Modul-YAML — die Zugangsdaten stehen auf oberster Ebene in configs/config.yml (twitchClientId/twitchClientSecret, siehe oben), die beobachteten Streamer werden komplett per Slash-Command in der Datenbank verwaltet.

---

Commands

Alle Unterbefehle benötigen die Berechtigung Manage Guild und sind nur auf Servern nutzbar (kein DM).

/twitch add

Beobachtet einen neuen Twitch-Streamer.

Option	Pflicht	Beschreibung
login	✅	Twitch-Benutzername
channel	❌	Text-/Ankündigungskanal für Live-Ankündigungen (Standard: aktueller Kanal)
ping-role	❌	Rolle, die beim Live-Gehen gepingt wird

/twitch add login:einstreamer
/twitch add login:einstreamer channel:#stream-alerts ping-role:@Stream-Fans

Fehlen die Twitch-Zugangsdaten, wird der Watch trotzdem angelegt — die Bestätigung enthält dann zusätzlich einen Hinweis, dass die Überwachung erst nach Einrichtung von twitchClientId/twitchClientSecret aktiv wird.

Limit: maximal 10 beobachtete Streamer pro Server.

---

/twitch remove <id>

Entfernt eine Beobachtung anhand der ID aus /twitch list.

/twitch remove id:3

---

/twitch list

Listet alle beobachteten Streamer des Servers mit ID, Login-Name, Ziel-Channel, ggf. Ping-Rolle und aktuellem Live-Status (🔴 wenn gerade live).

/twitch list

---

Ablauf & Besonderheiten

• Poll-Intervall: alle 5 Minuten wird der Live-Status aller beobachteten Streamer (serverübergreifend gebündelt) über die Twitch-Helix-API (GET /helix/streams) abgefragt. Ein Aufruf kostet nur 1 Punkt unabhängig von der Anzahl der Logins (Rate-Limit: 800 Punkte/Minute) — bis zu 100 Logins werden pro Anfrage gebündelt.
• Edge-Detection (offline → live): Es wird nur beim Übergang von offline zu live gepostet, nicht bei jedem Tick währenddessen der Stream weiterläuft. Der Live-Zustand (isLive) wird pro Watch in der Datenbank gespeichert und bei jedem Tick abgeglichen.
• App Access Token: Der Bot holt sich automatisch einen Twitch-App-Access-Token (client_credentials-Flow) und cached ihn bis kurz vor Ablauf (mit Sicherheitspuffer), damit nicht bei jedem Tick neu angefragt werden muss.
• Ankündigung: lila Embed (Twitch-Farbe) mit Stream-Titel, Spiel, Zuschauerzahl, Vorschaubild und Link zum Stream; optional Ping der hinterlegten Rolle.
• Ohne Zugangsdaten: Der Poller überspringt jeden Tick vollständig (nur Debug-Log, kein Spam), solange twitchClientId/twitchClientSecret fehlen.

---

Berechtigungen

Aktion	Berechtigung
/twitch add / remove / list	Manage Guild
Bot zum Posten der Ankündigung	Send Messages im Ziel-Channel
Twitch-App-Registrierung	Twitch-Account des Bot-Admins (kostenlos, außerhalb von Discord)