@pakor/wacap-wrapper

v1.0.7

Published

3 months ago

Comprehensive TypeScript wrapper for Baileys WhatsApp Web API with multi-session support

0High
0Medium
0Low

pakoor

whatsapp baileys wrapper multi-session typescript whatsapp-api

Wacap Wrapper

Comprehensive TypeScript wrapper for Baileys WhatsApp Web API with multi-session support, flexible storage options, and easy-to-use event handling.

Features

✨ Easy to Use - Simple, intuitive API for sends, groups, and lifecycle
🔄 Multi-Session Support - Manage hundreds of WhatsApp connections simultaneously
💾 Flexible Storage - SQLite (default, WAL) or Prisma (MySQL/PostgreSQL)
📡 Event Wrapper - Global + per-session events with normalized payloads
🔒 Type-Safe - Full TypeScript support with comprehensive type definitions
🛡️ SaaS Ready - Auto-reconnect with backoff, status tracking, and session loader
� QR Caode Options - Terminal, Base64, or both for flexible integration
📍 Rich Messages - Location, contacts, polls, reactions, and more
👥 Full Group Management - Create, update, invite codes, settings
🔐 Session Persistence - Sessions survive server restarts without re-login
📦 Auto Phone Format - Automatic JID formatting from phone numbers

Installation

npm i @pakor/wacap-wrapper

Dependencies

npm install @whiskeysockets/baileys pino better-sqlite3 qrcode-terminal qrcode eventemitter3

Optional: For Prisma Storage

npm install @prisma/client prisma

Quick Start

import { WacapWrapper, WacapEventType } from '@pakor/wacap-wrapper';

const wacap = new WacapWrapper({
  sessionsPath: './sessions',
  qrCode: { format: 'all' }, // terminal + base64
});

await wacap.init();

// Auto-load saved sessions (no re-scan QR needed!)
await wacap.sessions.startAll();

// Or start a new session
const session = await wacap.sessions.start('my-session');

// Listen for QR code
session.getEventManager().onQRCode((data) => {
  console.log('QR String:', data.qr);
  console.log('QR Base64:', data.qrBase64); // For web display
});

// Listen for messages
session.getEventManager().onMessageReceived(async (data) => {
  console.log('From:', data.from);
  console.log('Message:', data.body);
  
  // Auto-reply (phone number auto-formatted!)
  if (data.body === '!ping') {
    await wacap.send.text('my-session', data.from, 'Pong! 🏓');
  }
});

Phone Number Auto-Format

No need to manually format JIDs! The package handles it automatically:

// All these work the same:
await wacap.send.text('session', '08123456789', 'Hello!');
await wacap.send.text('session', '628123456789', 'Hello!');
await wacap.send.text('session', '+62 812-3456-789', 'Hello!');

// Groups are auto-detected:
await wacap.send.text('session', '123456789-1234567890', 'Hello group!');

// Manual formatting if needed:
import { formatJid } from '@pakor/wacap-wrapper';
formatJid('08123456789'); // '[email protected]'

QR Code Configuration

const wacap = new WacapWrapper({
  qrCode: {
    format: 'all',        // 'terminal' | 'base64' | 'raw' | 'all'
    width: 300,           // Base64 image width
    margin: 2,
    darkColor: '#000000',
    lightColor: '#ffffff',
  }
});

// Access QR in event
session.getEventManager().onQRCode((data) => {
  console.log(data.qr);       // Raw QR string
  console.log(data.qrBase64); // data:image/png;base64,...
});

Session Management

Stop vs Logout

| Method | Behavior | Use Case | |--------|----------|----------| | stop() | Disconnect, keep credentials | Server restart | | logout() | Logout from WhatsApp | User logout | | delete() | Logout + delete all data | Remove session |

// Stop (credentials preserved - no QR needed on restart)
await wacap.sessions.stop('my-session');

// Logout (need to scan QR again)
await wacap.logoutSession('my-session');

// Delete completely
await wacap.deleteSession('my-session');

// Graceful shutdown (all sessions preserved)
await wacap.destroy();

Sending Messages

Text Messages

await wacap.send.text('session', '08123456789', 'Hello!');

// With mentions
await wacap.send.text('session', 'group-id', 'Hello @user!', {
  mentions: ['08123456789']
});

Media Messages

// Image
await wacap.send.media('session', '08123456789', {
  url: 'https://example.com/image.jpg',
  mimetype: 'image/jpeg',
  caption: 'Check this out!'
});

// Document
await wacap.send.media('session', '08123456789', {
  url: 'https://example.com/doc.pdf',
  mimetype: 'application/pdf',
  fileName: 'document.pdf'
});

Location

await wacap.send.location('session', '08123456789', -6.2088, 106.8456, {
  name: 'Monas',
  address: 'Jakarta, Indonesia'
});

Contacts

// Single contact
await wacap.send.contact('session', '08123456789', {
  name: 'John Doe',
  phone: '+628123456789'
});

// Multiple contacts
await wacap.send.contacts('session', '08123456789', [
  { name: 'John', phone: '+628111' },
  { name: 'Jane', phone: '+628222' }
]);

Reactions

await wacap.send.reaction('session', '08123456789', 'MESSAGE_ID', '👍');

Polls

await wacap.send.poll('session', '08123456789', 'Favorite color?', [
  'Red', 'Blue', 'Green'
], 1); // single choice

Contact Management

// Check if number is on WhatsApp
const result = await wacap.contacts.check('session', '08123456789');
// { exists: true, jid: '[email protected]' }

// Check multiple numbers
const results = await wacap.contacts.checkMultiple('session', ['08111', '08222']);

