easy-connect-wpp 1.3.5 → 1.3.7

package/README.md

@@ -0,0 +1,864 @@
+# easy-connect-wpp
+
+Unofficial WhatsApp Client for Node.js powered by Baileys. Build scalable, event-driven WhatsApp integrations with full message support and automated reconnection.
+
+[![npm version](https://img.shields.io/npm/v/easy-connect-wpp.svg)](https://www.npmjs.com/package/easy-connect-wpp)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+## ⚠️ Disclaimer
+
+This is an **unofficial** WhatsApp client library. It is not affiliated with WhatsApp Inc. or Meta Platforms. Use at your own risk and ensure compliance with WhatsApp's Terms of Service.
+
+## Features
+
+✨ **Unofficial WhatsApp Client** — Reverse-engineered Baileys library  
+🚀 **Automatic Initialization** — Quick setup with QR code or pairing code  
+🎧 **Event-Driven Architecture** — Familiar callback pattern for all events  
+📨 **Full Message Support** — Text, images, videos, audio, documents, location, contacts, reactions  
+✅ **Type-Safe** — Full TypeScript support with comprehensive type definitions  
+🔄 **Auto-Reconnect** — Automatic reconnection with exponential backoff  
+👥 **Group Management** — Create, update, and manage WhatsApp groups  
+📊 **Session Management** — Persistent session storage and restoration  
+🛡️ **License Validation** — Built-in license verification system
+
+## Installation
+
+```bash
+npm install easy-connect-wpp
+```
+
+### Prerequisites
+
+- **Node.js** 18+
+- **Valid WhatsApp Account** (with verified phone number)
+- **Modern Browser** (for QR code scanning)
+
+## Quick Start
+
+```typescript
+import { SessionManager } from 'easy-connect-wpp';
+import { Session } from 'easy-connect-wpp/models/session';
+
+// 1. Create session
+const session: Session = {
+  session: 'my_session',
+  phoneNumber: '5511999999999',
+  licensePath: './license.json',
+  syncFullHistory: false,
+  pairingCode: false, // set to true for pairing code authentication
+  qrCode: true,
+  qrPrintTerminal: true,
+};
+
+const manager = new SessionManager();
+
+// 2. Register listeners
+manager.onQrCode((qrCode) => {
+  console.log('Scan QR code:', qrCode);
+});
+
+manager.onPairingCode((code) => {
+  console.log('Pairing code:', code);
+});
+
+manager.onMessage(async (message) => {
+  console.log(`Message from ${message.from}: ${message.content.conversation}`);
+});
+
+manager.onConnectionStatus((status) => {
+  console.log(`Connection status: ${status}`);
+});
+
+// 3. Create session
+await manager.createSession(session);
+```
+
+## API Reference
+
+### SessionManager Constructor
+
+```typescript
+const manager = new SessionManager();
+```
+
+### Session Configuration
+
+```typescript
+interface Session {
+  session: string; // Unique session identifier
+  phoneNumber: string; // WhatsApp phone number (with country code)
+  licensePath: string; // Path to license.json file
+  syncFullHistory?: boolean; // Sync full chat history (default: false)
+  pairingCode?: boolean; // Use pairing code instead of QR (default: false)
+  qrCode?: boolean; // Enable QR code (default: true)
+  qrPrintTerminal?: boolean; // Print QR in terminal (default: false)
+  maxRetries?: number; // Max reconnection attempts (default: 10)
+  version?: [number, number, number]; // WA version override (optional)
+}
+```
+
+### Methods
+
+#### `createSession(session: Session): Promise<void>`
+
+Initialize and connect WhatsApp session.
+
+```typescript
+await manager.createSession(session);
+```
+
+### Sending Messages
+
+#### `sendText(identifier: string, message: string): Promise<Response>`
+
+Send a text message.
+
+```typescript
+const phone = '5511999999999';
+const message = 'Hello!';
+const response = await manager.sendText(phone, message);
+if (response.status === 200) {
+  console.log('Message sent:', response.id);
+}
+```
+
+#### `sendTextEdit(identifier: string, message: string, messageId: string): Promise<Response>`
+
+Edit a previously sent text message.
+
+```typescript
+const phone = '5511999999999';
+const message = 'Hello (edited)';
+const messageId = '3AF91FDF7463FFB0CFCA';
+const response = await manager.sendTextEdit(phone, message, messageId);
+if (response.status === 200) {
+  console.log('Message edited:', response.id);
+}
+```
+
+#### `sendTextReply(identifier: string, message: string, options: Option): Promise<Response>`
+
+Send a reply to a specific message.
+
+```typescript
+const phone = '5511999999999';
+const message = 'Thanks!';
+const options = {
+  content: JSON.stringify({
+    id: 'original_message_id',
+    fromMe: false,
+    remoteJid: 'sender@s.whatsapp.net',
+    content: originalMessageContent,
+  }),
+};
+const response = await manager.sendTextReply(phone, message, options);
+if (response.status === 200) {
+  console.log('Reply sent:', response.id);
+}
+```
+
+#### `sendTextStatus(identifiers: string[], message: string, backgroundColor?: string): Promise<Response>`
+
+Send a text status to multiple contacts.
+
+```typescript
+const phones = ['5511999999999', '5511988888888'];
+const message = 'My status!';
+const backgroundColor = '#25D366';
+const response = await manager.sendTextStatus(phones, message, backgroundColor);
+if (response.status === 200) {
+  console.log('Status sent');
+}
+```
+
+#### `sendImage(identifier: string, content: string, option: ImageOption): Promise<Response>`
+
+Send an image with optional caption.
+
+```typescript
+const phone = '5511999999999';
+const content = 'https://example.com/image.jpg';
+const option = { caption: 'Check this out!' };
+const response = await manager.sendImage(phone, content, option);
+if (response.status === 200) {
+  console.log('Image sent:', response.id);
+}
+```
+
+#### `sendVideo(identifier: string, content: string, option: VideoOption): Promise<Response>`
+
+Send a video with optional caption.
+
+```typescript
+const phone = '5511999999999';
+const content = 'https://example.com/video.mp4';
+const option = { caption: 'My video', ptv: false };
+const response = await manager.sendVideo(phone, content, option);
+if (response.status === 200) {
+  console.log('Video sent:', response.id);
+}
+```
+
+#### `sendAudio(identifier: string, content: string, option?: AudioOption): Promise<Response>`
+
+Send an audio file.
+
+```typescript
+const phone = '5511999999999';
+const content = 'https://example.com/audio.mp3';
+const option = { mimetype: 'audio/mpeg' };
+const response = await manager.sendAudio(phone, content, option);
+if (response.status === 200) {
+  console.log('Audio sent:', response.id);
+}
+```
+
+#### `sendVoice(identifier: string, content: string, option?: AudioOption): Promise<Response>`
+
+Send a voice message.
+
+```typescript
+const phone = '5511999999999';
+const content = 'https://example.com/voice.ogg';
+const response = await manager.sendVoice(phone, content);
+if (response.status === 200) {
+  console.log('Voice sent:', response.id);
+}
+```
+
+#### `sendDocument(identifier: string, content: string, option: FileOption): Promise<Response>`
+
+Send a document with optional filename.
+
+```typescript
+const phone = '5511999999999';
+const content = 'https://example.com/document.pdf';
+const option = { filename: 'Report.pdf', caption: 'Here is your report' };
+const response = await manager.sendDocument(phone, content, option);
+if (response.status === 200) {
+  console.log('Document sent:', response.id);
+}
+```
+
+#### `sendLocation(identifier: string, latitude: number, longitude: number): Promise<Response>`
+
+Send a location.
+
+```typescript
+const phone = '5511999999999';
+const latitude = -23.5505;
+const longitude = -46.6333;
+const response = await manager.sendLocation(phone, latitude, longitude);
+if (response.status === 200) {
+  console.log('Location sent:', response.id);
+}
+```
+
+#### `sendContact(identifier: string, contactName: string, contactPhone: string, contactPhotoUrl?: string): Promise<Response>`
+
+Send a contact card.
+
+```typescript
+const phone = '5511999999999';
+const contactName = 'John Doe';
+const contactPhone = '5511988888888';
+const contactPhotoUrl = null;
+const response = await manager.sendContact(phone, contactName, contactPhone, contactPhotoUrl);
+if (response.status === 200) {
+  console.log('Contact sent:', response.id);
+}
+```
+
+#### `sendForward(identifier: string, options: Option): Promise<Response>`
+
+Forward a message.
+
+```typescript
+const phone = '5511999999999';
+const options = {
+  content: JSON.stringify({
+    id: 'original_message_id',
+    fromMe: false,
+    remoteJid: 'sender@s.whatsapp.net',
+    content: messageContent,
+  }),
+};
+const response = await manager.sendForward(phone, options);
+if (response.status === 200) {
+  console.log('Message forwarded:', response.id);
+}
+```
+
+#### `sendReaction(identifier: string, reaction: string, messageId: string): Promise<Response>`
+
+Send a reaction emoji to a message.
+
+```typescript
+const phone = '5511999999999';
+const reaction = '👍';
+const messageId = '3AF91FDF7463FFB0CFCA';
+const response = await manager.sendReaction(phone, reaction, messageId);
+if (response.status === 200) {
+  console.log('Reaction sent:', response.id);
+}
+```
+
+#### `deleteMessageForEveryone(identifier: string, messageId: string): Promise<Response>`
+
+Delete a message for everyone.
+
+```typescript
+const phone = '5511999999999';
+const messageId = '3AF91FDF7463FFB0CFCA';
+const response = await manager.deleteMessageForEveryone(phone, messageId);
+if (response.status === 200) {
+  console.log('Message deleted for everyone');
+}
+```
+
+#### `deleteMessageForMe(identifier: string, messageId: string): Promise<Response>`
+
+Delete a message only for you.
+
+```typescript
+const phone = '5511999999999';
+const messageId = '3AF91FDF7463FFB0CFCA';
+const response = await manager.deleteMessageForMe(phone, messageId);
+if (response.status === 200) {
+  console.log('Message deleted for you');
+}
+```
+
+#### `markReadAll(identifier: string): Promise<Response>`
+
+Mark all messages in a chat as read.
+
+```typescript
+const phone = '5511999999999';
+const response = await manager.markReadAll(phone);
+if (response.status === 200) {
+  console.log('All messages marked as read');
+}
+```
+
+#### `setPresence(identifier: string, type: 'unavailable' | 'available' | 'composing' | 'recording' | 'paused'): Promise<Response>`
+
+Set presence status (typing indicator).
+
+```typescript
+const phone = '5511999999999';
+const type = 'composing';
+const response = await manager.setPresence(phone, type);
+if (response.status === 200) {
+  console.log('Presence updated');
+}
+```
+
+### Group Management
+
+#### `groupCreate(name: string, description: string, type?: 'group' | 'community'): Promise<Response>`
+
+Create a group or community.
+
+```typescript
+const name = 'My Group';
+const description = 'Group description';
+const type = 'group';
+const result = await manager.groupCreate(name, description, type);
+if (result.status === 200) {
+  console.log('Group created:', result.content.id);
+}
+```
+
+#### `groupUpdate(identifier: string, name: string, description: string, type?: 'group' | 'community'): Promise<Response>`
+
+Update group name and description.
+
+```typescript
+const groupId = 'group_id_here';
+const name = 'New Name';
+const description = 'New Description';
+const response = await manager.groupUpdate(groupId, name, description, 'group');
+if (response.status === 200) {
+  console.log('Group updated');
+}
+```
+
+#### `groupUpdateSettings(identifier: string, type: 'group' | 'community', setting: 'announcement' | 'not_announcement' | 'locked' | 'unlocked'): Promise<Response>`
+
+Update group settings.
+
+```typescript
+const groupId = 'group_id_here';
+const type = 'group';
+const setting = 'announcement';
+const response = await manager.groupUpdateSettings(groupId, type, setting);
+if (response.status === 200) {
+  console.log('Settings updated');
+}
+```
+
+#### `groupParticipantAdd(identifier: string, participant: string): Promise<Response>`
+
+Add a participant to a group.
+
+```typescript
+const groupId = 'group_id_here';
+const participant = '5511999999999';
+const response = await manager.groupParticipantAdd(groupId, participant);
+if (response.status === 200) {
+  console.log('Participant added');
+}
+```
+
+#### `groupParticipantRemove(identifier: string, participant: string): Promise<Response>`
+
+Remove a participant from a group.
+
+```typescript
+const groupId = 'group_id_here';
+const participant = '5511999999999';
+const response = await manager.groupParticipantRemove(groupId, participant);
+if (response.status === 200) {
+  console.log('Participant removed');
+}
+```
+
+#### `getGroupMetadata(identifier: string): Promise<Response>`
+
+Get group information.
+
+```typescript
+const groupId = 'group_id_here';
+const response = await manager.getGroupMetadata(groupId);
+if (response.status === 200) {
+  const metadata = response.content;
+  console.log('Group name:', metadata.subject);
+}
+```
+
+#### `getGroupInviteCode(identifier: string): Promise<Response>`
+
+Get group invite code and link.
+
+```typescript
+const groupId = 'group_id_here';
+const response = await manager.getGroupInviteCode(groupId);
+if (response.status === 200) {
+  const { code, url } = response.content;
+  console.log('Invite link:', url);
+}
+```
+
+### Media Management
+
+#### `downloadMedia(options: Option): Promise<Response>`
+
+Download media from WhatsApp (returns buffer).
+
+```typescript
+const options = { content: JSON.stringify(messageObject) };
+const response = await manager.downloadMedia(options);
+if (response.status === 200) {
+  const buffer = response.content;
+  console.log('Media downloaded:', buffer.length, 'bytes');
+}
+```
+
+#### `downloadMediaAndSave(options: Option, directory: string): Promise<Response>`
+
+Download media and save to file.
+
+```typescript
+const options = { content: JSON.stringify(messageObject) };
+const directory = './downloads/media.jpg';
+const response = await manager.downloadMediaAndSave(options, directory);
+if (response.status === 200) {
+  console.log('Media saved to:', directory);
+}
+```
+
+### Profile Management
+
+#### `getPicture(identifier: string): Promise<Response>`
+
+Get profile picture URL.
+
+```typescript
+const phone = '5511999999999';
+const response = await manager.getPicture(phone);
+if (response.status === 200) {
+  const picUrl = response.content;
+  console.log('Profile picture:', picUrl);
+}
+```
+
+#### `updateProfilePicture(identifier: string, content: string): Promise<Response>`
+
+Update profile picture from URL, buffer, or stream.
+
+```typescript
+const phone = '5511999999999';
+const content = 'https://example.com/profile.jpg';
+const response = await manager.updateProfilePicture(phone, content);
+if (response.status === 200) {
+  console.log('Profile picture updated');
+}
+```
+
+#### `removeProfilePicture(identifier: string): Promise<Response>`
+
+Remove profile picture.
+
+```typescript
+const phone = '5511999999999';
+const response = await manager.removeProfilePicture(phone);
+if (response.status === 200) {
+  console.log('Profile picture removed');
+}
+```
+
+#### `onWhatsApp(identifier: string): Promise<Response>`
+
+Check if a phone number is registered on WhatsApp.
+
+```typescript
+const phone = '5511999999999';
+const response = await manager.onWhatsApp(phone);
+if (response.exists) {
+  console.log('Number is on WhatsApp');
+} else {
+  console.log('Number not found on WhatsApp');
+}
+```
+
+### Event Listeners
+
+#### `onMessage(callback: (message: EventResponse) => void): void`
+
+Listen for incoming messages.
+
+```typescript
+manager.onMessage((message) => {
+  console.log(`Type: ${message.type}`);
+  console.log(`From: ${message.from}`);
+  console.log(`IsGroup: ${message.isgroup}`);
+
+  if (message.type === 'conversation') {
+    console.log(`Text: ${message.content.conversation}`);
+  } else if (message.type === 'imageMessage') {
+    console.log(`Image caption: ${message.content.imageMessage?.caption}`);
+  }
+});
+```
+
+#### `onMessageAck(callback: (ack: any) => void): void`
+
+Listen for message acknowledgments.
+
+```typescript
+manager.onMessageAck((ack) => {
+  // Status: PENDING (1), SERVER_ACK (2), DELIVERY_ACK (3), READ (4), PLAYED (5)
+  console.log(`Message ${ack.id}: ${ack.status}`);
+});
+```
+
+#### `onMessageUpdate(callback: (message: any) => void): void`
+
+Listen for message updates.
+
+```typescript
+manager.onMessageUpdate((message) => {
+  console.log('Message updated:', message);
+});
+```
+
+#### `onConnectionStatus(callback: (status: ConnectionState) => void): void`
+
+Listen for connection changes.
+
+```typescript
+manager.onConnectionStatus((status) => {
+  console.log(`Connection: ${status}`);
+  // ConnectionState: NOT_LOGGED, CONNECTING, CONNECTED, DISCONNECTED
+});
+```
+
+#### `onQrCode(callback: (qr: string) => void): void`
+
+Listen for QR code updates.
+
+```typescript
+manager.onQrCode((qr) => {
+  console.log('New QR code generated');
+  // Display in UI
+});
+```
+
+#### `onPairingCode(callback: (code: string) => void): void`
+
+Listen for pairing code updates.
+
+```typescript
+manager.onPairingCode((code) => {
+  console.log(`Pairing code: ${code}`);
+});
+```
+
+#### `onChatsUpsert(callback: (chats: any) => void): void`
+
+Listen for chat updates.
+
+```typescript
+manager.onChatsUpsert((chats) => {
+  console.log('Chats updated:', chats);
+});
+```
+
+#### `onContactsUpsert(callback: (contacts: any) => void): void`
+
+Listen for contact updates.
+
+```typescript
+manager.onContactsUpsert((contacts) => {
+  console.log('Contacts updated:', contacts);
+});
+```
+
+#### `onGroupsUpsert(callback: (groups: any) => void): void`
+
+Listen for group updates.
+
+```typescript
+manager.onGroupsUpsert((groups) => {
+  console.log('Groups updated:', groups);
+});
+```
+
+#### `onGroupParticipantsUpdate(callback: (event: any) => void): void`
+
+Listen for group participant changes.
+
+```typescript
+manager.onGroupParticipantsUpdate((event) => {
+  console.log(`${event.action}: ${event.participants}`);
+});
+```
+
+#### `onBlocklistUpdate(callback: (event: any) => void): void`
+
+Listen for blocklist changes.
+
+```typescript
+manager.onBlocklistUpdate((event) => {
+  console.log('Blocklist updated:', event);
+});
+```
+
+#### `onCall(callback: (calls: any) => void): void`
+
+Listen for incoming calls.
+
+```typescript
+manager.onCall((calls) => {
+  console.log('Call received:', calls);
+});
+```
+
+## Complete Example
+
+```typescript
+import { SessionManager } from 'easy-connect-wpp';
+import { Session } from 'easy-connect-wpp/models/session';
+
+async function main() {
+  const session: Session = {
+    session: 'my_session',
+    phoneNumber: '5511999999999',
+    licensePath: './license.json',
+    qrCode: true,
+    qrPrintTerminal: true,
+  };
+
+  const manager = new SessionManager();
+
+  // Handle messages
+  manager.onMessage(async (message) => {
+    if (message.type === 'conversation') {
+      console.log(`📨 ${message.from}: ${message.content.conversation}`);
+
+      // Reply
+      await manager.sendText(message.from, 'Thanks! 👋');
+    } else if (message.type === 'imageMessage') {
+      console.log(`📸 Image received from ${message.from}`);
+
+      // Send reaction
+      await manager.sendReaction(message.from, '👍', message.id);
+    }
+  });
+
+  // Handle acknowledgments
+  manager.onMessageAck((ack) => {
+    console.log(`✔️ Message ${ack.id}: ${ack.status}`);
+  });
+
+  // Handle QR code
+  manager.onQrCode((qr) => {
+    console.log('📱 Scan QR code to login');
+    // Display in UI or use terminal
+  });
+
+  // Connection status
+  manager.onConnectionStatus((status) => {
+    console.log(`🔌 ${status}`);
+  });
+
+  // Graceful shutdown
+  process.on('SIGINT', async () => {
+    console.log('\n👋 Closing...');
+    await manager.logout();
+    process.exit(0);
+  });
+
+  // Create session and connect
+  await manager.createSession(session);
+  console.log('🚀 Running...');
+}
+
+main().catch(console.error);
+```
+
+## Authentication Methods
+
+### QR Code (Recommended)
+
+```typescript
+const session: Session = {
+  session: 'my_session',
+  phoneNumber: '5511999999999',
+  licensePath: './license.json',
+  qrCode: true,
+  qrPrintTerminal: true,
+  pairingCode: false,
+};
+
+manager.onQrCode((qr) => {
+  // Display QR in UI or mobile app
+});
+
+await manager.createSession(session);
+```
+
+### Pairing Code
+
+```typescript
+const session: Session = {
+  session: 'my_session',
+  phoneNumber: '5511999999999',
+  licensePath: './license.json',
+  pairingCode: true,
+  qrCode: false,
+};
+
+manager.onPairingCode((code) => {
+  console.log(`Enter code in WhatsApp: ${code}`);
+});
+
+await manager.createSession(session);
+```
+
+## License
+
+This library requires a valid license file. Place your `license.json` in the specified path.
+
+```typescript
+licensePath: './license.json';
+```
+
+## Error Handling
+
+All methods return a `Response` object:
+
+```typescript
+const response = await manager.sendText('5511999999999', 'Hello');
+
+if (response.status === 200) {
+  console.log('Success:', response.content);
+} else {
+  console.error('Error:', response.message);
+}
+```
+
+### Common Error Codes
+
+- **400** — Bad request or invalid parameters
+- **401** — Unauthorized (invalid license)
+- **404** — Phone not found on WhatsApp
+- **500** — Internal server error
+
+## Best Practices
+
+1. **Session Management** — Create one manager per phone number
+2. **Error Handling** — Always check response.status
+3. **Rate Limiting** — Avoid sending too many messages in short time
+4. **Graceful Shutdown** — Call logout() before exit
+5. **Event Processing** — Keep listeners fast, use queues for heavy work
+6. **License Validation** — Ensure license.json is valid and accessible
+7. **Connection Monitoring** — Listen to onConnectionStatus events
+
+## Troubleshooting
+
+### QR Code Not Appearing
+
+- Ensure `qrCode: true` in session config
+- Check terminal output or UI integration
+- Verify browser environment for QR display
+
+### Session Not Persisting
+
+- Check `tokens/instance-${phoneNumber}/` directory exists
+- Verify write permissions
+- Ensure session name is consistent
+
+### Messages Not Sending
+
+- Validate recipient phone number format
+- Check connection status before sending
+- Verify license is valid
+
+### Reconnection Issues
+
+- Check network connectivity
+- Review max retries setting
+- Monitor onConnectionStatus events
+
+## Performance Tips
+
+1. **Reuse instances** — One SessionManager per phone number
+2. **Batch messages** — Send multiple messages efficiently
+3. **Monitor events** — Use onConnectionStatus to detect disconnections
+4. **Cache metadata** — Store group/contact info locally
+5. **Clean shutdown** — Proper logout frees resources
+
+## Disclaimer
+
+This library is **not affiliated with WhatsApp Inc. or Meta Platforms**. It's a reverse-engineered implementation based on Baileys. Users are responsible for compliance with WhatsApp's Terms of Service. Use at your own risk.
+
+## Related Projects
+
+- [Baileys](https://github.com/WhiskeySockets/Baileys) — The underlying protocol implementation
+- [easy-connect-official-wpp-rc](https://www.npmjs.com/package/easy-connect-official-wpp-rc) — Official WhatsApp Cloud API client
+
+## License
+
+ISC
+
+## Support
+
+For issues and questions:
+
+- Check existing GitHub issues
+- Review example usage in repository
+- Consult the logging system for debugging