whalibmob 3.3.1 → 4.4.0

package/README.md

@@ -1,297 +1,753 @@
-# whalibmob
+<div align='center'>whalibmob is a pure JavaScript Node.js library for interacting with the WhatsApp Mobile API.</div>
 
-> Pure JavaScript Node.js WhatsApp client library and CLI. Operates as a real mobile iOS device with full **Signal Protocol** end-to-end encryption, SenderKey group messaging, multi-device fanout, persistent sessions, and automatic reconnection. No native binaries — runs anywhere Node.js runs.
+##
 
----
+> [!CAUTION]
+> Use a dedicated phone number with this library. Connecting with a number that is already active on a real device will cause WhatsApp to log that device out.
 
-> **⚠️ IMPORTANT:** Use a **brand-new phone number** dedicated exclusively to this library. Using an existing WhatsApp account already active on a real phone will cause WhatsApp to revoke the session. Register a fresh number that has never been used with WhatsApp before.
+> [!IMPORTANT]
+> This project is not affiliated, associated, authorized, endorsed by, or in any way officially connected with WhatsApp or any of its subsidiaries or affiliates. "WhatsApp" and related names are registered trademarks of their respective owners. Use at your own discretion.
 
----
+- whalibmob does not require a browser, Selenium, or any other external runtime — it communicates directly with WhatsApp using a **TCP socket** and the **Noise Protocol** handshake.
+- The library operates as a real **iOS mobile device**, not as WhatsApp Web. It uses the Mobile API endpoint, which behaves differently from the Web API.
+- Signal Protocol encryption is **fully inlined** in pure JavaScript — no native binaries, no node-gyp, runs anywhere Node.js runs.
 
-## Requirements
+## Install
 
-- **Node.js 18** or higher
-- A phone number that can receive SMS or voice calls
+```sh
+npm install whalibmob
+```
 
----
+Install the CLI globally:
 
-## Global Installation
+```sh
+npm install -g whalibmob
+```
 
