socketon 1.31.2-rc → 1.51.16

package/README.md

@@ -32,7 +32,7 @@ This is a fork of Baileys focused on stability, session handling, and more flexi
 
 ## Key Features
 
-- Custom Pairing Codes: Default "SOCKETON" code for easier authentication
+- Custom Pairing Codes: Default pairing code (obfuscated) for easier authentication
 - Enhanced Stability: Improved session handling and automatic reconnection
 - Multi-Device Support: Full compatibility with WhatsApp's multi-device feature
 - Interactive Messages: Buttons, lists, and native flow interactions
@@ -46,227 +46,381 @@ This is a fork of Baileys focused on stability, session handling, and more flexi
 
 ---
 
-## Installation
+## makeWASocketon - Simplified Socket Initialization
 
-```bash
-npm install socketon
-```
+`makeWASocketon()` is a simplified wrapper around `makeWASocket()` with built-in features like auto-reconnect, message serialization, and helper methods.
 
-Requirements:
-- Node.js >= 20.0.0
+### Quick Start - Basic
 
----
+```javascript
+const { makeWASocketon } = require('socketon');
+
+const sock = await makeWASocketon({
+  sessionDir: './session',        // Folder to store session
+  pairingNumber: '6281234567890', // Phone number (without +)
+  onMessage: async (msg) => {   // Message handler
+    if (msg.text === '!ping') {
+      await sock.reply(msg, 'Pong! PING');
+    }
+  }
+});
 
-## Quick Start
+// Auto-reconnect, auto-save credentials built-in!
+```
 
-### Basic Echo Bot
+### With Custom Pairing Code (Optional)
 
 ```javascript
-const { makeWASocket, useMultiFileAuthState } = require('socketon');
+const sock = await makeWASocketon({
+  sessionDir: './session',
+  pairingNumber: '6281234567890',
+  pairingCode: 'MYCODE12',       // Optional: 8 characters
+  onMessage: async (msg) => {
+    await sock.reply(msg, 'Hello! HELLO');
+  }
+});
+```
 
