Birthdays — Geburtstags-Glückwünsche & Rolle

GrumpyBirthdays lässt jeden User sein Geburtsdatum hinterlegen. Am Tag selbst postet der Bot automatisch eine Glückwunsch-Nachricht und kann optional eine temporäre "Geburtstagskind"-Rolle vergeben.

---

Aktivierung

In configs/config.yml:

addons:
  birthdays: true

Beim ersten Start wird configs/modules/birthdays.yml erzeugt.

---

birthdays.yml

enabled: true

channelId: ""      # Kanal für die Glückwunsch-Nachricht. "" = es wird nichts gepostet
roleId: ""         # Rolle, die am Geburtstag vergeben wird. "" = keine Rollenvergabe

message: "🎉 Happy Birthday {{user}}! 🎂"
# Platzhalter: {{user}} wird durch eine Mention ersetzt

---

Commands

/birthday set <date>

Setzt (oder überschreibt) das eigene Geburtsdatum.

Option	Beschreibung
date	Format DD.MM, z.B. 24.12 (auch DD-MM oder DD/MM werden akzeptiert)

/birthday set date:24.12

Das Jahr wird nicht gespeichert — nur Tag und Monat.

---

/birthday remove

Entfernt den eigenen gespeicherten Geburtstag.

/birthday remove

Schlägt fehl (mit Fehlermeldung), wenn kein Geburtstag gesetzt ist.

---

/birthday upcoming

Zeigt alle Geburtstage der nächsten 30 Tage, sortiert nach Nähe.

/birthday upcoming

Format je Zeile: @User — TT.MM · in X Tag(en) bzw. 🎉 heute! am Tag selbst.

---

/birthday reload

Lädt birthdays.yml neu, ohne den Bot neu zu starten.

/birthday reload

Berechtigung: Server verwalten (Manage Guild)

---

Ablauf: Congrats-Post & Rollenvergabe

Ein stündlicher Runner (nicht täglich!) prüft, ob heute (UTC) jemand Geburtstag hat.

Warum stündlich statt einmal täglich? Ein Bot-Neustart genau um Mitternacht UTC würde bei einer täglichen Prüfung das Zeitfenster komplett verpassen. Die stündliche Prüfung korrigiert sich selbst schnell wieder.

Pro fälligem Geburtstag (heute, noch nicht dieses Jahr gratuliert):

1. Ist channelId gesetzt → Glückwunsch-Nachricht wird dort gepostet (message mit ersetztem {{user}}).
2. Ist roleId gesetzt → die Rolle wird dem Mitglied zugewiesen.
3. Der User wird als "dieses Jahr bereits gratuliert" markiert (lastCongratsYear) — auch wenn Post oder Rollenvergabe fehlschlagen (z.B. wegen fehlender Berechtigung). So wird nicht stündlich erneut gegen ein kaputtes Setup angerannt; die Rollen-Aufräum-Logik (siehe unten) korrigiert das am Folgetag ohnehin.

Rollen-Aufräumen (am Folgetag): Wer die Geburtstagsrolle an einem vergangenen Tag dieses Jahres erhalten hat, aber heute nicht mehr Geburtstag hat, verliert die Rolle wieder — so bleibt sie nicht dauerhaft hängen.

Stündlicher Tick
  ├─ Fällige Geburtstage heute (noch nicht gratuliert dieses Jahr)
  │    ├─ Post in channelId (falls gesetzt)
  │    ├─ Rolle roleId vergeben (falls gesetzt)
  │    └─ als "gratuliert" markieren (best effort, auch bei Fehlern)
  └─ Abgelaufene Rolleninhaber (gratuliert, aber heute nicht mehr Geburtstag)
       └─ Rolle wieder entfernen

---

Schaltjahr-Behandlung (29. Februar)

Der 29. Februar ist als gültiges Datum erlaubt — der Bot merkt sich einfach month: 2, day: 29. Da die Fälligkeitsprüfung (findDueToday) auf dem tatsächlichen aktuellen UTC-Datum basiert, feuert dieser Geburtstag nur in Schaltjahren, wenn der 29. Februar real existiert. In Nicht-Schaltjahren gibt es keinen automatischen Ausweichtag (z.B. 1. März) — der Glückwunsch fällt in diesem Jahr einfach aus.

---

Berechtigungen

Command	Berechtigung
/birthday set	Jeder
/birthday remove	Jeder (nur eigener Eintrag)
/birthday upcoming	Jeder
/birthday reload	Manage Guild

Für die automatische Rollenvergabe benötigt der Bot Manage Roles, und seine eigene Rolle muss in der Hierarchie über der Geburtstagsrolle stehen. Alle Commands sind nur auf Servern nutzbar (kein DM-Kontext).