@kangwifi-pro/waliwa 1.0.0

package/docs/API.md

@@ -0,0 +1,745 @@
+# Waliwa API Reference
+
+Complete API reference for Waliwa library.
+
+## Table of Contents
+
+- [makeWASocket](#makewasocket)
+- [useFileAuthState](#usefileauthstate)
+- [WASocket](#wasocket)
+  - [Events](#events)
+  - [Send Messages](#send-messages)
+  - [Media](#media)
+  - [Groups](#groups)
+  - [Calls](#calls)
+  - [Chat Operations](#chat-operations)
+  - [Presence](#presence)
+  - [Connection](#connection)
+- [Core APIs](#core-apis)
+- [Auth APIs](#auth-apis)
+- [Utility APIs](#utility-apis)
+
+---
+
+## makeWASocket
+
+Main entry point. Creates WhatsApp socket and auto-connects.
+
+```typescript
+import { makeWASocket, useFileAuthState } from 'waliwa';
+
+const { state } = await useFileAuthState('./auth');
+const sock = makeWASocket({
+  authState: state,
+  printQRInTerminal: true
+});
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| config | WaliwaConfig | Yes | Configuration object |
+
+### Returns
+
+`WASocket` instance (already connected asynchronously).
+
+---
+
+## useFileAuthState
+
+Initialize file-based auth state for persistent sessions.
+
+```typescript
+const { state, saveCreds } = await useFileAuthState('./auth-folder');
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| folder | string | Yes | Directory path for storing session files |
+| prefix | string | No | File prefix (default: 'waliwa-session') |
+| logger | WALogger | No | Logger instance |
+
+### Returns
+
+```typescript
+{
+  state: AuthState;
+  saveCreds: () => Promise<void>;
+}
+```
+
+---
+
+## WASocket
+
+The main socket interface for WhatsApp operations.
+
+### Events
+
+All events are emitted via `sock.ev.on(eventName, callback)`.
+
+#### connection.update
+
+```typescript
+sock.ev.on('connection.update', (update: ConnectionUpdate) => {
+  const { connection, lastDisconnect, qr, isNewLogin } = update;
+  // connection: 'close' | 'open' | 'connecting'
+});
+```
+
+#### message.upsert
+
+```typescript
+sock.ev.on('message.upsert', ({ messages, type }) => {
+  // type: 'append' (history sync) | 'notify' (new message)
+  for (const msg of messages) {
+    console.log(msg.key.remoteJid, msg.message?.text);
+  }
+});
+```
+
+#### message.update
+
+```typescript
+sock.ev.on('message.update', ({ messages, keys }) => {
+  for (const msg of messages) {
+    console.log(`Message ${msg.key.id} status: ${msg.status}`);
+  }
+});
+```
+
+#### message.reaction
+
+```typescript
+sock.ev.on('message.reaction', ({ key, reaction, sender }) => {
+  console.log(`${sender} reacted ${reaction} to ${key.id}`);
+});
+```
+
+#### presence.update
+
+```typescript
+sock.ev.on('presence.update', ({ jid, presence, t }) => {
+  console.log(`${jid} is ${presence}`);
+});
+```
+
+#### calls
+
+```typescript
+sock.ev.on('calls', (callEvent) => {
+  console.log(`Incoming ${callEvent.isVideo ? 'video' : 'voice'} call from ${callEvent.from}`);
+});
+```
+
+#### group-participants.update
+
+```typescript
+sock.ev.on('group-participants.update', (update) => {
+  const { id, participants, action, author } = update;
+  // action: 'add' | 'remove' | 'promote' | 'demote'
+});
+```
+
+#### qr.update
+
+```typescript
+sock.ev.on('qr.update', (qrData) => {
+  console.log('New QR:', qrData.qrString);
+});
+```
+
+#### pairing-code.update
+
+```typescript
+sock.ev.on('pairing-code.update', (result) => {
+  console.log(`Pairing code: ${result.code}`);
+});
+```
+
+---
+
+### Send Messages
+
+#### sendMessage
+
+```typescript
+const result = await sock.sendMessage(
+  jid: JIDLike,
+  content: MessageContent,
+  options?: { messageId?: string; participant?: string; timeoutMs?: number }
+);
+```
+
+**Examples:**
+
+```typescript
+// Text
+await sock.sendMessage(jid, { text: 'Hello!' });
+
+// Reply
+await sock.sendMessage(jid, {
+  text: 'Reply',
+  quoted: originalMessage
+});
+
+// Image with caption
+await sock.sendMessage(jid, {
+  image: { stream: buffer, mimetype: 'image/jpeg' },
+  caption: 'Photo caption'
+});
+
+// Mention users
+await sock.sendMessage(jid, {
+  text: 'Hi @user1 @user2',
+  mentions: ['6281@whatsapp.net', '6282@whatsapp.net']
+});
+
+// Poll
+await sock.sendMessage(jid, {
+  poll: {
+    name: 'Which one?',
+    values: ['A', 'B', 'C'],
+    selectableCounts: [1]
+  }
+});
+
+// Location
+await sock.sendMessage(jid, {
+  location: {
+    degreesLatitude: -6.2088,
+    degreesLongitude: 106.8456,
+    name: 'Jakarta'
+  }
+});
+
+// Contact card
+await sock.sendMessage(jid, {
+  contact: {
+    displayName: 'John Doe',
+    vcard: 'BEGIN:VCARD\nVERSION:3.0\nFN:John\nTEL:+62...\nEND:VCARD'
+  }
+});
+
+// View once media
+await sock.sendMessage(jid, {
+  image: { stream: buf, mimetype: 'image/jpeg' },
+  viewOnce: true
+});
+
+// Ephemeral (auto-delete after 7 days)
+await sock.sendMessage(jid, {
+  text: 'This disappears',
+  ephemeralExpiration: 604800
+});
+```
+
+#### forwardMessage
+
+```typescript
+await sock.forwardMessage(to, originalMessage);
+```
+
+#### deleteMessage
+
+```typescript
+// Delete for me only
+await sock.deleteMessage(jid, msgKey, { revokeEveryone: false });
+
+// Delete for everyone
+await sock.deleteMessage(jid, msgKey, { revokeEveryone: true });
+```
+
+#### reactToMessage
+
+```typescript
+await sock.reactToMessage(jid, msgKey, '👍');
+await sock.reactToMessage(jid, msgKey, ''); // Remove reaction
+```
+
+#### sendReadReceipt
+
+```typescript
+await sock.sendReadReceipt(jid, [messageId1, messageId2]);
+// For group messages:
+await sock.sendReadReceipt(groupJid, [messageId], senderJid);
+```
+
+#### sendPresenceUpdate
+
+```typescript
+// Typing indicator
+await sock.sendPresenceUpdate(jid, 'composing');
+
+// Voice recording indicator
+await sock.sendPresenceUpdate(jid, 'recording');
+
+// Stop typing
+await sock.sendPresenceUpdate(jid, 'paused');
+```
+
+#### updatePresence
+
+```typescript
+// Set yourself online
+await sock.updatePresence('available');
+
+// Set yourself offline
+await sock.updatePresence('unavailable');
+```
+
+---
+
+### Media
+
+#### uploadMedia
+
+```typescript
+import { readFileSync } from 'fs';
+const buffer = readFileSync('photo.jpg');
+
+const result = await sock.uploadMedia(
+  buffer,
+  'image',           // media type: 'image' | 'video' | 'audio' | 'document' | 'sticker'
+  'image/jpeg',      // mimetype
+  'photo.jpg'        // filename (optional, required for documents)
+);
+
+console.log(result.url, result.mediaKey, result.fileLength);
+```
+
+#### downloadMedia
+
+```typescript
+const result = await sock.downloadMedia(
+  msg.message.image.url,    // URL dari incoming message
+  msg.message.image.mediaKey,
+  'image',
+  msg.message.image.mimetype,
+  'downloaded.jpg'
+);
+
+import { writeFileSync } from 'fs';
+writeFileSync('photo.jpg', result.buffer);
+```
+
+---
+
+### Groups
+
+#### groupCreate
+
+```typescript
+const group = await sock.groupCreate({
+  subject: 'My Group',
+  participants: ['6281@s.whatsapp.net', '6282@s.whatsapp.net'],
+  desc: 'Group description'
+});
+```
+
+#### groupMetadata
+
+```typescript
+const metadata = await sock.groupMetadata(groupJid);
+console.log(metadata.subject, metadata.participants.length);
+
+// Check if user is admin
+const isAdmin = metadata.participants.find(
+  p => jidToString(p.id) === userJid
+)?.isAdmin;
+```
+
+#### Group Operations
+
+```typescript
+// Update subject
+await sock.groupUpdateSubject(groupJid, 'New Name');
+
+// Update description
+await sock.groupUpdateDescription(groupJid, 'New description');
+
+// Participant actions
+await sock.groupParticipantsUpdate(groupJid, [userJid], 'add');
+await sock.groupParticipantsUpdate(groupJid, [userJid], 'remove');
+await sock.groupParticipantsUpdate(groupJid, [userJid], 'promote');
+await sock.groupParticipantsUpdate(groupJid, [userJid], 'demote');
+
+// Invite links
+const code = await sock.groupInviteCode(groupJid);
+// → "AbCdEfGhIjK"
+const url = `https://chat.whatsapp.com/${code}`;
+
+await sock.groupRevokeInvite(groupJid); // Revoke old, get new code
+await sock.groupJoinViaCode('inviteCode'); // Join external group
+
+// Leave group
+await sock.groupLeave(groupJid);
+
+// Settings
+await sock.groupSettingUpdate(groupJid, 'restrict', true);  // Only admins send
+await sock.groupSettingUpdate(groupJid, 'announce', true);  // Only admins edit info
+```
+
+---
+
+### Calls
+
+```typescript
+sock.ev.on('calls', async (callEvent) => {
+  console.log(`Call from ${callEvent.from}`);
+  
+  // Auto reject all calls
+  await sock.rejectCall(callEvent.id, callEvent.from);
+});
+```
+
+---
+
+### Chat Operations
+
+#### readChat
+
+```typescript
+await sock.readChat(jid);
+```
+
+#### archiveChat
+
+```typescript
+await sock.archiveChat(jid, true);   // Archive
+await sock.archiveChat(jid, false);   // Unarchive
+```
+
+#### muteChat
+
+```typescript
+await sock.muteChat(jid, 60 * 60 * 1000); // Mute for 1 hour
+await sock.muteChat(jid, 7 * 24 * 60 * 60 * 1000); // Mute for 1 week
+await sock.muteChat(jid, 0); // Unmute
+```
+
+#### pinChat
+
+```typescript
+await sock.pinChat(jid, 7 * 24 * 60 * 60 * 1000); // Pin for 7 days
+await sock.pinChat(jid, 0); // Unpin
+```
+
+#### deleteChat
+
+```typescript
+await sock.deleteChat(jid);
+```
+
+---
+
+### Presence
+
+#### presenceSubscribe
+
+```typescript
+// Subscribe to presence updates for multiple users
+await sock.presenceSubscribe([
+  '6281@s.whatsapp.net',
+  '6282@s.whatsapp.net'
+]);
+
+// Listen to updates
+sock.ev.on('presence.update', ({ jid, presence }) => {
+  console.log(`${jid} is ${presence}`);
+  // presence: 'available' | 'unavailable' | 'composing' | 'recording' | 'paused'
+});
+```
+
+---
+
+### Connection
+
+#### end
+
+```typescript
+await sock.end();        // Close connection
+await sock.end(true);    // End and signal new connection needed
+```
+
+#### getConnectionState
+
+```typescript
+const state = sock.getConnectionState();
+// 'close' | 'open' | 'connecting'
+```
+
+#### logout
+
+```typescript
+await sock.logout();  // Logout and clear session files
+```
+
+#### refreshQR
+
+```typescript
+const newQR = await sock.refreshQR();
+console.log(newQR.qrString);
+```
+
+#### requestPairingCode
+
+```typescript
+const result = await sock.requestPairingCode('6281234567890');
+console.log(`Pairing code: ${result.code}`);
+// → "AB12-CD34"
+```
+
+---
+
+## Core APIs
+
+### Crypto
+
+```typescript
+import {
+  generateCurveKeyPair,
+  curveSharedSecret,
+  sha256Hash,
+  hmacSha256,
+  hkdfDerive,
+  createAESCipher,
+  aesEncryptCBC,
+  aesDecryptCBC,
+  getRandomBytes
+} from 'waliwa';
+
+const keypair = generateCurveKeyPair();
+const shared = curveSharedSecret(keypair.private, otherPublic);
+const hash = sha256Hash(data);
+const mac = hmacSha256(key, data);
+const derived = hkdfDerive(ikm, salt, info, 32);
+```
+
+### Noise Protocol
+
+```typescript
+import { NoiseHandshake, TrafficCipher } from 'waliwa';
+
+const handshake = new NoiseHandshake(staticKeyPair, true);
+const clientHello = handshake.buildClientHello(payload);
+// ... send to server, receive response ...
+handshake.readResponderHandshake(response);
+const { sendKey, recvKey } = handshake.finalize();
+
+const cipher = new TrafficCipher(sendKey, recvKey);
+const encrypted = cipher.encrypt(plaintext);
+const decrypted = cipher.decrypt(ciphertext);
+```
+
+### Binary Protocol
+
+```typescript
+import { encodeBinaryNode, decodeBinaryNode, binaryNodeToString } from 'waliwa';
+
+const node = {
+  tag: 'message',
+  attrs: { to: 'user@s.whatsapp.net', type: 'text' },
+  content: [{ tag: 'conversation', attrs: {}, content: 'Hello' }]
+};
+
+const bytes = encodeBinaryNode(node);
+const decoded = decodeBinaryNode(bytes);
+console.log(binaryNodeToString(decoded));
+```
+
+---
+
+## Auth APIs
+
+### FileAuthState
+
+```typescript
+import { FileAuthState, createDefaultCreds } from 'waliwa';
+
+const state = new FileAuthState({
+  folder: './auth',
+  prefix: 'session',
+  writeDebounceMs: 100
+});
+
+// Access creds
+console.log(state.creds.registered);
+
+// Save manually
+state.markCredsDirty();
+
+// Clear session (logout)
+await state.clear();
+
+// Manage pre-keys
+const preKey = state.generatePreKey(1);
+state.setPreKey(2, keyPair);
+```
+
+### QR Code Generation
+
+```typescript
+import { generateQRCodeData, buildQRString, parseQRString } from 'waliwa';
+
+const qrData = generateQRCodeData({
+  creds: state.creds,
+  printInTerminal: true
+});
+
+console.log(qrData.qrString);
+console.log(qrData.ref);
+console.log(qrData.publicKey);
+
+// Parse existing QR
+const parsed = parseQRString(qrData.qrString);
+```
+
+### Pairing Code
+
+```typescript
+import { generatePairingCode, normalizePairingCode } from 'waliwa';
+
+const result = generatePairingCode('6281234567890', state.creds);
+console.log(result.code); // "AB12-CD34"
+
+// Normalize user input
+const clean = normalizePairingCode('ab12cd34'); // "AB12-CD34"
+```
+
+---
+
+## Utility APIs
+
+### JID Utilities
+
+```typescript
+import {
+  parseJid,
+  jidToString,
+  isGroupJid,
+  isUserJid,
+  jidEqual,
+  userJid,
+  groupJid
+} from 'waliwa';
+
+const jid = parseJid('6281234567890@s.whatsapp.net');
+console.log(jid.user);    // "6281234567890"
+console.log(jid.server);  // "s.whatsapp.net"
+
+isGroupJid('12345@g.us'); // true
+isUserJid('6281@s.whatsapp.net'); // true
+jidEqual('6281@s.whatsapp.net', '6281@s.whatsapp.net'); // true
+
+userJid('6281234567890'); // "6281234567890@s.whatsapp.net"
+groupJid('12345-67890'); // "12345-67890@g.us"
+```
+
+### Logger
+
+```typescript
+import { DefaultLogger, SilentLogger, defaultLogger } from 'waliwa';
+
+const logger = new DefaultLogger('debug');
+logger.info('Hello');
+logger.child({ module: 'auth' }).debug('Sub-logger');
+
+// Silent logger (no output)
+const silent = new SilentLogger();
+```
+
+### Retry & Throttle
+
+```typescript
+import { retry, RateLimiter, sleep, debounce, throttle } from 'waliwa';
+
+// Retry with exponential backoff
+const result = await retry(async () => {
+  return await riskyOperation();
+}, {
+  retries: 5,
+  minTimeout: 500,
+  maxTimeout: 30000,
+  onFailedAttempt: (err, attempt) => console.log(`Attempt ${attempt} failed`)
+});
+
+// Rate limiter (20 ops/second)
+const limiter = new RateLimiter(20);
+await limiter.acquire();
+// do work
+
+// Debounce
+const debounced = debounce(() => save(), 100);
+
+// Throttle
+const throttled = throttle(() => send(), 1000);
+```
+
+---
+
+## Type Definitions
+
+All types are exported from the main package:
+
+```typescript
+import type {
+  // Auth
+  AuthState, AuthenticationCreds, KeyPair, SignalKeyStore,
+  
+  // Messages
+  MessageContent, WAMessage, WAMessageKey, MessageStatus,
+  
+  // Groups
+  WAGroupMetadata, WAGroupParticipant, GroupCreateOptions,
+  
+  // Calls
+  WACallEvent, CallStatus,
+  
+  // Connection
+  WaliwaConfig, ConnectionUpdate, WALogger,
+  
+  // JID
+  JID, JIDLike,
+  
+  // Events
+  WAEventMap,
+  
+  // Advanced
+  PollOptions, NewsletterMetadata, BusinessProfileOptions
+} from 'waliwa';
+```
+
+---
+
+## Error Handling
+
+All async operations may throw errors. Common error types:
+
+```typescript
+try {
+  await sock.sendMessage(jid, { text: 'Hello' });
+} catch (err) {
+  if (err.message.includes('timeout')) {
+    // Message send timeout
+  } else if (err.message.includes('not connected')) {
+    // WebSocket not connected
+  } else if (err.message.includes('rate limit')) {
+    // Rate limited
+  }
+}
+```
+
+For robust production usage, always wrap in try/catch and implement retry logic with exponential backoff.
+
+---
+
+## Version
+
+Current version: **1.0.0**
+
+For changelog and migration guides, see [CHANGELOG.md](../CHANGELOG.md).