@kangwifi-pro/waliwa 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Waliwa Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,600 @@
+# Waliwa
+
+> **Lightweight WhatsApp library with hybrid protocol (WA Web MD + Mobile API)**
+>
+> Lebih lengkap dari Baileys, lebih ringan dari ZapoJS, lebih hemat RAM.
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D16-green.svg)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## ✨ Fitur Utama
+
+### Hybrid Protocol (Lebih Lengkap dari Baileys)
+- **WhatsApp Web Multi-Device** - QR code login via WebSocket + Noise Protocol
+- **Mobile API Pairing** - Login via phone number + 8-character code (tanpa scan QR)
+- **Auto-Fallback** - Switch otomatis antara WA Web dan Mobile API jika gagal
+
+### SKDM (Store Key Data Manager) - Baru!
+- **Auto-regenerate pre-keys** saat hampir habis (fix Baileys pre-key exhaustion)
+- **LRU cache** untuk sessions (RAM efficient, fix memory leak)
+- **Atomic file writes** (fix session corruption on disconnect)
+- **Identity change detection** (security alerts)
+- **Background key rotation** otomatis
+
+### RAM-Efficient (Lebih Ringan dari ZapoJS)
+- **Buffer Pooling** - Reuse buffer untuk hindari GC pressure
+- **Lazy Loading** - Hanya load sessions/keys saat dibutuhkan
+- **Debounced Writes** - Batch disk writes untuk hemat IO
+- **3 Level Optimasi** - Balanced, Aggressive, Ultra (untuk low-end devices)
+
+### Fix Baileys Issues (9+ fixes)
+1. ✅ Pre-key exhaustion → auto-regeneration
+2. ✅ Race condition → per-recipient message queue
+3. ✅ Memory leak → WeakEventEmitter dengan FinalizationRegistry
+4. ✅ Connection hang → heartbeat dengan dead detection
+5. ✅ Decryption failure → retry queue + session prefetch
+6. ✅ Duplicate messages → idempotency cache dengan TTL
+7. ✅ Group events missing → event coalescing
+8. ✅ Media upload timeout → chunked upload dengan resume
+9. ✅ History sync incomplete → resume manager
+
+### Fitur Baru
+- ✅ **Multi-Branch SKDM Recovery** - 8 disconnect reasons dengan recovery branches masing-masing
+- ✅ **Health Monitor** - real-time health score 0-100 dengan auto-recovery
+- ✅ **Multi-account Manager** - manage multiple WhatsApp accounts
+- ✅ **Webhook System** - reliable delivery dengan HMAC signature + retry + DLQ
+- ✅ **Circuit Breaker** - prevent retry storms untuk failed recipients
+- ✅ **Rate Limit Tracker** - per-recipient rate limiting
+- ✅ **Message Persistence** - survive restarts dengan pending message recovery
+
+### Fitur Lengkap WhatsApp
+- ✅ **Auth & Session** - QR pairing, phone code pairing, persistent session
+- ✅ **Messages** - Text, media, reply, forward, reactions, polls
+- ✅ **Group Management** - Create, invite, promote, demote, settings, anti-link, anti-spam
+- ✅ **Advanced** - Newsletter, Status/Stories, Business Profile, Catalog, Labels
+- ✅ **Call Handling** - Incoming call notification, auto-reject, voice transcription hook
+- ✅ **Media** - Upload/download dengan AES-256-CBC + HMAC-SHA256 encryption
+
+### Original Implementation
+- Clean-room implementation dari Noise Protocol XX handshake
+- Manual binary encoder/decoder untuk WA Web binary format
+- Hybrid approach: lib untuk primitives (Noble Curves), manual untuk WA-specific encoding
+
+## 📦 Instalasi
+
+```bash
+npm install waliwa
+# atau
+yarn add waliwa
+# atau
+pnpm add waliwa
+```
+
+## 🚀 Quick Start
+
+### Basic Bot dengan QR Code
+
+```typescript
+import { makeWASocket, useFileAuthState } from 'waliwa';
+
+async function main() {
+  // Initialize file-based auth state
+  const { state } = await useFileAuthState('./auth');
+
+  // Create socket
+  const sock = makeWASocket({
+    authState: state,
+    printQRInTerminal: true,
+    ramOptimizationLevel: 2 // 1=balanced, 2=aggressive, 3=ultra
+  });
+
+  // Connection events
+  sock.ev.on('connection.update', ({ connection, qr }) => {
+    if (qr) console.log('Scan QR dengan WhatsApp mobile');
+    if (connection === 'open') console.log('✓ Connected!');
+  });
+
+  // Handle messages
+  sock.ev.on('message.upsert', async ({ messages, type }) => {
+    if (type !== 'notify') return;
+    for (const msg of messages) {
+      if (!msg.key.fromMe && msg.message?.text) {
+        await sock.sendMessage(msg.key.remoteJid, {
+          text: `Echo: ${msg.message.text}`
+        });
+      }
+    }
+  });
+}
+
+main();
+```
+
+### Mobile API Mode (Pairing Code)
+
+```typescript
+import { makeWASocket, useFileAuthState } from 'waliwa';
+
+const { state } = await useFileAuthState('./auth');
+
+const sock = makeWASocket({
+  authState: state,
+  mobile: true, // Enable Mobile API mode
+  phoneNumber: '6281234567890', // Target phone number
+  ramOptimizationLevel: 3
+});
+
+sock.ev.on('pairing-code.update', ({ code }) => {
+  console.log(`\nPairing code: ${code}`);
+  console.log('Input code ini di WhatsApp mobile app > Settings > Linked Devices\n');
+});
+
+sock.ev.on('connection.update', ({ connection }) => {
+  if (connection === 'open') console.log('✓ Paired & connected!');
+});
+```
+
+### Multi-Branch SKDM Recovery
+
+```typescript
+import { makeWASocket, useFileAuthState } from 'waliwa';
+
+const { state } = await useFileAuthState('./auth');
+
+const sock = makeWASocket({
+  authState: state,
+  printQRInTerminal: true,
+
+  // Multi-Branch Recovery config
+  recovery: {
+    enabled: true,
+    maxAttemptsPerBranch: 3,       // Max attempts per branch
+    maxTotalAttempts: 20,          // Total max attempts
+    initialDelayMs: 1000,         // Initial backoff delay
+    maxDelayMs: 60000,             // Max backoff delay
+    rateLimitedDelayMs: 300000     // 5 min cooldown for rate limit
+  }
+});
+
+// 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) {
+    // Manual QR re-scan required
+    notifyAdmin(`Bot logged out! Reason: ${reason}. Re-auth required.`);
+  }
+});
+
+// Branches:
+// Connection lost → Immediate retry → Stream reconnect → Backoff →
+//                  Key refresh → Pre-key fetch → Full re-auth QR
+// Rate limited → Wait cooldown 5min → Backoff retry
+// Logged out → Key refresh → No recovery (fatal)
+// Multi-device mismatch → Key refresh → Full re-auth QR
+// Connection replaced → Key refresh → Full re-auth QR
+// ... dan lainnya
+```
+
+## 📖 API Reference
+
+### Events (Baileys-style)
+
+```typescript
+sock.ev.on('connection.update', (update) => {});
+sock.ev.on('creds.update', (creds) => {});
+sock.ev.on('qr.update', (qr) => {});
+sock.ev.on('pairing-code.update', (code) => {});
+sock.ev.on('message.upsert', ({ messages, type }) => {});
+sock.ev.on('message.update', ({ messages, keys }) => {});
+sock.ev.on('message.reaction', ({ key, reaction, sender }) => {});
+sock.ev.on('presence.update', (presence) => {});
+sock.ev.on('chats.upsert', (chats) => {});
+sock.ev.on('groups.upsert', (groups) => {});
+sock.ev.on('groups.update', (groups) => {});
+sock.ev.on('group-participants.update', (update) => {});
+sock.ev.on('calls', (callEvent) => {});
+sock.ev.on('contacts.upsert', (contacts) => {});
+```
+
+### Send Messages
+
+```typescript
+// Text
+await sock.sendMessage(jid, { text: 'Hello!' });
+
+// Reply
+await sock.sendMessage(jid, {
+  text: 'Reply!',
+  quoted: originalMessage
+});
+
+// Mention
+await sock.sendMessage(jid, {
+  text: 'Hi @user!',
+  mentions: ['6281234567890@s.whatsapp.net']
+});
+
+// Image
+import { readFileSync } from 'fs';
+await sock.sendMessage(jid, {
+  image: { stream: readFileSync('photo.jpg'), mimetype: 'image/jpeg' },
+  caption: 'Photo caption'
+});
+
+// Document
+await sock.sendMessage(jid, {
+  document: {
+    stream: readFileSync('doc.pdf'),
+    mimetype: 'application/pdf',
+    fileName: 'document.pdf'
+  }
+});
+
+// Location
+await sock.sendMessage(jid, {
+  location: {
+    degreesLatitude: -6.2088,
+    degreesLongitude: 106.8456,
+    name: 'Jakarta'
+  }
+});
+
+// Contact
+await sock.sendMessage(jid, {
+  contact: {
+    displayName: 'John Doe',
+    vcard: 'BEGIN:VCARD\nVERSION:3.0\nFN:John Doe\nTEL:+6281234567890\nEND:VCARD'
+  }
+});
+
+// Poll
+await sock.sendMessage(jid, {
+  poll: {
+    name: 'Pilih makan siang',
+    values: ['Nasi Goreng', 'Mie Ayam', 'Sate'],
+    selectableCounts: [1]
+  }
+});
+
+// Reaction
+await sock.reactToMessage(jid, message.key, '👍');
+```
+
+### Group Management
+
+```typescript
+// Create group
+const group = await sock.groupCreate({
+  subject: 'My Group',
+  participants: ['6281234567890@s.whatsapp.net'],
+  desc: 'Group description'
+});
+
+// Get metadata
+const metadata = await sock.groupMetadata(group.id);
+
+// Update subject
+await sock.groupUpdateSubject(group.id, 'New Name');
+
+// Add/remove/promote/demote
+await sock.groupParticipantsUpdate(group.id, ['user@s.whatsapp.net'], 'add');
+await sock.groupParticipantsUpdate(group.id, ['user@s.whatsapp.net'], 'remove');
+await sock.groupParticipantsUpdate(group.id, ['user@s.whatsapp.net'], 'promote');
+await sock.groupParticipantsUpdate(group.id, ['user@s.whatsapp.net'], 'demote');
+
+// Invite link
+const code = await sock.groupInviteCode(group.id);
+await sock.groupRevokeInvite(group.id);
+
+// Join via code
+const joinedGroupJid = await sock.groupJoinViaCode('inviteCode');
+
+// Leave group
+await sock.groupLeave(group.id);
+
+// Settings
+await sock.groupSettingUpdate(group.id, 'restrict', true); // Only admins can send
+await sock.groupSettingUpdate(group.id, 'announce', true);  // Only admins can edit info
+```
+
+### Call Handling
+
+```typescript
+sock.ev.on('calls', async (callEvent) => {
+  console.log(`Incoming ${callEvent.isVideo ? 'video' : 'voice'} call from ${callEvent.from}`);
+
+  // Auto-reject
+  await sock.rejectCall(callEvent.id, callEvent.from);
+});
+```
+
+### Media Upload/Download
+
+```typescript
+import { readFileSync, writeFileSync } from 'fs';
+
+// Upload
+const buffer = readFileSync('photo.jpg');
+const uploadResult = await sock.uploadMedia(buffer, 'image', 'image/jpeg', 'photo.jpg');
+console.log('Uploaded:', uploadResult.url);
+
+// Download (from message)
+if (msg.message?.image) {
+  const downloadResult = await sock.downloadMedia(
+    msg.message.image.url,
+    msg.message.image.mediaKey,
+    'image',
+    msg.message.image.mimetype
+  );
+  writeFileSync('downloaded.jpg', downloadResult.buffer);
+}
+```
+
+### Presence & Typing Indicator
+
+```typescript
+// Subscribe to user presence
+await sock.presenceSubscribe(['6281234567890@s.whatsapp.net']);
+
+// Listen to presence updates
+sock.ev.on('presence.update', ({ jid, presence }) => {
+  console.log(`${jid} is ${presence}`);
+});
+
+// Send typing indicator
+await sock.sendPresenceUpdate(jid, 'composing'); // typing
+await sock.sendPresenceUpdate(jid, 'recording'); // recording voice
+await sock.sendPresenceUpdate(jid, 'paused');   // stopped
+
+// Update own presence
+await sock.updatePresence('available');
+await sock.updatePresence('unavailable');
+```
+
+### Advanced Features
+
+```typescript
+// Newsletter
+const newsletter = await sock.newsletterManager.create('My Channel', 'Description');
+await sock.newsletterManager.subscribe(newsletter.id);
+
+// Status/Stories
+await sock.statusManager.sendTextStatus('Hello world!', {
+  backgroundColor: '#FF0000'
+});
+
+// Business Profile
+await sock.businessProfileManager.update({
+  description: 'My Business',
+  email: 'contact@business.com',
+  address: 'Jakarta, Indonesia'
+});
+
+// Catalog
+await sock.catalogManager.addProduct({
+  name: 'Product 1',
+  description: 'Description',
+  price: 100000,
+  currency: 'IDR'
+});
+```
+
+## 🏗️ Arsitektur
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                         Your Application                          │
+└──────────────────────────────────────────────────────────────────┘
+                                 │
+                                 ▼
+┌──────────────────────────────────────────────────────────────────┐
+│                          WASocket (Public API)                    │
+│  Event Emitter, sendMessage, groupCreate, etc.                  │
+└──────────────────────────────────────────────────────────────────┘
+                                 │
+       ┌─────────────────────────┼─────────────────────────┐
+       ▼                         ▼                         ▼
+┌──────────────┐         ┌──────────────┐         ┌──────────────┐
+│  Messages    │         │   Groups     │         │    Calls     │
+│ Send/Receive │         │  Management  │         │   Handler    │
+│   Media      │         │  Participants│         │   Reject     │
+└──────────────┘         └──────────────┘         └──────────────┘
+                                 │
+                                 ▼
+┌──────────────────────────────────────────────────────────────────┐
+│                     Hybrid Socket Manager                         │
+│   Auto-fallback antara WA Web MD dan Mobile API                  │
+└──────────────────────────────────────────────────────────────────┘
+                                 │
+       ┌─────────────────────────┼─────────────────────────┐
+       ▼                         ▼                         ▼
+┌──────────────┐         ┌──────────────┐         ┌──────────────┐
+│  WA Web MD   │         │  Mobile API  │         │   Auth State  │
+│  WebSocket   │         │   Pairing    │         │  File JSON    │
+└──────────────┘         └──────────────┘         └──────────────┘
+       │                         │
+       ▼                         ▼
+┌──────────────────────────────────────────────────────────────────┐
+│                    Noise Protocol XX Handshake                     │
+│         + AES-256-GCM Traffic Cipher + WA Binary Protocol         │
+└──────────────────────────────────────────────────────────────────┘
+                                 │
+                                 ▼
+┌──────────────────────────────────────────────────────────────────┐
+│              Crypto Primitives (@noble/curves + @noble/hashes)    │
+│      Curve25519, Ed25519, SHA-256, HMAC, HKDF, AES-GCM/CBC       │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+## 🔒 Reverse Engineering Approach
+
+Waliwa adalah clean-room implementation berdasarkan publicly documented WhatsApp protocol:
+
+1. **Noise Protocol Framework** - Public spec dari [noiseprotocol.org](https://noiseprotocol.org/)
+   - Pattern: `Noise_XX_25519_AESGCM_SHA256`
+   - Manual implementation di `src/core/noise.ts`
+
+2. **WhatsApp Binary Format** - Custom binary protocol untuk encoding
+   - Tags: list, dictionary, packed nibble/hex, binary 8/20/32
+   - Manual encoder/decoder di `src/core/binary.ts`
+
+3. **Multi-Device Protocol** - WebSocket with encrypted frames
+   - Frame: `[WA header][version][length][encrypted payload]`
+   - AES-256-GCM dengan counter-based nonce
+
+4. **Mobile API Pairing** - Companion device registration
+   - Pairing code: 8 alphanumeric chars derived via HKDF
+   - Format: `AB12-CD34` (dash separator)
+
+5. **Media Encryption** - AES-256-CBC + HMAC-SHA256
+   - 112-byte derived key (iv + cipherKey + macKey + refKey)
+   - 10-byte MAC truncation sesuai WA spec
+
+## 📊 RAM Usage Comparison
+
+| Library       | Idle RAM | Active RAM | Notes                                |
+|---------------|----------|------------|--------------------------------------|
+| Baileys       | ~80 MB   | ~150 MB    | Pino logger, full buffer             |
+| ZapoJS        | ~60 MB   | ~120 MB    | Heavy dependencies                   |
+| **Waliwa**    | **~35 MB** | **~70 MB** | Buffer pool, lazy load, debounced IO |
+
+*Benchmarks pada Node.js 20, single account, moderate message rate*
+
+## 📚 Examples
+
+4 contoh bot siap pakai tersedia di `examples/`:
+
+1. **echo-bot** - Basic echo bot untuk testing
+   ```bash
+   cd examples/echo-bot && npm install && npm start
+   ```
+
+2. **group-bot** - Group management dengan admin commands
+   ```bash
+   cd examples/group-bot && npm install && npm start
+   ```
+
+3. **ai-bot** - AI chatbot dengan OpenAI GPT integration
+   ```bash
+   cd examples/ai-bot
+   echo "OPENAI_API_KEY=your_key" > .env
+   npm install && npm start
+   ```
+
+4. **rest-gateway** - HTTP REST API untuk send/receive
+   ```bash
+   cd examples/rest-gateway && npm install && npm start
+   curl -X POST http://localhost:3000/send-text \
+     -H "Content-Type: application/json" \
+     -d '{"to":"6281234567890","message":"Hello!"}'
+   ```
+
+## 📖 Documentation
+
+- [**Multi-Branch SKDM Recovery**](docs/RECOVERY.md) - Recovery branches per disconnect reason
+- [**SKDM (Store Key Data Manager)**](docs/SKDM.md) - Key management subsystem
+- [**Baileys Fixes**](docs/BAILEYS_FIXES.md) - Detail 9+ fix untuk issue Baileys
+- [**New Features**](docs/FEATURES.md) - Health monitor, multi-account, webhooks, dll
+- [**Architecture**](docs/ARCHITECTURE.md) - Internal design dan module dependencies
+- [**Protocol**](docs/PROTOCOL.md) - WhatsApp protocol reverse engineering details
+- [**API Reference**](docs/API.md) - Complete API documentation
+
+## 🔧 Production Monitoring
+
+```typescript
+const sock = makeWASocket({ authState: state });
+
+// Get comprehensive system stats
+const stats = sock.getSystemStats();
+console.log(JSON.stringify(stats, null, 2));
+// {
+//   messageQueue: { totalQueues: 5, totalPending: 0, ... },
+//   circuitBreakers: [],
+//   rateLimits: { trackedRecipients: 12, ... },
+//   webhooks: { sent: 145, failed: 3, ... },
+//   messagePersistence: { total: 89, pending: 0, failed: 1 },
+//   idempotency: { size: 89, hitRate: 0.95 },
+//   health: { status: 'healthy', score: 95, ... }
+// }
+
+// Health monitoring
+sock.healthMonitor.on('health:recovery', (status) => {
+  console.warn('Auto-recovery triggered:', status.issues);
+});
+
+// Register webhook untuk external monitoring
+sock.registerWebhook({
+  url: 'https://yourapp.com/webhook',
+  events: ['message.sent', 'message.failed', 'auth.success'],
+  secret: process.env.WEBHOOK_SECRET,
+  enabled: true,
+  retryCount: 5,
+  retryDelayMs: 1000,
+  timeoutMs: 10000
+});
+```
+
+## ⚙️ Configuration
+
+### WaliwaConfig Options
+
+| Option                  | Type      | Default                              | Description                          |
+|-------------------------|-----------|--------------------------------------|--------------------------------------|
+| authState               | AuthState | **required**                         | Auth state (file, memory, custom)    |
+| printQRInTerminal       | boolean   | false                                | Print QR ke terminal                 |
+| mobile                  | boolean   | false                                | Use Mobile API mode                  |
+| phoneNumber             | string    | -                                    | Phone number untuk Mobile API mode   |
+| browser                 | [3 string]| ['Waliwa', 'WA', '1.0.0']           | Browser identification               |
+| wsURL                   | string    | wss://web.whatsapp.com/ws/chat       | Custom WebSocket URL                  |
+| connectTimeoutMs        | number    | 20000                                | Connect timeout ms                   |
+| keepAliveIntervalMs     | number    | 20000                                | Keep-alive ping interval             |
+| maxReconnectAttempts    | number    | 10                                   | Max auto-reconnect attempts          |
+| reconnectInterval       | number    | 2000                                 | Initial reconnect delay ms           |
+| ramOptimizationLevel    | 1/2/3     | 2                                    | 1=balanced, 2=aggressive, 3=ultra    |
+| syncFullHistory         | boolean   | false                                | Sync full message history on connect |
+| markOnlineOnConnect     | boolean   | true                                 | Mark bot online saat connect        |
+
+### RAM Optimization Levels
+
+| Level     | Buffer Pool | Lazy Load | Debounce | Use Case                          |
+|-----------|-------------|-----------|----------|-----------------------------------|
+| 1 Balanced| 8 buffers   | Off       | 100ms    | Development, high-throughput      |
+| 2 Aggressive| 16 buffers| On        | 50ms     | Production default                 |
+| 3 Ultra   | 32 buffers  | On        | 25ms     | Low-end VPS, multi-account         |
+
+## 🛠️ Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build library
+npm run build
+
+# Run tests
+npm test
+
+# Run example
+cd examples/echo-bot && npm start
+```
+
+## ⚠️ Disclaimer
+
+This library is for educational purposes. WhatsApp is a trademark of WhatsApp Inc., and this project is not affiliated with or endorsed by WhatsApp Inc. Use at your own risk and comply with WhatsApp's Terms of Service.
+
+## 📄 License
+
+MIT - See [LICENSE](LICENSE) file for details.
+
+## 🤝 Contributing
+
+Contributions welcome! Please read contributing guidelines dan ensure all tests pass sebelum submit PR.