-Install once, use the `wa` command from anywhere on your system:
+## Index
+
+- [Connecting Account](#connecting-account)
+  - [Register a New Number](#register-a-new-number)
+  - [Connect](#connect)
+- [Saving & Restoring Sessions](#saving--restoring-sessions)
+- [Handling Events](#handling-events)
+  - [Example to Start](#example-to-start)
+  - [All Events](#all-events)
+- [Sending Messages](#sending-messages)
+  - [Text Message](#text-message)
+  - [Quote Message](#quote-message)
+  - [Mention User](#mention-user)
+  - [Reaction Message](#reaction-message)
+  - [Edit Message](#edit-message)
+  - [Delete Message](#delete-message)
+  - [Forward Message](#forward-message)
+  - [Media Messages](#media-messages)
+    - [Image Message](#image-message)
+    - [Video Message](#video-message)
+    - [Audio Message](#audio-message)
+    - [Voice Note](#voice-note)
+    - [Document Message](#document-message)
+    - [Sticker Message](#sticker-message)
+  - [Status / Stories](#status--stories)
+- [Send States in Chat](#send-states-in-chat)
+  - [Reading Messages](#reading-messages)
+  - [Update Presence](#update-presence)
+- [Modifying Chats](#modifying-chats)
+  - [Archive / Unarchive a Chat](#archive--unarchive-a-chat)
+  - [Mute / Unmute a Chat](#mute--unmute-a-chat)
+  - [Mark a Chat Read / Unread](#mark-a-chat-read--unread)
+  - [Pin / Unpin a Chat](#pin--unpin-a-chat)
+  - [Star / Unstar a Message](#star--unstar-a-message)
+  - [Disappearing Messages](#disappearing-messages)
+- [User Queries](#user-queries)
+  - [Check If a Number Has WhatsApp](#check-if-a-number-has-whatsapp)
+  - [Fetch Profile About](#fetch-profile-about)
+  - [Fetch Profile Picture](#fetch-profile-picture)
+  - [Subscribe to Presence](#subscribe-to-presence)
+- [Change Profile](#change-profile)
+  - [Change Display Name](#change-display-name)
+  - [Change About Text](#change-about-text)
+  - [Change Profile Picture](#change-profile-picture)
+- [Privacy](#privacy)
+  - [Block / Unblock User](#block--unblock-user)
+  - [Get Block List](#get-block-list)
+  - [Update Privacy Settings](#update-privacy-settings)
+  - [Update Default Disappearing Mode](#update-default-disappearing-mode)
+- [Groups](#groups)
+  - [Create a Group](#create-a-group)
+  - [Add / Remove or Demote / Promote](#add--remove-or-demote--promote)
+  - [Change Subject](#change-subject)
+  - [Change Description](#change-description)
+  - [Change Settings](#change-settings)
+  - [Leave a Group](#leave-a-group)
+  - [Get Invite Code](#get-invite-code)
+  - [Revoke Invite Code](#revoke-invite-code)
+  - [Join Using Invitation Code](#join-using-invitation-code)
+  - [Query Metadata](#query-metadata)
+  - [Get Request Join List](#get-request-join-list)
+  - [Approve / Reject Request Join](#approve--reject-request-join)
+  - [Toggle Ephemeral in Group](#toggle-ephemeral-in-group)
+- [CLI Reference](#cli-reference)
+  - [Interactive Shell](#interactive-shell)
+- [WhatsApp IDs](#whatsapp-ids)
+- [Transport](#transport)
+- [Media Encryption](#media-encryption)
+
+## Connecting Account
+
+### Register a New Number
+
+Registration is a one-time process. You need a phone number that can receive an SMS or voice call.
+
+**Step 1 — request a verification code**
 
-```bash
-npm install -g whalibmob
+```js
+const {
+  createNewStore, saveStore, requestSmsCode
+} = require('whalibmob')
+const path = require('path')
+const fs   = require('fs')
+
+const phone    = '919634847671'           // country code + number, no '+'
+const sessDir  = path.join(process.env.HOME, '.waSession')
+const sessFile = path.join(sessDir, phone + '.json')
+
+fs.mkdirSync(sessDir, { recursive: true })
+
+const store = createNewStore(phone)
+saveStore(store, sessFile)
+
+await requestSmsCode(store, 'sms')   // 'sms' | 'voice' | 'wa_old'
 ```
 
-Verify it works:
+**Step 2 — verify the code**
 
-```bash
-wa version
+```js
+const { loadStore, saveStore, verifyCode } = require('whalibmob')
+
+const store  = loadStore(sessFile)
+const result = await verifyCode(store, '123456')
+
+if (result.status === 'ok') {
+  saveStore(result.store, sessFile)
+  console.log('registered')
+}
 ```
 
----
+### Connect
 
-## Quick Start
+```js
+const { WhalibmobClient } = require('whalibmob')
+const path = require('path')
+
+const client = new WhalibmobClient({
+  sessionDir: path.join(process.env.HOME, '.waSession')
+})
 
-### 1 — Check if a number has WhatsApp
+client.on('connected', () => {
+  console.log('connected')
+})
 
-```bash
-wa registration --check 919634847671
+await client.init('919634847671')
 ```
 
-### 2 — Request a verification code
+## Saving & Restoring Sessions
+
+Sessions are automatically persisted to disk as JSON files under the `sessionDir` you provide. The file is named `<phone>.json`. On the next `client.init()` call the session is restored and no re-registration is needed.
+
+```js
+const client = new WhalibmobClient({
+  sessionDir: path.join(process.env.HOME, '.waSession')
+})
+
+// no need to register again — just connect
+await client.init('919634847671')
+```
+
+> [!NOTE]
+> Each phone number uses its own session file. The library handles Signal Protocol key persistence automatically.
+
+## Handling Events
+
+whalibmob uses the EventEmitter syntax for events.
+
+### Example to Start
+
+```js
+const { WhalibmobClient } = require('whalibmob')
+const path = require('path')
+
+async function connect() {
+  const client = new WhalibmobClient({
+    sessionDir: path.join(process.env.HOME, '.waSession')
+  })
+
+  client.on('connected', async () => {
+    console.log('connected')
+    await client.sendText('919634847671@s.whatsapp.net', 'Hello!')
+  })
+
+  client.on('disconnected', () => {
+    console.log('disconnected — reconnecting...')
+    setTimeout(() => connect(), 3000)
+  })
+
+  client.on('message', msg => {
+    console.log('message from', msg.from, msg.text)
+  })
 
-```bash
-# Via SMS (default)
-wa registration --request-code 919634847671
+  client.on('auth_failure', ({ reason }) => {
+    console.error('session revoked:', reason)
+    // re-register the number
+  })
 
-# Via voice call
-wa registration --request-code 919634847671 --method voice
+  await client.init('919634847671')
+}
 
-# Via an old WhatsApp account
-wa registration --request-code 919634847671 --method wa_old
+connect()
 ```
 
-### 3 — Register with the code you received
+### All Events
+
+| Event | Payload | Description |
+|---|---|---|
+| `connected` | — | Session authenticated and ready |
+| `disconnected` | — | Connection closed |
+| `reconnecting` | `{ attempt, delay }` | Lost connection, will retry |
+| `reconnected` | — | Connection restored |
+| `auth_failure` | `{ reason }` | Session revoked or banned |
+| `message` | message object | Incoming message received |
+| `receipt` | `{ type, id, from }` | Delivery / read / played receipt |
+| `presence` | `{ from, available, lastSeen }` | Contact came online or went offline |
+| `notification` | node object | Group or contact update notification |
+| `call` | `{ from }` | Incoming call event |
+| `error` | Error | Unhandled transport error |
+
+The message object contains:
 
-```bash
-wa registration --register 919634847671 --code 123456
+```js
+{
+  id:          string,   // message ID
+  from:        string,   // sender JID
+  participant: string,   // group sender JID (groups only)
+  ts:          number,   // Unix timestamp
+  text:        string,   // text body (plain text messages)
+  plaintext:   Buffer,   // decrypted raw payload
+  mediaType:   string    // 'image' | 'video' | 'audio' | 'document' | 'sticker'
+}
 ```
 
-### 4 — Connect
+## Sending Messages
+
+### Text Message
 
-```bash
-wa connect 919634847671
+```js
+await client.sendText('919634847671@s.whatsapp.net', 'Hello!')
 ```
 
-You will enter an interactive shell:
+### Quote Message
 
+```js
+// pass { quotedMsgId, quotedParticipant } in options
+await client.sendText(
+  '919634847671@s.whatsapp.net',
+  'This is a reply',
+  { quotedMsgId: 'ABCDEF123456', quotedParticipant: '919634847671@s.whatsapp.net' }
+)
 ```
-wa> /send 911234567890@s.whatsapp.net Hello!
-wa> /presence
-wa> /presence away
-wa> /quit
+
+### Mention User
+
+```js
+await client.sendText(
+  '120363000000000000@g.us',
+  '@919634847671 hello!',
+  { mentions: ['919634847671@s.whatsapp.net'] }
+)
 ```
 
----
+### Reaction Message
 
-## CLI Reference
+```js
+// react to a message
+await client.sendReaction('919634847671@s.whatsapp.net', 'MSGID123', '👍')
 
-### Registration
+// remove a reaction — pass empty string
+await client.sendReaction('919634847671@s.whatsapp.net', 'MSGID123', '')
+```
 
-| Command | Description |
-|---|---|
-| `wa registration --check <phone>` | Check if a number has WhatsApp |
-| `wa registration --request-code <phone>` | Request SMS verification code |
-| `wa registration --request-code <phone> --method voice` | Request code via voice call |
-| `wa registration --request-code <phone> --method wa_old` | Request code via old WA account |
-| `wa registration --register <phone> --code <code>` | Complete registration |
+### Edit Message
 
-### Connection
+> [!NOTE]
+> Editing is only possible within 15 minutes of the original send.
 
-| Command | Description |
-|---|---|
-| `wa connect <phone>` | Connect and open interactive shell |
-| `wa listen <phone>` | Connect and print all incoming messages |
+```js
+await client.editMessage(
+  'MSGID123',                           // original message ID
+  '919634847671@s.whatsapp.net',
+  'Corrected text here'
+)
+```
+
+### Delete Message
+
+```js
+// delete for yourself only
+await client.deleteMessage('MSGID123', '919634847671@s.whatsapp.net', true, false)
+
+// delete for everyone (revoke)
+await client.deleteMessage('MSGID123', '919634847671@s.whatsapp.net', true, true)
+```
+
+### Forward Message
+
+```js
+await client.forwardMessage('919634847671@s.whatsapp.net', 'text to forward')
+```
+
+## Media Messages
+
+### Image Message
+
+```js
+// from file path
+await client.sendImage('919634847671@s.whatsapp.net', './photo.jpg', { caption: 'Look at this' })
+
+// from Buffer
+await client.sendImage('919634847671@s.whatsapp.net', buffer, {
+  caption: 'Photo',
+  mimetype: 'image/jpeg'
+})
+```
+
+### Video Message
+
+```js
+await client.sendVideo('919634847671@s.whatsapp.net', './clip.mp4', { caption: 'Watch this' })
+```
+
+### Audio Message
+
+```js
+await client.sendAudio('919634847671@s.whatsapp.net', './song.mp3')
+```
+
+### Voice Note
+
+```js
+// ptt: true renders the audio as a push-to-talk voice note with waveform
+await client.sendAudio('919634847671@s.whatsapp.net', './voice.ogg', { ptt: true })
+```
+
+### Document Message
+
+```js
+await client.sendDocument('919634847671@s.whatsapp.net', './report.pdf', {
+  fileName: 'Q1 Report.pdf'
+})
+```
+
+### Sticker Message
 
-### Sending Messages
+```js
+await client.sendSticker('919634847671@s.whatsapp.net', './sticker.webp')
+```
 
-```bash
-# Text message
-wa send <phone> --to <jid> --text "Hello!"
+## Status / Stories
+
+```js
+// post a text Status to status@broadcast
+await client.sendStatus('Good morning!')
+```
 
-# Image (with optional caption)
-wa send <phone> --to <jid> --image ./photo.jpg --caption "Check this out"
+## Send States in Chat
 
-# Video (with optional caption)
-wa send <phone> --to <jid> --video ./clip.mp4 --caption "Watch this"
+### Reading Messages
 
-# Voice note (push-to-talk)
-wa send <phone> --to <jid> --ptt ./voice.ogg
+```js
+// mark the last message in a chat as read
+client.markChatRead('919634847671@s.whatsapp.net')
+```
 
-# Audio file
-wa send <phone> --to <jid> --audio ./song.mp3
+### Update Presence
 
-# Document
-wa send <phone> --to <jid> --document ./report.pdf
+```js
+// set yourself as online / offline globally
+client.setOnline(true)
+client.setOnline(false)
+
+// show typing or recording in a specific chat
+client.setChatPresence('919634847671@s.whatsapp.net', 'composing')   // typing
+client.setChatPresence('919634847671@s.whatsapp.net', 'recording')   // recording audio
+client.setChatPresence('919634847671@s.whatsapp.net', 'paused')      // stopped
+```
 
-# Sticker
-wa send <phone> --to <jid> --sticker ./sticker.webp
+## Modifying Chats
 
-# Emoji reaction
-wa send <phone> --to <jid> --reaction 👍 --msg-id 3EB0ABCDEF123456
+### Archive / Unarchive a Chat
 
-# Group message
-wa send <phone> --to 120363000000000000@g.us --text "Hi everyone!"
+```js
+client.archiveChat('919634847671@s.whatsapp.net')
+client.unarchiveChat('919634847671@s.whatsapp.net')
 ```
 
-### JID Format
+### Mute / Unmute a Chat
+
+```js
+client.muteChat('919634847671@s.whatsapp.net', 8 * 60 * 60 * 1000)  // mute for 8 hours (ms)
+client.muteChat('919634847671@s.whatsapp.net', 0)                    // mute indefinitely
+client.unmuteChat('919634847671@s.whatsapp.net')
+```
+
+### Mark a Chat Read / Unread
+
+```js
+client.markChatRead('919634847671@s.whatsapp.net')
+client.markChatUnread('919634847671@s.whatsapp.net')
+```
+
+### Pin / Unpin a Chat
+
+```js
+client.pinChat('919634847671@s.whatsapp.net')
+client.unpinChat('919634847671@s.whatsapp.net')
+```
+
+### Star / Unstar a Message
+
+```js
+client.starMessage('MSGID123', '919634847671@s.whatsapp.net')
+client.unstarMessage('MSGID123', '919634847671@s.whatsapp.net')
+```
 
-| Target | JID |
+### Disappearing Messages
+
+| Duration | Seconds |
 |---|---|
-| Individual | `919634847671@s.whatsapp.net` |
-| Group | `120363000000000000@g.us` |
+| Off | 0 |
+| 24 hours | 86 400 |
+| 7 days | 604 800 |
+| 90 days | 7 776 000 |
 
-> Phone numbers must include the country code, without the `+` prefix.
+```js
+// set disappearing timer for a specific chat (DM or group)
+await client.changeEphemeralTimer('919634847671@s.whatsapp.net', 86400)
+await client.changeEphemeralTimer('120363000000000000@g.us', 604800)
 
-### All Options
+// remove disappearing messages
+await client.changeEphemeralTimer('919634847671@s.whatsapp.net', 0)
+```
 
-| Flag | Default | Description |
-|---|---|---|
-| `--session <dir>` | `~/.waSession` | Directory where session files are stored |
-| `--method` | `sms` | Verification method: `sms`, `voice`, or `wa_old` |
-| `--code` | — | Verification code received via SMS/voice |
-| `--to` | — | Recipient JID |
-| `--text` | — | Text message body |
-| `--caption` | — | Caption for image or video |
-| `--reaction` | — | Emoji to react with |
-| `--msg-id` | — | Message ID to react to (required with `--reaction`) |
+## User Queries
 
----
+### Check If a Number Has WhatsApp
 
-## Sessions
+```js
+const { checkNumberStatus } = require('whalibmob')
 
-Sessions are stored as JSON files in `~/.waSession/` by default.  
-Each phone number gets its own file: `~/.waSession/<phone>.json`.
+const result = await checkNumberStatus('919634847671')
+// result.status: 'registered' | 'registered_blocked' | 'not_registered' | 'cooldown' | 'unknown'
+console.log(result.status)
+```
 
-You only register once. After that, just connect:
+Check multiple numbers at once while connected:
 
-```bash
-wa connect 919634847671
+```js
+const results = await client.hasWhatsapp(['919634847671', '12345678901'])
+// returns array of JIDs that have WhatsApp
 ```
 
-To use a custom session directory:
+### Fetch Profile About
 
-```bash
-wa connect 919634847671 --session /data/my-sessions
-wa send   919634847671 --session /data/my-sessions --to 911234567890@s.whatsapp.net --text "Hi"
+```js
+const about = await client.queryAbout('919634847671@s.whatsapp.net')
+console.log(about)
 ```
 
----
+### Fetch Profile Picture
+
+```js
+const url = await client.queryPicture('919634847671@s.whatsapp.net')
+// also works for groups
+const groupUrl = await client.queryPicture('120363000000000000@g.us')
+```
 
-## Library API
+### Subscribe to Presence
 
 ```js
-const {
-  WhalibmobClient,
-  loadStore,
-  checkNumberStatus,
-  makeJid,
-  generateMessageId
-} = require('whalibmob');
+// triggers 'presence' events when the contact comes online or goes offline
+client.subscribeToPresence('919634847671@s.whatsapp.net')
+
+client.on('presence', ({ from, available, lastSeen }) => {
+  console.log(from, available ? 'online' : 'offline')
+})
 ```
 
-### Connect and send a message
+## Change Profile
+
+### Change Display Name
 
 ```js
-const { WhalibmobClient, loadStore } = require('whalibmob');
-const path = require('path');
+client.changeName('My Bot')
+```
 
-const sessionDir = path.join(process.env.HOME, '.waSession');
-const store = loadStore('919634847671', sessionDir);
+### Change About Text
 
-const client = new WhalibmobClient(store, { sessionDir });
+```js
+await client.changeAbout('Available 24/7')
+```
 
-client.on('connected', async () => {
-  await client.sendText('911234567890@s.whatsapp.net', 'Hello from whalibmob!');
-});
+### Change Profile Picture
 
-client.on('message', msg => {
-  console.log('Received:', msg);
-});
+```js
+// groups are also supported
+await client.changeProfilePicture('./avatar.jpg')
+await client.changeGroupPicture('120363000000000000@g.us', './group.jpg')
+```
+
+## Privacy
 
-client.on('disconnected', ({ reason }) => {
-  console.log('Disconnected:', reason);
-});
+### Block / Unblock User
 
-await client.connect();
+```js
+await client.blockContact('919634847671@s.whatsapp.net')
+await client.unblockContact('919634847671@s.whatsapp.net')
 ```
 
-### Send media
+### Get Block List
 
 ```js
-await client.sendImage   ('911234567890@s.whatsapp.net', './photo.jpg',   'Caption');
-await client.sendVideo   ('911234567890@s.whatsapp.net', './clip.mp4',    'Caption');
-await client.sendPtt     ('911234567890@s.whatsapp.net', './voice.ogg');
-await client.sendAudio   ('911234567890@s.whatsapp.net', './song.mp3');
-await client.sendDocument('911234567890@s.whatsapp.net', './report.pdf');
-await client.sendSticker ('911234567890@s.whatsapp.net', './sticker.webp');
+const list = await client.queryBlockList()
+console.log(list)   // [ '919634847671@s.whatsapp.net', ... ]
 ```
 
-### Check a number
+### Update Privacy Settings
 
 ```js
-const { checkNumberStatus } = require('whalibmob');
+// type:  'last_seen' | 'profile_picture' | 'status' | 'online' | 'read_receipts' | 'groups_add'
+// value: 'all' | 'contacts' | 'contact_blacklist' | 'none' | 'match_last_seen'
+
+await client.changePrivacySetting('last_seen',        'contacts')
+await client.changePrivacySetting('profile_picture',  'contacts')
+await client.changePrivacySetting('status',           'contacts')
+await client.changePrivacySetting('online',           'match_last_seen')
+await client.changePrivacySetting('read_receipts',    'none')
+await client.changePrivacySetting('groups_add',       'contacts')
+```
+
+### Update Default Disappearing Mode
 
-const result = await checkNumberStatus('919634847671');
-// result.status → 'registered' | 'registered_blocked' | 'not_registered' | 'cooldown' | 'unknown'
-console.log(result.status);
+```js
+// sets the default ephemeral timer for all new chats
+await client.changeNewChatsEphemeralTimer(86400)   // 1 day
+await client.changeNewChatsEphemeralTimer(0)       // off
 ```
 
-### Events
+## Groups
 
-| Event | Payload | Description |
-|---|---|---|
-| `connected` | — | Session authenticated and ready |
-| `disconnected` | `{ reason }` | Connection closed |
-| `auth_failure` | `{ reason }` | Auth failed (banned or session revoked) |
-| `message` | message object | Incoming message received |
-| `message.sent` | message object | Outgoing message confirmed by server |
-| `error` | Error | Unhandled transport error |
+### Create a Group
 
----
+```js
+const group = await client.createGroup('My Group', [
+  '919634847671@s.whatsapp.net',
+  '12345678901@s.whatsapp.net'
+])
+console.log('created group', group)
+```
 
-## Features
+### Add / Remove or Demote / Promote
 
-- **Mobile iOS fingerprint** — authentic iOS headers; WhatsApp servers treat it as an iPhone
-- **Signal Protocol E2E encryption** — X3DH key agreement, Double Ratchet for 1-to-1 messages, fully inlined (no native binaries, no GitHub dependencies)
-- **SenderKey group encryption** — efficient group messaging with chain-key advance and SKDM distribution
-- **Multi-device fanout** — messages delivered to every linked device of each recipient
-- **All media types** — images, video, audio, voice notes, documents, stickers
-- **Media encryption** — AES-256-CBC + HKDF-SHA256; files uploaded to WhatsApp CDN
-- **Emoji reactions** — react to any message by its ID
-- **Automatic reconnection** — exponential backoff (1 s → 2 → 4 → 8 → 15 → 30 s cap)
-- **Pre-key replenishment** — automatic upload when supply drops below threshold
-- **Persistent sessions** — JSON files on disk; no re-registration after restart
-- **Zero native dependencies** — pure JavaScript; works on Linux, macOS, Windows, Termux (Android)
+```js
+const groupJid = '120363000000000000@g.us'
 
----
+await client.addGroupParticipants(groupJid,     ['919634847671@s.whatsapp.net'])
+await client.removeGroupParticipants(groupJid,  ['919634847671@s.whatsapp.net'])
+await client.promoteGroupParticipants(groupJid, ['919634847671@s.whatsapp.net'])
+await client.demoteGroupParticipants(groupJid,  ['919634847671@s.whatsapp.net'])
+```
 
-## Reconnection Backoff
+### Change Subject
 
-| Attempt | Delay |
-|---|---|
-| 1 | 1 s |
-| 2 | 2 s |
-| 3 | 4 s |
-| 4 | 8 s |
-| 5 | 15 s |
-| 6+ | 30 s |
+```js
+await client.changeGroupSubject('120363000000000000@g.us', 'New Group Name')
+```
 
----
+### Change Description
 
-## Media Encryption Scheme
+```js
+await client.changeGroupDescription('120363000000000000@g.us', 'This is the group description')
+```
 
-1. A random 32-byte media key is generated.
-2. HKDF-SHA256 expands it into an IV, cipher key, and MAC key.
-3. The file is encrypted with AES-256-CBC.
-4. A 10-byte HMAC-SHA256 MAC is appended.
-5. The ciphertext is uploaded to WhatsApp CDN.
-6. The media key and CDN URL are embedded in the message envelope.
+### Change Settings
 
----
+```js
+// setting: 'edit_group_info' | 'send_messages' | 'add_participants' | 'approve_participants'
+// policy:  'admins' | 'all'
+
+await client.changeGroupSetting('120363000000000000@g.us', 'send_messages',   'admins')
+await client.changeGroupSetting('120363000000000000@g.us', 'edit_group_info', 'admins')
+await client.changeGroupSetting('120363000000000000@g.us', 'add_participants', 'all')
+```
+
+### Leave a Group
+
+```js
+await client.leaveGroup('120363000000000000@g.us')
+```
+
+### Get Invite Code
+
+```js
+const link = await client.queryGroupInviteLink('120363000000000000@g.us')
+// e.g. 'https://chat.whatsapp.com/AbCdEfGhIjK'
+console.log(link)
+```
+
+### Revoke Invite Code
+
+```js
+await client.revokeGroupInvite('120363000000000000@g.us')
+```
+
+### Join Using Invitation Code
+
+> [!NOTE]
+> Pass only the code portion — do not include `https://chat.whatsapp.com/`
+
+```js
+const jid = await client.acceptGroupInvite('AbCdEfGhIjK')
+console.log('joined', jid)
+```
+
+### Query Metadata
+
+```js
+const meta = await client.getGroupMetadata('120363000000000000@g.us')
+console.log(meta)
+```
+
+### Get Request Join List
+
+```js
+const pending = await client.queryGroupPendingParticipants('120363000000000000@g.us')
+console.log(pending)
+```
+
+### Approve / Reject Request Join
+
+```js
+await client.approveGroupParticipants('120363000000000000@g.us', [
+  '919634847671@s.whatsapp.net'
+])
+```
+
+### Toggle Ephemeral in Group
+
+```js
+await client.changeEphemeralTimer('120363000000000000@g.us', 86400)  // 1 day
+await client.changeEphemeralTimer('120363000000000000@g.us', 0)      // off
+```
+
+## CLI Reference
+
+```sh
+wa                                         open interactive shell
+wa connect <phone>                         connect and open interactive shell
+wa listen  <phone>                         connect and listen for messages (stay-alive)
+wa registration --request-code <phone>     request SMS verification code
+wa registration --request-code <phone> --method voice
+wa registration --request-code <phone> --method wa_old
+wa registration --register <phone> --code <code>
+wa registration --check <phone>
+wa version
+
+options:
+  --session <dir>    session directory (default: ~/.waSession)
+  --method           sms | voice | wa_old  (default: sms)
+```
+
+> [!TIP]
+> **The CLI shell never exits on its own.** It stays open after every command until you type `/quit` or press Ctrl+C. This includes after requesting or confirming a registration code.
+
+### Interactive Shell
+
+After connecting with `wa connect <phone>` a persistent prompt appears. All features of the library are available as commands:
+
+```
+/send    <jid> <text>                send text message
+/image   <jid> <file> [caption]      send image
+/video   <jid> <file> [caption]      send video
+/audio   <jid> <file>                send audio file
+/ptt     <jid> <file>                send voice note
+/doc     <jid> <file> [name]         send document
+/sticker <jid> <file>                send sticker
+/react   <jid> <msgId> <emoji>       react to message
+/edit    <jid> <msgId> <text>        edit a sent message
+/delete  <jid> <msgId> [all]         delete (add 'all' for everyone)
+/status  <text>                      post Status/Story
+/online  /offline                    set presence
+/typing  /recording /stop <jid>      typing indicators
+/read    /unread <jid>               mark chat
+/mute    /unmute <jid>               mute / unmute
+/pin     /unpin  <jid>               pin / unpin
+/archive /unarchive <jid>            archive / unarchive
+/star    /unstar <jid> <msgId>       star / unstar message
+/ephemeral <jid> <seconds>           set disappearing timer
+/block   /unblock <jid>              block / unblock
+/blocklist                           show blocked contacts
+/group create|leave|add|remove
+       |promote|demote|subject|desc
+       |invite|revoke|join|meta|settings ...
+/reg check|code|confirm ...          registration commands
+/privacy <type> <value>              change privacy setting
+/name <text>  /about <text>          update profile
+/session                             show session info
+/reconnect                           force reconnect
+/help                                show all commands
+/quit                                disconnect and exit
+```
+
+## WhatsApp IDs
+
+- Individual contacts: `[countrycode][number]@s.whatsapp.net`
+  - Example: `919634847671@s.whatsapp.net`
+- Groups: `[groupid]@g.us`
+  - Example: `120363000000000000@g.us`
+- Status broadcast: `status@broadcast`
+- Broadcast lists: `[timestamp]@broadcast`
+
+> [!NOTE]
+> Phone numbers must include the country code without the `+` prefix.
 
 ## Transport
 
-Uses **Noise_XX_25519_AESGCM_SHA256** over TCP to `g.whatsapp.net:443`:
+whalibmob uses **Noise_XX_25519_AESGCM_SHA256** over TCP to `g.whatsapp.net:443`:
 
 1. Client sends `ClientHello` with an ephemeral X25519 public key.
 2. Server replies `ServerHello` (ephemeral + encrypted static + payload).
 3. Three DH steps (EE, SE, SS) derive the final session keys.
 4. Client sends `ClientFinish` (encrypted static + encrypted payload).
-5. Library waits for server `<success>` before emitting `connected`, or `<failure>` for `auth_failure`.
+5. The library waits for a `<success>` stanza before emitting `connected`, or `<failure>` for `auth_failure`.
+
+Automatic reconnection uses exponential backoff:
+
+| Attempt | Delay |
+|---|---|
+| 1 | 1 s |
+| 2 | 2 s |
+| 3 | 4 s |
+| 4 | 8 s |
+| 5 | 15 s |
+| 6+ | 30 s |
+
+## Media Encryption
 
----
+1. A random 32-byte **media key** is generated.
+2. HKDF-SHA256 expands it into IV, cipher key, and MAC key.
+3. The file is encrypted with **AES-256-CBC**.
+4. A 10-byte **HMAC-SHA256** MAC is appended.
+5. The ciphertext is uploaded to the WhatsApp CDN.
+6. The media key and CDN URL are embedded in the encrypted message envelope sent to the recipient.
 
 ## License