From 22e9a59e2e60f1d610c75cd40dc41424ca335e31 Mon Sep 17 00:00:00 2001
From: Martin Porwoll <martin.porwoll@complexcaresolutions.de>
Date: Sun, 1 Mar 2026 09:27:13 +0000
Subject: [PATCH] docs: add README with setup and deployment instructions

---
 README.md | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..028f72e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,98 @@
+# Telegram Media Upload Bot
+
+Telegram Bot zum Hochladen von Bildern in die Payload CMS Media-Bibliothek mit Multi-Tenant-Unterstützung.
+
+## Features
+
+- Bilder als Foto oder Dokument (Originalqualität) hochladen
+- Album/Bulk-Upload (bis zu 10 Bilder)
+- Multi-Tenant: Ziel-Tenant per Inline-Keyboard wählen
+- Automatische Bildverarbeitung (responsive Größen) durch Payload CMS
+- User-Whitelist (nur autorisierte Telegram-User)
+- Rate-Limiting (10 Uploads/Minute pro User)
+- Token-Caching mit Auto-Refresh
+
+## Setup
+
+```bash
+# Dependencies installieren
+pnpm install
+
+# .env konfigurieren
+cp .env.example .env
+# → Werte in .env eintragen (Bot-Token, Payload-Credentials, User-IDs)
+```
+
+### Telegram Bot erstellen
+
+1. @BotFather in Telegram öffnen
+2. `/newbot` senden
+3. Token in `.env` als `TELEGRAM_BOT_TOKEN` eintragen
+4. Eigene Telegram User-ID in `ALLOWED_USER_IDS` eintragen
+5. Optional: `/setcommands` beim BotFather:
+   ```
+   start - Bot starten und Hilfe anzeigen
+   tenant - Ziel-Tenant wechseln
+   list - Letzte Uploads anzeigen
+   status - Bot- und API-Status prüfen
+   help - Ausführliche Hilfe
+   ```
+
+## Entwicklung
+
+```bash
+pnpm dev          # tsx watch mode
+pnpm lint         # TypeScript check
+pnpm build        # Kompilieren nach dist/
+```
+
+## Production
+
+```bash
+pnpm build
+pm2 start ecosystem.config.cjs
+pm2 save
+pm2 logs telegram-media-bot
+```
+
+## Bot-Befehle
+
+| Befehl | Beschreibung |
+|--------|-------------|
+| `/start` | Begrüßung und Kurzanleitung |
+| `/tenant` | Ziel-Tenant wechseln |
+| `/list` | Letzte 5 Uploads anzeigen |
+| `/status` | Bot- und API-Status |
+| `/help` | Ausführliche Hilfe |
+
+## Umgebungsvariablen
+
+| Variable | Pflicht | Beschreibung |
+|----------|---------|-------------|
+| `TELEGRAM_BOT_TOKEN` | Ja | Bot-Token von @BotFather |
+| `ALLOWED_USER_IDS` | Ja | Kommaseparierte Telegram User-IDs |
+| `PAYLOAD_API_URL` | Ja | Payload API URL (z.B. `https://cms.c2sgmbh.de/api`) |
+| `PAYLOAD_ADMIN_EMAIL` | Ja | Payload Admin E-Mail |
+| `PAYLOAD_ADMIN_PASSWORD` | Ja | Payload Admin Passwort |
+| `DEFAULT_TENANT_ID` | Nein | Standard-Tenant (Default: 4) |
+| `LOG_LEVEL` | Nein | Log-Level: debug, info, warn, error (Default: info) |
+| `NODE_ENV` | Nein | Environment (Default: development) |
+
+## Architektur
+
+```
+src/
+├── index.ts              # Entry Point
+├── bot.ts                # Grammy Bot + Session + Rate-Limiting
+├── config.ts             # Typisierte Konfiguration
+├── payload/
+│   └── client.ts         # Payload API Client (Login, Upload, Token-Caching)
+├── telegram/
+│   ├── handlers.ts       # Alle Message- und Command-Handler
+│   └── keyboards.ts      # Inline Keyboards (Tenant-Auswahl)
+├── middleware/
+│   └── auth.ts           # User-Whitelist Middleware
+└── utils/
+    ├── logger.ts         # Console Logger mit Levels
+    └── download.ts       # File Download Helper
+```