@kangwifi-pro/waliwa 1.0.0

package/docs/FEATURES.md

@@ -0,0 +1,532 @@
+# New Features
+
+Waliwa menambahkan fitur-fitur baru yang tidak ada di Baileys atau ZapoJS. Semua fitur terintegrasi dengan WASocket dan dapat diakses dengan mudah.
+
+## Daftar Fitur
+
+1. [Health Monitor](#1-health-monitor)
+2. [Multi-account Manager](#2-multi-account-manager)
+3. [Webhook System](#3-webhook-system)
+4. [Circuit Breaker](#4-circuit-breaker)
+5. [Rate Limit Tracker](#5-rate-limit-tracker)
+6. [Message Persistence](#6-message-persistence)
+
+---
+
+## 1. Health Monitor
+
+Real-time health tracking dengan auto-recovery. Memberikan score 0-100 berdasarkan multiple metrics.
+
+```typescript
+const sock = makeWASocket({ authState: state });
+
+// Get current health
+const health = sock.getHealth();
+console.log(health);
+// {
+//   status: 'healthy',  // 'healthy' | 'degraded' | 'unhealthy'
+//   score: 95,           // 0-100
+//   connection: {
+//     connected: true,
+//     uptime: 3600000,        // ms
+//     lastPingTime: 1234567890,
+//     reconnectCount: 2
+//   },
+//   metrics: {
+//     messagesSent: 145,
+//     messagesReceived: 89,
+//     sendFailures: 3,
+//     avgLatencyMs: 245
+//   },
+//   resources: {
+//     memoryUsageMb: 75.5,
+//     pendingSends: 0,
+//     queueSize: 0
+//   },
+//   issues: [],  // List of issues jika ada
+//   timestamp: 1234567890
+// }
+```
+
+### Health Events
+
+```typescript
+import { HealthMonitor } from 'waliwa';
+
+sock.healthMonitor.on('health:check', (status) => {
+  console.log(`Health: ${status.status} (${status.score}/100)`);
+  if (status.issues.length > 0) {
+    console.warn('Issues:', status.issues);
+  }
+});
+
+sock.healthMonitor.on('health:recovery', (status) => {
+  console.warn('Health degraded, triggering recovery');
+  // Custom recovery: reconnect, restart services, dll
+});
+```
+
+### Custom Recovery Actions
+
+```typescript
+sock.healthMonitor.on('health:recovery', async (status) => {
+  console.warn(`Health score: ${status.score}, issues: ${status.issues}`);
+
+  // Different recovery strategies based on issues
+  if (status.issues.includes('Connection appears down')) {
+    await sock.end();
+    await sock.connect();
+  }
+
+  if (status.issues.includes('High memory usage')) {
+    // Force garbage collection
+    if (global.gc) global.gc();
+  }
+
+  if (status.issues.includes('High send failure rate')) {
+    // Investigate failed messages
+    const failed = sock.messagePersistence.getFailed();
+    console.log(`${failed.length} failed messages`);
+  }
+});
+```
+
+---
+
+## 2. Multi-account Manager
+
+Manage multiple WhatsApp accounts dari satu process. Berguna untuk customer service bots, multiple business accounts, dll.
+
+```typescript
+import { MultiAccountManager } from 'waliwa';
+
+const manager = new MultiAccountManager({
+  maxAccounts: 10,
+  logger: defaultLogger
+});
+
+// Register accounts
+manager.registerAccount({
+  id: 'sales',
+  name: 'Sales Bot',
+  authFolder: './auth-sales',
+  enabled: true,
+  config: {
+    printQRInTerminal: false,
+    ramOptimizationLevel: 3 // Ultra untuk multi-account
+  }
+});
+
+manager.registerAccount({
+  id: 'support',
+  name: 'Support Bot',
+  authFolder: './auth-support',
+  enabled: true,
+  config: {
+    printQRInTerminal: false
+  }
+});
+
+// Connect accounts
+await manager.connectAccount('sales');
+await manager.connectAccount('support');
+
+// Send message from specific account
+await manager.sendMessageFrom('sales', '6281@s.whatsapp.net', {
+  text: 'Hello from Sales!'
+});
+
+await manager.sendMessageFrom('support', '6282@s.whatsapp.net', {
+  text: 'Hello from Support!'
+});
+
+// Broadcast to all accounts
+await manager.broadcast('6281@s.whatsapp.net', {
+  text: 'Broadcast from all accounts'
+});
+
+// List all accounts status
+console.log(manager.listAccounts());
+// [
+//   { id: 'sales', name: 'Sales Bot', connected: true, messagesSent: 5, ... },
+//   { id: 'support', name: 'Support Bot', connected: true, messagesSent: 3, ... }
+// ]
+```
+
+### Per-account Events
+
+```typescript
+manager.on('account:connected', (accountId) => {
+  console.log(`Account ${accountId} connected`);
+});
+
+manager.on('account:disconnected', (accountId) => {
+  console.log(`Account ${accountId} disconnected`);
+});
+
+manager.on('account:message', (accountId, messages) => {
+  console.log(`Account ${accountId} received ${messages.length} messages`);
+  // Route to different handlers based on accountId
+  if (accountId === 'sales') {
+    handleSalesMessage(messages);
+  } else if (accountId === 'support') {
+    handleSupportMessage(messages);
+  }
+});
+```
+
+---
+
+## 3. Webhook System
+
+Reliable webhook delivery dengan HMAC-SHA256 signature + retry + dead letter queue.
+
+### Register Webhook
+
+```typescript
+sock.registerWebhook({
+  url: 'https://yourapp.com/webhook',
+  events: ['message.sent', 'message.failed', 'auth.success'],
+  secret: 'your-webhook-secret', // HMAC signing
+  enabled: true,
+  retryCount: 5,
+  retryDelayMs: 1000,
+  timeoutMs: 10000
+});
+
+// Register untuk all events
+sock.registerWebhook({
+  url: 'https://yourapp.com/all-events',
+  events: ['*'],
+  enabled: true
+});
+```
+
+### Verify Webhook Signature (di receiver)
+
+```javascript
+// Express middleware untuk verify HMAC signature
+const crypto = require('crypto');
+
+app.post('/webhook', (req, res) => {
+  const signature = req.headers['x-waliwa-signature'];
+  const event = req.headers['x-waliwa-event'];
+
+  // Verify signature
+  const expected = 'sha256=' + crypto
+    .createHmac('sha256', 'your-webhook-secret')
+    .update(JSON.stringify(req.body))
+    .digest('hex');
+
+  if (signature !== expected) {
+    return res.status(401).send('Invalid signature');
+  }
+
+  // Process event
+  console.log(`Received event: ${event}`);
+  console.log('Payload:', req.body);
+
+  res.json({ received: true });
+});
+```
+
+### Webhook Stats & Dead Letter Queue
+
+```typescript
+const stats = sock.webhookManager.getStats();
+console.log(stats);
+// {
+//   sent: 145,
+//   failed: 3,
+//   retried: 8,
+//   pending: 0,
+//   deadLettered: 2
+// }
+
+// Get dead letter queue
+const dlq = sock.webhookManager.getDeadLetterQueue();
+console.log(`${dlq.length} permanently failed webhooks`);
+
+// Retry dari DLQ
+sock.webhookManager.retryDeadLetter(); // Retry all
+// atau specific:
+sock.webhookManager.retryDeadLetter('wh-1234567890-abc');
+```
+
+---
+
+## 4. Circuit Breaker
+
+Prevent retry storms untuk failed recipients. Saat recipient terus gagal (e.g., user block bot, invalid number), circuit breaker akan "open" dan stop sending sementara.
+
+```typescript
+// Otomatis aktif di WASocket.sendMessage()
+// Check sebelum send:
+if (!sock.circuitBreaker.canSend(jid)) {
+  console.log(`Circuit open for ${jid}, skipping send`);
+  return;
+}
+
+// Stats
+console.log(sock.circuitBreaker.getOpenCircuits());
+// [
+//   { jid: '6281@s.whatsapp.net', failureCount: 5, lastFailureTime: 1234567890 },
+//   { jid: '6282@s.whatsapp.net', failureCount: 3, lastFailureTime: 1234567891 }
+// ]
+
+// Manually reset circuit
+sock.resetCircuitBreaker('6281@s.whatsapp.net');
+
+// Get state untuk specific recipient
+const state = sock.circuitBreaker.getState('6281@s.whatsapp.net');
+// 'closed' (normal) | 'open' (blocked) | 'half-open' (testing)
+```
+
+### States
+
+| State | Behavior |
+|-------|----------|
+| `closed` | Normal operation, sends allowed |
+| `open` | Blocked, no sends (after 5 failures) |
+| `half-open` | Allow 1 test send (after cooldown 60s) |
+
+### Configuration
+
+```typescript
+import { CircuitBreaker } from 'waliwa';
+
+// Custom instance
+const breaker = new CircuitBreaker({
+  failureThreshold: 5,    // Open after 5 failures
+  cooldownMs: 60000      // 1 minute cooldown
+});
+```
+
+---
+
+## 5. Rate Limit Tracker
+
+Per-recipient rate limiting untuk comply dengan WhatsApp server limits.
+
+```typescript
+// Default limits (WhatsApp server):
+// - 5 messages/sec per recipient
+// - 60 messages/min per recipient
+// - 1000 messages/hour per recipient
+
+// Otomatis di WASocket.sendMessage()
+// Throw error jika exceeded:
+try {
+  await sock.sendMessage(jid, { text: 'Hi' });
+} catch (err) {
+  if (err.message.includes('Rate limit exceeded')) {
+    console.log('Rate limited, waiting...');
+    await sleep(60000); // Wait 1 min
+    await sock.sendMessage(jid, { text: 'Hi' });
+  }
+}
+
+// Check remaining quota
+const quota = sock.rateLimitTracker.getRemainingQuota('6281@s.whatsapp.net');
+console.log(quota);
+// { second: 4, minute: 45, hour: 950 }
+
+// Manual reset (e.g., after user interaction)
+sock.rateLimitTracker.reset('6281@s.whatsapp.net');
+```
+
+### Custom Limits
+
+```typescript
+import { RateLimitTracker } from 'waliwa';
+
+const tracker = new RateLimitTracker({
+  perSecond: 3,   // Custom: 3/sec
+  perMinute: 30,  // Custom: 30/min
+  perHour: 500    // Custom: 500/hour
+});
+```
+
+---
+
+## 6. Message Persistence
+
+Persist outgoing messages untuk survive restarts. Pending messages akan di-retry setelah bot restart.
+
+```typescript
+// Otomatis aktif di WASocket.sendMessage()
+// Setiap message disimpan dengan status 'pending'
+// Setelah send berhasil: status='sent'
+// Setelah send gagal: status='failed'
+
+// Get pending messages (untuk manual retry)
+const pending = sock.messagePersistence.getPending();
+console.log(`${pending.length} pending messages`);
+
+// Get failed messages
+const failed = sock.messagePersistence.getFailed();
+console.log(`${failed.length} failed messages`);
+
+// Retry all failed messages
+await sock.retryFailedMessages();
+
+// Manual update
+sock.messagePersistence.update('msg-123', {
+  status: 'sent',
+  attempts: 2
+});
+
+// Delete old message
+sock.messagePersistence.delete('msg-123');
+
+// Cleanup old messages (older than 24 hours)
+const cleaned = sock.messagePersistence.cleanup(24 * 60 * 60 * 1000);
+console.log(`Cleaned ${cleaned} old messages`);
+```
+
+### Auto-recovery on Restart
+
+Saat bot restart, pending messages otomatis di-retry:
+
+```typescript
+const sock = makeWASocket({ authState: state });
+
+sock.ev.on('connection.update', async ({ connection }) => {
+  if (connection === 'open') {
+    // Otomatis: pending messages dari session sebelumnya di-retry
+    console.log('Bot reconnected, retrying pending messages...');
+  }
+});
+```
+
+---
+
+## Integration Examples
+
+### Complete Production Setup
+
+```typescript
+import { makeWASocket, useFileAuthState } from 'waliwa';
+
+async function main() {
+  const state = await useFileAuthState('./auth');
+
+  const sock = makeWASocket({
+    authState: state,
+    printQRInTerminal: true,
+    ramOptimizationLevel: 2,
+
+    // SKDM config
+    minPreKeys: 5,
+    targetPreKeyCount: 100,
+    maxSessionCacheSize: 500
+  });
+
+  // Register webhook untuk external system
+  sock.registerWebhook({
+    url: 'https://api.yourapp.com/whatsapp/events',
+    events: ['message.sent', 'message.failed', 'auth.success', 'auth.failure'],
+    secret: process.env.WEBHOOK_SECRET,
+    enabled: true,
+    retryCount: 5,
+    retryDelayMs: 1000,
+    timeoutMs: 10000
+  });
+
+  // Health monitoring
+  sock.healthMonitor.on('health:check', (status) => {
+    if (status.status === 'degraded' || status.status === 'unhealthy') {
+      console.warn(`Health degraded: ${status.score}/100`, status.issues);
+      // Send alert to admin
+    }
+  });
+
+  sock.healthMonitor.on('health:recovery', async (status) => {
+    console.warn('Triggering recovery actions');
+    // Custom recovery: restart, notify admin, dll
+  });
+
+  // Message handling
+  sock.ev.on('message.upsert', async ({ messages, type }) => {
+    if (type !== 'notify') return;
+
+    for (const msg of messages) {
+      if (msg.key.fromMe) continue;
+
+      try {
+        // sendMessage sudah otomatis:
+        // - Check circuit breaker
+        // - Check rate limit
+        // - Persist message
+        // - Queue per recipient
+        // - Trigger webhook
+        await sock.sendMessage(msg.key.remoteJid, {
+          text: 'Hello!',
+          quoted: msg
+        });
+      } catch (err) {
+        if (err.message.includes('Circuit breaker')) {
+          console.log(`Skipping send to ${msg.key.remoteJid} (circuit open)`);
+        } else if (err.message.includes('Rate limit')) {
+          console.log(`Rate limited for ${msg.key.remoteJid}`);
+        } else {
+          console.error('Send failed:', err.message);
+        }
+      }
+    }
+  });
+
+  // Periodic stats logging
+  setInterval(() => {
+    const stats = sock.getSystemStats();
+    console.log('System stats:', JSON.stringify(stats, null, 2));
+  }, 60000);
+
+  // Graceful shutdown
+  process.on('SIGINT', async () => {
+    console.log('Shutting down...');
+    await sock.end();
+    process.exit(0);
+  });
+}
+
+main();
+```
+
+### Monitoring Dashboard
+
+```typescript
+// Endpoint untuk monitoring (e.g., di REST gateway)
+app.get('/health', (req, res) => {
+  res.json(sock.getHealth());
+});
+
+app.get('/stats', (req, res) => {
+  res.json({
+    system: sock.getSystemStats(),
+    skdm: sock.getSKDMStats(),
+    health: sock.getHealth()
+  });
+});
+
+app.get('/stats/circuits', (req, res) => {
+  res.json({
+    open: sock.circuitBreaker.getOpenCircuits(),
+    webhooks: sock.webhookManager.getStats(),
+    messages: {
+      pending: sock.messagePersistence.getPending().length,
+      failed: sock.messagePersistence.getFailed().length
+    }
+  });
+});
+
+app.post('/circuits/:jid/reset', (req, res) => {
+  sock.resetCircuitBreaker(req.params.jid);
+  res.json({ success: true });
+});
+
+app.post('/messages/retry-failed', async (req, res) => {
+  await sock.retryFailedMessages();
+  res.json({ success: true });
+});
+```