whalibmob 5.5.84 → 5.5.89

package/README.md

@@ -157,6 +157,7 @@ npm install -g whalibmob
     - [Quoted Reply](#quoted-reply)
     - [Location Message](#location-message)
     - [Contact Message (vCard)](#contact-message-vcard)
+    - [Call Link](#call-link)
     - [Media Messages](#media-messages)
       - [Image Message](#image-message)
       - [Video Message](#video-message)
@@ -165,6 +166,7 @@ npm install -g whalibmob
       - [Document Message](#document-message)
       - [Sticker Message](#sticker-message)
     - [Status / Stories](#status--stories)
+    - [Status Privacy](#status-privacy)
   - [Send States in Chat](#send-states-in-chat)
     - [Reading Messages](#reading-messages)
     - [Mark Voice Message Played](#mark-voice-message-played)
@@ -188,6 +190,7 @@ npm install -g whalibmob
   - [Privacy](#privacy)
     - [Block / Unblock User](#block--unblock-user)
     - [Get Block List](#get-block-list)
+    - [Read Privacy Settings](#read-privacy-settings)
     - [Update Privacy Settings](#update-privacy-settings)
     - [Update Default Disappearing Mode](#update-default-disappearing-mode)
   - [Communities](#communities)
@@ -604,6 +607,8 @@ connect()
 | `chat_read` | `{ jid, read }` | Chat marked read (`read: true`) or unread (`read: false`) |
 | `chat_muted` | `{ jid, muted, until }` | Chat muted or unmuted; `until` is epoch ms (−1 = indefinite) |
 | `chat_pinned` | `{ jid, pinned }` | Chat pinned or unpinned |
+| `blocklist` | `{ action, dhash, prevDhash, changes }` | Block list changed on another device; `changes` is `[{ jid, action }]` |
+| `privacy_settings` | `{ changes, settings }` | Privacy settings changed on another device |
 | `chat_archived` | `{ jid, archived }` | Chat archived or unarchived |
 | `message_starred` | `{ msgId, chatJid, starred }` | Message starred or unstarred |
 | `stream_error` | `{ reason }` | Server sent a fatal stream error |
@@ -1137,6 +1142,7 @@ const { id, encKey } = await client.sendPoll(
   1            // voters may pick 1 option (0 = unlimited)
 )
 // encKey (32-byte Buffer) is needed to decrypt incoming poll votes
+// (also returned as `messageSecret`, which is the name the protocol uses)
 ```
 
 ### Quoted Reply
@@ -1181,6 +1187,12 @@ await client.sendLocation('919634847671@s.whatsapp.net', 48.8566, 2.3522, {
 await client.sendLocation('120363000000000000@g.us', 51.5074, -0.1278, {
   name: 'London'
 })
+
+// with a map image for the bubble — WhatsApp draws a blank card without one
+await client.sendLocation('919634847671@s.whatsapp.net', 48.8566, 2.3522, {
+  name: 'Eiffel Tower',
+  thumbnail: jpegBuffer
+})
 ```
 
 ### Contact Message (vCard)
@@ -1200,8 +1212,37 @@ const vcard = [
 await client.sendContact('919634847671@s.whatsapp.net', 'Alice Smith', vcard)
 ```
 
+### Call Link
+
+Ask WhatsApp for a link that lets someone join a call by tapping it, instead of
+being rung. Returns the token, the shareable link and the media type.
+
+```js
+const { link } = await client.createCallLink('video')
+// https://call.whatsapp.com/video/XXXXXXXX
+
+// audio is the default
+const audio = await client.createCallLink()
+
+// schedule it — startTime is seconds since the epoch
+await client.createCallLink('video', { startTime: 1800000000 })
+
+// create it and send it in one step
+await client.sendCallLink('919634847671@s.whatsapp.net', 'video', {
+  text: 'Join me here:'
+})
+```
+
 ## Media Messages
 
+Photos and videos are sent with an inline preview so they show up in the chat
+directly, rather than as a placeholder the recipient has to tap. The dimensions
+are read out of the file header with no dependency at all. The preview itself
+uses `jimp` (installed automatically as an optional dependency) or `sharp` if
+you have it; failing both, a photo that carries an EXIF thumbnail still gets
+one. Video previews need `ffmpeg` on PATH — on Termux, `pkg install ffmpeg`.
+Without any of these the media still sends, just without the preview.
+
 ### Image Message
 
 ```js
@@ -1250,11 +1291,41 @@ await client.sendSticker('919634847671@s.whatsapp.net', './sticker.webp')
 
 ## Status / Stories
 
+A Status is posted to `status@broadcast` and travels the SenderKey path a group
+message does — one encrypted body plus a key distribution to every recipient.
+Who those recipients are comes from your status privacy settings, resolved
+against the contacts in the synced history store.
+
 ```js
-// post a text Status to status@broadcast
+// text
 await client.sendStatus('Good morning!')
+
+// photo, video, voice — same arguments as the matching send* methods
+await client.sendStatus({ image: './photo.jpg', caption: 'Look at this' })
+await client.sendStatus({ video: './clip.mp4' })
+await client.sendStatus({ audio: './voice.ogg' })
+
+// styled text status
+await client.sendStatus('Colorful', { backgroundArgb: 0xFF25D366, font: 3 })
+
+// post to an explicit list instead of the privacy-derived one
+await client.sendStatus('Hi', { recipients: ['919634847671@s.whatsapp.net'] })
+```
+
+### Status Privacy
+
+```js
+const [def, ...rest] = await client.queryStatusPrivacy()
+// def = { type: 'contacts' | 'blacklist' | 'whitelist', isDefault, list }
 ```
 
+`contacts` sends to everyone in your address book, `blacklist` to everyone
+except `list`, `whitelist` to `list` only. Your own JID is always included so
+the post reaches your other devices.
+
+If history has not synced yet the contact list is unknown, and `sendStatus`
+will say so rather than post to nobody — pass `recipients` in that case.
+
 ## Send States in Chat
 
 ### Reading Messages
@@ -1420,8 +1491,12 @@ await client.changeGroupPicture('120363000000000000@g.us', fs.readFileSync('./gr
 ### Block / Unblock User
 
 ```js
-await client.blockContact('919634847671@s.whatsapp.net')
+// both return the updated block list, and throw if the server refuses
+const blocked = await client.blockContact('919634847671@s.whatsapp.net')
 await client.unblockContact('919634847671@s.whatsapp.net')
+
+// blocking done from the phone arrives as an event
+client.on('blocklist', ({ changes }) => console.log(changes))
 ```
 
 ### Get Block List
@@ -1434,17 +1509,40 @@ 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'
+// type:  'last_seen' | 'profile_picture' | 'status' | 'online' | 'read_receipts'
+//        'groups_add' | 'call_add' | 'messages' | 'defense' | 'stickers'
+// value: 'all' | 'contacts' | 'contact_blacklist' | 'contact_allowlist' | 'none'
+//        'match_last_seen' | 'known' | 'on_standard' | 'off'
 
+// returns the settings as they now stand; throws if the server refuses
 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')
+await client.changePrivacySetting('call_add',         'known')
 ```
 
+### Read Privacy Settings
+
+```js
+const s = await client.queryPrivacySettings()
+// { lastSeen, profile, status, online, readReceipts,
+//   groupAdd, callAdd, messages, defense, stickers }
+// anything the server did not report is null
+
+await client.queryPrivacySettings({ force: true })   // skip the cache
+
+// a change made on the phone arrives as an event
+client.on('privacy_settings', ({ changes, settings }) => console.log(changes))
+```
+
+Turning `read_receipts` off changes what read receipts go out: they become
+`read-self`, which syncs the read state across your own devices without telling
+the sender. The settings are fetched once after connect so this holds from the
+first message.
+
 ### Update Default Disappearing Mode
 
 ```js

package/cli.js

@@ -336,7 +336,8 @@ const HELP = `
     /react    <jid> <msgId> <emoji>           react to a message
     /edit     <jid> <msgId> <text>            edit a sent message
     /delete   <jid> <msgId> [all]             delete message (add 'all' for everyone)
-    /status   <text>                          post a Status/Story
+    /status   <text>                          post a text Status/Story
+    /status   image|video|audio <file> [caption]  post a media Status/Story
     /forward  <jid> <text|msgObj>             forward text (or decoded msg) with forwarded flag
     /poll     <jid> <question> | <opt1> | <opt2> [selectable=N]  send a poll
     /location <jid> <lat> <lon> [name] [| address]              send a location pin
@@ -354,11 +355,13 @@ const HELP = `
     /name    <text>                          change display name
     /about   <text>                          change own bio / about text
     /photo   <file>                          change own profile picture (JPEG)
-    /privacy <type> <value>                  change privacy setting
+    /privacy [<type> <value>]                show or change privacy settings
                                                types:  last_seen profile_picture status
                                                        online read_receipts groups_add
+                                                       call_add messages defense stickers
                                                values: all contacts contact_blacklist
-                                                       none match_last_seen
+                                                       contact_allowlist none known
+                                                       match_last_seen on_standard off
 
   Contacts
     /whatsapp  <phone...>                    check which numbers have WhatsApp
@@ -828,8 +831,19 @@ async function handleLine(line) {
       case '/status': {
         requireConn();
         const [, ...rest] = p;
-        if (!rest.length) { fail('usage: /status <text>'); break; }
-        const r = await _client.sendStatus(rest.join(' '));
+        if (!rest.length) {
+          fail('usage: /status <text>   |   /status image|video|audio <file> [caption]');
+          break;
+        }
+        const kind = rest[0] && rest[0].toLowerCase();
+        let r;
+        if ((kind === 'image' || kind === 'video' || kind === 'audio') && rest[1]) {
+          const opts = { [kind]: rest[1] };
+          if (rest.length > 2) opts.caption = rest.slice(2).join(' ');
+          r = await _client.sendStatus(opts);
+        } else {
+          r = await _client.sendStatus(rest.join(' '));
+        }
         out('status posted  ' + (r && r.id ? r.id : ''));
         break;
       }
@@ -968,10 +982,19 @@ async function handleLine(line) {
       case '/privacy': {
         requireConn();
         const [, type, value] = p;
-        if (!type || !value) {
-          fail('usage: /privacy <type> <value>');
-          out('  types:  last_seen  profile_picture  status  online  read_receipts  groups_add');
-          out('  values: all  contacts  contact_blacklist  none  match_last_seen');
+        // with no arguments, show what the settings currently are
+        if (!type) {
+          const s = await _client.queryPrivacySettings({ force: true });
+          out('  privacy settings');
+          for (const k of Object.keys(s)) out('    ' + k.padEnd(14) + (s[k] || '(unset)'));
+          break;
+        }
+        if (!value) {
+          fail('usage: /privacy [<type> <value>]');
+          out('  types:  last_seen  profile_picture  status  online  read_receipts');
+          out('          groups_add  call_add  messages  defense  stickers');
+          out('  values: all  contacts  contact_blacklist  contact_allowlist  none');
+          out('          match_last_seen  known  on_standard  off');
           break;
         }
         await _client.changePrivacySetting(type, value);
@@ -1161,8 +1184,8 @@ async function handleLine(line) {
         requireConn();
         const jid = normalizeJid(p[1]);
         if (!jid) { fail('usage: /block <jid>'); break; }
-        await _client.blockContact(jid);
-        out('blocked  ' + jid);
+        const after = await _client.blockContact(jid);
+        out('blocked  ' + jid + '  (' + after.length + ' blocked in total)');
         break;
       }
 
@@ -1170,8 +1193,8 @@ async function handleLine(line) {
         requireConn();
         const jid = normalizeJid(p[1]);
         if (!jid) { fail('usage: /unblock <jid>'); break; }
-        await _client.unblockContact(jid);
-        out('unblocked  ' + jid);
+        const left = await _client.unblockContact(jid);
+        out('unblocked  ' + jid + '  (' + left.length + ' blocked in total)');
         break;
       }