-async function startBot() {
-  // Setup authentication
-  const { state, saveCreds } = await useMultiFileAuthState('./auth');
+### Configuration Options
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `sessionDir` | string | Yes | - | Folder to store session files |
+| `pairingNumber` | string | Yes | - | Phone number (e.g., "6281234567890") |
+| `pairingCode` | string | No | Default | Custom pairing code (must be 8 chars) |
+| `onMessage` | function | Yes | - | Callback for new messages |
+| `onConnection` | function | No | - | Callback for connection status updates |
+| `onGroupJoin` | function | No | - | Callback for group joins |
+| `onGroupLeave` | function | No | - | Callback for group leaves |
+| `onError` | function | No | - | Callback for errors |
+| `enableAutoReconnect` | boolean | No | true | Enable auto-reconnect on disconnect |
+| `enableMetadataCache` | boolean | No | true | Enable group metadata caching |
+| `syncFullHistory` | boolean | No | false | Sync full message history |
+| `browser` | object | No | Browsers.ubuntu("Chrome") | Browser configuration |
+| `logger` | object | No | pino default | Custom logger instance |
+
+### Built-in Helper Methods
 
-  // Create WhatsApp socket
-  const sock = makeWASocket({
-    auth: state,
-    printQRInTerminal: true
-  });
+```javascript
+// Serialize message (automatically done in onMessage)
+const serialized = sock.serialize(rawMessage);
 
-  // Handle connection
-  sock.ev.on('connection.update', (update) => {
-    const { connection, qr } = update;
+// Get group metadata with caching
+const metadata = await sock.getGroupMetadata('group@g.us');
 
-    if (qr) console.log('Scan QR Code:', qr);
-    if (connection === 'open') console.log('Connected to WhatsApp!');
-  });
+// Clear group cache
+sock.clearGroupCache(); // Clear all
+sock.clearGroupCache('group@g.us'); // Clear specific
 
-  // Handle messages
-  sock.ev.on('messages.upsert', async ({ messages }) => {
-    for (const msg of messages) {
-      if (msg.key.fromMe) continue;
+// Download media
+const buffer = await sock.downloadMedia(message);
+const filePath = await sock.downloadMedia(message, 'image', 'photo.jpg');
 
-      const jid = msg.key.remoteJid;
-      const text = msg.message?.conversation || msg.message?.extendedTextMessage?.text || '';
+// Decode JID
+const decodedJid = sock.decodeJid('user:5@s.whatsapp.net');
 
-      console.log(`Message from ${jid}: ${text}`);
+// Send message
+await sock.send('jid@s.whatsapp.net', { text: 'Hello' });
 
-      // Echo response
-      if (text) {
-        await sock.sendMessage(jid, { text: `Echo: ${text}` });
-      }
-    }
-  });
+// Reply to message
+await sock.reply(message, 'Reply!');
 
-  // Save credentials
-  sock.ev.on('creds.update', saveCreds);
-}
+// Forward message
+await sock.forward('jid@s.whatsapp.net', message);
 
-startBot().catch(console.error);
+// Set presence
+await sock.setPresence('available');
+await sock.setPresence('composing', 'jid@s.whatsapp.net');
+await sock.setPresence('recording', 'jid@s.whatsapp.net');
+
+// Graceful shutdown
+await sock.shutdown();
 ```
 
-### Pairing Code Authentication
+### Connection Status Events
 
 ```javascript
-const { makeWASocket, useMultiFileAuthState } = require('socketon');
-
-async function startWithPairing() {
-  const { state, saveCreds } = await useMultiFileAuthState('./auth');
+const sock = await makeWASocketon({
+  sessionDir: './session',
+  pairingNumber: '6281234567890',
+  onConnection: (status, data) => {
+    switch(status) {
+      case 'connecting':
+        console.log('Connecting...');
+        break;
+      case 'open':
+        console.log('Connection opened successfully!');
+        break;
+      case 'close':
+        console.log('Connection closed');
+        if (data.autoReconnect) {
+          console.log('Auto-reconnecting...');
+        }
+        break;
+      case 'reconnecting':
+        console.log('Reconnecting (attempt ' + data.attempt + ')');
+        break;
+      case 'loggedOut':
+        console.log('Session logged out. Delete session folder.');
+        break;
+      case 'requesting_pairing_code':
+        console.log('Requesting pairing code...');
+        break;
+      case 'pairing_code_ready':
+        console.log('Pairing Code:', data.code);
+        console.log('Pairing Number:', data.pairingNumber);
+        break;
+    }
+  },
+  onMessage: async (msg) => {
+    console.log('Message:', msg.text);
+  }
+});
+```
 
-  const sock = makeWASocket({
-    auth: state,
-    printQRInTerminal: false // Disable QR, use pairing code
-  });
+### Example Bot - Full
 
-  sock.ev.on('connection.update', async (update) => {
-    const { connection } = update;
+```javascript
+const { makeWASocketon } = require('socketon');
+
+const sock = await makeWASocketon({
+  sessionDir: './bot-session',
+  pairingNumber: '6281234567890',
+  onConnection: (status) => {
+    if (status === 'open') {
+      console.log('Bot is ready!');
+    }
+  },
+  onGroupJoin: async (msg) => {
+    await sock.reply(msg, 'Welcome @' + msg.author + '!');
+  },
+  onGroupLeave: async (msg) => {
+    await sock.reply(msg, 'Goodbye @' + msg.author + '!');
+  },
+  onMessage: async (msg) => {
+    const text = msg.text.toLowerCase();
+    
+    if (text === '!menu') {
+      await sock.reply(msg, `
+MENU
+• !ping - Test bot
+• !info - Bot info
+• !owner - Contact owner
+      `);
+    }
+    else if (text === '!ping') {
+      await sock.reply(msg, 'Pong! PING');
+    }
+    else if (text === '!info') {
+      await sock.reply(msg, `
+BOT INFO
+Status: Online
+Session: ' + sock.sessionId
+Socketon: v1.51.16
+      `);
+    }
+  }
+});
+
+// Handle graceful shutdown
+process.on('SIGINT', async () => {
+  console.log('Shutting down...');
+  await sock.shutdown();
+  process.exit(0);
+});
+```
 
-    if (connection === 'open') {
-      // Use default "SOCKETON" pairing code
-      const pairingCode = await sock.requestPairingCode('6281234567890');
-      console.log('Pairing Code:', pairingCode);
+### Auto-Reconnect with Exponential Backoff
 
-      // Or use custom pairing code
-      // const customCode = await sock.requestPairingCode('6281234567890', 'MYCODE');
-      // console.log('Custom Pairing Code:', customCode);
-    }
-  });
+Socketon includes built-in auto-reconnect with exponential backoff to prevent getting banned:
 
-  sock.ev.on('creds.update', saveCreds);
-}
+- Base delay: 5 seconds
+- Max delay: 60 seconds  
+- Max attempts: 10
 
-startWithPairing().catch(console.error);
+Reconnect formula:
+```
+delay = min(5000 * 2^attempt, 60000)
 ```
 
----
+### Validation Rules
 
-## Documentation
+- Pairing Code: Must be exactly 8 characters if provided
+- Session Directory: Must be provided (auto-created if not exists)
+- Pairing Number: Must be provided (phone number without +)
+- onMessage: Must be a function
 
