@deathnaitsa/wa-api 2.0.4 → 2.0.5

package/README.md

@@ -2,34 +2,68 @@
 
 Eine minimalistische, stabile WhatsApp Multi-Device API basierend auf Baileys mit erweiterten Session-Management und Statistik-Features.
 
+## 📑 Inhaltsverzeichnis
+
+- [Status](#-status)
+- [Features](#-features)
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+  - [ES Modules](#es-modules-empfohlen)
+  - [CommonJS](#commonjs)
+- [API Dokumentation](#-api-dokumentation)
+  - [Session Management](#-session-management-implementiert)
+  - [Nachrichten](#-nachrichten-implementiert)
+  - [Media & Stickers](#-media--stickers-implementiert)
+  - [Group Management](#-group-management-implementiert)
+  - [Advanced Messaging](#-advanced-messaging-implementiert)
+  - [Contact Management](#-contact-management-implementiert)
+  - [Presence & Typing](#-presence--typing-implementiert)
+  - [Poll Messages](#-poll-messages-implementiert)
+  - [Status/Stories](#-statusstories-implementiert)
+  - [Broadcast Lists](#-broadcast-lists-implementiert)
+  - [Message Queue & Rate Limiting](#-message-queue--rate-limiting-implementiert)
+  - [Webhook Support](#-webhook-support-implementiert)
+  - [Auto-Reconnect](#-auto-reconnect-implementiert)
+  - [Events](#-events-implementiert)
+  - [Statistiken](#-statistiken-implementiert)
+- [Bot-Beispiel](#-bot-beispiel)
+- [Statistik-System](#-statistik-system)
+- [Architektur](#-architektur)
+- [Technologie](#-technologie)
+- [Performance](#-performance)
+- [Bekannte Einschränkungen](#-bekannte-einschränkungen--design-entscheidungen)
+- [Sicherheit](#-sicherheit)
+- [Lizenz](#-lizenz)
+
 ## ⚠️ Status
 
-**🚧 Work in Progress** - Die API ist funktional und stabil, aber noch nicht feature-complete. Aktive Entwicklung läuft.
+**🎉 Feature-Complete v2.0** - Die API ist stabil, vollständig und production-ready!
 
 ### ✅ Implementiert
-- Multi-Session Support
-- Session Control (Start, Stop, Restart, Pause, Resume)
-- Event System (Messages, Connected, Disconnected)
-- Statistik-System mit JSON-Persistenz
-- Message Parsing mit Mentions & Quoted Messages
-- Uptime & Performance Tracking
-- **Media Support** (Bilder, Videos, GIF-Playback)
-- **Sticker Support** (Bilder, GIFs, Videos → Sticker mit wa-sticker-formatter)
-- Media Download
-- **Group Management** (Erstellen, Bearbeiten, Teilnehmer verwalten)
-- **Advanced Messaging** (Audio, Document, Location, Contact, Reactions)
-- **Contact Management** (Kontakte abrufen, Profilbilder, Status)
-- **Presence & Typing** (Tipp-Indikatoren, Aufnahme-Status)
-
-### 🚧 In Entwicklung
-- Message Queue System
-- Rate Limiting
-- Webhook Support
-
-### 📋 Geplant
-- Status/Story Features
-- Broadcast Lists
-- Auto-Reconnect Optionen
+- ✅ Multi-Session Support
+- ✅ Session Control (Start, Stop, Restart, Pause, Resume)
+- ✅ Event System (Messages, Connected, Disconnected)
+- ✅ Statistik-System mit JSON-Persistenz
+- ✅ Message Parsing mit Mentions & Quoted Messages
+- ✅ Uptime & Performance Tracking
+- ✅ **Media Support** (Bilder, Videos, GIF-Playback)
+- ✅ **Sticker Support** (Bilder, GIFs, Videos → Sticker mit wa-sticker-formatter)
+- ✅ Media Download
+- ✅ **Group Management** (Erstellen, Bearbeiten, Teilnehmer verwalten)
+- ✅ **Advanced Messaging** (Audio, Document, Location, Contact, Reactions)
+- ✅ **Contact Management** (Kontakte abrufen, Profilbilder, Status)
+- ✅ **Presence & Typing** (Tipp-Indikatoren, Aufnahme-Status)
+- ✅ **Poll Messages** (Umfragen erstellen)
+- ✅ **Status/Stories** (Status hochladen)
+- ✅ **Broadcast Lists** (Massenversand)
+- ✅ **Message Queue & Rate Limiting** (Queue-System mit Prioritäten)
+- ✅ **Webhook Support** (Externe Integrationen)
+- ✅ **Auto-Reconnect** (Exponential Backoff, Max Retries)
+
+### 📋 Geplante Erweiterungen
+- Message Editing (wenn Baileys unterstützt)
+- Business API Features
+- Multi-Device Sync Improvements
 
 ## ✨ Features
 
@@ -124,6 +158,85 @@ onMessage((msg) => {
 });
 ```
 
+**Message Object Struktur:**
+
+Das `msg` Object in `onMessage()` enthält folgende Felder:
+
+```javascript
+{
+    // Basis-Informationen
+    sessionId: 'bot1',                           // Session ID
+    id: '3EB0XXXXX',                            // Nachrichten-ID
+    from: '4915123456789@s.whatsapp.net',       // Chat JID
+    fromMe: false,                               // Vom Bot gesendet?
+    name: 'Max Mustermann',                      // Absender-Name
+    message: 'Hallo, wie geht es?',             // Nachrichtentext
+    timestamp: 1703001234,                       // Unix Timestamp
+    
+    // Gruppen-Informationen
+    isGroup: false,                              // Ist Gruppenchat?
+    participant: '4915123456789@s.whatsapp.net', // Absender in Gruppe
+    
+    // Erweiterte Features
+    type: 'conversation',                        // Nachrichtentyp
+    mentions: ['4915987654321@s.whatsapp.net'],  // Erwähnte Kontakte (@mentions)
+    quoted: { /* quotedMessage Object */ },      // Zitierte Nachricht
+    
+    // Raw Baileys Message (für erweiterte Nutzung)
+    raw: { /* vollständiges Baileys message object */ }
+}
+```
+
+**Nachrichtentypen (`msg.type`):**
+- `conversation` - Einfache Textnachricht
+- `extendedTextMessage` - Text mit Links/Mentions
+- `imageMessage` - Bild
+- `videoMessage` - Video
+- `audioMessage` - Audio/Voice
+- `documentMessage` - Dokument
+- `stickerMessage` - Sticker
+- `locationMessage` - Standort
+- `contactMessage` - Kontakt
+- `pollCreationMessage` - Umfrage
+
+**Beispiele:**
+
+```javascript
+onMessage(async (msg) => {
+    // Text-Nachricht
+    if (msg.type === 'conversation' || msg.type === 'extendedTextMessage') {
+        console.log(`Text: ${msg.message}`);
+    }
+    
+    // Gruppennachricht
+    if (msg.isGroup) {
+        console.log(`Gruppe: ${msg.from}`);
+        console.log(`Von: ${msg.participant}`);
+    }
+    
+    // Erwähnungen (@mentions)
+    if (msg.mentions && msg.mentions.length > 0) {
+        console.log(`Erwähnt: ${msg.mentions.join(', ')}`);
+    }
+    
+    // Antwort auf Nachricht (quoted)
+    if (msg.quoted) {
+        console.log(`Antwortet auf: ${msg.quoted}`);
+    }
+    
+    // Media herunterladen
+    if (msg.type === 'imageMessage' || msg.type === 'videoMessage') {
+        const buffer = await downloadMedia(msg);
+        console.log(`Media heruntergeladen: ${buffer.length} bytes`);
+    }
+    
+    // Auf Nachricht antworten
+    if (msg.message === '!ping') {
+        await client.replyMessage(msg.sessionId, msg, 'Pong! 🏓');
+    }
+});
+```
+
 #### ✅ Media & Stickers (Implementiert)
 ```javascript
 import { 
@@ -262,18 +375,222 @@ console.log({
 countReceivedMessage('bot1');
 ```
 
-#### ❌ Noch nicht implementiert
+### ✅ Poll Messages (Implementiert)
+```javascript
+import { sendPoll } from '@deathnaitsa/wa-api';
+
+// Umfrage mit Einzelauswahl
+await sendPoll('bot1', 'nummer@s.whatsapp.net', 
+    'Was ist deine Lieblingsfarbe?', 
+    ['Rot', 'Blau', 'Grün', 'Gelb'],
+    1  // Nur 1 Option wählbar
+);
+
+// Umfrage mit Mehrfachauswahl
+await sendPoll('bot1', 'groupId@g.us', 
+    'Welche Programmiersprachen nutzt du?', 
+    ['JavaScript', 'Python', 'Java', 'C++', 'Go', 'Rust'],
+    3  // Bis zu 3 Optionen wählbar
+);
+```
+
+### ✅ Status/Stories (Implementiert)
+```javascript
+import { uploadStatus, getStatuses } from '@deathnaitsa/wa-api';
+
+// Text-Status hochladen
+await uploadStatus('bot1', { text: 'Hallo Welt! 👋' });
+
+// Bild-Status hochladen
+await uploadStatus('bot1', {
+    image: './status-image.jpg',
+    caption: 'Schöner Tag! ☀️'
+});
+
+// Video-Status hochladen
+await uploadStatus('bot1', {
+    video: './status-video.mp4',
+    caption: 'Check this out! 🎥'
+});
+
+// Status-Liste abrufen (wenn verfügbar)
+const statuses = await getStatuses('bot1');
+```
+
+### ✅ Broadcast Lists (Implementiert)
 ```javascript
-// Status/Stories
-// await client.sendStory(sessionId, content);
+import { sendBroadcast } from '@deathnaitsa/wa-api';
+
+// Broadcast an mehrere Empfänger
+const recipients = [
+    '4915123456789@s.whatsapp.net',
+    '4915987654321@s.whatsapp.net',
+    '4916612345678@s.whatsapp.net'
+];
 
-// Broadcast Lists
-// await client.createBroadcastList(sessionId, name, recipients);
-// await client.sendBroadcast(sessionId, broadcastListId, message);
+const results = await sendBroadcast('bot1', recipients, { 
+    text: '🎉 Wichtige Ankündigung für alle!' 
+});
+
+// Ergebnisse prüfen
+results.forEach(result => {
+    console.log(`${result.recipient}: ${result.success ? '✅' : '❌'}`);
+});
+
+// Broadcast mit Medien
+await sendBroadcast('bot1', recipients, {
+    image: './announcement.jpg',
+    caption: 'Neues Update verfügbar!'
+});
+```
+
+### ✅ Message Queue & Rate Limiting (Implementiert)
+```javascript
+import { 
+    queueMessage, 
+    setRateLimit, 
+    getQueueStatus,
+    clearQueue,
+    pauseQueue,
+    resumeQueue 
+} from '@deathnaitsa/wa-api';
+
+// Rate Limit setzen (30 Nachrichten pro Minute)
+setRateLimit('bot1', 30);
+
+// Nachricht mit Priorität zur Queue hinzufügen
+queueMessage('bot1', 'nummer@s.whatsapp.net', 
+    { text: 'Normale Nachricht' }, 
+    0  // Priorität: 0 = normal
+);
+
+queueMessage('bot1', 'nummer@s.whatsapp.net', 
+    { text: 'Wichtige Nachricht!' }, 
+    10  // Priorität: 10 = hoch (wird zuerst gesendet)
+);
+
+// Queue Status abrufen
+const status = getQueueStatus('bot1');
+console.log(`Queue: ${status.queueLength} Nachrichten`);
+console.log(`Rate Limit: ${status.rateLimit.count}/${status.rateLimit.limit}`);
+
+// Queue verwalten
+clearQueue('bot1');      // Queue leeren
+pauseQueue('bot1');      // Queue pausieren
+resumeQueue('bot1');     // Queue fortsetzen
+```
+
+**Vorteile:**
+- 🚫 Verhindert Spam-Erkennung
+- 📊 Automatisches Rate Limiting
+- 🎯 Prioritäts-basierte Zustellung
+- ⏸️ Pausieren/Fortsetzen möglich
+
+### ✅ Webhook Support (Implementiert)
+```javascript
+import { 
+    registerWebhook, 
+    unregisterWebhook, 
+    getWebhooks 
+} from '@deathnaitsa/wa-api';
+
+// Webhook registrieren
+const webhookId = registerWebhook(
+    'https://your-server.com/webhook',
+    ['message', 'connected', 'disconnected'],  // Events
+    'your-secret-key'  // Optional: für Signature Verification
+);
+
+console.log(`Webhook registriert: ${webhookId}`);
+
+// Webhook entfernen
+unregisterWebhook(webhookId);
+
+// Alle Webhooks anzeigen
+const webhooks = getWebhooks();
+console.log(webhooks);
+```
+
+**Webhook Payload:**
+```json
+{
+  "event": "message",
+  "data": {
+    "sessionId": "bot1",
+    "from": "4915123456789@s.whatsapp.net",
+    "message": "Hallo!",
+    "timestamp": 1703001234567
+  },
+  "timestamp": 1703001234567
+}
+```
+
+**Signature Verification:**
+```javascript
+const crypto = require('crypto');
+
+function verifyWebhook(payload, signature, secret) {
+    const hash = crypto.createHmac('sha256', secret)
+        .update(payload)
+        .digest('hex');
+    return hash === signature;
+}
+
+// Im Webhook-Handler:
+const signature = req.headers['x-webhook-signature'];
+const isValid = verifyWebhook(req.body, signature, 'your-secret-key');
+```
+
+### ✅ Auto-Reconnect (Implementiert)
+```javascript
+import { setAutoReconnect, getConnectionHealth } from '@deathnaitsa/wa-api';
+
+// Auto-Reconnect aktivieren
+setAutoReconnect(
+    'bot1',
+    true,   // enabled
+    5,      // maxRetries
+    2       // backoff multiplier
+);
+
+// Verhalten:
+// - 1. Versuch: nach 5 Sekunden
+// - 2. Versuch: nach 10 Sekunden (5 * 2^1)
+// - 3. Versuch: nach 20 Sekunden (5 * 2^2)
+// - 4. Versuch: nach 40 Sekunden (5 * 2^3)
+// - 5. Versuch: nach 80 Sekunden (5 * 2^4)
+
+// Connection Health prüfen
+const health = getConnectionHealth('bot1');
+console.log({
+    connected: health.connected,
+    status: health.status,
+    uptime: health.uptime,
+    autoReconnect: health.autoReconnect,
+    retryCount: health.retryCount,
+    maxRetries: health.maxRetries
+});
+
+// Events abhören
+client.on('reconnect:failed', ({ sessionId }) => {
+    console.log(`${sessionId} konnte nicht wiederverbunden werden`);
+});
+```
+
+**Vorteile:**
+- 📈 Exponential Backoff verhindert Server-Überlastung
+- 🔢 Konfigurierbare Max Retries
+- 🎯 Automatische Wiederverbindung bei Netzwerkfehlern
+- 📊 Connection Health Monitoring
+
+#### ❌ Noch nicht implementiert
+```javascript
+// Message Editing (wartet auf Baileys Support)
+// await client.editMessage(sessionId, messageKey, newText);
 
-// Advanced Features
-// await client.queueMessage(sessionId, to, message, priority);
-// await client.setRateLimit(sessionId, messagesPerMinute);
+// Business API Features
+// await client.getBusinessCategories();
+// await client.updateBusinessHours();
 ```
 
 ## 🚀 Neue Features in v2.0
@@ -456,17 +773,59 @@ await markChatRead('bot1', 'chatId@s.whatsapp.net', [messageKey1, messageKey2]);
 
 ## 🎮 Bot-Beispiel
 
-Siehe `socket.js` für ein vollständiges Bot-Beispiel mit:
-- Chat-Assignment System (keine Doppel-Antworten bei mehreren Sessions)
-- Command-Lock System (keine Race-Conditions)
-- Deutsche Befehle
-  - **Basis**: !ping, !info, !liste, !stats, !gesamtstats
-  - **Gruppen**: !gruppeninfo, !gruppenlink, !gruppenname, !gruppenbio, !hinzufügen, !entfernen, !promoten, !demoten
-  - **Nachrichten**: !ort, !reaktion, !tippen, !aufnehmen
-  - **Profil & Kontakt**: !profilbild, !status, !kontakt, !meinestatus
-  - **Session**: !neustart, !pause, !fortsetzen, !stopp, !löschen, !start, !zuweisen, !zuweisungen
-- Session-Control Commands
-- Latenz-Messung
+Siehe `socket.js` für ein vollständiges Bot-Beispiel mit **50+ Befehlen**:
+
+### Basis-Befehle
+- **!ping** / **!ping all** - Bot & alle Sessions testen
+- **!info** - Nachrichteninfo anzeigen
+- **!liste** - Alle Sessions auflisten
+- **!stats** - Detaillierte Session-Statistiken
+- **!gesamtstats** - Gesamtstatistik aller Sessions
+
+### Gruppen-Befehle
+- **!gruppeninfo** - Infos zur aktuellen Gruppe
+- **!gruppenlink** - Einladungslink der Gruppe
+- **!gruppenname** - Gruppennamen ändern
+- **!gruppenbio** - Gruppenbeschreibung ändern
+- **!hinzufügen** / **!entfernen** - Teilnehmer verwalten
+- **!promoten** / **!demoten** - Admin-Rechte verwalten
+
+### Nachrichten-Befehle
+- **!ort** - Standort senden
+- **!reaktion** - Auf Nachricht reagieren
+- **!tippen** / **!aufnehmen** - Indikatoren anzeigen
+- **!umfrage** - Umfrage erstellen
+- **!broadcast** - Broadcast senden
+
+### Status & Queue
+- **!status** - Status hochladen
+- **!queue** - Nachricht zur Queue hinzufügen
+- **!queuestatus** - Queue Status anzeigen
+- **!clearqueue** - Queue leeren
+- **!ratelimit** - Rate Limit setzen
+
+### Profil & Kontakt
+- **!profilbild** - Profilbild anzeigen
+- **!status** - Status abrufen
+- **!kontakt** - Kontaktinfo anzeigen
+- **!meinestatus** - Eigenen Status ändern
+
+### Verbindung
+- **!autoreconnect** - Auto-Reconnect aktivieren
+- **!health** - Verbindungs-Status prüfen
+
+### Session-Verwaltung
+- **!neustart** / **!pause** / **!fortsetzen** / **!stopp** - Session Control
+- **!löschen** - Session-Daten löschen
+- **!start** - Neue Session starten
+- **!zuweisen** - Chat einer Session zuweisen
+- **!zuweisungen** - Alle Zuweisungen anzeigen
+
+**Features:**
+- ✅ Chat-Assignment System (keine Doppel-Antworten)
+- ✅ Command-Lock System (keine Race-Conditions)
+- ✅ Latenz-Messung
+- ✅ Error-Handling
 
 ## 📊 Statistik-System
 
@@ -567,34 +926,40 @@ wa_credentials/             # Session-Daten
 
 ## 🛠️ Bekannte Einschränkungen & Design-Entscheidungen
 
-### Nicht implementiert (Stand: Dezember 2024)
-- ❌ Status/Story Features (Upload/View/Delete Stories)
-- ❌ Broadcast Lists
-- ❌ Auto-Reconnect (bewusst einfach gehalten)
-- ❌ Message Queue/Rate Limiting
-- ❌ Webhook Support
-- ❌ Poll Messages
-- ❌ Chat Archive/Mute/Pin Features
-
-### Neu implementiert in v2.0 ✅
-- ✅ Group Management (Complete)
-- ✅ Advanced Messaging (Audio, Document, Location, Contact, Reactions)
-- ✅ Contact Management (Profile Pictures, Status, Block/Unblock)
-- ✅ Presence & Typing Indicators
-- ✅ Profile Updates (Status, Name, Picture)
+### Was ist NICHT implementiert
+- ❌ Message Editing (wartet auf Baileys Support)
+- ❌ Business API erweiterte Features
+- ❌ Chat Archive/Mute/Pin über API (manuell möglich)
+
+### Vollständig implementiert in v2.0 ✅
+- ✅ Group Management (Complete - 12 Funktionen)
+- ✅ Advanced Messaging (Complete - 6 Funktionen)
+- ✅ Contact Management (Complete - 7 Funktionen)
+- ✅ Presence & Typing (Complete - 7 Funktionen)
+- ✅ Poll Messages (Complete)
+- ✅ Status/Stories (Complete)
+- ✅ Broadcast Lists (Complete)
+- ✅ Message Queue & Rate Limiting (Complete - 6 Funktionen)
+- ✅ Webhook Support (Complete - 3 Funktionen)
+- ✅ Enhanced Auto-Reconnect (Complete mit Exponential Backoff)
+
+**Total: 60+ Funktionen implementiert!**
 
 ### Design-Philosophie
-- **Einfachheit über Features** - Lieber stabil als feature-reich
-- **Kein Auto-Reconnect** - Manuelles Management für mehr Kontrolle
-- **Minimale Dependencies** - Nur Baileys, Pino, QRCode-Terminal, wa-sticker-formatter
+- **Feature-Complete über Minimalismus** - Alle wichtigen Features implementiert
+- **Production-Ready** - Robustes Error-Handling und Rate Limiting
+- **Dual Package Support** - CommonJS + ES Modules
 - **Event-Driven** - Keine Polling, nur Events
 - **Map-basiert** - Schnelle Session-Lookups
+- **Obfuskiert** - Source Code geschützt
 
 ### Performance-Charakteristiken
 - ✅ Sehr schnelle Session-Switches
-- ✅ Geringer Memory-Footprint (~50-80MB pro Session)
+- ✅ Geringer Memory-Footprint (~50-100MB pro Session)
 - ✅ Keine Blocking Operations
-- ⚠️ Kein Built-in Rate Limiting (muss selbst implementiert werden)
+- ✅ Built-in Rate Limiting
+- ✅ Queue System für Mass-Messaging
+- ✅ Auto-Reconnect mit Exponential Backoff
 
 ## 🔒 Sicherheit