@kangwifi-pro/waliwa 1.0.0

package/docs/RECOVERY.md

@@ -0,0 +1,409 @@
+# Multi-Branch SKDM Recovery System
+
+Unlike basic reconnect yang hanya mencoba satu jalur, Waliwa mengimplementasikan sistem pemulihan Multi-Branch Session Key & Device Management (SKDM) yang lengkap. Saat pemutusan koneksi (disconnect) terjadi, sistem akan mencoba berbagai strategi pemulihan secara berurutan.
+
+## Tabel Cabang Pemulihan
+
+| Disconnect Reason | Recovery Branches (in order) | Fatal? |
+|-------------------|------------------------------|--------|
+| **Connection lost** (1006/1001) | Immediate retry → Stream reconnect → Backoff → Key refresh → Pre-key fetch → Full re-auth | ❌ |
+| **Rate limited** (429) | Wait cooldown (5min) → Backoff retry | ❌ |
+| **Restart required** (428) | Update app version → Key refresh → Full re-auth QR | ❌ |
+| **Logged out** (401/403) | Key refresh → No recovery | ✅ Fatal |
+| **Forbidden** (511) | Immediate retry → Key refresh → No recovery | ❌ |
+| **Multi-device mismatch** (409) | Key refresh → Full re-auth QR → No recovery | ❌ |
+| **Bad session** | Key refresh → Pre-key fetch → Full re-auth QR | ❌ |
+| **Connection replaced** (440) | Key refresh → Full re-auth QR | ❌ |
+| **Unknown** | Backoff retry → Key refresh → Full re-auth QR | ❌ |
+
+Setiap cabang memiliki batas percobaan (retry limit) tersendiri (default 3). Total percobaan di semua cabang dibatasi (default 20).
+
+## Konfigurasi
+
+```typescript
+import { makeWASocket, useFileAuthState } from 'waliwa';
+
+const { state } = await useFileAuthState('./auth');
+
+const sock = makeWASocket({
+  authState: state,
+  printQRInTerminal: true,
+
+  // Multi-Branch SKDM Recovery configuration
+  recovery: {
+    enabled: true,                    // Enable recovery system (default: true)
+    maxAttemptsPerBranch: 3,          // Max attempts per branch (default: 3)
+    maxTotalAttempts: 20,             // Total max attempts across all branches (default: 20)
+    initialDelayMs: 1000,            // Initial delay for backoff (default: 1000ms)
+    maxDelayMs: 60000,               // Max delay for backoff (default: 60000ms)
+    rateLimitedDelayMs: 300000        // Cooldown for rate limited (default: 5min)
+  }
+});
+```
+
+## Pemulihan Per Disconnect Reason
+
+### 1. Connection Lost (codes 1006, 1001, 0, undefined)
+
+Branch paling lengkap - 6 strategi pemulihan berurutan.
+
+**Flow:**
+```
+Connection lost detected
+        ↓
+1. Immediate retry (0ms delay)
+   ↓ fail
+2. Stream reconnect (500ms delay) - resume stream state
+   ↓ fail
+3. Backoff retry (1s, 2s, 4s exponential)
+   ↓ fail x 3
+4. Key refresh (SKDM regenerate pre-keys)
+   ↓ fail
+5. Pre-key fetch (force new pre-keys from server)
+   ↓ fail
+6. Full re-auth QR (clear creds, new QR scan)
+```
+
+### 2. Rate Limited (code 429)
+
+Wait untuk cooldown lalu coba lagi.
+
+**Flow:**
+```
+Rate limited detected (429)
+        ↓
+1. Wait cooldown 5 minutes
+   ↓
+2. Backoff retry
+```
+
+### 3. Restart Required (code 428)
+
+Server butuh update version. Update browser identification.
+
+**Flow:**
+```
+Restart required (428)
+        ↓
+1. Update app version (bump browser version)
+   ↓
+2. Key refresh
+   ↓
+3. Full re-auth QR
+```
+
+### 4. Logged Out (codes 401, 403) - FATAL
+
+Tidak ada pemulihan yang possible. Clear creds dan emit fatal event.
+
+**Flow:**
+```
+Logged out (401/403)
+        ↓
+1. Key refresh (last attempt)
+   ↓
+❌ No recovery - emit 'recovery:failed' dengan fatal=true
+```
+
+### 5. Forbidden (code 511)
+
+Coba sekali lagi, lalu refresh keys.
+
+**Flow:**
+```
+Forbidden (511)
+        ↓
+1. Immediate retry
+   ↓ fail
+2. Key refresh
+   ↓ fail
+❌ No recovery
+```
+
+### 6. Multi-device Mismatch (code 409)
+
+Multi-device state tidak sinkron dengan server.
+
+**Flow:**
+```
+Multi-device mismatch (409)
+        ↓
+1. Key refresh
+   ↓ fail
+2. Full re-auth QR
+   ↓ fail
+❌ No recovery
+```
+
+### 7. Bad Session (generic)
+
+Session tidak valid, butuh refresh dan re-fetch pre-keys.
+
+**Flow:**
+```
+Bad session detected
+        ↓
+1. Key refresh
+   ↓ fail
+2. Pre-key fetch
+   ↓ fail
+3. Full re-auth QR
+```
+
+### 8. Connection Replaced (code 440)
+
+Koneksi diganti dengan device lain. Coba re-auth.
+
+**Flow:**
+```
+Connection replaced (440)
+        ↓
+1. Key refresh
+   ↓ fail
+2. Full re-auth QR
+```
+
+## Aksi Pemulihan (Recovery Actions)
+
+| Action | Deskripsi | Default Delay |
+|--------|-----------|---------------|
+| `immediate_retry` | Coba reconnect langsung tanpa delay | 0ms |
+| `stream_reconnect` | Resume koneksi dari stream state yang tersimpan | 500ms |
+| `backoff_retry` | Reconnect dengan exponential backoff | 1s, 2s, 4s... |
+| `wait_cooldown` | Tunggu cooldown 5 menit (untuk rate limit) | 300000ms |
+| `update_app_version` | Update identifikasi browser/app version | 1s |
+| `key_refresh` | Refresh Signal keys via SKDM | 1s |
+| `prekey_fetch` | Fetch pre-keys baru dari server | 1s |
+| `full_reauth_qr` | Full re-authentication dengan QR code baru | 1s |
+| `no_recovery` | Tidak ada pemulihan yang possible (fatal) | - |
+
+## Event
+
+RecoveryManager mengeluarkan beberapa event untuk monitoring:
+
+```typescript
+sock.recoveryManager.on('recovery:start', (info) => {
+  console.log(`Recovery started: ${info.reason} (code: ${info.code})`);
+});
+
+sock.recoveryManager.on('recovery:branch:start', (info) => {
+  console.log(`Branch started: ${info.reason}`);
+  console.log(`Actions: ${info.actions.join(' → ')}`);
+});
+
+sock.recoveryManager.on('recovery:action:start', (info) => {
+  console.log(`Action: ${info.action} (attempt ${info.attempt})`);
+});
+
+sock.recoveryManager.on('recovery:action:success', (info) => {
+  console.log(`✓ ${info.action} succeeded in ${info.duration}ms`);
+});
+
+sock.recoveryManager.on('recovery:action:failed', (info) => {
+  console.log(`✗ ${info.action} failed: ${info.error}`);
+});
+
+sock.recoveryManager.on('recovery:success', (info) => {
+  console.log(`✓ Recovery succeeded after ${info.totalAttempts} attempts in ${info.duration}ms`);
+});
+
+sock.recoveryManager.on('recovery:failed', (info) => {
+  console.log(`✗ Recovery failed (fatal: ${info.fatal})`);
+  if (info.fatal) {
+    console.log('Manual intervention required (re-scan QR)');
+  }
+});
+
+sock.recoveryManager.on('recovery:progress', (info) => {
+  console.log(`Progress: ${info.progress.toFixed(1)}% (${info.totalAttempts}/${info.maxTotalAttempts})`);
+});
+```
+
+## API
+
+### Get Recovery Stats
+
+```typescript
+const stats = sock.getRecoveryStats();
+console.log(stats);
+// {
+//   totalRecoveries: 5,
+//   successfulRecoveries: 4,
+//   failedRecoveries: 1,
+//   successRate: 0.8,
+//   byReason: {
+//     connection_lost: { success: 3, failure: 0 },
+//     rate_limited: { success: 1, failure: 0 },
+//     logged_out: { success: 0, failure: 1 }
+//   }
+// }
+```
+
+### Check Recovery Status
+
+```typescript
+if (sock.isRecovering()) {
+  const ctx = sock.getCurrentRecovery();
+  console.log(`Recovering from: ${ctx.reason}`);
+  console.log(`Current action: ${ctx.history[ctx.history.length - 1]?.action}`);
+  console.log(`Progress: ${ctx.totalAttempts}/${20} total attempts`);
+}
+```
+
+### Manual Trigger (untuk testing)
+
+```typescript
+import { mapCodeToReason } from 'waliwa';
+
+// Simulate disconnect
+const reason = mapCodeToReason(429);
+const success = await sock.triggerRecovery(reason, 429, 'rate limit exceeded');
+console.log(`Recovery ${success ? 'succeeded' : 'failed'}`);
+```
+
+### Cancel Ongoing Recovery
+
+```typescript
+// Cancel recovery manually
+sock.recoveryManager.cancel();
+```
+
+## Custom Branches
+
+Anda dapat mengganti (override) cabang default dengan yang custom:
+
+```typescript
+import { makeWASocket, RecoveryManager, type RecoveryBranch } from 'waliwa';
+
+const customBranches: RecoveryBranch[] = [
+  {
+    reason: 'connection_lost',
+    actions: ['immediate_retry', 'backoff_retry'], // Simplified
+    maxAttempts: 5
+  },
+  {
+    reason: 'rate_limited',
+    actions: ['wait_cooldown', 'immediate_retry'],
+    maxAttempts: 2
+  }
+  // ... (other branches pakai default)
+];
+
+// Pass via config (atau instantiate manual)
+const recoveryManager = new RecoveryManager({
+  branches: customBranches,
+  maxAttemptsPerBranch: 5,
+  maxTotalAttempts: 30
+});
+```
+
+## Custom Action Handlers
+
+Override handler default untuk action tertentu:
+
+```typescript
+import { makeWASocket, type RecoveryAction } from 'waliwa';
+
+const sock = makeWASocket({
+  authState: state,
+  recovery: {
+    enabled: true,
+    actionHandlers: {
+      // Custom handler untuk key_refresh
+      key_refresh: async (ctx) => {
+        console.log(`Custom key refresh (attempt ${ctx.attempt})`);
+        // Custom logic: backup old keys sebelum refresh
+        await backupKeys();
+        // Lalu refresh
+        await sock.getSKDM()?.preKeyManager.regeneratePreKeys();
+        // Try reconnect
+        return await sock.recoveryManager.connect();
+      },
+
+      // Custom handler untuk full_reauth_qr
+      full_reauth_qr: async (ctx) => {
+        console.log('Custom full re-auth');
+        // Send notification ke admin
+        await notifyAdmin('Bot needs re-authentication!');
+        // Lalu start re-auth
+        await sock.recoveryManager.startFullReauth();
+        return true;
+      }
+    }
+  }
+});
+```
+
+## Production Setup Example
+
+```typescript
+import { makeWASocket, useFileAuthState } from 'waliwa';
+
+async function main() {
+  const { state } = await useFileAuthState('./auth');
+
+  const sock = makeWASocket({
+    authState: state,
+    printQRInTerminal: true,
+    ramOptimizationLevel: 2,
+
+    // Multi-branch recovery
+    recovery: {
+      enabled: true,
+      maxAttemptsPerBranch: 3,
+      maxTotalAttempts: 20,
+      initialDelayMs: 1000,
+      maxDelayMs: 60000,
+      rateLimitedDelayMs: 300000 // 5 minutes
+    }
+  });
+
+  // Monitor recovery events
+  sock.recoveryManager.on('recovery:start', ({ reason, code }) => {
+    console.warn(`⚠️  Recovery started: ${reason} (code ${code})`);
+  });
+
+  sock.recoveryManager.on('recovery:success', ({ reason, totalAttempts, duration }) => {
+    console.log(`✅ Recovery succeeded: ${reason} in ${duration}ms (${totalAttempts} attempts)`);
+  });
+
+  sock.recoveryManager.on('recovery:failed', ({ reason, fatal }) => {
+    console.error(`❌ Recovery failed: ${reason} (fatal: ${fatal})`);
+    if (fatal) {
+      // Send alert ke admin - manual QR scan required
+      notifyAdmin(`Bot logged out! Reason: ${reason}. Manual re-auth required.`);
+    }
+  });
+
+  // Periodic stats logging
+  setInterval(() => {
+    const stats = sock.getRecoveryStats();
+    console.log('Recovery stats:', stats);
+  }, 60000);
+
+  // Graceful shutdown
+  process.on('SIGINT', async () => {
+    console.log('Shutting down...');
+    // Cancel ongoing recovery
+    sock.recoveryManager.cancel();
+    await sock.end();
+    process.exit(0);
+  });
+}
+
+main();
+```
+
+## Perbandingan dengan Baileys
+
+| Aspek | Baileys | Waliwa |
+|-------|---------|--------|
+| Reconnect strategy | Single path (exponential backoff) | Multi-branch berdasarkan disconnect reason |
+| Rate limit handling | Sama dengan disconnect biasa | Cooldown khusus 5 menit |
+| Logged out | Coba reconnect sama | Fatal - clear creds, minta QR ulang |
+| Connection replaced | Tetap coba reconnect | Key refresh + re-auth QR |
+| Multi-device mismatch | Tidak ada handling khusus | Key refresh + re-auth QR |
+| Max retry limit | Single global limit | Per-branch + total cap |
+| Custom handlers | Tidak ada | Setiap action bisa di-override |
+| Recovery events | Tidak ada | 7 event types untuk monitoring |
+| Recovery stats | Tidak ada | Per-reason success/failure tracking |

