whalibmob 5.5.84 → 5.5.89

package/lib/Client.js

@@ -30,9 +30,57 @@ const {
   HistorySyncType
 } = require('./HistorySyncHandler');
 
+// Status posts are messages addressed here.
+const STATUS_BROADCAST_JID = 'status@broadcast';
+
+// The two prefixes a call-link token is wrapped in, as WhatsApp Web uses them.
+const CALL_AUDIO_PREFIX = 'https://call.whatsapp.com/voice/';
+const CALL_VIDEO_PREFIX = 'https://call.whatsapp.com/video/';
+
 // whatsmeow's InviteLinkPrefix — the one prefix group invite codes are wrapped in.
 const INVITE_LINK_PREFIX = 'https://chat.whatsapp.com/';
 
+// The names privacy settings actually go by on the wire, and the friendly
+// aliases this library has always accepted for them. whatsmeow's
+// PrivacySettingType constants are the right-hand column.
+const PRIVACY_NAME_ALIASES = {
+  last_seen: 'last',            last: 'last',
+  profile_picture: 'profile',   profile_pic: 'profile',    profile: 'profile',
+  status: 'status',
+  online: 'online',
+  read_receipts: 'readreceipts', readreceipts: 'readreceipts',
+  groups_add: 'groupadd',       group_add: 'groupadd',     groupadd: 'groupadd',
+  call_add: 'calladd',          calladd: 'calladd',
+  messages: 'messages',
+  defense: 'defense',
+  stickers: 'stickers'
+};
+
+// Wire name → the key it is reported under in the settings object.
+const PRIVACY_WIRE_TO_KEY = {
+  last:         'lastSeen',
+  profile:      'profile',
+  status:       'status',
+  online:       'online',
+  readreceipts: 'readReceipts',
+  groupadd:     'groupAdd',
+  calladd:      'callAdd',
+  messages:     'messages',
+  defense:      'defense',
+  stickers:     'stickers'
+};
+
+// Reduce a JID to its bare user — whatsmeow's ToNonAD. Blocking, and anything
+// else that names an account rather than one of its devices, wants this form.
+function toNonAdJid(input) {
+  const s      = String(input || '');
+  const at     = s.indexOf('@');
+  const user   = at >= 0 ? s.slice(0, at) : s;
+  const server = at >= 0 ? s.slice(at + 1) : 's.whatsapp.net';
+  const colon  = user.indexOf(':');
+  return (colon >= 0 ? user.slice(0, colon) : user) + '@' + server;
+}
+
 // Accept a full invite URL or a bare code and return the code.
 function stripInviteUrl(codeOrUrl) {
   return String(codeOrUrl || '')
@@ -181,6 +229,9 @@ class WhalibmobClient extends EventEmitter {
     // Flipped by setOnline(). Delivery receipts sent while this is false carry
     // type="inactive", which the sender's app records but does not render.
     this._sendActiveReceipts = false;
+    // Cached privacy settings, as whatsmeow caches them. Warmed after connect
+    // and refreshed whenever the server reports a change; markRead reads it.
+    this._privacySettings = null;
     if (opts.pino !== undefined) _whaConfigLogger(opts.pino);
   }
 
@@ -321,6 +372,11 @@ class WhalibmobClient extends EventEmitter {
     this._requestMediaConnection();
     this._uploadPreKeys();
 
+    // Warm the privacy settings so read receipts respect them from the first
+    // message rather than from whenever something first asks for them.
+    this.queryPrivacySettings({ force: true }).catch(err =>
+      _whaDbg('[DBG] PRIVACY_FETCH_FAILED ' + (err && err.message)));
+
     // ── Reconnect: flush stale device cache + background re-usync ─────────────
     // On first connect _hasConnectedOnce is false — nothing extra to do.
     // On every reconnect (network drop / NAT reset / server restart) we flush the
@@ -1030,6 +1086,19 @@ class WhalibmobClient extends EventEmitter {
     this._socket.sendNode(new BinaryNode('ack', attrs, null));
   }
 
+  // A read receipt only tells the sender we read it when read receipts are on.
+  // whatsmeow's MarkRead checks the same setting and downgrades "read" to
+  // "read-self", which marks the message read across our own devices without
+  // reporting it to the other side. Nothing here looked at the setting, so a
+  // user who had turned read receipts off still sent blue ticks.
+  _readReceiptType(base) {
+    const settings = this._privacySettings;
+    if (settings && settings.readReceipts === 'none' && base === 'read') {
+      return 'read-self';
+    }
+    return base;
+  }
+
   // True when a JID names this account, in either address family.
   _isOwnUser(jid) {
     if (!jid) return false;
@@ -1076,7 +1145,7 @@ class WhalibmobClient extends EventEmitter {
     if (this.autoRead === false) return;
     const node = new BinaryNode('receipt', {
       id:   msgId,
-      type: 'read',
+      type: this._readReceiptType('read'),
       to:   fromJid,
       t:    String(Math.floor(Date.now() / 1000))
     }, null);
@@ -1197,6 +1266,46 @@ class WhalibmobClient extends EventEmitter {
 
   // ─── Notification handling ────────────────────────────────────────────────
 
+  // <privacy><category name="..." value="..."/></privacy> inside an account_sync
+  // notification. The node carries only what changed, so it is folded into the
+  // cached settings rather than replacing them.
+  _handlePrivacySettingsNotification(node) {
+    const changed = this._parsePrivacySettings(node);
+    const merged  = Object.assign({}, this._privacySettings || {});
+    const changes = {};
+    for (const key of Object.keys(changed)) {
+      if (changed[key] !== null) { merged[key] = changed[key]; changes[key] = changed[key]; }
+    }
+    this._privacySettings = merged;
+    _whaDbg('[DBG] PRIVACY_CHANGE ' + JSON.stringify(changes));
+    this.emit('privacy_settings', { changes, settings: merged });
+  }
+
+  // <blocklist action="..." dhash="..." prev_dhash="..."><item jid=... action=.../></blocklist>
+  // Mirrors whatsmeow's handleBlocklist: the action on the node describes the
+  // whole change, each child names one JID and what happened to it.
+  _handleBlocklistNotification(node) {
+    const attrs   = node.attrs || {};
+    const changes = [];
+    if (Array.isArray(node.content)) {
+      for (const child of node.content) {
+        if (!child || !child.attrs || !child.attrs.jid) continue;
+        changes.push({
+          jid:    String(child.attrs.jid),
+          action: child.attrs.action ? String(child.attrs.action) : null
+        });
+      }
+    }
+    _whaDbg('[DBG] BLOCKLIST_CHANGE action=' + (attrs.action || '') +
+      ' changes=' + changes.map(c => c.action + ':' + c.jid).join(','));
+    this.emit('blocklist', {
+      action:    attrs.action     ? String(attrs.action)     : null,
+      dhash:     attrs.dhash      ? String(attrs.dhash)      : null,
+      prevDhash: attrs.prev_dhash ? String(attrs.prev_dhash) : null,
+      changes
+    });
+  }
+
   _handleNotification(node) {
     const attrs = node.attrs || {};
     const type  = attrs.type || '';
@@ -1212,6 +1321,16 @@ class WhalibmobClient extends EventEmitter {
       // Account sync notification — may contain device list updates
       const devicesNode = findChildDeep(node, 'devices');
       if (devicesNode) this._processDeviceUpdate(devicesNode);
+      // ...and block list changes. Blocking someone from the phone arrives
+      // here; nothing was watching for it, so the client's idea of who is
+      // blocked only ever changed when it did the blocking itself.
+      const blocklistNode = findChildDeep(node, 'blocklist');
+      if (blocklistNode) this._handleBlocklistNotification(blocklistNode);
+      // ...and privacy setting changes, which arrive the same way. whatsmeow
+      // re-reads the settings on this and raises an event; nothing was watching
+      // the node, so a change made on the phone never reached the cache.
+      const privacyNode = findChildDeep(node, 'privacy');
+      if (privacyNode) this._handlePrivacySettingsNotification(privacyNode);
     }
 
     if (type === 'w:gp2') {
@@ -1392,6 +1511,20 @@ class WhalibmobClient extends EventEmitter {
 
   _handleCall(node) {
     const attrs = node.attrs || {};
+
+    // A <call> can also be the answer to something we asked for — creating a
+    // call link, for one. Those come back on the same tag with the id we sent,
+    // so they have to be handed to the waiting caller and not treated as an
+    // incoming call to reject.
+    if (attrs.id) {
+      const handler = this._pendingIqs.get(attrs.id);
+      if (handler) {
+        this._pendingIqs.delete(attrs.id);
+        handler(node);
+        return;
+      }
+    }
+
     this.emit('call', { from: attrs.from || '', node });
     // Reject call automatically
     if (this._socket && this._connected) {
@@ -2279,7 +2412,7 @@ class WhalibmobClient extends EventEmitter {
 
     const attrs = {
       id:   ids[0],
-      type: opts.type === 'played' ? 'played' : 'read',
+      type: this._readReceiptType(opts.type === 'played' ? 'played' : 'read'),
       to:   jidStrToObj(chatJid),
       t:    String(Math.floor(Date.now() / 1000))
     };
@@ -2605,7 +2738,29 @@ class WhalibmobClient extends EventEmitter {
     return httpGetBuffer(info.url);
   }
 
-  // Query blocked contacts list
+  // Parse the <list> a blocklist query or update comes back with.
+  //
+  // whatsmeow's parseBlocklist walks every child and takes its jid, without
+  // caring what the tag is called, and keeps the dhash off the list itself.
+  // The JIDs are stringified here: the binary decoder hands them back as JID
+  // objects, and while those print correctly they are not strings, so the array
+  // this used to return failed any includes() or === against a JID string —
+  // which is exactly what the documented shape invites you to do.
+  _parseBlocklist(listNode) {
+    const jids = [];
+    if (listNode && Array.isArray(listNode.content)) {
+      for (const child of listNode.content) {
+        if (!child || !child.attrs || !child.attrs.jid) continue;
+        jids.push(String(child.attrs.jid));
+      }
+    }
+    const dhash = (listNode && listNode.attrs && listNode.attrs.dhash)
+      ? String(listNode.attrs.dhash) : null;
+    return { dhash, jids };
+  }
+
+  // Query blocked contacts list. Returns an array of JID strings; never throws,
+  // an unreachable server yields an empty list.
   async queryBlockList() {
     const id   = this._genMsgId();
     const node = new BinaryNode('iq', {
@@ -2616,11 +2771,8 @@ class WhalibmobClient extends EventEmitter {
     }, null);
     const resp = await this._sendIq(node);
     if (!resp) return [];
-    const list = findChild(resp, 'list');
-    if (!list || !Array.isArray(list.content)) return [];
-    return list.content
-      .filter(n => n && n.description === 'item' && n.attrs && n.attrs.jid)
-      .map(n => n.attrs.jid);
+    if (resp.attrs && resp.attrs.type === 'error') return [];
+    return this._parseBlocklist(findChild(resp, 'list')).jids;
   }
 
   // Change display name
@@ -2665,29 +2817,114 @@ class WhalibmobClient extends EventEmitter {
     return this._sendIq(node);
   }
 
-  // Change privacy settings
-  // type: 'last_seen'|'profile_picture'|'status'|'online'|'read_receipts'|'groups_add'
-  // value: 'all'|'contacts'|'contact_blacklist'|'none'|'match_last_seen'
-  // excluded: array of JIDs excluded from value (for contact_blacklist)
+  // ─── Privacy settings ─────────────────────────────────────────────────────
+
+  // Read the current privacy settings.
+  //
+  // Returns { lastSeen, profile, status, online, readReceipts, groupAdd,
+  //           callAdd, messages, defense, stickers } — any the server did not
+  // report come back null. Served from cache unless opts.force is set.
+  //
+  // There was no way to read these at all before, which also meant nothing
+  // could act on them; see markRead for what that cost.
+  async queryPrivacySettings(opts) {
+    opts = opts || {};
+    if (this._privacySettings && !opts.force) return this._privacySettings;
+
+    const node = new BinaryNode('iq', {
+      id:    this._genMsgId(),
+      xmlns: 'privacy',
+      to:    's.whatsapp.net',
+      type:  'get'
+    }, [new BinaryNode('privacy', {}, null)]);
+
+    const resp = await this._sendIq(node);
+    if (!resp) throw new Error('queryPrivacySettings: no reply from server (IQ timed out)');
+    if (resp.attrs && resp.attrs.type === 'error') {
+      const errNode = findChild(resp, 'error');
+      const code    = errNode && errNode.attrs && errNode.attrs.code;
+      throw new Error('queryPrivacySettings: server rejected the request' +
+        (code ? ' (' + code + ')' : ''));
+    }
+    const privacyNode = findChild(resp, 'privacy');
+    this._privacySettings = this._parsePrivacySettings(privacyNode);
+    return this._privacySettings;
+  }
+
+  // <privacy><category name="..." value="..."/>...</privacy>
+  _parsePrivacySettings(privacyNode) {
+    const out = {};
+    for (const key of Object.keys(PRIVACY_WIRE_TO_KEY)) out[PRIVACY_WIRE_TO_KEY[key]] = null;
+    if (privacyNode && Array.isArray(privacyNode.content)) {
+      for (const child of privacyNode.content) {
+        if (!child || child.description !== 'category' || !child.attrs) continue;
+        const key = PRIVACY_WIRE_TO_KEY[String(child.attrs.name)];
+        if (key) out[key] = child.attrs.value ? String(child.attrs.value) : null;
+      }
+    }
+    return out;
+  }
+
+  // Change a privacy setting. Returns the settings as they now stand.
+  //
+  // type:  'last_seen' | 'profile_picture' | 'status' | 'online' |
+  //        'read_receipts' | 'groups_add' | 'call_add' | 'messages' |
+  //        'defense' | 'stickers'   (the protocol's own spellings work too)
+  // value: 'all' | 'contacts' | 'contact_blacklist' | 'contact_allowlist' |
+  //        'none' | 'match_last_seen' | 'known' | 'on_standard' | 'off'
+  // excluded: JIDs to exclude — see the note below
+  //
+  // The names above are friendly aliases. What goes on the wire is what
+  // whatsmeow sends: last, profile, status, online, readreceipts, groupadd,
+  // calladd, messages, defense, stickers. Four of the six names this used to
+  // put on the wire — last_seen, profile_picture, read_receipts, groups_add —
+  // are not names the server knows, so those settings never changed and the
+  // discarded reply meant it never said so either.
   async changePrivacySetting(type, value, excluded) {
-    const categoryAttrs = { name: type, value };
+    const name = PRIVACY_NAME_ALIASES[String(type)];
+    if (!name) {
+      throw new Error('changePrivacySetting: unknown setting "' + type + '" — one of ' +
+        Object.keys(PRIVACY_NAME_ALIASES).join(', '));
+    }
+
+    // Neither whatsmeow nor WhatsApp Web puts <user> children on this IQ; the
+    // exclusion list is maintained separately. Kept for callers that pass it,
+    // and only emitted when they do.
     const children = [];
     if (excluded && excluded.length > 0) {
       for (const jid of excluded) {
-        children.push(new BinaryNode('user', { jid: makeJid(jid) }, null));
+        children.push(new BinaryNode('user', { jid: jidStrToObj(toNonAdJid(makeJid(jid))) }, null));
       }
     }
-    const categoryNode = new BinaryNode('category', categoryAttrs, children.length > 0 ? children : null);
-    const id = this._genMsgId();
+
     const node = new BinaryNode('iq', {
-      id,
+      id:    this._genMsgId(),
       xmlns: 'privacy',
       to:    's.whatsapp.net',
       type:  'set'
     }, [
-      new BinaryNode('privacy', {}, [categoryNode])
+      new BinaryNode('privacy', {}, [
+        new BinaryNode('category', { name, value: String(value) },
+          children.length > 0 ? children : null)
+      ])
     ]);
-    return this._sendIq(node);
+
+    const resp = await this._sendIq(node);
+    if (!resp) throw new Error('changePrivacySetting: no reply from server (IQ timed out)');
+    if (resp.attrs && resp.attrs.type === 'error') {
+      const errNode = findChild(resp, 'error');
+      const code    = errNode && errNode.attrs && errNode.attrs.code;
+      const text    = errNode && errNode.attrs && errNode.attrs.text;
+      throw new Error('changePrivacySetting: server rejected ' + name + '=' + value +
+        (code ? ' (' + code + (text ? ' ' + text : '') + ')' : ''));
+    }
+
+    // whatsmeow folds the change into its cached copy and hands the whole thing
+    // back rather than making the caller re-query.
+    const key = PRIVACY_WIRE_TO_KEY[name];
+    this._privacySettings = Object.assign({}, this._privacySettings || {},
+      { [key]: String(value) });
+    return this._privacySettings;
   }
 
   // ──────────────────────────────────────────────────────────────────────────
@@ -2708,10 +2945,132 @@ class WhalibmobClient extends EventEmitter {
     return this._sender.deleteMessage(origMsgId, chatJid, fromMe, forEveryone, opts);
   }
 
-  // Send a WhatsApp Status/Story
-  async sendStatus(text, opts) {
+  // ─── Status / Stories ─────────────────────────────────────────────────────
+
+  // Who your Status posts go to.
+  //
+  // Returns [{ type, isDefault, list }] with the default first, as whatsmeow's
+  // GetStatusPrivacy does. type is 'contacts', 'blacklist' or 'whitelist'; list
+  // holds the JIDs the last two are built from. A server that has never been
+  // told otherwise answers nothing, which means the default: all contacts.
+  async queryStatusPrivacy() {
+    const node = new BinaryNode('iq', {
+      id:    this._genMsgId(),
+      xmlns: 'status',
+      to:    's.whatsapp.net',
+      type:  'get'
+    }, [new BinaryNode('privacy', {}, null)]);
+
+    const resp = await this._sendIq(node);
+    if (!resp || (resp.attrs && resp.attrs.type === 'error')) {
+      return [{ type: 'contacts', isDefault: true, list: [] }];
+    }
+
+    const privacyNode = findChild(resp, 'privacy');
+    const out = [];
+    if (privacyNode && Array.isArray(privacyNode.content)) {
+      for (const listNode of privacyNode.content) {
+        if (!listNode || listNode.description !== 'list' || !listNode.attrs) continue;
+        const entry = {
+          type:      listNode.attrs.type ? String(listNode.attrs.type) : 'contacts',
+          isDefault: String(listNode.attrs.default) === 'true',
+          list:      []
+        };
+        if (Array.isArray(listNode.content)) {
+          for (const u of listNode.content) {
+            if (u && u.description === 'user' && u.attrs && u.attrs.jid) {
+              entry.list.push(String(u.attrs.jid));
+            }
+          }
+        }
+        // The default is always reported first.
+        if (entry.isDefault) out.unshift(entry); else out.push(entry);
+      }
+    }
+    return out.length ? out : [{ type: 'contacts', isDefault: true, list: [] }];
+  }
+
+  // Resolve the status privacy settings into the JIDs a post actually goes to,
+  // the way whatsmeow's getStatusBroadcastRecipients does: a whitelist is the
+  // list itself, anything else is every known contact minus the blacklist, and
+  // our own JID is added so the post lands on our own devices too.
+  //
+  // Contacts come from the synced history store — this client has no separate
+  // contact database — so a session that has not synced history yet has to be
+  // given the list explicitly.
+  async _getStatusRecipients() {
+    let privacy;
+    try {
+      privacy = (await this.queryStatusPrivacy())[0];
+    } catch (_) {
+      privacy = { type: 'contacts', list: [] };
+    }
+
+    const ownJid = String(this._store.phoneNumber) + '@s.whatsapp.net';
+    let recipients;
+
+    if (privacy.type === 'whitelist') {
+      recipients = privacy.list.slice();
+    } else {
+      const hist = this.getHistoryStore();
+      const contacts = (hist && hist.contacts) ? Object.keys(hist.contacts) : [];
+      // Only real contacts — an entry the history sync created purely to hold a
+      // push name is not somebody you have in your address book.
+      const named = contacts.filter(jid => {
+        const c = hist.contacts[jid];
+        return c && (c.name || c.displayName) && !jid.endsWith('@g.us') &&
+          !jid.endsWith('@broadcast');
+      });
+      const blocked = new Set(privacy.type === 'blacklist' ? privacy.list : []);
+      recipients = named.filter(jid => !blocked.has(jid));
+    }
+
+    if (!recipients.some(j => this._isOwnUser(j))) recipients.push(ownJid);
+    _whaDbg('[DBG] STATUS_RECIPIENTS type=' + privacy.type +
+      ' count=' + recipients.length);
+    return recipients;
+  }
+
+  // Post a Status/Story.
+  //
+  //   sendStatus('Good morning!')                       text
+  //   sendStatus({ image: './a.jpg', caption: 'hi' })   photo
+  //   sendStatus({ video: './v.mp4' })                  video
+  //   sendStatus({ audio: './v.ogg' })                  voice
+  //
+  // opts (also accepted as fields of the object form):
+  //   recipients      post to these JIDs instead of the privacy-derived list
+  //   backgroundArgb  background colour of a text status, e.g. 0xFF25D366
+  //   textArgb, font  the rest of a text status' styling
+  //
+  // Text posted with a background or font becomes an ExtendedTextMessage, which
+  // is what carries them; plain text stays a plain conversation.
+  async sendStatus(content, opts) {
     if (!this._sender || !this._connected) throw new Error('Not connected');
-    return this._sender.sendText('status@broadcast', text, opts);
+    opts = Object.assign({},
+      (content && typeof content === 'object') ? content : {},
+      opts || {});
+
+    const recipients = opts.recipients || opts.statusJidList ||
+      await this._getStatusRecipients();
+    const sendOpts = Object.assign({}, opts, { _statusRecipients: recipients });
+
+    if (opts.image) return this._sender.sendImage(STATUS_BROADCAST_JID, opts.image, sendOpts);
+    if (opts.video) return this._sender.sendVideo(STATUS_BROADCAST_JID, opts.video, sendOpts);
+    if (opts.audio) return this._sender.sendAudio(STATUS_BROADCAST_JID, opts.audio, sendOpts);
+
+    const text = (typeof content === 'string') ? content : (opts.text || opts.caption || '');
+    const styled = opts.backgroundArgb != null || opts.textArgb != null || opts.font != null;
+    if (!styled) return this._sender.sendText(STATUS_BROADCAST_JID, text, sendOpts);
+
+    const { encodeMessage, encodeExtendedText } = require('./proto/MessageProto');
+    const buf = encodeMessage('extendedText', encodeExtendedText(text, {
+      backgroundArgb: opts.backgroundArgb,
+      textArgb:       opts.textArgb,
+      font:           opts.font
+    }));
+    return this._sender._sendMessage(STATUS_BROADCAST_JID,
+      generateMessageId(), buf, 'text', sendOpts);
   }
 
   // Forward a message
@@ -3140,32 +3499,52 @@ class WhalibmobClient extends EventEmitter {
     return this._sendIq(node);
   }
 
-  // Block a contact
+  // Block a contact. Returns the updated block list.
   async blockContact(jid) {
-    const id = this._genMsgId();
-    const node = new BinaryNode('iq', {
-      id,
-      xmlns: 'blocklist',
-      to:    's.whatsapp.net',
-      type:  'set'
-    }, [
-      new BinaryNode('item', { action: 'block', jid: makeJid(jid) }, null)
-    ]);
-    return this._sendIq(node);
+    return this._updateBlocklist(jid, 'block');
   }
 
-  // Unblock a contact
+  // Unblock a contact. Returns the updated block list.
   async unblockContact(jid) {
-    const id = this._genMsgId();
+    return this._updateBlocklist(jid, 'unblock');
+  }
+
+  // The one IQ behind both, as whatsmeow's UpdateBlocklist sends it:
+  //
+  //   <iq xmlns="blocklist" type="set" to="s.whatsapp.net">
+  //     <item jid="<JID>" action="block|unblock"/>
+  //   </iq>
+  //
+  // Three things were wrong with the pair this replaces. The jid went out as a
+  // raw string rather than a binary JID. It was not reduced to its bare user
+  // first, so blocking a contact you happened to name with a device suffix sent
+  // the server a device JID it has nothing to block. And the reply was thrown
+  // away without being looked at — including a type="error" reply — so a block
+  // the server refused came back looking exactly like one that worked.
+  async _updateBlocklist(jid, action) {
+    const target = toNonAdJid(makeJid(jid));
     const node = new BinaryNode('iq', {
-      id,
+      id:    this._genMsgId(),
       xmlns: 'blocklist',
       to:    's.whatsapp.net',
       type:  'set'
     }, [
-      new BinaryNode('item', { action: 'unblock', jid: makeJid(jid) }, null)
+      new BinaryNode('item', { jid: jidStrToObj(target), action }, null)
     ]);
-    return this._sendIq(node);
+
+    const resp = await this._sendIq(node);
+    if (!resp) {
+      throw new Error(action + 'Contact: no reply from server (IQ timed out)');
+    }
+    if (resp.attrs && resp.attrs.type === 'error') {
+      const errNode = findChild(resp, 'error');
+      const code    = errNode && errNode.attrs && errNode.attrs.code;
+      const text    = errNode && errNode.attrs && errNode.attrs.text;
+      throw new Error(action + 'Contact: server rejected the request' +
+        (code ? ' (' + code + (text ? ' ' + text : '') + ')' : ''));
+    }
+    // The server answers with the whole list as it now stands.
+    return this._parseBlocklist(findChild(resp, 'list')).jids;
   }
 
   // Pin / unpin a chat (mobile: local state)
@@ -3264,6 +3643,56 @@ class WhalibmobClient extends EventEmitter {
     return this._chatStates[key];
   }
 
+  // ──────────────────────────────────────────────────────────────────────────
+  // CALL LINKS
+  // ──────────────────────────────────────────────────────────────────────────
+
+  // Ask the server for a call link that can be shared in a chat, so the other
+  // side joins by tapping it instead of being rung.
+  //
+  //   type  'audio' (default) or 'video'
+  //   opts  { startTime } — seconds since the epoch, to schedule the call
+  //
+  // Returns { token, link, type }. The stanza is the one WhatsApp Web sends:
+  // <call to="@call"><link_create media="..."/></call>, answered with the token
+  // on a link_create of its own.
+  async createCallLink(type, opts) {
+    opts = opts || {};
+    const media = type === 'video' ? 'video' : 'audio';
+    const id    = this._genMsgId();
+    const children = opts.startTime
+      ? [new BinaryNode('event', { start_time: String(opts.startTime) }, null)]
+      : null;
+
+    const resp = await this._sendIq(new BinaryNode('call', { id, to: '@call' }, [
+      new BinaryNode('link_create', { media }, children)
+    ]));
+
+    if (!resp) throw new Error('createCallLink: no reply from server (timed out)');
+    if (resp.attrs && resp.attrs.type === 'error') {
+      const errNode = findChild(resp, 'error');
+      const code    = errNode && errNode.attrs && errNode.attrs.code;
+      throw new Error('createCallLink: server rejected the request' +
+        (code ? ' (' + code + ')' : ''));
+    }
+    const created = findChild(resp, 'link_create');
+    const token   = created && created.attrs && created.attrs.token;
+    if (!token) throw new Error('createCallLink: server reply carried no token');
+
+    const prefix = media === 'video' ? CALL_VIDEO_PREFIX : CALL_AUDIO_PREFIX;
+    return { token: String(token), link: prefix + token, type: media };
+  }
+
+  // Create a call link and send it as a message in one step.
+  // Returns the send result with the link attached.
+  async sendCallLink(to, type, opts) {
+    opts = opts || {};
+    const { link } = await this.createCallLink(type, opts);
+    const text = opts.text ? (opts.text + ' ' + link) : link;
+    const res  = await this.sendText(to, text, opts);
+    return Object.assign({}, res, { link });
+  }
+
   // ──────────────────────────────────────────────────────────────────────────
   // GROUP OPERATIONS
   // ──────────────────────────────────────────────────────────────────────────