whalibmob 5.5.83 → 5.5.86

package/lib/Client.js

@@ -21,7 +21,7 @@ const { NodeCache }       = require('@cacheable/node-cache');
 // Group metadata cache lifetime — matches DeviceManager's device cache.
 const GROUP_META_CACHE_TTL = '5m';
 const { SignalProtocol }  = require('./signal/SignalProtocol');
-const { DeviceManager }   = require('./DeviceManager');
+const { DeviceManager, jidStrToObj } = require('./DeviceManager');
 const {
   processHistorySyncNotification,
   decodeHistorySyncNotification,
@@ -30,6 +30,22 @@ const {
   HistorySyncType
 } = require('./HistorySyncHandler');
 
+// 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/';
+
+// Accept a full invite URL or a bare code and return the code.
+function stripInviteUrl(codeOrUrl) {
+  return String(codeOrUrl || '')
+    .trim()
+    .replace(/^https?:\/\/chat\.whatsapp\.com\//i, '')
+    .replace(/[?#].*$/, '')
+    .trim();
+}
+
 const PING_INTERVAL_MS    = 25000;
 const KEEPALIVE_INTERVAL  = 20000;
 const RECONNECT_BACKOFF   = [1000, 2000, 4000, 8000, 15000, 30000];
@@ -163,6 +179,12 @@ class WhalibmobClient extends EventEmitter {
     this._tcTokenStore            = null; // TcTokenStore — loaded in init()
     this._inFlightTcTokenIssuance = new Set(); // dedupe concurrent proactive issuePrivacyTokens per JID
     this._inFlight463Recoveries   = new Set(); // dedupe concurrent 463-triggered token issuances per JID (separate from proactive)
+    // Blue-tick every message as it arrives. Set to false for whatsmeow's model,
+    // where read is only ever sent by an explicit markRead() call.
+    this.autoRead = opts.autoRead !== false;
+    // 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;
     if (opts.pino !== undefined) _whaConfigLogger(opts.pino);
   }
 
@@ -667,6 +689,7 @@ class WhalibmobClient extends EventEmitter {
 
     if (skmsgNode && isGroup) {
       this._sendMessageAck(id, fromRaw, partRaw);
+      this._sendDeliveryReceipt(id, fromRaw, partRaw);
       // SKDM must be processed (awaited) before we attempt skmsg decryption,
       // because the first message from a sender always bundles both together.
       if (participantsNode) {
@@ -678,6 +701,7 @@ class WhalibmobClient extends EventEmitter {
 
     if (dmEncNode && this._signal) {
       this._sendMessageAck(id, fromRaw, partRaw);
+      this._sendDeliveryReceipt(id, fromRaw, partRaw);
       this._decryptDMMessage({ node, from, participant, fromRaw, partRaw, senderPn, id, ts, dmEncNode });
       return;
     }
@@ -690,6 +714,7 @@ class WhalibmobClient extends EventEmitter {
     ) : null;
 
     this._sendMessageAck(id, fromRaw, partRaw);
+    this._sendDeliveryReceipt(id, fromRaw, partRaw);
     this.emit('message', { id, from, participant, ts, text, node });
     this._sendReadReceipt(id, fromRaw, partRaw);
   }
@@ -1009,15 +1034,55 @@ class WhalibmobClient extends EventEmitter {
     this._socket.sendNode(new BinaryNode('ack', attrs, null));
   }
 
-  // Read receipt — sent after decryption succeeds.
-  // Gives sender 2 blue checkmarks.
+  // True when a JID names this account, in either address family.
+  _isOwnUser(jid) {
+    if (!jid) return false;
+    const user = String(jid).split('@')[0].split(':')[0];
+    if (!user) return false;
+    if (user === String(this._store && this._store.phoneNumber)) return true;
+    const ownLid = this._myLid ? String(this._myLid).split('@')[0].split(':')[0] : null;
+    return !!ownLid && user === ownLid;
+  }
+
+  // Delivery receipt — the sender's two grey ticks.
+  //
+  // Distinct from the <ack> above: the ack tells the server we took the stanza,
+  // the receipt tells the sender it reached a device. whatsmeow sends both for
+  // every incoming message (sendAck + sendMessageReceipt) and leaves the blue
+  // ticks to an explicit MarkRead. whalibmob only ever sent the ack and then
+  // jumped straight to type="read", so a sender never saw the grey stage.
+  //
+  // A client that has not marked itself available sends this with
+  // type="inactive": the sender's app records the delivery but does not render
+  // it, which is how WhatsApp Web behaves in the background.
+  _sendDeliveryReceipt(msgId, fromJid, partJid) {
+    if (!this._socket || !this._connected) return;
+    const attrs = { id: msgId, to: fromJid };
+    if (partJid && String(partJid) !== String(fromJid)) attrs.participant = partJid;
+    // A message that came from one of our own other devices is receipted with
+    // type="sender", never as a delivery to ourselves.
+    if (this._isOwnUser(partJid || fromJid)) {
+      attrs.type = 'sender';
+    } else if (!this._sendActiveReceipts) {
+      attrs.type = 'inactive';
+    }
+    this._socket.sendNode(new BinaryNode('receipt', attrs, null));
+  }
+
+  // Read receipt — the sender's two blue ticks.
+  //
+  // Sent automatically after a message decodes unless autoRead is turned off, in
+  // which case marking a chat read is up to the caller via markRead(). Turning
+  // it off gives whatsmeow's model, where read is always explicit.
   // fromJid / partJid are raw JID objects (AD_JID encoding for correct routing).
   _sendReadReceipt(msgId, fromJid, partJid) {
     if (!this._socket || !this._connected) return;
+    if (this.autoRead === false) return;
     const node = new BinaryNode('receipt', {
       id:   msgId,
       type: 'read',
-      to:   fromJid
+      to:   fromJid,
+      t:    String(Math.floor(Date.now() / 1000))
     }, null);
     if (partJid && String(partJid) !== String(fromJid)) {
       node.attrs.participant = partJid;
@@ -1331,6 +1396,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) {
@@ -1523,8 +1602,11 @@ class WhalibmobClient extends EventEmitter {
         return { jid: pJid, role: pRole };
       });
 
-    // description
+    // description — the id is the "topic id" the server wants echoed back as
+    // prev= on the next edit, so it has to survive the parse.
     const descNode = children.find(n => n && n.description === 'description');
+    const descriptionId = (descNode && descNode.attrs && descNode.attrs.id)
+      ? String(descNode.attrs.id) : null;
     let description = null;
     if (descNode) {
       const bodyNode = Array.isArray(descNode.content)
@@ -1563,6 +1645,7 @@ class WhalibmobClient extends EventEmitter {
       subjectTime: parseInt(a.s_t, 10) || 0,
       subjectBy:  a.s_o || null,
       description,
+      descriptionId,
       ephemeral,
       onlyAdminsSend: announce,
       onlyAdminsEdit: restrict,
@@ -2182,12 +2265,54 @@ class WhalibmobClient extends EventEmitter {
 
   // ─── Public API ───────────────────────────────────────────────────────────
 
+  // Alias kept from the original API — setOnline is the implementation.
   setPresence(available) {
-    if (this._sender) this._sender.sendPresence(available);
+    return this.setOnline(available);
   }
 
-  markRead(jid, messageIds) {
-    if (this._sender) this._sender.markRead(jid, messageIds);
+  // Mark messages as read — the sender's two blue ticks.
+  //
+  // jid        chat the messages are in (the group JID for a group)
+  // messageIds one id or an array of ids, all from the SAME sender
+  // opts       { participant, type } — participant is who sent them and is
+  //            required in a group; type may be 'read' (default) or 'played'
+  //            to mark a voice note as listened to.
+  //
+  // Shaped the way whatsmeow's MarkRead builds it: the FIRST id on the receipt
+  // and the rest as <item> children of a <list> node. whalibmob used the last id
+  // and put the items straight into <receipt>, which is not a shape the server
+  // reads back — the extra ids were silently ignored, so only one message per
+  // call was ever marked. The participant was missing entirely, so a group read
+  // never told the server whose message had been read.
+  markRead(jid, messageIds, opts) {
+    if (!this._socket || !this._connected) return;
+    const ids = (Array.isArray(messageIds) ? messageIds : [messageIds])
+      .map(String).filter(Boolean);
+    if (ids.length === 0) return;
+
+    opts = opts || {};
+    const chatJid = makeJid(jid);
+    const isGroup = chatJid.endsWith('@g.us') || chatJid.endsWith('@community')
+      || chatJid.endsWith('@broadcast');
+
+    const attrs = {
+      id:   ids[0],
+      type: opts.type === 'played' ? 'played' : 'read',
+      to:   jidStrToObj(chatJid),
+      t:    String(Math.floor(Date.now() / 1000))
+    };
+    // Only group and broadcast receipts carry a participant; on a 1:1 chat the
+    // `to` already identifies the sender.
+    if (isGroup && opts.participant) {
+      attrs.participant = jidStrToObj(makeJid(opts.participant));
+    }
+
+    const children = ids.length > 1
+      ? [new BinaryNode('list', {}, ids.slice(1).map(
+          id => new BinaryNode('item', { id }, null)))]
+      : null;
+
+    this._socket.sendNode(new BinaryNode('receipt', attrs, children));
   }
 
   async sendText(to, text, opts) {
@@ -2229,43 +2354,89 @@ class WhalibmobClient extends EventEmitter {
   // PRESENCE
   // ──────────────────────────────────────────────────────────────────────────
 
-  // Set global online/offline status)
+  // Our own JID in the family a chat is addressed with — the LID when the chat
+  // is LID-addressed, the phone JID otherwise. chatstate carries a `from`, and
+  // it has to be in the same space as the `to` beside it.
+  _ownJidFor(chatJid) {
+    const str = String(chatJid || '');
+    if (str.endsWith('@lid') && this._myLid) {
+      return String(this._myLid).split('@')[0].split(':')[0] + '@lid';
+    }
+    return String(this._store && this._store.phoneNumber) + '@s.whatsapp.net';
+  }
+
+  // Set global online/offline status.
+  //
+  // whatsmeow refuses to send this without a push name (ErrNoPushName): the
+  // server takes the display name from this node, and sending it empty makes
+  // every other user see "-" instead of a name. Going available also flips the
+  // client into sending active delivery receipts — see _sendDeliveryReceipt.
+  //
+  // Returns true when the node went out, false when it was skipped.
   setOnline(available) {
-    if (!this._socket || !this._connected) return;
-    const name = (this._store && this._store.pushName) || '';
+    if (!this._socket || !this._connected) return false;
+    const name = (this._store && (this._store.pushName || this._store.name)) || '';
+    if (!name) {
+      _whaDbg('[DBG] PRESENCE skipped: no push name set — other users would see "-"');
+      return false;
+    }
+    this._sendActiveReceipts = !!available;
     this._socket.sendNode(new BinaryNode('presence', {
       name,
       type: available ? 'available' : 'unavailable'
     }, null));
+    return true;
   }
 
-  // Set typing/recording presence in a specific chat)
+  // Set typing/recording presence in a specific chat.
   // presence: 'composing' | 'paused' | 'recording'
+  //
+  // whatsmeow's SendChatPresence puts both `from` (our own JID) and `to` on the
+  // chatstate node and expresses recording as composing with media="audio" —
+  // there is no separate recording state in the protocol. The `from` was missing
+  // here, and both JIDs were raw strings, which the server ignores for @lid
+  // chats, so the indicator never showed for a LID-addressed contact.
   setChatPresence(chatJid, presence) {
     if (!this._socket || !this._connected) return;
-    const jid = makeJid(chatJid);
+    const jid   = makeJid(chatJid);
+    const attrs = {
+      from: jidStrToObj(this._ownJidFor(jid)),
+      to:   jidStrToObj(jid)
+    };
     if (presence === 'composing' || presence === 'recording') {
-      const attrs = {};
-      if (presence === 'recording') attrs.media = 'audio';
-      this._socket.sendNode(new BinaryNode('chatstate', { to: jid }, [
-        new BinaryNode('composing', attrs, null)
+      const stateAttrs = presence === 'recording' ? { media: 'audio' } : {};
+      this._socket.sendNode(new BinaryNode('chatstate', attrs, [
+        new BinaryNode('composing', stateAttrs, null)
       ]));
     } else {
-      this._socket.sendNode(new BinaryNode('chatstate', { to: jid }, [
+      this._socket.sendNode(new BinaryNode('chatstate', attrs, [
         new BinaryNode('paused', {}, null)
       ]));
     }
   }
 
-  // Subscribe to presence updates for contacts
+  // Subscribe to presence updates for contacts.
+  //
+  // whatsmeow attaches the contact's privacy token when it has one; without it
+  // the server may decline to send their presence. It also notes that the server
+  // only forwards presence to clients that have marked themselves available, so
+  // call setOnline(true) first.
   subscribeToPresence(jids) {
     if (!this._socket || !this._connected) return;
     const arr = Array.isArray(jids) ? jids : [jids];
-    for (const jid of arr) {
+    const { normalizeJidForTcToken } = require('./messages/TcTokenStore');
+    for (const raw of arr) {
+      const jid   = makeJid(raw);
+      const entry = this._tcTokenStore && this._tcTokenStore.get(
+        normalizeJidForTcToken(jid)
+      );
+      const children = (entry && entry.token && entry.token.length)
+        ? [new BinaryNode('tctoken', {}, entry.token)]
+        : null;
       this._socket.sendNode(new BinaryNode('presence', {
-        to:   makeJid(jid),
+        to:   jidStrToObj(jid),
         type: 'subscribe'
-      }, null));
+      }, children));
     }
   }
 
@@ -2359,22 +2530,97 @@ class WhalibmobClient extends EventEmitter {
   }
 
   // Query profile picture URL
-  async queryPicture(jid) {
+  // Profile picture URL, or null when there is none.
+  // Unchanged signature; queryPictureInfo has the rest of what the server sends.
+  async queryPicture(jid, opts) {
+    const info = await this.queryPictureInfo(jid, opts);
+    return (info && info.url) || null;
+  }
+
+  // Full profile picture info, the way whatsmeow's GetProfilePictureInfo returns
+  // it: { id, url, type, directPath, hash }, or null when the user has no
+  // picture or it has not changed since opts.existingId.
+  //
+  // opts: { preview, existingId, isCommunity }
+  //   preview     ask for the small thumbnail instead of the full image
+  //   existingId  the id you already hold — the server answers 304 and this
+  //               returns null when it still matches
+  //   isCommunity resolve a community's picture, which goes through w:g2
+  //
+  // The target was a raw string before, which the server drops for an @lid, and
+  // the reply's status codes were not read at all: a 204 (no picture set) has no
+  // url attribute, so it came back as null with no way to tell it apart from a
+  // failed query.
+  async queryPictureInfo(jid, opts) {
+    opts = opts || {};
     const jidFull = makeJid(jid);
-    const id = this._genMsgId();
-    const node = new BinaryNode('iq', {
-      id,
-      xmlns:  'w:profile:picture',
-      to:     's.whatsapp.net',
-      target: jidFull,
-      type:   'get'
-    }, [
-      new BinaryNode('picture', { query: 'url', type: 'image' }, null)
-    ]);
-    const resp = await this._sendIq(node);
+    const attrs = {
+      query: 'url',
+      type:  opts.preview ? 'preview' : 'image'
+    };
+    if (opts.existingId) attrs.id = String(opts.existingId);
+    if (opts.inviteCode) attrs.invite = String(opts.inviteCode);
+
+    let iqAttrs, content;
+    if (opts.isCommunity) {
+      attrs.parent_group_jid = jidStrToObj(jidFull);
+      iqAttrs = { id: this._genMsgId(), xmlns: 'w:g2', to: jidStrToObj(jidFull), type: 'get' };
+      content = [new BinaryNode('pictures', {}, [new BinaryNode('picture', attrs, null)])];
+    } else {
+      const { normalizeJidForTcToken } = require('./messages/TcTokenStore');
+      const entry = this._tcTokenStore &&
+        this._tcTokenStore.get(normalizeJidForTcToken(jidFull));
+      const picChildren = (entry && entry.token && entry.token.length)
+        ? [new BinaryNode('tctoken', {}, entry.token)]
+        : null;
+      iqAttrs = {
+        id:     this._genMsgId(),
+        xmlns:  'w:profile:picture',
+        to:     's.whatsapp.net',
+        target: jidStrToObj(jidFull),
+        type:   'get'
+      };
+      content = [new BinaryNode('picture', attrs, picChildren)];
+    }
+
+    const resp = await this._sendIq(new BinaryNode('iq', iqAttrs, content));
     if (!resp) return null;
-    const pic = findChild(resp, 'picture');
-    return (pic && pic.attrs && pic.attrs.url) || null;
+    if (resp.attrs && resp.attrs.type === 'error') {
+      const errNode = findChild(resp, 'error');
+      const code    = errNode && errNode.attrs && String(errNode.attrs.code);
+      // 404 = no picture set, 401/403 = their privacy settings hide it. Neither
+      // is a failure worth throwing over.
+      if (code === '404' || code === '401' || code === '403') return null;
+      throw new Error('queryPictureInfo: server rejected the request' +
+        (code ? ' (' + code + ')' : ''));
+    }
+
+    const wrapper = opts.isCommunity ? findChild(resp, 'pictures') : resp;
+    const pic = wrapper ? findChild(wrapper, 'picture') : null;
+    if (!pic || !pic.attrs) return null;
+
+    const status = pic.attrs.status ? parseInt(pic.attrs.status, 10) : 0;
+    if (status === 304 || status === 204) return null;   // unchanged / not set
+
+    return {
+      id:         pic.attrs.id         ? String(pic.attrs.id)         : null,
+      url:        pic.attrs.url        ? String(pic.attrs.url)        : null,
+      type:       pic.attrs.type       ? String(pic.attrs.type)       : null,
+      directPath: pic.attrs.direct_path ? String(pic.attrs.direct_path) : null,
+      hash:       pic.attrs.hash
+        ? Buffer.from(String(pic.attrs.hash), 'base64')
+        : null
+    };
+  }
+
+  // Download a profile picture and hand back the JPEG bytes, or null when the
+  // user has none. Profile pictures are served unencrypted, unlike message
+  // media, so this is a plain fetch of the URL the query returns.
+  async downloadProfilePicture(jid, opts) {
+    const info = await this.queryPictureInfo(jid, opts);
+    if (!info || !info.url) return null;
+    const { httpGetBuffer } = require('./MediaService');
+    return httpGetBuffer(info.url);
   }
 
   // Query blocked contacts list
@@ -3036,24 +3282,125 @@ 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
   // ──────────────────────────────────────────────────────────────────────────
 
   // Create a group
   // participants: array of phone numbers or JIDs
+  // Create a group.
+  //
+  // opts: { ephemeralSeconds, announce, locked, joinApprovalRequired,
+  //         memberAddMode, parent, linkedParentJid }
+  //
+  // Built the way whatsmeow's CreateGroup does: every participant is a binary
+  // JID (a raw string is dropped for an @lid), a LID participant also carries
+  // the phone number the server matches it against, and each carries our privacy
+  // token so the invite is not treated as an anonymous reach-out. The setting
+  // nodes are siblings of the participants inside <create>.
   async createGroup(subject, participants, opts) {
     opts = opts || {};
     const id       = this._genMsgId();
+    const { normalizeJidForTcToken } = require('./messages/TcTokenStore');
     // participant nodes MUST use attr `jid`, not `value`
     const partNodes = (participants || []).map(p => {
-      const jid = makeJid(p);
-      return new BinaryNode('participant', { jid }, null);
+      const jid   = makeJid(p);
+      const attrs = { jid: jidStrToObj(jid) };
+      if (jid.endsWith('@lid')) {
+        const pn = this._lidToPn.get(jid.split('@')[0].split(':')[0]);
+        if (pn) attrs.phone_number = jidStrToObj(pn + '@s.whatsapp.net');
+      }
+      const entry = this._tcTokenStore &&
+        this._tcTokenStore.get(normalizeJidForTcToken(jid));
+      const children = (entry && entry.token && entry.token.length)
+        ? [new BinaryNode('privacy', {}, entry.token)]
+        : null;
+      return new BinaryNode('participant', attrs, children);
     });
+
+    const settingNodes = [];
+    if (opts.parent) {
+      settingNodes.push(new BinaryNode('parent', {
+        default_membership_approval_mode:
+          opts.defaultMembershipApprovalMode || 'request_required'
+      }, null));
+    } else if (opts.linkedParentJid) {
+      settingNodes.push(new BinaryNode('linked_parent', {
+        jid: jidStrToObj(makeJid(opts.linkedParentJid))
+      }, null));
+    }
+    if (opts.locked)   settingNodes.push(new BinaryNode('locked', {}, null));
+    if (opts.announce) settingNodes.push(new BinaryNode('announcement', {}, null));
+    if (opts.ephemeralSeconds) {
+      // whatsmeow sends trigger="1" alongside the expiration; without it the
+      // server accepts the group but leaves disappearing messages off.
+      settingNodes.push(new BinaryNode('ephemeral', {
+        expiration: String(opts.ephemeralSeconds),
+        trigger:    '1'
+      }, null));
+    }
+    if (opts.joinApprovalRequired) {
+      settingNodes.push(new BinaryNode('membership_approval_mode', {}, [
+        new BinaryNode('group_join', { state: 'on' }, null)
+      ]));
+    }
+    if (opts.memberAddMode) {
+      settingNodes.push(new BinaryNode('member_add_mode', {},
+        Buffer.from(String(opts.memberAddMode), 'utf8')));
+    }
+
     const baseAttrs = { subject, key: String(Math.floor(Date.now() / 1000)) };
-    const createChildren = opts.ephemeralSeconds
-      ? [...partNodes, new BinaryNode('ephemeral', { expiration: String(opts.ephemeralSeconds) }, null)]
-      : partNodes;
+    const createChildren = [...partNodes, ...settingNodes];
     const node = new BinaryNode('iq', {
       id,
       xmlns: 'w:g2',
@@ -3124,14 +3471,31 @@ class WhalibmobClient extends EventEmitter {
   async _groupParticipantAction(groupJid, action, jids) {
     const gJid = makeJid(groupJid);
     const arr  = Array.isArray(jids) ? jids : [jids];
-    const participantNodes = arr.map(j =>
-      new BinaryNode('participant', { jid: makeJid(j) }, null)
-    );
+    const { normalizeJidForTcToken } = require('./messages/TcTokenStore');
+    // Same shape whatsmeow's UpdateGroupParticipants builds: binary JIDs, and on
+    // an add, the phone number behind a LID plus our privacy token for them.
+    const participantNodes = arr.map(j => {
+      const jid   = makeJid(j);
+      const attrs = { jid: jidStrToObj(jid) };
+      let children = null;
+      if (action === 'add') {
+        if (jid.endsWith('@lid')) {
+          const pn = this._lidToPn.get(jid.split('@')[0].split(':')[0]);
+          if (pn) attrs.phone_number = jidStrToObj(pn + '@s.whatsapp.net');
+        }
+        const entry = this._tcTokenStore &&
+          this._tcTokenStore.get(normalizeJidForTcToken(jid));
+        if (entry && entry.token && entry.token.length) {
+          children = [new BinaryNode('privacy', {}, entry.token)];
+        }
+      }
+      return new BinaryNode('participant', attrs, children);
+    });
     const id = this._genMsgId();
     const node = new BinaryNode('iq', {
       id,
       xmlns: 'w:g2',
-      to:    gJid,
+      to:    jidStrToObj(gJid),
       type:  'set'
     }, [
       new BinaryNode(action, {}, participantNodes)
@@ -3161,19 +3525,38 @@ class WhalibmobClient extends EventEmitter {
   }
 
   // Change group description
-  // description: string or null to remove
-  async changeGroupDescription(groupJid, description) {
-    const id = this._genMsgId();
-    const children = description != null
-      ? [new BinaryNode('body', {}, Buffer.from(description, 'utf8'))]
-      : null;
-    const descAttrs = description != null
-      ? { id: this._genMsgId() }
-      : { delete: 'true' };
+  // description: string or null/'' to remove
+  //
+  // whatsmeow's SetGroupTopic sends prev=<current topic id> so the server can
+  // reject an edit made against a description someone else has already replaced.
+  // Without it the change is refused. The current id is looked up from the group
+  // metadata when the caller does not supply one.
+  async changeGroupDescription(groupJid, description, opts) {
+    opts = opts || {};
+    const gJid = makeJid(groupJid);
+    const id   = this._genMsgId();
+    const isDelete = description == null || description === '';
+
+    let prevId = opts.prevId;
+    if (prevId === undefined) {
+      try {
+        const meta = await this.getGroupMetadata(gJid);
+        prevId = meta && meta.descriptionId;
+      } catch (_) { prevId = null; }
+    }
+
+    const descAttrs = { id: opts.newId || this._genMsgId() };
+    if (prevId) descAttrs.prev = prevId;
+    let children = [new BinaryNode('body', {}, Buffer.from(String(description), 'utf8'))];
+    if (isDelete) {
+      descAttrs.delete = 'true';
+      children = null;
+    }
+
     const node = new BinaryNode('iq', {
       id,
       xmlns: 'w:g2',
-      to:    makeJid(groupJid),
+      to:    jidStrToObj(gJid),
       type:  'set'
     }, [
       new BinaryNode('description', descAttrs, children)
@@ -3181,6 +3564,61 @@ class WhalibmobClient extends EventEmitter {
     return this._sendIq(node);
   }
 
+  // ─── Group settings ───────────────────────────────────────────────────────
+  //
+  // Both are a single empty node whose TAG carries the state, exactly as
+  // whatsmeow's SetGroupAnnounce / SetGroupLocked send them — there is no
+  // attribute form of these.
+
+  // announce=true → only admins can send messages
+  async setGroupAnnounce(groupJid, announce) {
+    return this._groupSettingIq(groupJid, announce ? 'announcement' : 'not_announcement');
+  }
+
+  // locked=true → only admins can edit group info (subject, description, icon)
+  async setGroupLocked(groupJid, locked) {
+    return this._groupSettingIq(groupJid, locked ? 'locked' : 'unlocked');
+  }
+
+  // mode=true → new members must be approved by an admin
+  async setGroupJoinApprovalMode(groupJid, mode) {
+    return this._groupSettingIq(groupJid, 'membership_approval_mode', [
+      new BinaryNode('group_join', { state: mode ? 'on' : 'off' }, null)
+    ]);
+  }
+
+  // mode: 'all_member_add' | 'admin_add'
+  async setGroupMemberAddMode(groupJid, mode) {
+    return this._groupSettingIq(groupJid, 'member_add_mode',
+      Buffer.from(String(mode), 'utf8'));
+  }
+
+  // content is passed to the setting node verbatim: null for the flag settings
+  // whose state lives in the tag, child nodes for membership_approval_mode, raw
+  // bytes for member_add_mode.
+  async _groupSettingIq(groupJid, tag, content) {
+    const node = new BinaryNode('iq', {
+      id:    this._genMsgId(),
+      xmlns: 'w:g2',
+      to:    jidStrToObj(makeJid(groupJid)),
+      type:  'set'
+    }, [
+      new BinaryNode(tag, {}, content === undefined ? null : content)
+    ]);
+    const resp = await this._sendIq(node);
+    if (!resp) throw new Error(tag + ': 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(tag + ': server rejected the request' +
+        (code ? ' (' + code + (text ? ' ' + text : '') + ')' : ''));
+    }
+    // The group's own view of these flags is now stale.
+    this.invalidateGroupMetadata(groupJid);
+    return resp;
+  }
+
   // Change group picture
   // buf: Buffer with JPEG image data, or null to remove
   async changeGroupPicture(groupJid, buf) {
@@ -3197,17 +3635,63 @@ class WhalibmobClient extends EventEmitter {
     return this._sendIq(node);
   }
 
-  // Get group invite link
-  async queryGroupInviteLink(groupJid) {
-    const code = await this._queryGroupInviteCode(groupJid);
-    return code ? 'https://chat.whatsapp.com/' + code : null;
+  // Get the group's invite link.
+  //
+  // reset=true revokes the current link and returns a freshly minted one — the
+  // same IQ with type="set" instead of "get", which is how whatsmeow's
+  // GetGroupInviteLink handles its reset flag.
+  async queryGroupInviteLink(groupJid, reset) {
+    const code = await this._queryGroupInviteCode(groupJid, reset);
+    return code ? INVITE_LINK_PREFIX + code : null;
+  }
+
+  // Revoke the current invite link and return the replacement.
+  async revokeGroupInviteLink(groupJid) {
+    return this.queryGroupInviteLink(groupJid, true);
+  }
+
+  // Join a group from an invite link or bare code.
+  // Returns the JID of the group that was joined. When the group requires admin
+  // approval the server answers with a membership_approval_request instead, and
+  // that JID is returned — the join is pending, not complete.
+  async joinGroupWithLink(inviteCodeOrUrl) {
+    const code = stripInviteUrl(inviteCodeOrUrl);
+    const node = new BinaryNode('iq', {
+      id:    this._genMsgId(),
+      xmlns: 'w:g2',
+      to:    'g.us',
+      type:  'set'
+    }, [new BinaryNode('invite', { code }, null)]);
+
+    const resp = await this._sendIq(node);
+    if (!resp) throw new Error('joinGroupWithLink: no reply from server (IQ timed out)');
+    if (resp.attrs && resp.attrs.type === 'error') {
+      const errNode = findChild(resp, 'error');
+      const codeAttr = errNode && errNode.attrs && errNode.attrs.code;
+      // whatsmeow maps these two specifically: 410 is a revoked link, 406 an
+      // invalid one. Anything else is passed through as the server worded it.
+      const reason = String(codeAttr) === '410' ? 'the invite link has been revoked'
+                   : String(codeAttr) === '406' ? 'the invite link is not valid'
+                   : 'server rejected the request' +
+                     (codeAttr ? ' (' + codeAttr + ')' : '');
+      throw new Error('joinGroupWithLink: ' + reason);
+    }
+    const pending = findChild(resp, 'membership_approval_request');
+    if (pending && pending.attrs && pending.attrs.jid) {
+      return { jid: String(pending.attrs.jid), pendingApproval: true };
+    }
+    const grp = findChild(resp, 'group');
+    if (!grp || !grp.attrs || !grp.attrs.jid) {
+      throw new Error('joinGroupWithLink: server reply contained no <group> node');
+    }
+    return { jid: String(grp.attrs.jid), pendingApproval: false };
   }
 
   // queryGroupInviteInfo — fetch group metadata from an invite link code
   // Returns parsed group metadata (same shape as getGroupMetadata) or null.
   // inviteCode is the bare code (no URL prefix needed; URL also accepted).
   async queryGroupInviteInfo(inviteCodeOrUrl) {
-    const code = String(inviteCodeOrUrl).replace(/.*chat\.whatsapp\.com\//, '').trim();
+    const code = stripInviteUrl(inviteCodeOrUrl);
     const id   = this._genMsgId();
     const node = new BinaryNode('iq', {
       id,
@@ -3224,13 +3708,13 @@ class WhalibmobClient extends EventEmitter {
     return this._parseGroupNode(grp);
   }
 
-  async _queryGroupInviteCode(groupJid) {
+  async _queryGroupInviteCode(groupJid, reset) {
     const id = this._genMsgId();
     const node = new BinaryNode('iq', {
       id,
       xmlns: 'w:g2',
-      to:    makeJid(groupJid),
-      type:  'get'
+      to:    jidStrToObj(makeJid(groupJid)),
+      type:  reset ? 'set' : 'get'
     }, [
       new BinaryNode('invite', {}, null)
     ]);
@@ -3241,34 +3725,24 @@ class WhalibmobClient extends EventEmitter {
   }
 
   // Revoke group invite
+  // Revoke the current invite link. Returns the replacement link.
+  //
+  // This threw the reply away, so a caller had no way to learn the new code and
+  // had to query the link again. It is the same IQ revokeGroupInviteLink sends.
   async revokeGroupInvite(groupJid) {
-    const id = this._genMsgId();
-    const node = new BinaryNode('iq', {
-      id,
-      xmlns: 'w:g2',
-      to:    makeJid(groupJid),
-      type:  'set'
-    }, [
-      new BinaryNode('invite', {}, null)
-    ]);
-    return this._sendIq(node);
+    return this.revokeGroupInviteLink(groupJid);
   }
 
-  // Join group by invite code
-  async acceptGroupInvite(inviteCode) {
-    const id = this._genMsgId();
-    const node = new BinaryNode('iq', {
-      id,
-      xmlns: 'w:g2',
-      to:    'g.us',
-      type:  'set'
-    }, [
-      new BinaryNode('invite', { code: inviteCode }, null)
-    ]);
-    const resp = await this._sendIq(node);
-    if (!resp) return null;
-    const grp = findChild(resp, 'group');
-    return (grp && grp.attrs && (grp.attrs.jid || grp.attrs.value)) || null;
+  // Join a group by invite code or full link. Returns the group JID, or null.
+  //
+  // Accepts a full https://chat.whatsapp.com/... link as well as a bare code —
+  // it used to pass whatever it was given straight through as the code, so a
+  // pasted link was rejected. A group that gates joins on admin approval answers
+  // with membership_approval_request rather than group; that JID is returned too
+  // (use joinGroupWithLink when you need to tell the two apart).
+  async acceptGroupInvite(inviteCodeOrUrl) {
+    const r = await this.joinGroupWithLink(inviteCodeOrUrl).catch(() => null);
+    return r ? r.jid : null;
   }
 
   // Change group settings
@@ -3297,13 +3771,10 @@ class WhalibmobClient extends EventEmitter {
       default:
         throw new Error('Unknown group setting: ' + setting);
     }
-    const node = new BinaryNode('iq', {
-      id,
-      xmlns: 'w:g2',
-      to:    makeJid(groupJid),
-      type:  'set'
-    }, [body]);
-    return this._sendIq(node);
+    // Routed through the shared helper so a refusal from the server (not an
+    // admin, not a member) surfaces as an error instead of resolving null, and
+    // so the group's cached metadata does not keep reporting the old flags.
+    return this._groupSettingIq(groupJid, body.description, body.content);
   }
 
   // Query participants pending approval