package/docs/SKDM.md

@@ -0,0 +1,233 @@
+# SKDM (Store Key Data Manager)
+
+SKDM adalah subsystem cerdas untuk manage Signal protocol keys. Dibuat untuk mengatasi issue-issue Baileys yang sering dikeluhkan terkait key management.
+
+## Masalah Baileys yang Diatasi SKDM
+
+| Baileys Issue | SKDM Solution |
+|---------------|---------------|
+| Pre-key exhaustion (pre-keys habis tanpa warning) | PreKeyManager dengan auto-regeneration |
+| Session corruption on disconnect | AtomicFileWriter (write ke .tmp lalu rename) |
+| Decryption failure untuk old messages | SessionManager.prefetchSessions() |
+| Memory leak dari sessions lama | LRUCache dengan TTL eviction |
+| App state keys bertumpuk tanpa cleanup | AppStateKeyManager.cleanup() |
+| Identity changes gak tracked | IdentityKeyManager dengan change detection |
+
+## Quick Start
+
+```typescript
+import { makeWASocket, useFileAuthState, SKDM } from 'waliwa';
+
+const state = await useFileAuthState('./auth');
+
+// SKDM otomatis initialized di dalam WASocket
+const sock = makeWASocket({
+  authState: state,
+  printQRInTerminal: true
+});
+
+// Akses SKDM instance
+const skdm = sock.getSKDM();
+
+// Get stats
+console.log(skdm?.getStats());
+// Output:
+// {
+//   preKeys: { total: 95, nextId: 105, lastRegenTime: 1234567890, needsRegen: false },
+//   sessions: { size: 12, hits: 45, misses: 3, hitRate: 0.937, totalSessions: 50, expiredSessions: 0 },
+//   identities: { total: 50, changed: 0 },
+//   appStateKeys: 15,
+//   pendingSaves: 0
+// }
+```
+
+## Komponen SKDM
+
+### 1. PreKeyManager
+
+Auto-regenerate pre-keys saat hampir habis. Mencegah Baileys issue di mana bot tiba-tiba tidak bisa menerima pesan baru karena pre-keys habis.
+
+```typescript
+const skdm = sock.getSKDM();
+
+// Manual trigger
+await skdm.preKeyManager.regeneratePreKeys();
+
+// Check stats
+const stats = skdm.preKeyManager.getStats();
+console.log(`Pre-keys: ${stats.total}/${stats.target}`);
+console.log(`Needs regeneration: ${stats.needsRegen}`);
+
+// Consume pre-key (otomatis saat receive message)
+skdm.preKeyManager.consumePreKey(42);
+// Auto-triggers regeneration if low
+```
+
+**Konfigurasi:**
+
+```typescript
+makeWASocket({
+  authState: state,
+  // SKDM config
+  minPreKeys: 5,           // Regenerate jika < 5 pre-keys
+  maxPreKeysBatch: 50,    // Max 50 pre-keys per regeneration
+  targetPreKeyCount: 100, // Maintain 100 pre-keys total
+  enableKeyRotation: true // Background rotation tiap 1 jam
+});
+```
+
+### 2. SessionManager
+
+LRU cache untuk sessions - mencegah memory leak.
+
+```typescript
+const skdm = sock.getSKDM();
+
+// Get session (auto-cache)
+const session = skdm.sessionManager.getSession('6281@s.whatsapp.net');
+
+// Prefetch sessions untuk multiple users
+// Berguna sebelum bulk decrypt group messages
+skdm.sessionManager.prefetchSessions([
+  'user1@s.whatsapp.net',
+  'user2@s.whatsapp.net',
+  'user3@s.whatsapp.net'
+]);
+
+// Cleanup expired sessions (otomatis tiap 6 jam)
+const cleaned = skdm.sessionManager.cleanupExpiredSessions();
+console.log(`Cleaned ${cleaned} sessions`);
+
+// Get cache stats
+const stats = skdm.sessionManager.getStats();
+console.log(`Cache hit rate: ${(stats.hitRate * 100).toFixed(1)}%`);
+```
+
+### 3. IdentityKeyManager
+
+Track identity changes untuk security.
+
+```typescript
+const skdm = sock.getSKDM();
+
+// Check identity changes (security alerts)
+const changed = skdm.identityManager.getChangedIdentities();
+if (changed.length > 0) {
+  console.warn('Identity changed untuk users:', changed);
+  // Verify dengan user, lalu acknowledge
+  for (const jid of changed) {
+    // After manual verification:
+    skdm.identityManager.acknowledge(jid);
+  }
+}
+
+// Trust identity (override safety)
+skdm.identityManager.trust('6281@s.whatsapp.net');
+```
+
+### 4. AppStateKeyManager
+
+Manage app state sync keys dengan cleanup otomatis.
+
+```typescript
+const skdm = sock.getSKDM();
+
+// Cleanup old app state keys (keep last 50)
+const cleaned = skdm.appStateManager.cleanup(50);
+console.log(`Cleaned ${cleaned} old app state keys`);
+```
+
+### 5. AtomicFileWriter
+
+Atomic writes untuk prevent corruption saat disconnect/power failure.
+
+```typescript
+import { AtomicFileWriter } from 'waliwa';
+
+// Safe write - akan write ke .tmp lalu rename (atomic di POSIX)
+await AtomicFileWriter.writeFile(
+  './auth/session.json',
+  JSON.stringify(sessionData),
+  'utf-8'
+);
+
+// Even jika process crash saat write:
+// - .tmp file mungkin tertinggal (safe to delete)
+// - Original file tidak corrupt
+```
+
+## LRU Cache
+
+SKDM menggunakan LRU cache custom untuk RAM efficiency.
+
+```typescript
+import { LRUCache } from 'waliwa';
+
+const cache = new LRUCache<string, any>(500); // Max 500 entries
+
+cache.set('key1', { data: 'value' });
+const value = cache.get('key1');
+
+const stats = cache.getStats();
+console.log(stats);
+// { size: 1, hits: 1, misses: 0, hitRate: 1 }
+```
+
+## Monitoring
+
+SKDM exposes stats untuk monitoring:
+
+```typescript
+// Comprehensive stats
+const stats = sock.getSKDMStats();
+console.log(JSON.stringify(stats, null, 2));
+
+// System stats (includes SKDM + other components)
+const systemStats = sock.getSystemStats();
+console.log(JSON.stringify(systemStats, null, 2));
+```
+
+## Background Jobs
+
+SKDM menjalankan beberapa background jobs otomatis:
+
+| Job | Interval | Purpose |
+|-----|----------|---------|
+| Pre-key rotation check | 1 hour | Regenerate pre-keys jika low |
+| Session cleanup | 6 hours | Hapus expired sessions (>30 days) |
+| AppState key cleanup | 24 hours | Hapus unused app state keys |
+
+Jobs otomatis di-stop saat `sock.end()` dipanggil.
+
+## Configuration
+
+Semua konfigurasi SKDM via WaliwaConfig:
+
+```typescript
+makeWASocket({
+  authState: state,
+
+  // PreKey config
+  minPreKeys: 5,
+  maxPreKeysBatch: 50,
+  targetPreKeyCount: 100,
+  enableKeyRotation: true,
+
+  // Session cache config
+  maxSessionCacheSize: 500,
+  sessionExpiryMs: 30 * 24 * 60 * 60 * 1000, // 30 days
+  enableSessionPrefetch: true,
+
+  // Storage
+  storageFolder: './auth',
+  prefix: 'waliwa-session'
+});
+```
+
+## Best Practices
+
+1. **Always call `sock.end()`** saat shutdown untuk flush pending saves
+2. **Monitor `getSKDMStats()`** secara periodik untuk detect issues
+3. **Handle identity changes** sebagai security alert
+4. **Don't manually edit** session files - use SKDM API
+5. **Backup auth folder** sebelum updates besar