-### Complete Guide
-For comprehensive documentation covering everything from basic to advanced usage:
-
-[Read the Complete Guide](COMPLETE_GUIDE.md)
-
-The complete guide includes:
-- Detailed installation and setup
-- Authentication methods (QR code, pairing code)
-- Message handling (text, media, interactive)
-- Group management and newsletter features
-- Business API integration and webhooks
-- Event system and error handling
-- Advanced usage patterns and performance optimization
-- Database integration and real-world use cases
-- Deployment guides and troubleshooting
-- API reference and migration guide
-
-### Examples Directory
-Check the [examples/](examples/) directory for runnable code samples:
-
-- Basic Bot: Simple echo bot with command handling
-- Media Handling: Download/upload images, videos, documents
-- Group Management: Admin bot for group control
-- Business Features: Product catalog and ordering system
-- Analytics: Bot with usage statistics and monitoring
-- Deployment: Production-ready setup with Docker/PM2
-
-### Use Cases
-
-Socketon is perfect for building:
-- Chatbots: Customer service, entertainment, automation
-- Business Applications: CRM integration, order management
-- Automation Tools: Message forwarding, scheduling
-- Analytics Bots: Message tracking, user engagement
-- Fun Bots: Games, quizzes, interactive experiences
-- E-commerce: Product catalogs, order processing
+Error: "pairingCode must be 8 characters long"
+       (If pairingCode is not 8 characters)
 
 ---
 
