From 86ace42fcac4dd4e855dd65e5b69155fe961da9d Mon Sep 17 00:00:00 2001 From: "matthias.lotz" Date: Sat, 29 Nov 2025 20:05:40 +0100 Subject: [PATCH] feat: Add Telegram Bot standalone test (Phase 1) - Add FEATURE_PLAN-telegram.md with 6-phase implementation roadmap - Add scripts/README.telegram.md with step-by-step setup guide - Add scripts/telegram-test.js standalone test script - Add scripts/.env.telegram.example template for credentials - Update .gitignore to protect Telegram credentials Phase 1 complete: Bot setup, privacy mode configuration, and successful test message delivery. --- .gitignore | 5 + FeatureRequests/FEATURE_PLAN-telegram.md | 358 ++++++++++++++++ scripts/.env.telegram.example | 15 + scripts/README.telegram.md | 506 +++++++++++++++++++++++ scripts/telegram-test.js | 166 ++++++++ 5 files changed, 1050 insertions(+) create mode 100644 FeatureRequests/FEATURE_PLAN-telegram.md create mode 100644 scripts/.env.telegram.example create mode 100644 scripts/README.telegram.md create mode 100644 scripts/telegram-test.js diff --git a/.gitignore b/.gitignore index 585944b..c55a002 100644 --- a/.gitignore +++ b/.gitignore @@ -9,6 +9,11 @@ node_modules/ .env .env.local +# Telegram credentials +scripts/.env.telegram +scripts/node_modules/ +scripts/package-lock.json + # IDE .vscode/ .idea/ diff --git a/FeatureRequests/FEATURE_PLAN-telegram.md b/FeatureRequests/FEATURE_PLAN-telegram.md new file mode 100644 index 0000000..2fc6217 --- /dev/null +++ b/FeatureRequests/FEATURE_PLAN-telegram.md @@ -0,0 +1,358 @@ +# Feature Plan: Telegram Bot Integration + +## Übersicht + +Implementierung eines Telegram Bots zur automatischen Benachrichtigung der Werkstatt-Gruppe über wichtige Events im Image Uploader System. + +**Basis:** [FEATURE_REQUEST-telegram.md](./FEATURE_REQUEST-telegram.md) + +--- + +## Phasen-Aufteilung + +### Phase 1: Bot Setup & Standalone-Test ⭐ **CURRENT** +**Ziel:** Telegram Bot erstellen und isoliert testen (ohne App-Integration) + +**Status:** 🟡 In Planung + +**Deliverables:** +- [ ] Telegram Bot via BotFather erstellt +- [ ] Bot zu Test-Telegram-Gruppe hinzugefügt +- [ ] Chat-ID ermittelt +- [ ] `scripts/telegram-test.js` - Standalone Test-Script +- [ ] `scripts/README.telegram.md` - Setup-Anleitung +- [ ] `.env.telegram` - Template für Bot-Credentials +- [ ] Erfolgreiche Test-Nachricht versendet + +**Akzeptanzkriterium:** +✅ Bot sendet erfolgreich Nachricht an Testgruppe + +--- + +### Phase 2: Backend-Service Integration +**Ziel:** TelegramNotificationService in Backend integrieren + +**Dependencies:** Phase 1 abgeschlossen + +**Deliverables:** +- [ ] `backend/src/services/TelegramNotificationService.js` +- [ ] ENV-Variablen in `docker/dev/backend/config/.env` +- [ ] Unit-Tests für Service +- [ ] Docker Dev Environment funktioniert + +--- + +### Phase 3: Upload-Benachrichtigungen +**Ziel:** Automatische Benachrichtigungen bei neuem Upload + +**Dependencies:** Phase 2 abgeschlossen + +**Deliverables:** +- [ ] Integration in `routes/batchUpload.js` +- [ ] `sendUploadNotification()` Methode +- [ ] Formatierung mit Icons/Emojis +- [ ] Integration-Tests + +--- + +### Phase 4: User-Änderungs-Benachrichtigungen +**Ziel:** Benachrichtigungen bei Consent-Änderungen & Löschungen + +**Dependencies:** Phase 3 abgeschlossen + +**Deliverables:** +- [ ] Integration in `routes/management.js` (PUT/DELETE) +- [ ] `sendConsentChangeNotification()` Methode +- [ ] `sendGroupDeletedNotification()` Methode +- [ ] Integration-Tests + +--- + +### Phase 5: Tägliche Lösch-Warnungen +**Ziel:** Cron-Job für bevorstehende Löschungen + +**Dependencies:** Phase 4 abgeschlossen + +**Deliverables:** +- [ ] Cron-Job Setup (node-cron) +- [ ] `sendDeletionWarning()` Methode +- [ ] Admin-Route für manuellen Trigger +- [ ] Dokumentation + +--- + +### Phase 6: Production Deployment +**Ziel:** Rollout in Production-Umgebung + +**Dependencies:** Phase 1-5 abgeschlossen + getestet + +**Deliverables:** +- [ ] Production ENV-Variablen +- [ ] Docker Prod Environment konfiguriert +- [ ] Bot in echte Werkstatt-Gruppe eingefügt +- [ ] Monitoring/Logging +- [ ] README.md Update + +--- + +## Phase 1 - Detaillierter Plan + +### 1. Vorbereitung (5 min) + +**Auf Windows 11 Host-System:** + +```bash +# Node.js Version prüfen +node --version # Sollte >= 18.x sein + +# Projektverzeichnis öffnen +cd /home/lotzm/gitea.hobbyhimmel/Project-Image-Uploader/scripts + +# Dependencies installieren (lokal) +npm init -y # Falls noch keine package.json +npm install node-telegram-bot-api dotenv +``` + +### 2. Telegram Bot erstellen (10 min) + +**Anleitung:** Siehe `scripts/README.telegram.md` + +**Schritte:** +1. Telegram öffnen (Windows 11 App) +2. [@BotFather](https://t.me/botfather) suchen +3. `/newbot` Command +4. Bot-Name: "Werkstatt Image Uploader Bot" +5. Username: `werkstatt_uploader_bot` (oder verfügbar) +6. **Token kopieren** → `.env.telegram` + +### 3. Test-Gruppe erstellen & Bot hinzufügen (5 min) + +**Schritte:** +1. Neue Telegram-Gruppe erstellen: "Werkstatt Upload Bot Test" +2. Bot zur Gruppe hinzufügen: @werkstatt_uploader_bot +3. **Chat-ID ermitteln** (siehe README.telegram.md) +4. Chat-ID speichern → `.env.telegram` + +### 4. Test-Script erstellen (10 min) + +**Datei:** `scripts/telegram-test.js` + +**Features:** +- Lädt `.env.telegram` +- Validiert Bot-Token +- Sendet Test-Nachricht +- Error-Handling + +### 5. Erste Nachricht senden (2 min) + +```bash +cd scripts +node telegram-test.js +``` + +**Erwartete Ausgabe:** +``` +✅ Telegram Bot erfolgreich verbunden! +Bot-Name: Werkstatt Image Uploader Bot +Bot-Username: @werkstatt_uploader_bot + +📤 Sende Test-Nachricht an Chat -1001234567890... +✅ Nachricht erfolgreich gesendet! +``` + +**In Telegram-Gruppe:** +``` +🤖 Telegram Bot Test + +Dies ist eine Test-Nachricht vom Werkstatt Image Uploader Bot. + +Status: ✅ Erfolgreich verbunden! +Zeitstempel: 2025-11-29 14:23:45 +``` + +--- + +## Dateistruktur (Phase 1) + +``` +scripts/ +├── README.telegram.md # Setup-Anleitung (NEU) +├── telegram-test.js # Test-Script (NEU) +├── .env.telegram.example # ENV-Template (NEU) +├── .env.telegram # Echte Credentials (gitignored, NEU) +├── package.json # Lokale Dependencies (NEU) +└── node_modules/ # npm packages (gitignored) +``` + +--- + +## Environment Variables (Phase 1) + +**Datei:** `scripts/.env.telegram` + +```bash +# Telegram Bot Configuration +TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz +TELEGRAM_CHAT_ID=-1001234567890 +``` + +--- + +## Dependencies (Phase 1) + +**Package:** `scripts/package.json` + +```json +{ + "name": "telegram-test-scripts", + "version": "1.0.0", + "description": "Standalone Telegram Bot Testing", + "main": "telegram-test.js", + "scripts": { + "test": "node telegram-test.js" + }, + "dependencies": { + "node-telegram-bot-api": "^0.66.0", + "dotenv": "^16.3.1" + } +} +``` + +--- + +## Sicherheit (Phase 1) + +**`.gitignore` ergänzen:** + +``` +# Telegram Credentials +scripts/.env.telegram +scripts/node_modules/ +scripts/package-lock.json +``` + +**Wichtig:** +- ❌ Niemals `.env.telegram` committen! +- ✅ Nur `.env.telegram.example` (ohne echte Tokens) committen +- ✅ Bot-Token regenerieren, falls versehentlich exposed + +--- + +## Testing Checklist (Phase 1) + +- [ ] Node.js Version >= 18.x +- [ ] Telegram App installiert (Windows 11) +- [ ] Bot via BotFather erstellt +- [ ] Bot-Token gespeichert in `.env.telegram` +- [ ] Test-Gruppe erstellt +- [ ] Bot zur Gruppe hinzugefügt +- [ ] Chat-ID ermittelt +- [ ] Chat-ID gespeichert in `.env.telegram` +- [ ] `npm install` erfolgreich +- [ ] `node telegram-test.js` läuft ohne Fehler +- [ ] Test-Nachricht in Telegram-Gruppe empfangen +- [ ] Formatierung (Emojis, Zeilenumbrüche) korrekt + +--- + +## Troubleshooting (Phase 1) + +### Problem: "Unauthorized (401)" +**Lösung:** Bot-Token falsch → BotFather prüfen, `.env.telegram` korrigieren + +### Problem: "Bad Request: chat not found" +**Lösung:** Chat-ID falsch → Neue Nachricht in Gruppe senden, Chat-ID neu ermitteln + +### Problem: "ETELEGRAM: 403 Forbidden" +**Lösung:** Bot wurde aus Gruppe entfernt → Bot erneut zur Gruppe hinzufügen + +### Problem: "Module not found: node-telegram-bot-api" +**Lösung:** +```bash +cd scripts +npm install +``` + +--- + +## Nächste Schritte (nach Phase 1) + +1. **Code-Review:** `scripts/telegram-test.js` +2. **Dokumentation Review:** `scripts/README.telegram.md` +3. **Commit:** + ```bash + git add scripts/ + git commit -m "feat: Add Telegram Bot standalone test (Phase 1)" + ``` +4. **Phase 2 starten:** Backend-Integration planen + +--- + +## Zeitschätzung + +| Phase | Aufwand | Beschreibung | +|-------|---------|--------------| +| **Phase 1** | **~45 min** | Bot Setup + Standalone-Test | +| Phase 2 | ~2h | Backend-Service | +| Phase 3 | ~2h | Upload-Benachrichtigungen | +| Phase 4 | ~2h | Änderungs-Benachrichtigungen | +| Phase 5 | ~2h | Cron-Job | +| Phase 6 | ~1h | Production Deployment | +| **Gesamt** | **~9-10h** | Vollständige Integration | + +--- + +## Conventional Commits (ab Phase 1) + +**Phase 1:** +```bash +git commit -m "feat: Add Telegram Bot test script" +git commit -m "docs: Add Telegram Bot setup guide" +git commit -m "chore: Add node-telegram-bot-api dependency to scripts" +``` + +**Phase 2:** +```bash +git commit -m "feat: Add TelegramNotificationService" +git commit -m "test: Add TelegramNotificationService unit tests" +``` + +**Phase 3-6:** +```bash +git commit -m "feat: Add upload notification to Telegram" +git commit -m "feat: Add consent change notifications" +git commit -m "feat: Add daily deletion warnings cron job" +git commit -m "docs: Update README with Telegram features" +``` + +--- + +## Release-Planung + +**Phase 1:** Kein Release (interne Tests) + +**Phase 6 (Final):** +- **Version:** `2.0.0` (Major Release) +- **Branch:** `feature/telegram-notifications` +- **Release-Command:** `npm run release:major` + +--- + +## Status-Tracking + +**Letzte Aktualisierung:** 2025-11-29 + +| Phase | Status | Datum | +|-------|--------|-------| +| Phase 1 | 🟡 In Planung | 2025-11-29 | +| Phase 2 | ⚪ Ausstehend | - | +| Phase 3 | ⚪ Ausstehend | - | +| Phase 4 | ⚪ Ausstehend | - | +| Phase 5 | ⚪ Ausstehend | - | +| Phase 6 | ⚪ Ausstehend | - | + +**Legende:** +- 🟢 Abgeschlossen +- 🟡 In Arbeit +- 🔴 Blockiert +- ⚪ Ausstehend diff --git a/scripts/.env.telegram.example b/scripts/.env.telegram.example new file mode 100644 index 0000000..e2251f3 --- /dev/null +++ b/scripts/.env.telegram.example @@ -0,0 +1,15 @@ +# Telegram Bot Configuration Template +# +# Kopiere diese Datei zu .env.telegram und trage deine echten Werte ein: +# cp .env.telegram.example .env.telegram +# +# WICHTIG: .env.telegram NIEMALS committen! (ist in .gitignore) + +# Bot-Token von @BotFather +# Beispiel: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz1234567890 +TELEGRAM_BOT_TOKEN=YOUR_BOT_TOKEN_HERE + +# Chat-ID der Telegram-Gruppe (negativ für Gruppen!) +# Ermitteln via: https://api.telegram.org/bot/getUpdates +# Beispiel: -1001234567890 +TELEGRAM_CHAT_ID=YOUR_CHAT_ID_HERE diff --git a/scripts/README.telegram.md b/scripts/README.telegram.md new file mode 100644 index 0000000..dc5bab8 --- /dev/null +++ b/scripts/README.telegram.md @@ -0,0 +1,506 @@ +# Telegram Bot Setup & Testing Guide + +## Übersicht + +Diese Anleitung beschreibt Schritt-für-Schritt, wie du den Telegram Bot für den Image Uploader erstellst und testest. + +**Phase 1:** Standalone-Test (ohne Backend-Integration) + +--- + +## Voraussetzungen + +- ✅ Windows 11 mit installiertem Telegram Desktop +- ✅ Telegram Account +- ✅ Node.js >= 18.x installiert +- ✅ Zugriff auf dieses Git-Repository + +--- + +## 1. Telegram Bot erstellen + +### 1.1 BotFather öffnen + +1. **Telegram Desktop** öffnen +2. In der Suche eingeben: `@BotFather` +3. Chat mit **BotFather** öffnen (offizieller Bot mit blauem Haken ✓) + +### 1.2 Neuen Bot erstellen + +**Commands im BotFather-Chat eingeben:** + +``` +/newbot +``` + +**BotFather fragt nach Namen:** +``` +Alright, a new bot. How are we going to call it? +Please choose a name for your bot. +``` + +**Antworten mit:** +``` +Werkstatt Image Uploader Bot +``` + +**BotFather fragt nach Username:** +``` +Good. Now let's choose a username for your bot. +It must end in `bot`. Like this, for example: TetrisBot or tetris_bot. +``` + +**Antworten mit (muss auf `bot` enden):** +``` +werkstatt_uploader_bot +``` + +⚠️ **Falls Username vergeben:** Anderen Namen wählen (z.B. `werkstatt_upload_bot`, `hobbyhimmel_uploader_bot`) + +### 1.3 Bot-Token speichern + +**BotFather antwortet mit:** +``` +Done! Congratulations on your new bot. +You will find it at t.me/werkstatt_uploader_bot. +You can now add a description, about section and profile picture for your bot. + +Use this token to access the HTTP API: +123456789:ABCdefGHIjklMNOpqrsTUVwxyz1234567890 + +Keep your token secure and store it safely, it can be used by anyone to control your bot. +``` + +**Token kopieren** (z.B. `123456789:ABCdefGHIjklMNOpqrsTUVwxyz1234567890`) + +➡️ **Diesen Token brauchst du gleich für `.env.telegram`!** + +--- + +## 2. Test-Telegram-Gruppe erstellen + +### 2.1 Neue Gruppe erstellen + +1. In Telegram: **Neuer Chat** → **Neue Gruppe** +2. Gruppennamen eingeben: `Werkstatt Upload Bot Test` +3. **Weiter** klicken +4. (Optional) Weitere Mitglieder hinzufügen (oder nur dich selbst) +5. **Erstellen** klicken + +### 2.2 Bot zur Gruppe hinzufügen + +1. Test-Gruppe öffnen +2. Auf Gruppennamen (oben) klicken → **Mitglieder hinzufügen** +3. Suche nach: `@werkstatt_uploader_bot` (dein Bot-Username) +4. Bot auswählen → **Hinzufügen** + +**Telegram zeigt:** +``` +werkstatt_uploader_bot wurde zur Gruppe hinzugefügt +``` + +### 2.3 Privacy Mode deaktivieren (WICHTIG!) + +⚠️ **Ohne diesen Schritt sieht der Bot keine Gruppennachrichten!** + +1. **BotFather** öffnen +2. Command eingeben: `/mybots` +3. Deinen Bot auswählen: `@werkstatt_uploader_bot` +4. **Bot Settings** klicken +5. **Group Privacy** klicken +6. **Turn off** klicken + +**BotFather bestätigt:** +``` +Privacy mode is disabled for . +All messages will now be sent to the bot. +``` + +### 2.4 Bot als Admin hinzufügen (optional, aber empfohlen) + +1. Gruppe öffnen → Gruppennamen klicken +2. **Administratoren** → **Administrator hinzufügen** +3. `@werkstatt_uploader_bot` auswählen +4. **Berechtigungen:** + - ✅ Nachrichten senden + - ❌ Alle anderen optional (nicht nötig) +5. **Speichern** + +--- + +## 3. Chat-ID ermitteln + +Die Chat-ID wird benötigt, um Nachrichten an die richtige Gruppe zu senden. + +### Methode 1: Via Telegram API (empfohlen) + +**Schritt 1:** Nachricht in Test-Gruppe senden + +- Öffne die Test-Gruppe +- Sende eine beliebige Nachricht (z.B. "Test") + +**Schritt 2:** Browser öffnen und folgende URL aufrufen: + +``` +https://api.telegram.org/bot/getUpdates +``` + +**Ersetze ``** mit deinem echten Token! + +**Beispiel:** +``` +https://api.telegram.org/bot123456789:ABCdefGHIjklMNOpqrsTUVwxyz/getUpdates +``` + +⚠️ **Wenn du `{"ok":true,"result":[]}` siehst (leeres result-Array):** + +Das bedeutet, der Bot hat noch keine Nachrichten empfangen. **Checkliste:** + +1. ✅ Hast du den Bot zur Gruppe hinzugefügt? (Schritt 2.2) +2. ✅ Hast du **NACH** dem Hinzufügen eine Nachricht gesendet? (Schritt 1) +3. ✅ War die Nachricht in der **richtigen Gruppe** (nicht im Bot-Direct-Chat)? + +**Lösung - Mach jetzt folgendes:** +- Telegram öffnen +- **Test-Gruppe** öffnen (nicht den Bot direkt!) +- Prüfe, ob der Bot als Mitglied angezeigt wird +- Sende eine neue Nachricht: "Test" +- **Sofort** zurück zum Browser → Seite neu laden (F5) + +**Schritt 3:** Im JSON-Response nach `chat` suchen: + +```json +{ + "ok": true, + "result": [ + { + "update_id": 123456789, + "message": { + "message_id": 1, + "from": { ... }, + "chat": { + "id": -1001234567890, // ← DAS IST DEINE CHAT-ID! + "title": "Werkstatt Upload Bot Test", + "type": "supergroup" + }, + "text": "Test" + } + } + ] +} +``` + +**Chat-ID kopieren** (z.B. `-1001234567890`) + +⚠️ **Wichtig:** Gruppen-Chat-IDs sind **negativ** und beginnen meist mit `-100`! + +### Methode 2: Via curl (Linux/WSL) + +```bash +curl "https://api.telegram.org/bot/getUpdates" | jq '.result[0].message.chat.id' +``` + +--- + +## 4. Environment-Datei erstellen + +### 4.1 Template kopieren + +```bash +cd scripts +cp .env.telegram.example .env.telegram +``` + +### 4.2 `.env.telegram` bearbeiten + +**Datei öffnen:** `scripts/.env.telegram` + +```bash +# Telegram Bot Configuration +TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz +TELEGRAM_CHAT_ID=-1001234567890 +``` + +**Deine echten Werte eintragen:** +- `TELEGRAM_BOT_TOKEN` → Token von BotFather (Schritt 1.3) +- `TELEGRAM_CHAT_ID` → Chat-ID aus Schritt 3 (negativ!) + +**Speichern** und schließen. + +--- + +## 5. Dependencies installieren + +```bash +cd scripts + +# package.json initialisieren (falls nicht vorhanden) +npm init -y + +# Telegram Bot API installieren +npm install node-telegram-bot-api dotenv +``` + +**Erwartete Ausgabe:** +``` +added 15 packages, and audited 16 packages in 2s +``` + +--- + +## 6. Test-Script ausführen + +### 6.1 Script starten + +```bash +node telegram-test.js +``` + +### 6.2 Erwartete Ausgabe (Erfolg) + +``` +🔧 Lade Telegram-Konfiguration... +✅ Konfiguration geladen! + +🤖 Verbinde mit Telegram Bot... +✅ Telegram Bot erfolgreich verbunden! + +Bot-Details: + Name: Werkstatt Image Uploader Bot + Username: @werkstatt_uploader_bot + ID: 1234567890 + +📤 Sende Test-Nachricht an Chat -1001234567890... +✅ Nachricht erfolgreich gesendet! + +Message-ID: 42 +``` + +### 6.3 Telegram-Gruppe prüfen + +**In der Test-Gruppe sollte jetzt erscheinen:** + +``` +🤖 Telegram Bot Test + +Dies ist eine Test-Nachricht vom Werkstatt Image Uploader Bot. + +Status: ✅ Erfolgreich verbunden! +Zeitstempel: 2025-11-29 14:23:45 + +--- +ℹ️ Dieser Bot sendet automatische Benachrichtigungen für den Image Uploader. +``` + +--- + +## 7. Troubleshooting + +### ❌ Fehler: "Error: Unauthorized (401)" + +**Ursache:** Bot-Token ist falsch oder ungültig + +**Lösung:** +1. BotFather öffnen +2. `/token` eingeben +3. Deinen Bot auswählen +4. Neuen Token kopieren +5. `.env.telegram` aktualisieren +6. Script erneut starten + +--- + +### ❌ Fehler: "Bad Request: chat not found" + +**Ursache:** Chat-ID ist falsch + +**Lösung:** +1. Test-Gruppe öffnen +2. Neue Nachricht senden +3. Chat-ID erneut ermitteln (Schritt 3) +4. `.env.telegram` aktualisieren +5. Script erneut starten + +--- + +### ❌ Fehler: "Error: ETELEGRAM: 403 Forbidden" + +**Ursache:** Bot wurde aus der Gruppe entfernt oder kann nicht posten + +**Lösung:** +1. Test-Gruppe öffnen +2. Prüfen, ob Bot noch Mitglied ist +3. Falls nicht: Bot erneut hinzufügen (Schritt 2.2) +4. Falls ja: Bot als Admin hinzufügen (Schritt 2.3) +5. Script erneut starten + +--- + +### ❌ Fehler: "Cannot find module 'node-telegram-bot-api'" + +**Ursache:** Dependencies nicht installiert + +**Lösung:** +```bash +cd scripts +npm install +node telegram-test.js +``` + +--- + +### ❌ Fehler: "TELEGRAM_BOT_TOKEN is not defined" + +**Ursache:** `.env.telegram` fehlt oder nicht korrekt + +**Lösung:** +1. Prüfen, ob `.env.telegram` existiert: `ls -la scripts/.env.telegram` +2. Falls nicht: Template kopieren (Schritt 4.1) +3. Werte eintragen (Schritt 4.2) +4. Script erneut starten + +--- + +## 8. Erweiterte Tests + +### Test 1: Formatierung mit Emojis + +**Script anpassen:** `telegram-test.js` + +```javascript +const message = ` +📸 Neuer Upload! + +Uploader: Max Mustermann +Bilder: 12 +Gruppe: 2024 - Schweißkurs November + +Workshop: ✅ Ja +Social Media: 📘 Instagram, 🎵 TikTok + +🔗 Zur Freigabe: https://internal.hobbyhimmel.de/moderation +`; + +bot.sendMessage(chatId, message); +``` + +**Ausführen:** +```bash +node telegram-test.js +``` + +**Telegram prüfen:** Emojis sollten korrekt angezeigt werden + +--- + +### Test 2: HTML-Formatierung + +**Script anpassen:** + +```javascript +const message = ` +🤖 Telegram Bot Test + +HTML-Formatierung funktioniert! + +Status: ✅ Erfolgreich + +Link zur Website +`; + +bot.sendMessage(chatId, message, { parse_mode: 'HTML' }); +``` + +**Ausführen & prüfen:** Fetter Text, kursiver Text, Code, Link + +--- + +### Test 3: Markdown-Formatierung + +**Script anpassen:** + +```javascript +const message = ` +*🤖 Telegram Bot Test* + +_Markdown-Formatierung funktioniert!_ + +\`Status: ✅ Erfolgreich\` + +[Link zur Website](https://hobbyhimmel.de) +`; + +bot.sendMessage(chatId, message, { parse_mode: 'Markdown' }); +``` + +--- + +## 9. Sicherheit + +### ⚠️ Wichtig! + +- ❌ **NIEMALS** `.env.telegram` committen! +- ❌ **NIEMALS** Bot-Token öffentlich teilen! +- ✅ `.env.telegram` ist in `.gitignore` eingetragen +- ✅ Nur `.env.telegram.example` (ohne echte Tokens) committen + +### Bot-Token kompromittiert? + +**Falls Token versehentlich exposed:** + +1. BotFather öffnen +2. `/revoke` eingeben +3. Deinen Bot auswählen +4. **Neuen Token** kopieren +5. `.env.telegram` aktualisieren +6. Alle Services neu starten + +--- + +## 10. Nächste Schritte + +### ✅ Phase 1 abgeschlossen? + +Checklist: +- [x] Bot erstellt +- [x] Test-Gruppe erstellt +- [x] Bot zur Gruppe hinzugefügt +- [x] Chat-ID ermittelt +- [x] `.env.telegram` konfiguriert +- [x] `npm install` erfolgreich +- [x] `node telegram-test.js` läuft ohne Fehler +- [x] Test-Nachricht in Telegram empfangen + +### ➡️ Weiter zu Phase 2 + +**Backend-Integration:** +1. `TelegramNotificationService.js` erstellen +2. Service in Docker Dev Environment integrieren +3. ENV-Variablen in Backend übertragen +4. Unit-Tests schreiben + +**Siehe:** `FeatureRequests/FEATURE_PLAN-telegram.md` + +--- + +## Referenzen + +- [Telegram Bot API Dokumentation](https://core.telegram.org/bots/api) +- [node-telegram-bot-api (npm)](https://www.npmjs.com/package/node-telegram-bot-api) +- [BotFather Commands](https://core.telegram.org/bots#botfather) + +--- + +## Support + +**Bei Problemen:** +1. Troubleshooting-Sektion durchlesen (Schritt 7) +2. Telegram Bot API Logs prüfen +3. BotFather `/mybots` → Bot auswählen → API Token prüfen +4. Chat-ID erneut ermitteln + +**Erfolgreicher Test? 🎉** +```bash +git add scripts/ +git commit -m "feat: Add Telegram Bot standalone test (Phase 1)" +``` diff --git a/scripts/telegram-test.js b/scripts/telegram-test.js new file mode 100644 index 0000000..71613c8 --- /dev/null +++ b/scripts/telegram-test.js @@ -0,0 +1,166 @@ +#!/usr/bin/env node + +/** + * Telegram Bot Standalone Test Script + * + * Testet die grundlegende Funktionalität des Telegram Bots + * ohne Integration in das Backend. + * + * Phase 1: Bot Setup & Standalone-Test + * + * Usage: + * node telegram-test.js + * + * Prerequisites: + * - .env.telegram mit TELEGRAM_BOT_TOKEN und TELEGRAM_CHAT_ID + * - npm install node-telegram-bot-api dotenv + */ + +require('dotenv').config({ path: '.env.telegram' }); +const TelegramBot = require('node-telegram-bot-api'); + +// ============================================================================= +// Configuration +// ============================================================================= + +const BOT_TOKEN = process.env.TELEGRAM_BOT_TOKEN; +const CHAT_ID = process.env.TELEGRAM_CHAT_ID; + +// ============================================================================= +// Validation +// ============================================================================= + +console.log('🔧 Lade Telegram-Konfiguration...'); + +if (!BOT_TOKEN) { + console.error('❌ FEHLER: TELEGRAM_BOT_TOKEN ist nicht definiert!'); + console.error(''); + console.error('Bitte .env.telegram erstellen und Bot-Token eintragen:'); + console.error(''); + console.error(' TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz'); + console.error(' TELEGRAM_CHAT_ID=-1001234567890'); + console.error(''); + console.error('Siehe: scripts/README.telegram.md'); + process.exit(1); +} + +if (!CHAT_ID) { + console.error('❌ FEHLER: TELEGRAM_CHAT_ID ist nicht definiert!'); + console.error(''); + console.error('Bitte .env.telegram erstellen und Chat-ID eintragen:'); + console.error(''); + console.error(' TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz'); + console.error(' TELEGRAM_CHAT_ID=-1001234567890'); + console.error(''); + console.error('Chat-ID ermitteln: https://api.telegram.org/bot/getUpdates'); + console.error('Siehe: scripts/README.telegram.md'); + process.exit(1); +} + +console.log('✅ Konfiguration geladen!'); +console.log(''); + +// ============================================================================= +// Bot Initialization +// ============================================================================= + +console.log('🤖 Verbinde mit Telegram Bot...'); + +// Create bot instance (polling disabled for one-off script) +const bot = new TelegramBot(BOT_TOKEN, { polling: false }); + +// ============================================================================= +// Main Test Function +// ============================================================================= + +async function runTest() { + try { + // Step 1: Verify bot connection + const botInfo = await bot.getMe(); + + console.log('✅ Telegram Bot erfolgreich verbunden!'); + console.log(''); + console.log('Bot-Details:'); + console.log(` Name: ${botInfo.first_name}`); + console.log(` Username: @${botInfo.username}`); + console.log(` ID: ${botInfo.id}`); + console.log(''); + + // Step 2: Prepare test message + const timestamp = new Date().toLocaleString('de-DE', { + year: 'numeric', + month: '2-digit', + day: '2-digit', + hour: '2-digit', + minute: '2-digit', + second: '2-digit' + }); + + const message = ` +🤖 Telegram Bot Test + +Dies ist eine Test-Nachricht vom Werkstatt Image Uploader Bot. + +Status: ✅ Erfolgreich verbunden! +Zeitstempel: ${timestamp} + +--- +ℹ️ Dieser Bot sendet automatische Benachrichtigungen für den Image Uploader. +`.trim(); + + // Step 3: Send test message + console.log(`📤 Sende Test-Nachricht an Chat ${CHAT_ID}...`); + + const sentMessage = await bot.sendMessage(CHAT_ID, message); + + console.log('✅ Nachricht erfolgreich gesendet!'); + console.log(''); + console.log(`Message-ID: ${sentMessage.message_id}`); + console.log(''); + console.log('🎉 Test erfolgreich abgeschlossen!'); + console.log(''); + console.log('➡️ Nächste Schritte:'); + console.log(' 1. Telegram-Gruppe öffnen und Nachricht prüfen'); + console.log(' 2. Verschiedene Nachrichtenformate testen (siehe README.telegram.md)'); + console.log(' 3. Phase 2 starten: Backend-Integration'); + + } catch (error) { + console.error('❌ FEHLER beim Senden der Nachricht:'); + console.error(''); + + if (error.response && error.response.body) { + const errorData = error.response.body; + console.error(`Error Code: ${errorData.error_code}`); + console.error(`Description: ${errorData.description}`); + console.error(''); + + // Helpful error messages + if (errorData.error_code === 401) { + console.error('💡 Lösung: Bot-Token ist ungültig oder falsch.'); + console.error(' → BotFather öffnen und Token prüfen'); + console.error(' → .env.telegram aktualisieren'); + } else if (errorData.error_code === 400 && errorData.description.includes('chat not found')) { + console.error('💡 Lösung: Chat-ID ist falsch oder ungültig.'); + console.error(' → Chat-ID erneut ermitteln: https://api.telegram.org/bot/getUpdates'); + console.error(' → Neue Nachricht in Gruppe senden, dann getUpdates aufrufen'); + console.error(' → .env.telegram aktualisieren'); + } else if (errorData.error_code === 403) { + console.error('💡 Lösung: Bot hat keine Berechtigung, in diese Gruppe zu schreiben.'); + console.error(' → Bot zur Gruppe hinzufügen'); + console.error(' → Bot als Admin hinzufügen (empfohlen)'); + } + } else { + console.error(error.message); + } + + console.error(''); + console.error('📖 Siehe Troubleshooting: scripts/README.telegram.md'); + process.exit(1); + } +} + +// ============================================================================= +// Execute Test +// ============================================================================= + +runTest();