whalibmob 5.1.5 → 5.1.8

package/README.md

@@ -53,7 +53,12 @@ npm install -g whalibmob
   - [Profile Commands](#profile-commands)
     - [Change Display Name](#cli-change-display-name)
     - [Change About Text](#cli-change-about-text)
+    - [Change Profile Picture](#cli-change-profile-picture)
     - [Change Privacy Settings](#cli-change-privacy-settings)
+  - [Contact Commands](#contact-commands)
+    - [Check Who Has WhatsApp](#check-who-has-whatsapp)
+    - [Get Profile Picture URL](#get-profile-picture-url)
+    - [Get Contact About Text](#get-contact-about-text)
   - [Chat Management Commands](#chat-management-commands)
     - [Mark Read / Unread](#mark-read--unread)
     - [Mute / Unmute](#mute--unmute)
@@ -61,6 +66,7 @@ npm install -g whalibmob
     - [Archive / Unarchive](#archive--unarchive)
     - [Star / Unstar a Message](#star--unstar-a-message-cli)
     - [Disappearing Messages](#cli-disappearing-messages)
+    - [Default Disappearing Timer](#default-disappearing-timer)
     - [Block / Unblock](#block--unblock)
     - [Show Block List](#show-block-list)
   - [Group Commands](#group-commands)
@@ -70,10 +76,15 @@ npm install -g whalibmob
     - [Promote / Demote Admins](#promote--demote-admins)
     - [Change Group Name](#change-group-name)
     - [Change Group Description](#change-group-description)
+    - [Change Group Picture](#change-group-picture)
     - [Get Invite Link](#get-invite-link)
     - [Revoke Invite Link](#revoke-invite-link)
     - [Join a Group by Invite Code](#join-a-group-by-invite-code)
+    - [List All Groups](#list-all-groups)
     - [Query Group Metadata](#query-group-metadata)
+    - [List Group Participants](#list-group-participants)
+    - [Pending Join Requests](#pending-join-requests)
+    - [Approve / Reject Join Requests](#approve--reject-join-requests)
     - [Group Settings](#group-settings)
   - [Registration Commands (in-shell)](#registration-commands-in-shell)
   - [Connection Commands (in-shell)](#connection-commands-in-shell)
@@ -86,6 +97,7 @@ npm install -g whalibmob
   - [Handling Events](#handling-events)
     - [Example to Start](#example-to-start)
     - [All Events](#all-events)
+  - [Receiving Media](#receiving-media)
   - [Sending Messages](#sending-messages)
     - [Text Message](#text-message)
     - [Quote Message](#quote-message)
@@ -94,6 +106,7 @@ npm install -g whalibmob
     - [Edit Message](#edit-message)
     - [Delete Message](#delete-message)
     - [Forward Message](#forward-message)
+    - [Poll](#poll)
     - [Media Messages](#media-messages)
       - [Image Message](#image-message)
       - [Video Message](#video-message)
@@ -126,6 +139,18 @@ npm install -g whalibmob
     - [Get Block List](#get-block-list)
     - [Update Privacy Settings](#update-privacy-settings)
     - [Update Default Disappearing Mode](#update-default-disappearing-mode)
+  - [Communities](#communities)
+    - [Create a Community](#create-a-community)
+    - [Deactivate / Delete a Community](#deactivate--delete-a-community)
+    - [Link Groups into a Community](#link-groups-into-a-community)
+    - [Unlink a Group from a Community](#unlink-a-group-from-a-community)
+  - [Newsletters (Channels)](#newsletters-channels)
+    - [Create a Newsletter](#create-a-newsletter)
+    - [Join / Leave a Newsletter](#join--leave-a-newsletter)
+    - [Query Newsletter Metadata](#query-newsletter-metadata)
+    - [Update Newsletter Description](#update-newsletter-description)
+    - [Post a Text Update to Your Newsletter](#post-a-text-update-to-your-newsletter)
+  - [Business Profile](#business-profile)
   - [Groups](#groups)
     - [Create a Group](#create-a-group)
     - [Add / Remove or Demote / Promote](#add--remove-or-demote--promote)
@@ -136,6 +161,7 @@ npm install -g whalibmob
     - [Get Invite Code](#get-invite-code)
     - [Revoke Invite Code](#revoke-invite-code)
     - [Join Using Invitation Code](#join-using-invitation-code)
+    - [Fetch All Groups](#fetch-all-groups)
     - [Query Metadata](#query-metadata)
     - [Get Request Join List](#get-request-join-list)
     - [Approve / Reject Request Join](#approve--reject-request-join)
@@ -248,7 +274,8 @@ async function connect() {
   })
 
   client.on('message', msg => {
-    console.log('message from', msg.from, msg.text)
+    const d = msg.decoded
+    if (d && d.type === 'text') console.log('message from', msg.from, d.text)
   })
 
   client.on('auth_failure', ({ reason }) => {
@@ -282,16 +309,167 @@ 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'
+  id:          string,   // unique message ID
+  from:        string,   // sender JID — may be a LID (e.g. '112345678901234@s.whatsapp.net')
+  participant: string,   // group member JID (groups only; equals from for DMs)
+  ts:          number,   // Unix timestamp (seconds)
+  node:        object,   // raw XML node — node.attrs.sender_pn holds the real phone JID
+  decoded:     object,   // structured payload — shape depends on message type (see below)
 }
 ```
 
+> [!NOTE]
+> WhatsApp Multi-Device uses **LID JIDs** internally. The `from` field may be a LID like
+> `112345678901234@s.whatsapp.net` rather than the real phone number. To get the actual
+> phone number JID always read `msg.node.attrs.sender_pn`:
+> ```js
+> const spn = msg.node.attrs.sender_pn         // { user: '919634847671', server: 's.whatsapp.net' }
+> const phoneJid = spn.user + '@s.whatsapp.net' // '919634847671@s.whatsapp.net'
+> ```
+
+The `decoded` object shape per message type:
+
+```js
+// Text
+{ type: 'text', text: string }
+
+// Image
+{ type: 'image', caption: string, url: string, mimetype: string, mediaKey: Buffer, directPath: string }
+
+// Video
+{ type: 'video', caption: string, url: string, mimetype: string, mediaKey: Buffer, directPath: string }
+
+// Audio (music file)
+{ type: 'audio', url: string, mimetype: string, mediaKey: Buffer, directPath: string }
+
+// Voice note (push-to-talk)
+{ type: 'voice', url: string, mimetype: string, mediaKey: Buffer, directPath: string }
+
+// Document
+{ type: 'document', fileName: string, url: string, mimetype: string, mediaKey: Buffer, directPath: string }
+
+// Sticker
+{ type: 'sticker', url: string, mimetype: string, mediaKey: Buffer, directPath: string }
+
+// Reaction
+{ type: 'reaction', emoji: string }
+
+// Protocol (revoke, ephemeral, etc.)
+{ type: 'protocol', subtype: string }
+```
+
+## Receiving Media
+
+When a media message arrives, `msg.decoded` contains a CDN `url` and a `mediaKey`.
+The actual file is stored encrypted on WhatsApp's CDN and must be downloaded and decrypted.
+
+**Decryption uses two steps:**
+1. HKDF-SHA256 expands `mediaKey` into IV, cipher key, and MAC key.
+2. AES-256-CBC decrypts the ciphertext; a 10-byte HMAC-SHA256 MAC is verified first.
+
+```js
+const crypto = require('crypto')
+const https  = require('https')
+const http   = require('http')
+const fs     = require('fs')
+const path   = require('path')
+
+// HKDF info strings per media type
+const MEDIA_HKDF_INFO = {
+  image:    'WhatsApp Image Keys',
+  video:    'WhatsApp Video Keys',
+  audio:    'WhatsApp Audio Keys',
+  voice:    'WhatsApp Audio Keys',
+  document: 'WhatsApp Document Keys',
+  sticker:  'WhatsApp Image Keys',
+}
+
+function deriveMediaKeys(mediaKey, mediaType) {
+  const info     = Buffer.from(MEDIA_HKDF_INFO[mediaType] || 'WhatsApp Image Keys', 'utf8')
+  const expanded = Buffer.from(crypto.hkdfSync('sha256', mediaKey, Buffer.alloc(0), info, 112))
+  return {
+    iv:        expanded.slice(0,  16),
+    cipherKey: expanded.slice(16, 48),
+    macKey:    expanded.slice(48, 80),
+  }
+}
+
+function decryptMedia(encrypted, mediaKey, mediaType) {
+  const { iv, cipherKey, macKey } = deriveMediaKeys(mediaKey, mediaType)
+  const ciphertext = encrypted.slice(0, -10)
+  const fileMac    = encrypted.slice(-10)
+
+  // Verify MAC
+  const hmac     = crypto.createHmac('sha256', macKey)
+  hmac.update(iv)
+  hmac.update(ciphertext)
+  const computed = hmac.digest().slice(0, 10)
+  if (!computed.equals(fileMac)) throw new Error('MAC mismatch — corrupt file or wrong key')
+
+  // Decrypt
+  const decipher = crypto.createDecipheriv('aes-256-cbc', cipherKey, iv)
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()])
+}
+
+function downloadBuffer(url) {
+  return new Promise((resolve, reject) => {
+    const lib = url.startsWith('https') ? https : http
+    const req = lib.get(url, { headers: { 'User-Agent': 'WhatsApp/2.23.24.83 A' } }, res => {
+      if (res.statusCode !== 200) { res.resume(); return reject(new Error('HTTP ' + res.statusCode)) }
+      const chunks = []
+      res.on('data',  c => chunks.push(c))
+      res.on('end',   () => resolve(Buffer.concat(chunks)))
+      res.on('error', reject)
+    })
+    req.on('error', reject)
+    req.setTimeout(30000, () => { req.destroy(); reject(new Error('timeout')) })
+  })
+}
+
+async function downloadAndDecrypt(msgId, mediaType, url, mediaKey, opts) {
+  const extensions = { image: '.jpg', video: '.mp4', audio: '.ogg', voice: '.ogg',
+                       document: '', sticker: '.webp' }
+  let ext = extensions[mediaType] || ''
+  if (mediaType === 'document' && opts && opts.fileName) ext = path.extname(opts.fileName) || '.bin'
+
+  const encrypted = await downloadBuffer(url)
+  const decrypted = decryptMedia(encrypted, mediaKey, mediaType)
+
+  const outPath = path.join('./media', msgId + ext)
+  fs.mkdirSync('./media', { recursive: true })
+  fs.writeFileSync(outPath, decrypted)
+  return outPath
+}
+```
+
+**Using it in the `message` event:**
+
+```js
+const MEDIA_TYPES = new Set(['image', 'video', 'audio', 'voice', 'document', 'sticker'])
+
+client.on('message', async msg => {
+  const d = msg.decoded
+  if (!d) return
+
+  // Resolve the real phone JID (works even with LID from-fields)
+  const spn       = msg.node && msg.node.attrs && msg.node.attrs.sender_pn
+  const senderJid = spn ? (spn.user + '@s.whatsapp.net') : msg.from
+
+  if (d.type === 'text') {
+    console.log('text from', senderJid, ':', d.text)
+  }
+
+  if (MEDIA_TYPES.has(d.type) && d.url && d.mediaKey) {
+    try {
+      const filePath = await downloadAndDecrypt(msg.id, d.type, d.url, d.mediaKey, { fileName: d.fileName })
+      console.log('saved', d.type, 'to', filePath)
+    } catch (e) {
+      console.error('media download failed:', e.message)
+    }
+  }
+})
+```
+
 ## Sending Messages
 
 ### Text Message
@@ -356,8 +534,33 @@ await client.deleteMessage('MSGID123', '919634847671@s.whatsapp.net', true, true
 
 ### Forward Message
 
+Forward text or a full media message (image, video, audio, document, sticker) without
+re-uploading.  Pass a decoded message object from the `message` event to forward any media type.
+
 ```js
+// Forward text
 await client.forwardMessage('919634847671@s.whatsapp.net', 'text to forward')
+
+// Forward any received message (full media, no re-upload)
+client.on('message', async (msg) => {
+  if (msg.decoded && msg.decoded.type !== 'text') {
+    await client.forwardMessage('919634847671@s.whatsapp.net', msg)
+  }
+})
+```
+
+### Poll
+
+Send a WhatsApp poll.  `selectableCount` is how many options a voter may choose (0 = any).
+
+```js
+const { id, encKey } = await client.sendPoll(
+  '919634847671@s.whatsapp.net',
+  'Best language?',
+  ['JavaScript', 'Python', 'Rust'],
+  1            // voters may pick 1 option (0 = unlimited)
+)
+// encKey (32-byte Buffer) is needed to decrypt incoming poll votes
 ```
 
 ## Media Messages
@@ -420,8 +623,8 @@ await client.sendStatus('Good morning!')
 ### Reading Messages
 
 ```js
-// mark the last message in a chat as read
-client.markChatRead('919634847671@s.whatsapp.net')
+// mark all messages in a chat as read (sends IQ to server)
+await client.markChatRead('919634847671@s.whatsapp.net')
 ```
 
 ### Update Presence
@@ -449,16 +652,16 @@ 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')
+await client.muteChat('919634847671@s.whatsapp.net', 8 * 60 * 60 * 1000)  // mute for 8 hours (ms)
+await client.muteChat('919634847671@s.whatsapp.net', 0)                    // mute indefinitely
+await client.unmuteChat('919634847671@s.whatsapp.net')
 ```
 
 ### Mark a Chat Read / Unread
 
 ```js
-client.markChatRead('919634847671@s.whatsapp.net')
-client.markChatUnread('919634847671@s.whatsapp.net')
+await client.markChatRead('919634847671@s.whatsapp.net')   // sends IQ to server
+client.markChatUnread('919634847671@s.whatsapp.net')       // local state only
 ```
 
 ### Pin / Unpin a Chat
@@ -554,10 +757,16 @@ await client.changeAbout('Available 24/7')
 
 ### Change Profile Picture
 
+Both methods accept a **Buffer** (use `fs.readFileSync` to load a file).
+
 ```js
-// groups are also supported
-await client.changeProfilePicture('./avatar.jpg')
-await client.changeGroupPicture('120363000000000000@g.us', './group.jpg')
+const fs = require('fs')
+
+// change your own profile picture
+await client.changeProfilePicture(fs.readFileSync('./avatar.jpg'))
+
+// change a group's picture (you must be admin)
+await client.changeGroupPicture('120363000000000000@g.us', fs.readFileSync('./group.jpg'))
 ```
 
 ## Privacy
@@ -602,12 +811,16 @@ await client.changeNewChatsEphemeralTimer(0)       // off
 
 ### Create a Group
 
+Returns the same metadata object as `getGroupMetadata` (jid, subject, participants, etc.).
+
 ```js
 const group = await client.createGroup('My Group', [
   '919634847671@s.whatsapp.net',
   '12345678901@s.whatsapp.net'
 ])
-console.log('created group', group)
+console.log('created', group.jid)       // '120363000000000000@g.us'
+console.log('subject', group.subject)   // 'My Group'
+console.log('members', group.participants.map(p => p.jid))
 ```
 
 ### Add / Remove or Demote / Promote
@@ -674,11 +887,24 @@ const jid = await client.acceptGroupInvite('AbCdEfGhIjK')
 console.log('joined', jid)
 ```
 
+### Fetch All Groups
+
+Returns an array of metadata objects for every group you are a member of. Each object has the same shape as `getGroupMetadata`.
+
+```js
+const groups = await client.fetchAllGroups()
+for (const g of groups) {
+  console.log(g.jid, g.subject, g.participants.length + ' members')
+}
+```
+
 ### Query Metadata
 
 ```js
 const meta = await client.getGroupMetadata('120363000000000000@g.us')
-console.log(meta)
+// returns: { jid, subject, creation, creator, subjectTime, subjectBy,
+//            description, ephemeral, onlyAdminsSend, onlyAdminsEdit, participants[] }
+console.log(meta.subject, meta.participants.length + ' members')
 ```
 
 ### Get Request Join List
@@ -690,8 +916,16 @@ console.log(pending)
 
 ### Approve / Reject Request Join
 
+The second parameter is a boolean: `true` to approve, `false` to reject.
+
 ```js
-await client.approveGroupParticipants('120363000000000000@g.us', [
+// approve join requests
+await client.approveGroupParticipants('120363000000000000@g.us', true, [
+  '919634847671@s.whatsapp.net'
+])
+
+// reject join requests
+await client.approveGroupParticipants('120363000000000000@g.us', false, [
   '919634847671@s.whatsapp.net'
 ])
 ```
@@ -703,6 +937,96 @@ await client.changeEphemeralTimer('120363000000000000@g.us', 86400)  // 1 day
 await client.changeEphemeralTimer('120363000000000000@g.us', 0)      // off
 ```
 
+## Communities
+
+WhatsApp Communities are a superset of groups — a parent container that can hold multiple linked
+sub-groups plus an automatic general-chat group.
+
+### Create a Community
+
+```js
+const community = await client.createCommunity('My Community', 'A place for discussion')
+// community.jid  — e.g. 120363000000000001@g.us
+```
+
+### Deactivate / Delete a Community
+
+```js
+await client.deactivateCommunity('120363000000000001@g.us')
+```
+
+### Link Groups into a Community
+
+```js
+const linked = await client.linkGroupsToCommunity(
+  '120363000000000001@g.us',          // community JID
+  ['120363000000000002@g.us',         // group JIDs to link
+   '120363000000000003@g.us']
+)
+```
+
+### Unlink a Group from a Community
+
+```js
+await client.unlinkGroupFromCommunity(
+  '120363000000000001@g.us',   // community JID
+  '120363000000000002@g.us'    // group JID
+)
+```
+
+## Newsletters (Channels)
+
+Newsletters are one-to-many broadcast channels.  Only the owner can post; anyone can subscribe.
+
+### Create a Newsletter
+
+```js
+const nl = await client.createNewsletter('Tech News', 'Daily updates on tech')
+// nl.jid — e.g. 120363000000000004@newsletter
+```
+
+### Join / Leave a Newsletter
+
+```js
+await client.joinNewsletter('120363000000000004@newsletter')
+await client.leaveNewsletter('120363000000000004@newsletter')
+```
+
+### Query Newsletter Metadata
+
+```js
+const meta = await client.queryNewsletterMetadata('120363000000000004@newsletter')
+// { jid, name, description, subscriberCount }
+```
+
+### Update Newsletter Description
+
+```js
+await client.changeNewsletterDescription('120363000000000004@newsletter', 'New description here')
+```
+
+### Post a Text Update to Your Newsletter
+
+```js
+await client.sendNewsletterText('120363000000000004@newsletter', 'Breaking: WhatsApp adds polls!')
+```
+
+## Business Profile
+
+Query the public business profile of any WhatsApp Business account:
+
+```js
+const bp = await client.queryBusinessProfile('919634847671@s.whatsapp.net')
+if (bp) {
+  console.log(bp.category)     // e.g. "Software & IT Services"
+  console.log(bp.email)        // business email (if set)
+  console.log(bp.website)      // business website (if set)
+  console.log(bp.address)      // physical address (if set)
+  console.log(bp.description)  // business description (if set)
+}
+// Returns null if the number is not a WhatsApp Business account
+```
+
 ## CLI — Getting Started
 
 ### Install the CLI
@@ -997,6 +1321,15 @@ wa> /about Available 24/7 for support
 about updated
 ```
 
+#### CLI Change Profile Picture
+
+Reads the image from disk and uploads it as your profile picture. Supported formats: JPEG, PNG.
+
+```sh
+wa> /photo ./avatar.jpg
+profile picture updated
+```
+
 #### CLI Change Privacy Settings
 
 ```sh
@@ -1014,6 +1347,43 @@ Available values: `all` · `contacts` · `contact_blacklist` · `none` · `match
 
 ---
 
+### Contact Commands
+
+#### Check Who Has WhatsApp
+
+Checks multiple phone numbers (plain digits, no `+`) and lists which ones are registered on WhatsApp:
+
+```sh
+wa> /whatsapp 919634847671 12345678901
+  has whatsapp (1)
+    919634847671@s.whatsapp.net
+  not found (1)
+    12345678901
+```
+
+#### Get Profile Picture URL
+
+Returns the CDN URL for a contact's or group's profile picture:
+
+```sh
+wa> /picture 919634847671@s.whatsapp.net
+  https://mmg.whatsapp.net/v/...
+
+wa> /picture 120363000000000000@g.us
+  https://mmg.whatsapp.net/v/...
+```
+
+#### Get Contact About Text
+
+Fetches the bio / about text for a contact:
+
+```sh
+wa> /contact about 919634847671@s.whatsapp.net
+  Available 24/7
+```
+
+---
+
 ### Chat Management Commands
 
 #### Mark Read / Unread
@@ -1077,6 +1447,21 @@ wa> /ephemeral 120363000000000000@g.us 604800
 wa> /ephemeral 919634847671@s.whatsapp.net 0
 ```
 
+#### Default Disappearing Timer
+
+Sets the global default ephemeral timer applied to all **new** chats:
+
+```sh
+wa> /ephemeral-default 86400
+default ephemeral set  86400
+
+# turn off
+wa> /ephemeral-default 0
+default ephemeral set  0
+```
+
+Accepts the same values as `/ephemeral`: 0, 86400, 604800, 7776000.
+
 #### Block / Unblock
 
 ```sh
@@ -1105,7 +1490,9 @@ wa> /blocklist
 ```sh
 wa> /group create MyGroup 919634847671@s.whatsapp.net 12345678901@s.whatsapp.net
 creating group...
-created
+created  120363000000000000@g.us
+  subject  MyGroup
+  members  919634847671@s.whatsapp.net, 12345678901@s.whatsapp.net
 ```
 
 #### CLI Leave a Group
@@ -1151,6 +1538,15 @@ wa> /group desc 120363000000000000@g.us This is the group for project updates
 description updated
 ```
 
+#### Change Group Picture
+
+Reads the image from disk and sets it as the group's profile picture. You must be an admin.
+
+```sh
+wa> /group photo 120363000000000000@g.us ./group-logo.jpg
+group picture updated
+```
+
 #### Get Invite Link
 
 ```sh
@@ -1180,14 +1576,66 @@ joined  120363000000000000@g.us
 
 ```sh
 wa> /group meta 120363000000000000@g.us
-  {
-    "id": "120363000000000000@g.us",
-    "subject": "My Group",
-    "desc": "Group description",
-    ...
-  }
+  jid              120363000000000000@g.us
+  subject          My Group
+  description      Group description here
+  creator          919634847671@s.whatsapp.net
+  created          2024-01-15 10:30:00
+  participants     3
+  onlyAdminsSend   false
+  onlyAdminsEdit   true
+  ephemeral        0
+```
+
+#### List All Groups
+
+Fetches all groups you are a member of and prints a numbered list:
+
+```sh
+wa> /groups
+  groups (3)
+    1  120363000000000000@g.us  My Project Group  (5 members)
+    2  120363111111111111@g.us  Family Chat        (12 members)
+    3  120363222222222222@g.us  Friends            (8 members)
+```
+
+#### List Group Participants
+
+Lists all participants of a group with their roles:
+
+```sh
+wa> /group participants 120363000000000000@g.us
+  participants (3)
+    919634847671@s.whatsapp.net  [admin]
+    12345678901@s.whatsapp.net
+    98765432109@s.whatsapp.net
 ```
 
+#### Pending Join Requests
+
+Lists users who have requested to join a group (only visible when `approve_participants` is enabled):
+
+```sh
+wa> /group pending 120363000000000000@g.us
+  pending (2)
+    919634847671@s.whatsapp.net
+    12345678901@s.whatsapp.net
+```
+
+#### Approve / Reject Join Requests
+
+```sh
+# approve one or more pending members
+wa> /group approve 120363000000000000@g.us 919634847671@s.whatsapp.net
+approved  919634847671@s.whatsapp.net
+
+# reject one or more pending members
+wa> /group reject 120363000000000000@g.us 919634847671@s.whatsapp.net
+rejected  919634847671@s.whatsapp.net
+```
+
+Multiple JIDs can be listed, separated by spaces.
+
 #### Group Settings
 
 Controls who can send messages, edit group info, add participants, or requires approval to join:
@@ -1263,6 +1711,7 @@ wa> /quit
 
 | Command | Description |
 |---|---|
+| **Messaging** | |
 | `/send <jid> <text>` | Send a text message |
 | `/image <jid> <file> [caption]` | Send an image |
 | `/video <jid> <file> [caption]` | Send a video |
@@ -1275,18 +1724,26 @@ wa> /quit
 | `/delete <jid> <msgId> [all]` | Delete a message (add `all` for everyone) |
 | `/status <text>` | Post a Status / Story |
 | `/forward <jid> <text>` | Send with forwarded flag |
+| **Presence** | |
 | `/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 |
+| **Profile** | |
 | `/name <text>` | Change your display name |
 | `/about <text>` | Change your bio / about text |
+| `/photo <file>` | Change your profile picture |
 | `/privacy <type> <value>` | Change a privacy setting |
+| **Contacts** | |
+| `/whatsapp <phone...>` | Check which numbers have WhatsApp |
+| `/picture <jid>` | Get profile picture CDN URL |
+| `/contact about <jid>` | Get bio / about text of a contact |
+| **Chat Management** | |
 | `/read <jid>` | Mark chat as read |
 | `/unread <jid>` | Mark chat as unread |
-| `/mute <jid> [minutes]` | Mute a chat |
+| `/mute <jid> [minutes]` | Mute a chat (indefinitely if no minutes given) |
 | `/unmute <jid>` | Unmute a chat |
 | `/pin <jid>` | Pin a chat |
 | `/unpin <jid>` | Unpin a chat |
@@ -1294,10 +1751,12 @@ wa> /quit
 | `/unarchive <jid>` | Unarchive a chat |
 | `/star <jid> <msgId>` | Star a message |
 | `/unstar <jid> <msgId>` | Unstar a message |
-| `/ephemeral <jid> <seconds>` | Set disappearing messages timer |
+| `/ephemeral <jid> <seconds>` | Set disappearing messages timer for a chat |
+| `/ephemeral-default <seconds>` | Set global default ephemeral timer for new chats |
 | `/block <jid>` | Block a contact |
 | `/unblock <jid>` | Unblock a contact |
 | `/blocklist` | Show all blocked contacts |
+| **Groups** | |
 | `/group create <name> <jid...>` | Create a group |
 | `/group leave <jid>` | Leave a group |
 | `/group add <jid> <member...>` | Add participants |
@@ -1306,14 +1765,22 @@ wa> /quit
 | `/group demote <jid> <member...>` | Demote from admin |
 | `/group subject <jid> <name>` | Rename group |
 | `/group desc <jid> <text>` | Change group description |
+| `/group photo <jid> <file>` | Change group picture |
 | `/group invite <jid>` | Get invite link |
 | `/group revoke <jid>` | Revoke invite link |
 | `/group join <code>` | Join group by invite code |
+| `/groups` | List all groups you are a member of |
 | `/group meta <jid>` | Query group metadata |
+| `/group participants <jid>` | List group participants with roles |
+| `/group pending <jid>` | List pending join requests |
+| `/group approve <jid> <member...>` | Approve pending join requests |
+| `/group reject <jid> <member...>` | Reject pending join requests |
 | `/group settings <jid> <setting> <policy>` | Change group setting |
+| **Registration** | |
 | `/reg check <phone>` | Check if number has WhatsApp |
 | `/reg code <phone> [method]` | Request verification code |
 | `/reg confirm <phone> <code>` | Complete registration |
+| **Connection** | |
 | `/connect <phone>` | Connect to WhatsApp |
 | `/disconnect` | Disconnect current session |
 | `/reconnect` | Force reconnection |
@@ -1358,12 +1825,42 @@ Automatic reconnection uses exponential backoff:
 
 ## Media Encryption
 
+### Sending (upload flow)
+
 1. A random 32-byte **media key** is generated.
-2. HKDF-SHA256 expands it into IV, cipher key, and MAC key.
+2. HKDF-SHA256 expands it into IV (16 bytes), cipher key (32 bytes), and MAC key (32 bytes).
 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.
+4. A 10-byte **HMAC-SHA256** MAC is appended to the ciphertext.
+5. The encrypted blob is uploaded to the WhatsApp CDN.
+6. The media key and CDN URL are embedded in the Signal-encrypted message envelope sent to the recipient.
+
+### Receiving (download + decrypt flow)
+
+When you receive a media message, `msg.decoded` contains:
+- `url` — the HTTPS CDN link to download the encrypted blob
+- `mediaKey` — the 32-byte key (as a `Buffer`) needed to decrypt it
+- `directPath` — CDN path (fallback if full URL is unavailable)
+
+The decryption process mirrors the upload:
+
+| Step | Operation |
+|---|---|
+| 1 | Download encrypted blob from CDN URL |
+| 2 | HKDF-SHA256(`mediaKey`, `""`, `"WhatsApp <Type> Keys"`, 112) → expanded key material |
+| 3 | Split: `[0:16]` = IV · `[16:48]` = AES cipher key · `[48:80]` = HMAC key |
+| 4 | Verify: `HMAC-SHA256(macKey, IV ∥ ciphertext)[:10]` must equal last 10 bytes of blob |
+| 5 | Decrypt: `AES-256-CBC(cipherKey, IV, ciphertext)` — strip last 10 bytes first |
+
+HKDF info strings:
+
+| Media type | Info string |
+|---|---|
+| `image` / `sticker` | `WhatsApp Image Keys` |
+| `video` | `WhatsApp Video Keys` |
+| `audio` / `voice` | `WhatsApp Audio Keys` |
+| `document` | `WhatsApp Document Keys` |
+
+See the [Receiving Media](#receiving-media) section for a complete working code example.
 
 ## License