whalibmob 3.3.1 → 5.0.0

package/README.md

@@ -1,297 +1,1369 @@
-# whalibmob
+<div align='center'>whalibmob is a pure JavaScript Node.js library for interacting with the WhatsApp Mobile API.</div>
+<div align='center'>v5.0.0</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.
+
+## Install
+
+```sh
+npm install whalibmob
+```
+
+Install the CLI globally:
 
-## Requirements
+```sh
+npm install -g whalibmob
+```
 
-- **Node.js 18** or higher
-- A phone number that can receive SMS or voice calls
+## Index
+
+- [CLI — Getting Started](#cli--getting-started)
+  - [Install the CLI](#install-the-cli)
+  - [First-Time Setup: Register a Number](#first-time-setup-register-a-number)
+  - [Connect](#cli-connect)
+  - [Listen Mode](#listen-mode)
+- [CLI — Interactive Shell Commands](#cli--interactive-shell-commands)
+  - [Messaging Commands](#messaging-commands)
+    - [Send Text](#send-text)
+    - [Send Image](#send-image)
+    - [Send Video](#send-video)
+    - [Send Audio](#send-audio)
+    - [Send Voice Note](#send-voice-note)
+    - [Send Document](#send-document)
+    - [Send Sticker](#send-sticker)
+    - [React to a Message](#react-to-a-message)
+    - [Edit a Message](#edit-a-message)
+    - [Delete a Message](#delete-a-message)
+    - [Post a Status / Story](#post-a-status--story)
+    - [Forward a Message](#forward-a-message)
+  - [Presence Commands](#presence-commands)
+    - [Set Online / Offline](#set-online--offline)
+    - [Typing and Recording Indicators](#typing-and-recording-indicators)
+    - [Subscribe to a Contact's Presence](#subscribe-to-a-contacts-presence)
+  - [Profile Commands](#profile-commands)
+    - [Change Display Name](#cli-change-display-name)
+    - [Change About Text](#cli-change-about-text)
+    - [Change Privacy Settings](#cli-change-privacy-settings)
+  - [Chat Management Commands](#chat-management-commands)
+    - [Mark Read / Unread](#mark-read--unread)
+    - [Mute / Unmute](#mute--unmute)
+    - [Pin / Unpin](#pin--unpin)
+    - [Archive / Unarchive](#archive--unarchive)
+    - [Star / Unstar a Message](#star--unstar-a-message-cli)
+    - [Disappearing Messages](#cli-disappearing-messages)
+    - [Block / Unblock](#block--unblock)
+    - [Show Block List](#show-block-list)
+  - [Group Commands](#group-commands)
+    - [Create a Group](#cli-create-a-group)
+    - [Leave a Group](#cli-leave-a-group)
+    - [Add / Remove Participants](#add--remove-participants)
+    - [Promote / Demote Admins](#promote--demote-admins)
+    - [Change Group Name](#change-group-name)
+    - [Change Group Description](#change-group-description)
+    - [Get Invite Link](#get-invite-link)
+    - [Revoke Invite Link](#revoke-invite-link)
+    - [Join a Group by Invite Code](#join-a-group-by-invite-code)
+    - [Query Group Metadata](#query-group-metadata)
+    - [Group Settings](#group-settings)
+  - [Registration Commands (in-shell)](#registration-commands-in-shell)
+  - [Connection Commands (in-shell)](#connection-commands-in-shell)
+  - [Full Command Reference Table](#full-command-reference-table)
+- [Library API](#library-api)
+  - [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)
+- [WhatsApp IDs](#whatsapp-ids)
+- [Transport](#transport)
+- [Media Encryption](#media-encryption)
 
 ---
 
-## Global Installation
+## Library API
 
-Install once, use the `wa` command from anywhere on your system:
+## Connecting Account
 
-```bash
-npm install -g whalibmob
+### 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**
+
+```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
+
+```js
+const { WhalibmobClient } = require('whalibmob')
+const path = require('path')
 
-## Quick Start
+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')
+```
+
+## 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)
+  })
+
+  client.on('auth_failure', ({ reason }) => {
+    console.error('session revoked:', reason)
+    // re-register the number
+  })
+
+  await client.init('919634847671')
+}
+
+connect()
+```
+
+### 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:
+
+```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'
+}
+```
+
+## Sending Messages
+
+### Text Message
+
+```js
+await client.sendText('919634847671@s.whatsapp.net', 'Hello!')
+```
+
+### 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' }
+)
+```
+
+### Mention User
+
+```js
+await client.sendText(
+  '120363000000000000@g.us',
+  '@919634847671 hello!',
+  { mentions: ['919634847671@s.whatsapp.net'] }
+)
+```
+
+### Reaction Message
+
+```js
+// react to a message
+await client.sendReaction('919634847671@s.whatsapp.net', 'MSGID123', '👍')
+
+// remove a reaction — pass empty string
+await client.sendReaction('919634847671@s.whatsapp.net', 'MSGID123', '')
+```
+
+### Edit Message
+
+> [!NOTE]
+> Editing is only possible within 15 minutes of the original send.
+
+```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')
 ```
 
-### 2 — Request a verification code
+## 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
+
+```js
+await client.sendSticker('919634847671@s.whatsapp.net', './sticker.webp')
+```
+
+## Status / Stories
+
+```js
+// post a text Status to status@broadcast
+await client.sendStatus('Good morning!')
+```
+
+## Send States in Chat
+
+### Reading Messages
+
+```js
+// mark the last message in a chat as read
+client.markChatRead('919634847671@s.whatsapp.net')
+```
+
+### Update Presence
+
+```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
+```
+
+## Modifying Chats
+
+### Archive / Unarchive a Chat
+
+```js
+client.archiveChat('919634847671@s.whatsapp.net')
+client.unarchiveChat('919634847671@s.whatsapp.net')
+```
+
+### 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')
+```
+
+### Disappearing Messages
+
+| Duration | Seconds |
+|---|---|
+| Off | 0 |
+| 24 hours | 86 400 |
+| 7 days | 604 800 |
+| 90 days | 7 776 000 |
+
+```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)
+
+// remove disappearing messages
+await client.changeEphemeralTimer('919634847671@s.whatsapp.net', 0)
+```
+
+## User Queries
+
+### Check If a Number Has WhatsApp
+
+```js
+const { checkNumberStatus } = require('whalibmob')
+
+const result = await checkNumberStatus('919634847671')
+// result.status: 'registered' | 'registered_blocked' | 'not_registered' | 'cooldown' | 'unknown'
+console.log(result.status)
+```
+
+Check multiple numbers at once while connected:
+
+```js
+const results = await client.hasWhatsapp(['919634847671', '12345678901'])
+// returns array of JIDs that have WhatsApp
+```
+
+### Fetch Profile About
+
+```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')
+```
+
+### Subscribe to Presence
+
+```js
+// 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')
+})
+```
+
+## Change Profile
+
+### Change Display Name
+
+```js
+client.changeName('My Bot')
+```
+
+### Change About Text
+
+```js
+await client.changeAbout('Available 24/7')
+```
+
+### Change Profile Picture
+
+```js
+// groups are also supported
+await client.changeProfilePicture('./avatar.jpg')
+await client.changeGroupPicture('120363000000000000@g.us', './group.jpg')
+```
+
+## Privacy
+
+### Block / Unblock User
+
+```js
+await client.blockContact('919634847671@s.whatsapp.net')
+await client.unblockContact('919634847671@s.whatsapp.net')
+```
+
+### Get Block List
+
+```js
+const list = await client.queryBlockList()
+console.log(list)   // [ '919634847671@s.whatsapp.net', ... ]
+```
+
+### Update Privacy Settings
+
+```js
+// 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
+
+```js
+// sets the default ephemeral timer for all new chats
+await client.changeNewChatsEphemeralTimer(86400)   // 1 day
+await client.changeNewChatsEphemeralTimer(0)       // off
+```
+
+## Groups
+
+### Create a Group
+
+```js
+const group = await client.createGroup('My Group', [
+  '919634847671@s.whatsapp.net',
+  '12345678901@s.whatsapp.net'
+])
+console.log('created group', group)
+```
+
+### Add / Remove or Demote / Promote
+
+```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'])
+```
+
+### Change Subject
+
+```js
+await client.changeGroupSubject('120363000000000000@g.us', 'New Group Name')
+```
+
+### Change Description
+
+```js
+await client.changeGroupDescription('120363000000000000@g.us', 'This is the group description')
+```
+
+### 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)
+```
 
-```bash
-# Via SMS (default)
+### 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 — Getting Started
+
+### Install the CLI
+
+Install whalibmob globally to get the `wa` command available from anywhere on your system:
+
+```sh
+npm install -g whalibmob
+```
+
+Verify the installation:
+
+```sh
+wa version
+```
+
+### First-Time Setup: Register a Number
+
+Registration is a one-time process. You need a phone number that can receive an SMS or voice call. **Use a dedicated number** — do not use a number already active on a real WhatsApp device.
+
+**Step 1 — request a verification code**
+
+```sh
+# via SMS (default)
 wa registration --request-code 919634847671
 
-# Via voice call
+# via voice call
 wa registration --request-code 919634847671 --method voice
 
-# Via an old WhatsApp account
+# via an old WhatsApp account
 wa registration --request-code 919634847671 --method wa_old
 ```
 
-### 3 — Register with the code you received
+The CLI sends the code request, prints the result, and then **stays open** in the interactive shell. You will see:
 
-```bash
+```
+requesting sms code for +919634847671...
+  status  sent
+  now run: wa registration --register 919634847671 --code <code>
+
+staying in shell — use /reg confirm 919634847671 <code> to complete
+wa>
+```
+
+**Step 2 — confirm the code you received**
+
+Either run the one-shot command:
+
+```sh
 wa registration --register 919634847671 --code 123456
 ```
 
-### 4 — Connect
+Or type it directly in the shell that stayed open:
+
+```sh
+wa> /reg confirm 919634847671 123456
+```
+
+On success you will see:
+
+```
+registered  session saved to /home/user/.waSession/919634847671.json
+now run: /connect 919634847671
+```
+
+**Check if a number already has WhatsApp**
+
+```sh
+wa registration --check 919634847671
+```
+
+Output:
+
+```
+checking +919634847671...
+  status  registered
+```
+
+Possible statuses: `registered` · `registered_blocked` · `not_registered` · `cooldown` · `unknown`
+
+### CLI Connect
 
-```bash
+After registering, connect with:
+
+```sh
 wa connect 919634847671
 ```
 
-You will enter an interactive shell:
+The shell opens with a persistent prompt:
 
 ```
-wa> /send 911234567890@s.whatsapp.net Hello!
-wa> /presence
-wa> /presence away
-wa> /quit
+connecting to +919634847671...
+connected as +919634847671
+wa +919634847671>
+```
+
+> [!TIP]
+> **The shell never exits on its own.** It stays open until you type `/quit` or press Ctrl+C. This is true for every command — registration, connection, sending messages — everything.
+
+Use a custom session directory with `--session`:
+
+```sh
+wa connect 919634847671 --session /data/my-sessions
+```
+
+### Listen Mode
+
+Connect and print all incoming events to the terminal. The process stays alive indefinitely until you press Ctrl+C:
+
+```sh
+wa listen 919634847671
+```
+
+Output as messages arrive:
+
+```
+connected  listening on +919634847671  (Ctrl+C to stop)
+  ────────────────────────────────────────────────────────
+  time                    2025-03-13 10:00:05
+  from                    919634847671@s.whatsapp.net
+  id                      3EB0ABCDEF123456
+  text                    Hello there!
 ```
 
 ---
 
-## CLI Reference
+## CLI — Interactive Shell Commands
 
-### Registration
+After running `wa connect <phone>`, every feature of the library is available as a `/command`. Type `/help` at any time to see all commands.
 
-| 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 |
+> [!NOTE]
+> JIDs can be written as plain phone numbers (e.g. `919634847671`) — the shell automatically appends `@s.whatsapp.net`. For groups, use the full `@g.us` JID.
 
-### Connection
+### Messaging Commands
 
-| Command | Description |
-|---|---|
-| `wa connect <phone>` | Connect and open interactive shell |
-| `wa listen <phone>` | Connect and print all incoming messages |
+#### Send Text
 
-### Sending Messages
+```sh
+wa> /send 919634847671@s.whatsapp.net Hello, how are you?
+sent  3EB0ABCDEF123456
 
-```bash
-# Text message
-wa send <phone> --to <jid> --text "Hello!"
+# to a group
+wa> /send 120363000000000000@g.us Hello everyone!
+```
 
-# Image (with optional caption)
-wa send <phone> --to <jid> --image ./photo.jpg --caption "Check this out"
+#### Send Image
 
-# Video (with optional caption)
-wa send <phone> --to <jid> --video ./clip.mp4 --caption "Watch this"
+```sh
+wa> /image 919634847671@s.whatsapp.net ./photo.jpg
+wa> /image 919634847671@s.whatsapp.net ./photo.jpg Look at this!
+```
 
-# Voice note (push-to-talk)
-wa send <phone> --to <jid> --ptt ./voice.ogg
+The second argument is the file path. The optional third argument is the caption.
 
-# Audio file
-wa send <phone> --to <jid> --audio ./song.mp3
+#### Send Video
 
-# Document
-wa send <phone> --to <jid> --document ./report.pdf
+```sh
+wa> /video 919634847671@s.whatsapp.net ./clip.mp4
+wa> /video 919634847671@s.whatsapp.net ./clip.mp4 Watch this
+```
 
-# Sticker
-wa send <phone> --to <jid> --sticker ./sticker.webp
+#### Send Audio
 
-# Emoji reaction
-wa send <phone> --to <jid> --reaction 👍 --msg-id 3EB0ABCDEF123456
+Sends the file as a regular audio attachment:
 
-# Group message
-wa send <phone> --to 120363000000000000@g.us --text "Hi everyone!"
+```sh
+wa> /audio 919634847671@s.whatsapp.net ./song.mp3
 ```
 
-### JID Format
+#### Send Voice Note
 
-| Target | JID |
-|---|---|
-| Individual | `919634847671@s.whatsapp.net` |
-| Group | `120363000000000000@g.us` |
+Sends the file as a push-to-talk voice note with waveform:
 
-> Phone numbers must include the country code, without the `+` prefix.
+```sh
+wa> /ptt 919634847671@s.whatsapp.net ./voice.ogg
+```
 
-### All Options
+#### Send Document
 
-| 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`) |
+```sh
+wa> /doc 919634847671@s.whatsapp.net ./report.pdf
+wa> /doc 919634847671@s.whatsapp.net ./report.pdf "Q1 Report.pdf"
+```
+
+The optional third argument overrides the displayed filename.
+
+#### Send Sticker
+
+The file must be in WebP format:
+
+```sh
+wa> /sticker 919634847671@s.whatsapp.net ./sticker.webp
+```
+
+#### React to a Message
+
+```sh
+wa> /react 919634847671@s.whatsapp.net 3EB0ABCDEF123456 👍
+
+# remove a reaction — pass a space or empty string
+wa> /react 919634847671@s.whatsapp.net 3EB0ABCDEF123456 " "
+```
+
+The message ID is shown in the incoming message display as `id`.
+
+#### Edit a Message
+
+> [!NOTE]
+> Editing is only possible within 15 minutes of the original send.
+
+```sh
+wa> /edit 919634847671@s.whatsapp.net 3EB0ABCDEF123456 Corrected text here
+```
+
+#### Delete a Message
+
+```sh
+# delete for yourself only
+wa> /delete 919634847671@s.whatsapp.net 3EB0ABCDEF123456
+
+# delete for everyone (revoke)
+wa> /delete 919634847671@s.whatsapp.net 3EB0ABCDEF123456 all
+```
+
+#### Post a Status / Story
+
+Posts a text Status visible to your contacts:
+
+```sh
+wa> /status Good morning everyone!
+```
+
+#### Forward a Message
+
+Sends a message with the forwarded flag set:
+
+```sh
+wa> /forward 919634847671@s.whatsapp.net This message was forwarded
+```
 
 ---
 
-## Sessions
+### Presence Commands
 
-Sessions are stored as JSON files in `~/.waSession/` by default.  
-Each phone number gets its own file: `~/.waSession/<phone>.json`.
+#### Set Online / Offline
 
-You only register once. After that, just connect:
+```sh
+wa> /online
+wa> /offline
+```
 
-```bash
-wa connect 919634847671
+#### Typing and Recording Indicators
+
+```sh
+# show "typing…" in a chat
+wa> /typing 919634847671@s.whatsapp.net
+
+# show "recording audio…" in a chat
+wa> /recording 919634847671@s.whatsapp.net
+
+# stop the indicator
+wa> /stop 919634847671@s.whatsapp.net
 ```
 
-To use a custom session directory:
+#### Subscribe to a Contact's Presence
 
-```bash
-wa connect 919634847671 --session /data/my-sessions
-wa send   919634847671 --session /data/my-sessions --to 911234567890@s.whatsapp.net --text "Hi"
+Subscribes to online/offline events for a contact. The shell will print presence updates as they arrive:
+
+```sh
+wa> /subscribe 919634847671@s.whatsapp.net
+subscribed to 919634847671@s.whatsapp.net
+
+# when they come online:
+  presence  919634847671@s.whatsapp.net  online
 ```
 
 ---
 
-## Library API
+### Profile Commands
 
-```js
-const {
-  WhalibmobClient,
-  loadStore,
-  checkNumberStatus,
-  makeJid,
-  generateMessageId
-} = require('whalibmob');
+#### CLI Change Display Name
+
+```sh
+wa> /name My Bot Name
+name updated
 ```
 
-### Connect and send a message
+#### CLI Change About Text
 
-```js
-const { WhalibmobClient, loadStore } = require('whalibmob');
-const path = require('path');
+```sh
+wa> /about Available 24/7 for support
+about updated
+```
 
-const sessionDir = path.join(process.env.HOME, '.waSession');
-const store = loadStore('919634847671', sessionDir);
+#### CLI Change Privacy Settings
 
-const client = new WhalibmobClient(store, { sessionDir });
+```sh
+wa> /privacy last_seen contacts
+wa> /privacy profile_picture contacts
+wa> /privacy status contacts
+wa> /privacy online match_last_seen
+wa> /privacy read_receipts none
+wa> /privacy groups_add contacts
+```
 
-client.on('connected', async () => {
-  await client.sendText('911234567890@s.whatsapp.net', 'Hello from whalibmob!');
-});
+Available types: `last_seen` · `profile_picture` · `status` · `online` · `read_receipts` · `groups_add`
 
-client.on('message', msg => {
-  console.log('Received:', msg);
-});
+Available values: `all` · `contacts` · `contact_blacklist` · `none` · `match_last_seen`
 
-client.on('disconnected', ({ reason }) => {
-  console.log('Disconnected:', reason);
-});
+---
+
+### Chat Management Commands
 
-await client.connect();
+#### Mark Read / Unread
+
+```sh
+wa> /read   919634847671@s.whatsapp.net
+wa> /unread 919634847671@s.whatsapp.net
 ```
 
-### Send media
+#### Mute / Unmute
 
-```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');
+```sh
+# mute for 60 minutes
+wa> /mute 919634847671@s.whatsapp.net 60
+
+# mute indefinitely
+wa> /mute 919634847671@s.whatsapp.net
+
+# unmute
+wa> /unmute 919634847671@s.whatsapp.net
 ```
 
-### Check a number
+#### Pin / Unpin
 
-```js
-const { checkNumberStatus } = require('whalibmob');
+```sh
+wa> /pin   919634847671@s.whatsapp.net
+wa> /unpin 919634847671@s.whatsapp.net
+```
+
+#### Archive / Unarchive
 
-const result = await checkNumberStatus('919634847671');
-// result.status → 'registered' | 'registered_blocked' | 'not_registered' | 'cooldown' | 'unknown'
-console.log(result.status);
+```sh
+wa> /archive   919634847671@s.whatsapp.net
+wa> /unarchive 919634847671@s.whatsapp.net
 ```
 
-### Events
+#### Star / Unstar a Message (CLI)
 
-| 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 |
+```sh
+wa> /star   919634847671@s.whatsapp.net 3EB0ABCDEF123456
+wa> /unstar 919634847671@s.whatsapp.net 3EB0ABCDEF123456
+```
+
+#### CLI Disappearing Messages
+
+| Duration | Seconds |
+|---|---|
+| Off | 0 |
+| 24 hours | 86400 |
+| 7 days | 604800 |
+| 90 days | 7776000 |
+
+```sh
+# set 1-day timer on a DM
+wa> /ephemeral 919634847671@s.whatsapp.net 86400
+
+# set 1-week timer on a group
+wa> /ephemeral 120363000000000000@g.us 604800
+
+# turn off
+wa> /ephemeral 919634847671@s.whatsapp.net 0
+```
+
+#### Block / Unblock
+
+```sh
+wa> /block   919634847671@s.whatsapp.net
+blocked  919634847671@s.whatsapp.net
+
+wa> /unblock 919634847671@s.whatsapp.net
+unblocked  919634847671@s.whatsapp.net
+```
+
+#### Show Block List
+
+```sh
+wa> /blocklist
+  blocked (2)
+    919634847671@s.whatsapp.net
+    12345678901@s.whatsapp.net
+```
 
 ---
 
-## Features
+### Group Commands
+
+#### CLI Create a Group
+
+```sh
+wa> /group create MyGroup 919634847671@s.whatsapp.net 12345678901@s.whatsapp.net
+creating group...
+created
+```
+
+#### CLI Leave a Group
+
+```sh
+wa> /group leave 120363000000000000@g.us
+left  120363000000000000@g.us
+```
+
+#### Add / Remove Participants
+
+```sh
+# add participants
+wa> /group add 120363000000000000@g.us 919634847671@s.whatsapp.net
 
-- **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)
+# remove participants
+wa> /group remove 120363000000000000@g.us 919634847671@s.whatsapp.net
+```
+
+Multiple participants can be listed, separated by spaces.
+
+#### Promote / Demote Admins
+
+```sh
+# promote to admin
+wa> /group promote 120363000000000000@g.us 919634847671@s.whatsapp.net
+
+# demote from admin
+wa> /group demote 120363000000000000@g.us 919634847671@s.whatsapp.net
+```
+
+#### Change Group Name
+
+```sh
+wa> /group subject 120363000000000000@g.us New Group Name
+subject updated
+```
+
+#### Change Group Description
+
+```sh
+wa> /group desc 120363000000000000@g.us This is the group for project updates
+description updated
+```
+
+#### Get Invite Link
+
+```sh
+wa> /group invite 120363000000000000@g.us
+  https://chat.whatsapp.com/AbCdEfGhIjKlMnOpQrStUv
+```
+
+#### Revoke Invite Link
+
+Invalidates the current invite link and generates a new one:
+
+```sh
+wa> /group revoke 120363000000000000@g.us
+invite link revoked
+```
+
+#### Join a Group by Invite Code
+
+Pass only the code part — do not include `https://chat.whatsapp.com/`:
+
+```sh
+wa> /group join AbCdEfGhIjKlMnOpQrStUv
+joined  120363000000000000@g.us
+```
+
+#### Query Group Metadata
+
+```sh
+wa> /group meta 120363000000000000@g.us
+  {
+    "id": "120363000000000000@g.us",
+    "subject": "My Group",
+    "desc": "Group description",
+    ...
+  }
+```
+
+#### Group Settings
+
+Controls who can send messages, edit group info, add participants, or requires approval to join:
+
+```sh
+# only admins can send messages
+wa> /group settings 120363000000000000@g.us send_messages admins
+
+# everyone can send messages
+wa> /group settings 120363000000000000@g.us send_messages all
+
+# only admins can edit group info
+wa> /group settings 120363000000000000@g.us edit_group_info admins
+
+# only admins can add participants
+wa> /group settings 120363000000000000@g.us add_participants admins
+
+# require admin approval for join requests
+wa> /group settings 120363000000000000@g.us approve_participants admins
+```
 
 ---
 
-## Reconnection Backoff
+### Registration Commands (in-shell)
 
-| Attempt | Delay |
-|---|---|
-| 1 | 1 s |
-| 2 | 2 s |
-| 3 | 4 s |
-| 4 | 8 s |
-| 5 | 15 s |
-| 6+ | 30 s |
+These commands work from within the shell — useful when you need to register a second number without closing the current session:
+
+```sh
+# check if a phone number has WhatsApp
+wa> /reg check 919634847671
+
+# request a verification code
+wa> /reg code 919634847671
+wa> /reg code 919634847671 voice
+wa> /reg code 919634847671 wa_old
+
+# confirm the code received
+wa> /reg confirm 919634847671 123456
+registered  session saved to /home/user/.waSession/919634847671.json
+now run: /connect 919634847671
+```
 
 ---
 
-## Media Encryption Scheme
+### Connection Commands (in-shell)
+
+```sh
+# connect to a number (while already in the shell)
+wa> /connect 919634847671
+
+# disconnect
+wa> /disconnect
+
+# force a reconnection
+wa> /reconnect
 
-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.
+# show current session info
+wa> /session
+  phone                   919634847671
+  name                    My Bot
+  session                 /home/user/.waSession
+
+# show all available commands
+wa> /help
+
+# disconnect and exit the shell
+wa> /quit
+```
 
 ---
 
+### Full Command Reference Table
+
+| Command | Description |
+|---|---|
+| `/send <jid> <text>` | Send a text message |
+| `/image <jid> <file> [caption]` | Send an image |
+| `/video <jid> <file> [caption]` | Send a video |
+| `/audio <jid> <file>` | Send an audio file |
+| `/ptt <jid> <file>` | Send a voice note (push-to-talk) |
+| `/doc <jid> <file> [name]` | Send a document |
+| `/sticker <jid> <file>` | Send a sticker (.webp) |
+| `/react <jid> <msgId> <emoji>` | React to a message |
+| `/edit <jid> <msgId> <text>` | Edit a sent message |
+| `/delete <jid> <msgId> [all]` | Delete a message (add `all` for everyone) |
+| `/status <text>` | Post a Status / Story |
+| `/forward <jid> <text>` | Send with forwarded flag |
+| `/online` | Set yourself as online |
+| `/offline` | Set yourself as offline |
+| `/typing <jid>` | Show typing indicator in a chat |
+| `/recording <jid>` | Show recording audio indicator |
+| `/stop <jid>` | Stop typing / recording |
+| `/subscribe <jid>` | Subscribe to a contact's presence |
+| `/name <text>` | Change your display name |
+| `/about <text>` | Change your bio / about text |
+| `/privacy <type> <value>` | Change a privacy setting |
+| `/read <jid>` | Mark chat as read |
+| `/unread <jid>` | Mark chat as unread |
+| `/mute <jid> [minutes]` | Mute a chat |
+| `/unmute <jid>` | Unmute a chat |
+| `/pin <jid>` | Pin a chat |
+| `/unpin <jid>` | Unpin a chat |
+| `/archive <jid>` | Archive a chat |
+| `/unarchive <jid>` | Unarchive a chat |
+| `/star <jid> <msgId>` | Star a message |
+| `/unstar <jid> <msgId>` | Unstar a message |
+| `/ephemeral <jid> <seconds>` | Set disappearing messages timer |
+| `/block <jid>` | Block a contact |
+| `/unblock <jid>` | Unblock a contact |
+| `/blocklist` | Show all blocked contacts |
+| `/group create <name> <jid...>` | Create a group |
+| `/group leave <jid>` | Leave a group |
+| `/group add <jid> <member...>` | Add participants |
+| `/group remove <jid> <member...>` | Remove participants |
+| `/group promote <jid> <member...>` | Promote to admin |
+| `/group demote <jid> <member...>` | Demote from admin |
+| `/group subject <jid> <name>` | Rename group |
+| `/group desc <jid> <text>` | Change group description |
+| `/group invite <jid>` | Get invite link |
+| `/group revoke <jid>` | Revoke invite link |
+| `/group join <code>` | Join group by invite code |
+| `/group meta <jid>` | Query group metadata |
+| `/group settings <jid> <setting> <policy>` | Change group setting |
+| `/reg check <phone>` | Check if number has WhatsApp |
+| `/reg code <phone> [method]` | Request verification code |
+| `/reg confirm <phone> <code>` | Complete registration |
+| `/connect <phone>` | Connect to WhatsApp |
+| `/disconnect` | Disconnect current session |
+| `/reconnect` | Force reconnection |
+| `/session` | Show session info |
+| `/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