// Get profile picture
const url = await wacap.contacts.getProfilePicture('session', '08123456789');

// Block/unblock
await wacap.contacts.block('session', '08123456789');
await wacap.contacts.unblock('session', '08123456789');

Chat Management

// Mark as read
await wacap.chat.markAsRead('session', '08123456789', ['MSG_ID_1', 'MSG_ID_2']);

// Archive/unarchive
await wacap.chat.archive('session', '08123456789', true);

// Mute (timestamp in ms, null to unmute)
await wacap.chat.mute('session', '08123456789', Date.now() + 86400000);

// Pin/unpin
await wacap.chat.pin('session', '08123456789', true);

// Delete message
await wacap.chat.deleteMessage('session', '08123456789', 'MSG_ID', true); // for everyone

Group Management

// Create group
const group = await wacap.groups.create('session', 'Group Name', [
  '08123456789', '08987654321'
]);

// Manage participants
await wacap.groups.addParticipants('session', 'group-id', ['08111']);
await wacap.groups.removeParticipants('session', 'group-id', ['08111']);
await wacap.groups.promoteParticipants('session', 'group-id', ['08111']);
await wacap.groups.demoteParticipants('session', 'group-id', ['08111']);

// Get group info
const info = await wacap.groups.getInfo('session', 'group-id');

// Update group
await wacap.groups.updateSubject('session', 'group-id', 'New Name');
await wacap.groups.updateDescription('session', 'group-id', 'New description');

// Group settings
await wacap.groups.updateSettings('session', 'group-id', 'announcement'); // only admins send
await wacap.groups.updateSettings('session', 'group-id', 'not_announcement'); // everyone sends

// Invite codes
const code = await wacap.groups.getInviteCode('session', 'group-id');
await wacap.groups.revokeInviteCode('session', 'group-id');
await wacap.groups.joinViaCode('session', 'INVITE_CODE');

// Leave group
await wacap.groups.leave('session', 'group-id');

Profile Management

await wacap.profile.updateStatus('session', '🤖 Bot is online!');
await wacap.profile.updateName('session', 'My Bot');

Presence Management

// Online/offline
await wacap.presence.update('session', null, 'available');
await wacap.presence.update('session', null, 'unavailable');

// Typing indicator
await wacap.presence.update('session', '08123456789', 'composing');
await wacap.presence.update('session', '08123456789', 'paused');

// Recording indicator
await wacap.presence.update('session', '08123456789', 'recording');

Global Events

// Listen to ALL sessions at once
wacap.onGlobal(WacapEventType.MESSAGE_RECEIVED, (data) => {
  console.log(`[${data.sessionId}] ${data.body}`);
});

wacap.onGlobal(WacapEventType.QR_CODE, (data) => {
  console.log(`QR for ${data.sessionId}:`, data.qrBase64);
});

wacap.onGlobal(WacapEventType.CONNECTION_OPEN, (data) => {
  console.log(`${data.sessionId} connected!`);
});

Event Types

enum WacapEventType {
  // Connection
  CONNECTION_UPDATE, CONNECTION_OPEN, CONNECTION_CLOSE, QR_CODE,
  
  // Messages
  MESSAGE_RECEIVED, MESSAGE_SENT, MESSAGE_UPDATE, MESSAGE_DELETE,
  
  // Chats
  CHAT_UPDATE, CHAT_DELETE,
  
  // Contacts & Groups
  CONTACT_UPDATE, GROUP_UPDATE, GROUP_PARTICIPANTS_UPDATE,
  
  // Others
  PRESENCE_UPDATE, CALL,
  
  // Session lifecycle
  SESSION_START, SESSION_STOP, SESSION_ERROR,
}

HTTP Server Example

The package includes a complete HTTP server example with REST API:

npx ts-node examples/example-ussage.ts

Endpoints:

POST /sessions - Create session
GET /sessions - List sessions
GET /qr/:id - Get QR code (JSON with base64)
GET /qr/:id/image - Get QR as PNG image
POST /send/text - Send text message
POST /send/media - Send media
POST /send/location - Send location
POST /send/contact - Send contact
POST /send/poll - Send poll
POST /contacts/check - Check WhatsApp number
And more...

See examples/API-ENDPOINTS.md for full documentation.

Storage Options

SQLite (Default)

Zero configuration
File-based, perfect for small-medium deployments
WAL mode for better performance

Prisma (MySQL/PostgreSQL)

import { PrismaClient } from '@prisma/client';

const wacap = new WacapWrapper({
  storageAdapter: 'prisma',
  prismaClient: new PrismaClient(),
});

Configuration

interface WacapConfig {
  sessionsPath?: string;              // './sessions'
  storageAdapter?: 'sqlite' | 'prisma';
  debug?: boolean;
  logger?: { level: string };
  prismaClient?: any;
  qrCode?: {
    format?: 'terminal' | 'base64' | 'raw' | 'all';
    width?: number;
    margin?: number;
    darkColor?: string;
    lightColor?: string;
  };
  browser?: [string, string, string];
  connectionTimeout?: number;         // 60000
  maxRetries?: number;                // 5
}

Examples

examples/basic-usage.ts - Basic usage
examples/complete-features.ts - All features demo
examples/prisma-usage.ts - Prisma storage
examples/example-ussage.ts - HTTP server with auto-reply bot

Documentation

API.md - Full API documentation
examples/API-ENDPOINTS.md - HTTP endpoints

License

MIT License

Credits

Built on Baileys.

Disclaimer

Not affiliated with WhatsApp or Meta. Use responsibly.