-## Migration from Baileys
-
-Migrating from Baileys is usually simple, just change the import:
-
-```javascript
-// From Baileys
-const { makeWASocket } = require('@whiskeysockets/baileys');
+## Installation
 
-// To Socketon
-const { makeWASocket } = require('socketon');
+```bash
+npm install socketon
 ```
 
-For detailed migration steps, see the [Migration Guide](COMPLETE_GUIDE.md#migration-guide) in the complete documentation.
+Requirements:
+- Node.js >= 20.0.0
 
 ---
 
-## Troubleshooting
-
-### Common Issues
+## Core Architecture
 
-Connection Problems:
-- Check internet connection
-- Ensure WhatsApp account is active
-- Try deleting auth/ folder and re-authenticating
+### Layered Socket System
 
-Authentication Issues:
-- Delete auth folder and scan QR again
-- Check file permissions on auth directory
-- Ensure stable network during authentication
+Socketon uses a layered architecture for better modularity and maintainability:
 
-Message Failures:
-- Verify JID format
-- Check if recipient blocked you
-- Implement retry logic for reliability
+```
+makeWASocket()
+  └── makeCommunitiesSocket()    # Communities support
+      └── makeBusinessSocket()      # Business features
+          └── makeMessagesRecvSocket()  # Message receiving
+              └── makeMessagesSocket()   # Message sending
+                  └── makeNewsletterSocket() # Newsletter features
+                      └── makeGroupsSocket() # Group management
+                          └── makeChatsSocket()  # Chat operations
+                              └── makeSocket()  # Core WebSocket connection
+```
 
-For detailed troubleshooting, see [COMPLETE_GUIDE.md#troubleshooting](COMPLETE_GUIDE.md#troubleshooting).
+### Key Components
+
+Socket Layer (lib/Socket/)
+- socket.js: Core WebSocket connection, Noise protocol handshake, pairing code authentication
+- messages-send.js: Message generation, encryption, device enumeration
+- messages-recv.js: Message decryption, receipt handling, retry logic
+- groups.js: Group metadata, participants management, invite codes
+- communities.js: Community creation, linked groups, membership approval
+- business.js: Product catalog, orders, business profile
+- newsletter.js: Newsletter creation, following, reactions
+- chats.js: Chat operations
+- socketon.js: Simplified wrapper (makeWASocketon)
+
+Signal Layer (lib/Signal/)
+- libsignal.js: E2E encryption using libsignal-xeuka
+- Group cipher and sender key distribution for group messages
+- Session management and LID/PN addressing for multi-device
+
+Binary Protocol (lib/WABinary/)
+- encode.js: Binary node encoding for WhatsApp protocol
+- decode.js: Binary node decoding
+- constants.js: Protocol constants (643KB)
+- jid-utils.js: JID parsing, encoding, and validation
+
+Utils (lib/Utils/)
+- messages.js: Message generation helpers, media handling
+- messages-media.js: Media upload/download, encryption, thumbnail generation
+- event-buffer.js: Event buffering and flushing mechanism
+- auth-utils.js: Authentication helpers, pre-key management
+
+### Security Features
+
+Layer 1: Noise Protocol (XX pattern)
+- Ephemeral key exchange
+- Perfect forward secrecy
+- X25519 ECDH
+- AES-256-GCM
+- SHA-256 authentication
+
+Layer 2: Signal Protocol (E2E)
+- Double Ratchet
+- X3DH key agreement
+- Pre-key bundles
+- Sender keys for groups
+
+Layer 3: Advanced Device Verification
+- ADV signatures
+- Account signature key
+- Device signature
+- Chain of trust
+
+Layer 4: Obfuscation
+- Pairing code: XOR + hex arrays
+- Newsletter URL: XOR + random variables
 
 ---
 
-## Contributing
-
-We welcome contributions! Please see our [Contributing Guide](COMPLETE_GUIDE.md#contributing) for details.
-
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests if applicable
-5. Submit a pull request
+## Documentation
 
-<a href="https://github.com/IbraDecode/socketon/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=IbraDecode/socketon" alt="contributors" />
-</a>
+### Key Files
+
+Core Socket:
+- lib/Socket/index.js - Entry point (makeWASocket)
+- lib/Socket/socket.js - Core connection (820 lines)
+- lib/Socket/socketon.js - Simplified wrapper (402 lines)
+- lib/Socket/messages-send.js - Message sending (1100 lines)
+- lib/Socket/messages-recv.js - Message receiving (1163 lines)
+- lib/Socket/groups.js - Group management (312 lines)
+- lib/Socket/communities.js - Communities (413 lines)
+- lib/Socket/business.js - Business API (377 lines)
+- lib/Socket/newsletter.js - Newsletter (245 lines)
+- lib/Socket/chats.js - Chat operations
+- lib/Socket/mex.js - Mex queries
+- lib/Socket/Client/ - WebSocket client
+
+Encryption:
+- lib/Signal/libsignal.js - Signal protocol (324 lines)
+- lib/Signal/Group/ - Group encryption
+- lib/Signal/lid-mapping.js - LID/PN mapping
+- lib/Utils/crypto.js - Crypto primitives (130 lines)
+- lib/Utils/noise-handler.js - Noise protocol (144 lines)
+- lib/Utils/auth-utils.js - Auth credentials (219 lines)
+
+Binary Protocol:
+- lib/WABinary/encode.js - Binary encoding (218 lines)
+- lib/WABinary/decode.js - Binary decoding (240 lines)
+- lib/WABinary/constants.js - Protocol constants (643 KB)
+- lib/WABinary/jid-utils.js - JID utilities
+- lib/WABinary/generic-utils.js - Helper functions
+
+Utilities:
+- lib/Utils/messages.js - Message generation (35 KB)
+- lib/Utils/messages-media.js - Media handling (21 KB)
+- lib/Utils/event-buffer.js - Event buffering (17 KB)
+- lib/Utils/message-retry-manager.js - Retry logic (113 lines)
+- lib/Utils/pre-key-manager.js - Pre-key management
+- lib/Utils/validate-connection.js - Login/registration (200 lines)
+- lib/Utils/generics.js - Generic helpers (355 lines)
+
+Storage:
+- lib/Store/make-in-memory-store.js - In-memory DB (290 lines)
+- lib/Store/object-repository.js - Object repository
+- lib/Store/make-cache-manager-store.js - Cache manager
+- lib/KeyDB/KeyedDB.js - Binary search DB
+
+Protocols:
+- lib/WAUSync/ - USync protocols
+- lib/WAM/ - WhatsApp Message types
+- WAProto/ - Protocol buffers (4.2 MB)
+
+Configuration:
+- lib/Defaults/index.js - Default config (123 lines)
 
 ---
 
-## License
+## Support & Community
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+- Telegram Community: Join our community
+- GitHub Issues: Report bugs
+- WhatsApp: +31617786379
+- Complete Documentation
 
 ---
 
-## Credits
+## License
 
-- Original Baileys: [@adiwajshing/baileys](https://github.com/adiwajshing/baileys)
-- Socketon Enhancement: [IbraDecode](https://github.com/IbraDecode)
+This project is licensed under the MIT License - see the LICENSE file for details.
 
 ---
 
-## Support & Community
+## Credits
 
-- **Telegram Community**: [Join our community](https://t.me/socketon)
-- **GitHub Issues**: [Report bugs](https://github.com/IbraDecode/socketon/issues)
-- **WhatsApp**: +31617786379
-- **Complete Documentation**: [COMPLETE_GUIDE.md](COMPLETE_GUIDE.md)
+- Original Baileys: Baileys
+- Socketon Enhancement: IbraDecode
 
 ---
 
-Ready to build your WhatsApp bot? Start with the Quick Start above, or explore the complete documentation for advanced features!
-
-## Version Management
-
-See [VERSION_MANAGEMENT.md](VERSION_MANAGEMENT.md) for detailed versioning and release information.
-
-Socketon v0.31.0 - Built by IbraDecode
-
 <p align="center">
   <a href="#readme-top">back to top</a>
 </p>