whalibmob 5.14.19 → 5.17.0

package/README.md

@@ -9,6 +9,8 @@
 
 CONTACT ME ON TELEGRAM  IF YOU WANT TO WORK WITH ME AND IF YOU HAVE PROBLEM WITH WHALIBMOB : @brtyu545
 
+**Need test numbers to try whalibmob with?** Message me on Telegram at **@brtyu545** — I can provide phone numbers for receiving SMS verification codes, so you can register and test whalibmob without using your own number.
+
 If you want News about whalibmob enter this whalibmob channel: https://t.me/+sHN4MDCyB7U5OWY0
 
 
@@ -2005,6 +2007,7 @@ Every option is optional; `sessionDir` is the only one most senders ever set.
 | `sessionDir` | `~/.waSession` | The authentication folder. Each number gets its own subfolder inside it — see [Saving & Restoring Sessions](#saving--restoring-sessions). |
 | `autoFixNumber` | `true` | Re-file the session automatically when the server reports the account under a different number. Set `false` to be told instead of fixed — see [The Number WhatsApp Files Your Account Under](#the-number-whatsapp-files-your-account-under). |
 | `autoRead` | `true` | Send read receipts for incoming messages. `false` leaves them unread. |
+| `refreshVersion` | `true` | **iOS sessions only.** Check the App Store for the current build on every `init()` and write it into the session file. Set `false` to keep announcing whatever the session registered with — see [Keeping the Announced Version Current](#keeping-the-announced-version-current). Android is unaffected either way. |
 | `pino` | off | Debug logging. `true` turns it on at `debug` level; an object is passed to `pino` as-is. |
 | `sentCacheSize` | `2000` | How many sent messages keep their plaintext so a retry receipt naming them can be answered. |
 | `maxRetryResends` | `5` | How many times one message may be re-sent in answer to retry receipts before the client gives up. |
@@ -2571,6 +2574,60 @@ of a pile by prefix.
 > is moved unless you ask — `wa migrate-sessions` does that, one number or all
 > of them, and re-running it is safe.
 
+### Keeping the Announced Version Current
+
+Every connection announces the WhatsApp build it claims to be. The server checks
+it, and when it stops recognising the number it refuses the handshake with
+`405` — a failure that says nothing about the version and has nothing to do with
+the account.
+
+A session records the version it registered with. Left alone it announces that
+same number forever, so a number registered in spring is still claiming a spring
+build in autumn, and one day the connect simply stops working.
+
+**iOS sessions now refresh themselves.** On every `init()` the client asks the
+App Store what the current build is and writes it into `<phone>.json` before the
+handshake. Nothing to run, nothing to remember:
+
+```js
+client.on('version_update', ({ from, to }) => {
+  console.log('announcing', to, 'instead of', from)
+})
+
+await client.init('40756469325')
+```
+
+Three rules keep this from being the thing that breaks a working session:
+
+- **It never goes backwards.** The App Store lookup answers with a pinned
+  fallback rather than failing when it cannot reach the network, and that
+  fallback can easily be older than what the session holds. Moving a session to
+  an older version is the one outcome that makes a `405` *more* likely.
+- **`WA_VERSION` still wins.** A version pinned on the way out of a `405` is a
+  decision, and is never quietly replaced.
+- **A failed lookup changes nothing.** The session keeps the version it has and
+  the connect carries on.
+
+Set `{ refreshVersion: false }` on the client to turn it off.
+
+> [!NOTE]
+> **Android is deliberately left alone.** Its version comes out of the APK the
+> token material was read from, and the two have to agree — the registration
+> token is computed from that build. Refreshing the announced version behind the
+> caller's back would put it out of step with the token. Android keeps the
+> explicit flow: `wa apk-material --download`, then `wa refresh-version`.
+
+The manual tool still works on both platforms, and is the only way to move an
+Android session:
+
+```bash
+wa refresh-version 40756469325                    # current build for the platform
+wa refresh-version 40756469325 --version 2.25.1.2 # or one you name
+```
+
+Companion sessions have never had this problem: `connectWeb()` reads the live
+web revision on every connect already.
+
 ### One-time Pre-keys
 
 A pre-key is a one-shot Diffie-Hellman key the account leaves with the server so

package/index.js

@@ -7,6 +7,7 @@ const SessionPaths = require('./lib/SessionPaths');
 const { createNewStore, saveStore, loadStore, toSixParts, fromSixParts, storeToJson, storeFromJson } = require('./lib/Store');
 const { checkIfRegistered, requestSmsCode, verifyCode } = require('./lib/Registration');
 const { SignalProtocol } = require('./lib/signal/SignalProtocol');
+const WAM = require('./lib/WAM');
 const { SignalStore } = require('./lib/signal/SignalStore');
 const { SenderKeyStore, SenderKeyCrypto } = require('./lib/signal/SenderKey');
 const { DeviceManager } = require('./lib/DeviceManager');
@@ -103,6 +104,14 @@ module.exports = {
   encodeCompanionRegisterPayload,
   encodeCompanionLoginPayload,
   fetchWaWebVersion,
+  // WAM — the web client's stats channel: the event/global tables, the binary
+  // encoder and the BinaryInfo holder, all as the reference client defines
+  // them. See client.wamBuffer / client.sendWAMBuffer().
+  WAM,
+  encodeWAM:  WAM.encodeWAM,
+  BinaryInfo: WAM.BinaryInfo,
+  WEB_EVENTS: WAM.WEB_EVENTS,
+  WEB_GLOBALS: WAM.WEB_GLOBALS,
   // Signal / encryption internals
   SignalProtocol,
   SignalStore,

package/lib/Client.js

@@ -175,6 +175,18 @@ const RECONNECT_BACKOFF   = [1000, 2000, 4000, 8000, 15000, 30000];
 
 // How many attempts an upload gets before it is left for the next check, and
 // how long it waits between them.
+// How long a placeholder resend waits before it is actually asked for, and how
+// long it waits for an answer before the request is forgotten. The first is
+// there because most of these resolve on their own; the second because a phone
+// that is switched off will never answer and the entry must not block a later
+// attempt forever.
+const PLACEHOLDER_SETTLE_MS  = 2000;
+const PLACEHOLDER_TIMEOUT_MS = 8000;
+// An hour, matching the reference client, and a ceiling so a flood of
+// undecryptable stanzas cannot grow the map without bound.
+const PLACEHOLDER_TTL_MS     = 60 * 60 * 1000;
+const PLACEHOLDER_MAX        = 500;
+
 const PRE_KEY_UPLOAD_TRIES   = 4;
 const PRE_KEY_UPLOAD_BACKOFF = (attempt) => Math.min(1000 * Math.pow(2, attempt), 10000);
 
@@ -367,6 +379,13 @@ class WhalibmobClient extends EventEmitter {
     // automatically on the first refused login. Set { autoFixNumber: false } to
     // be told about it instead.
     this._autoFixNumber  = opts.autoFixNumber !== false;
+    // An iOS session checks the App Store for the current build on every
+    // connect and writes it back — see _refreshIosVersion(). Set
+    // { refreshVersion: false } to keep announcing whatever the session
+    // registered with. Android is not affected either way: its version comes
+    // out of the APK the token material was read from, and that stays a
+    // deliberate step.
+    this._refreshVersion = opts.refreshVersion !== false;
     this._numberFixAttempted = false;
     this._pingTimer               = null;
     this._keepTimer               = null;
@@ -381,6 +400,19 @@ class WhalibmobClient extends EventEmitter {
     // One mutex per client — two accounts in the same process are unrelated
     // and must not wait on each other.
     this._preKeyMutex             = new Mutex();
+    // How far this machine's clock is from the server's, in milliseconds.
+    //
+    // The server stamps `t` on the stanzas that matter — <success> and
+    // pair-success — and the unified_session id is derived from a clock that is
+    // supposed to be the server's, not ours. Computing it from Date.now() alone
+    // makes the id drift by however wrong the local clock is, which on a phone
+    // or a container without NTP can be minutes. Zero until the server says
+    // otherwise, which is the same as not correcting at all.
+    this._serverTimeOffsetMs      = 0;
+    // Message ids we have asked the phone to resend, and have not seen since.
+    // An entry is the request itself: while it is there, no second request for
+    // that id goes out. Bounded and time-limited — see _placeholderResendCache.
+    this.__placeholderResend      = new Map();
     // Incoming work runs one item at a time, in arrival order.
     //
     // Stanzas arrive faster than they are handled, and the handling is
@@ -472,6 +504,67 @@ class WhalibmobClient extends EventEmitter {
     return this.init(phoneNumber);
   }
 
+  /**
+   * Bring an iOS session's announced version up to date, on every connect.
+   *
+   * A session records the version it registered with and announces that
+   * forever after. Months later the server stops accepting it and the connect
+   * is refused with a 405 that says nothing about why — and the only remaining
+   * move, before this, was to run `wa refresh-version` by hand or register the
+   * number again. The companion path never had that problem because
+   * connectWeb() reads the live revision every time; this is the same idea for
+   * the primary one.
+   *
+   * iOS only, and deliberately so. Android's version comes out of the APK the
+   * token material was read from — the two have to agree, because the token is
+   * computed from that build — so refreshing it behind the caller's back would
+   * put the announced version and the token out of step. Android keeps its
+   * Play Store flow exactly as it was.
+   *
+   * Three rules keep this from being the thing that breaks a working session:
+   *
+   *   • It never goes backwards. fetchIosVersion() answers with the pinned
+   *     fallback rather than failing when the lookup does not work, and that
+   *     fallback can easily be older than what a session already holds. Moving
+   *     a session to an older version is the one outcome that makes a 405 more
+   *     likely rather than less.
+   *   • WA_VERSION still wins. Someone who has pinned a version on the way out
+   *     of a 405 must not have it quietly replaced.
+   *   • It never throws, and it never blocks for long. A lookup that fails
+   *     leaves the session exactly as it was and the connect carries on.
+   */
+  async _refreshIosVersion() {
+    if (!this._refreshVersion || this._mode === 'web' || !this._store) return;
+    if (process.env.WA_VERSION) {
+      _whaDbg('[DBG] VERSION refresh skipped — WA_VERSION is set');
+      return;
+    }
+
+    const device = this._store.device || getDeviceConfig();
+    if (device.os === 'android') return;   // the APK flow owns this
+
+    try {
+      const { compareVersions } = require('./Registration');
+      const before = this._store.version;
+      const live   = await fetchIosVersion(!!device.business);
+      if (!live) return;
+
+      if (before && compareVersions(live, before) <= 0) {
+        _whaDbg('[DBG] VERSION already current (' + before + ', App Store says ' + live + ')');
+        return;
+      }
+
+      this._store.version = live;
+      this._persistStore();
+      _whaDbg('[DBG] VERSION refreshed ' + (before || 'none') + ' → ' + live +
+        ' (App Store listing)');
+      this.emit('version_update', { from: before || null, to: live, source: 'App Store listing' });
+    } catch (err) {
+      // A session that cannot ask keeps the version it has.
+      _whaDbg('[DBG] VERSION refresh failed: ' + (err && err.message));
+    }
+  }
+
   async init(phoneNumber) {
     phoneNumber = String(phoneNumber).replace(/\D/g, '');
     this._phoneNumber = phoneNumber;
@@ -501,6 +594,10 @@ class WhalibmobClient extends EventEmitter {
       );
     }
 
+    // Before the handshake, which reads the version straight out of the store.
+    // iOS only; Android keeps its APK flow. See _refreshIosVersion().
+    await this._refreshIosVersion();
+
     const signalFile  = path.join(this._sessionDir, `${phoneNumber}.signal.json`);
     const skFile      = path.join(this._sessionDir, `${phoneNumber}.sk.json`);
     const tcTokenFile = path.join(this._sessionDir, `${phoneNumber}.tctoken.json`);
@@ -926,6 +1023,11 @@ class WhalibmobClient extends EventEmitter {
   async _handleCompanionFinish(node) {
     const { buildCompanionFinishBundle } = require('./PairingCode');
 
+    // Same as the reference client does on pair-success: this stanza carries
+    // the server's clock, and the unified_session sent a moment later is
+    // derived from it.
+    this._updateServerTimeOffset(node);
+
     const reg = findChild(node, 'link_code_companion_reg');
     if (!reg) return;
 
@@ -1084,11 +1186,27 @@ class WhalibmobClient extends EventEmitter {
   // pairing and after each login. It carries no state we need; sending it keeps
   // our traffic shaped like the client we are claiming to be. Failures are
   // ignored, as they are in the reference.
+  // Take the server's clock from whatever stanza carries it.
+  //
+  // Mirrors the reference client: read `t` off <success> and off pair-success,
+  // and keep the difference from ours. Anything unparseable or non-positive is
+  // ignored rather than allowed to poison the offset.
+  _updateServerTimeOffset(node) {
+    const t = node && node.attrs && node.attrs.t;
+    if (!t) return;
+    const parsed = Number(t);
+    if (!Number.isFinite(parsed) || parsed <= 0) return;
+    this._serverTimeOffsetMs = parsed * 1000 - Date.now();
+    _whaDbg('[DBG] SERVER_TIME_OFFSET ' + this._serverTimeOffsetMs + 'ms');
+  }
+
   _sendUnifiedSession() {
     if (this._mode !== 'web' || !this._socket) return;
     try {
       const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
-      const id = ((Date.now() + 3 * 24 * 60 * 60 * 1000) % WEEK_MS).toString();
+      // Server clock, not ours — see _serverTimeOffsetMs.
+      const now = Date.now() + this._serverTimeOffsetMs;
+      const id = ((now + 3 * 24 * 60 * 60 * 1000) % WEEK_MS).toString();
       this._socket.sendNode(new BinaryNode('ib', {}, [
         new BinaryNode('unified_session', { id }, null)
       ]));
@@ -1305,6 +1423,9 @@ class WhalibmobClient extends EventEmitter {
     // ── Feature 1: Parse <success> node ──────────────────────────────────────
     // Extract ADVSignedDeviceIdentity, platform, and other account info that
     // the server provides on each successful authentication.
+    // The server's clock, before anything derived from it is computed.
+    this._updateServerTimeOffset(successNode);
+
     this._parseSuccessNode(successNode);
 
     // ── Feature 3 (part A): Send <active> IQ ─────────────────────────────────
@@ -2044,6 +2165,27 @@ class WhalibmobClient extends EventEmitter {
 
   // ─── Node dispatch ────────────────────────────────────────────────────────
 
+  // The queue the reconnect backlog drains through. Built on first use so a
+  // session that never goes offline never pays for it.
+  get _offlineQueue() {
+    if (!this.__offlineQueue) {
+      const { makeOfflineNodeProcessor } = require('./OfflineNodeProcessor');
+      this.__offlineQueue = makeOfflineNodeProcessor(new Map([
+        ['message',      (n) => this._handleMessage(n)],
+        ['receipt',      (n) => this._handleReceipt(n)],
+        ['notification', (n) => this._handleNotification(n)],
+        ['call',         (n) => this._handleCall(n)]
+      ]), {
+        isOpen:  () => !!(this._socket && this._connected),
+        onError: (err, ctx) => {
+          _whaDbg('[DBG] OFFLINE_QUEUE_ERR ' + ctx + ': ' + (err && err.message));
+          this.emit('node_error', { tag: ctx, err });
+        }
+      });
+    }
+    return this.__offlineQueue;
+  }
+
   _onNode(node) {
     if (!node || !node.description) return;
     const tag = node.description;
@@ -2061,6 +2203,16 @@ class WhalibmobClient extends EventEmitter {
     // behind it in the same offline batch was lost. Contain it: log the stanza
     // that did it, tell the caller, carry on reading.
     try {
+      // Backlog from the reconnect, not live traffic. The server stamps these
+      // `offline`, and handling a burst of them the way live stanzas are
+      // handled starts every one of them at once — see OfflineNodeProcessor.
+      if (node.attrs && node.attrs.offline &&
+          (tag === 'message' || tag === 'receipt' ||
+           tag === 'notification' || tag === 'call')) {
+        this._offlineQueue.enqueue(tag, node);
+        return;
+      }
+
       if      (tag === 'iq')           this._handleIq(node);
       else if (tag === 'message')      this._handleMessage(node);
       else if (tag === 'receipt')      this._handleReceipt(node);
@@ -2517,6 +2669,9 @@ class WhalibmobClient extends EventEmitter {
           return;
         }
 
+        // If we had asked the phone to resend this one, it has answered.
+        this._resolvePlaceholderResend(id);
+
         this.emit('message', { id, from, participant, ts, decoded, node });
         this._sendReadReceipt(id, fromRaw, partRaw);
 
@@ -3053,6 +3208,29 @@ class WhalibmobClient extends EventEmitter {
 
     if (!this._socket || !this._connected) return;
 
+    // Ask the phone as well, for the first couple of rounds.
+    //
+    // The retry receipt asks the *sender* to encrypt it again, which only helps
+    // when their session is the thing that went wrong. When ours is — a spent
+    // pre-key, a ratchet that moved on — no amount of asking them helps, and
+    // the plaintext is sitting on our own phone the whole time. The reference
+    // client asks both, and gives up on the phone after two rounds.
+    //
+    // Deliberately not awaited: a retry receipt must go out now, and this is a
+    // slower second route to the same message.
+    if (count <= 2) {
+      const attrs = (origNode && origNode.attrs) || {};
+      const from  = attrs.from ? String(attrs.from) : null;
+      if (from) {
+        this.requestPlaceholderResend({
+          remoteJid: from,
+          fromMe:    false,
+          id:        msgId
+        }).catch(err =>
+          _whaDbg('[DBG] PLACEHOLDER request failed: ' + (err && err.message)));
+      }
+    }
+
     // Pick a prekey that is not already advertised by another unresolved retry.
     // A prekey is deleted the moment a pkmsg using it is decrypted, so handing
     // the same one to two senders means the second arrives after the key is
@@ -3839,6 +4017,213 @@ class WhalibmobClient extends EventEmitter {
     this._ensureServerPreKeys('server asked');
   }
 
+  // Outstanding resend requests, with an hour's memory and a ceiling.
+  //
+  // A plain Map would hold every id the session ever failed to decrypt. The TTL
+  // is what the reference client uses; the ceiling is what keeps a burst of
+  // undecryptable stanzas from growing it without bound, dropping the oldest
+  // entries first — the ones whose request has already timed out anyway.
+  get _placeholderResendCache() {
+    const map = this.__placeholderResend;
+    const now = Date.now();
+    return {
+      has: (id) => {
+        const e = map.get(id);
+        if (!e) return false;
+        if (Date.now() - e.at > PLACEHOLDER_TTL_MS) { map.delete(id); return false; }
+        return true;
+      },
+      get: (id) => {
+        const e = map.get(id);
+        if (!e) return undefined;
+        if (Date.now() - e.at > PLACEHOLDER_TTL_MS) { map.delete(id); return undefined; }
+        return e.value;
+      },
+      set: (id, value) => {
+        map.set(id, { value, at: now });
+        // Map keeps insertion order, so the first key is the oldest.
+        while (map.size > PLACEHOLDER_MAX) map.delete(map.keys().next().value);
+      },
+      delete: (id) => map.delete(id),
+      get size() { return map.size; }
+    };
+  }
+
+  // ─── Peer data operations, and asking the phone to resend ─────────────────
+  //
+  // A peer-data-operation request is how a companion asks its own phone for
+  // something. It goes out as a ProtocolMessage addressed to this account, with
+  // the stanza marked category="peer" so the server routes it to the other
+  // devices instead of delivering it as a chat message to yourself.
+  //
+  // @param {object} pdo  see encodePeerDataOperationRequestMessage
+  // @returns {Promise<string>} the id of the message that carried the request
+  async sendPeerDataOperationMessage(pdo) {
+    if (!this._sender || !this._connected) throw new Error('Not connected');
+    const me = this._store && this._store.me && this._store.me.id;
+    if (!me) throw new Error('Not authenticated');
+
+    const {
+      encodeMessage, encodeProtocolMessage,
+      encodePeerDataOperationRequestMessage,
+      PROTOCOL_TYPE_PEER_DATA_OPERATION_REQUEST
+    } = require('./proto/MessageProto');
+
+    const payload = encodeProtocolMessage({
+      type: PROTOCOL_TYPE_PEER_DATA_OPERATION_REQUEST,
+      peerDataOperationRequestMessage: encodePeerDataOperationRequestMessage(pdo)
+    });
+    const msgBuf = encodeMessage('protocol', payload);
+    const msgId  = this._genMsgId();
+
+    await this._sender._sendMessage(String(me), msgId, msgBuf, 'text', {
+      _protocol:      true,           // not a reach-out; keeps it off the tcToken gate
+      category:       'peer',
+      pushPriority:   'high_force',
+      additionalNodes: [new BinaryNode('meta', { appdata: 'default' }, null)]
+    });
+    return msgId;
+  }
+
+  /**
+   * Ask the phone to send a message again.
+   *
+   * A message that cannot be decrypted — a session that moved on, a key that
+   * was already spent — is gone as far as this device is concerned. The phone
+   * still has the plaintext, so the fix is to ask it, not to retry the
+   * ciphertext.
+   *
+   * The cache is what stops that turning into a storm. One request per message
+   * id, and the entry is what says a request is outstanding:
+   *
+   *   • already asked            → say nothing, return
+   *   • it arrives within 2s     → the entry is gone, answer 'RESOLVED'
+   *   • no answer after 8s       → drop the entry so a later attempt may ask
+   *
+   * @param {{remoteJid: string, fromMe: boolean, id: string}} messageKey
+   * @param {object} [msgData]  metadata to keep for whatever handles the reply
+   * @returns {Promise<string|undefined|'RESOLVED'>}
+   */
+  async requestPlaceholderResend(messageKey, msgData) {
+    if (!messageKey || !messageKey.id) return;
+    const me = this._store && this._store.me && this._store.me.id;
+    if (!me) throw new Error('Not authenticated');
+
+    const cache = this._placeholderResendCache;
+    if (cache.has(messageKey.id)) {
+      _whaDbg('[DBG] PLACEHOLDER already requested for ' + messageKey.id);
+      return;
+    }
+    cache.set(messageKey.id, msgData || true);
+
+    // Give it a moment. Most of these resolve on their own — the message that
+    // failed to decrypt is very often followed by the sender's own retry.
+    await new Promise(r => setTimeout(r, PLACEHOLDER_SETTLE_MS));
+    if (!cache.has(messageKey.id)) {
+      _whaDbg('[DBG] PLACEHOLDER ' + messageKey.id + ' arrived before asking');
+      return 'RESOLVED';
+    }
+
+    // The phone may simply be off. Let the entry go so this is not the last
+    // word on the subject.
+    setTimeout(() => {
+      if (cache.has(messageKey.id)) {
+        _whaDbg('[DBG] PLACEHOLDER no answer for ' + messageKey.id + ' — phone likely offline');
+        cache.delete(messageKey.id);
+      }
+    }, PLACEHOLDER_TIMEOUT_MS).unref?.();
+
+    const { PeerDataOperationRequestType } = require('./proto/MessageProto');
+    _whaDbg('[DBG] PLACEHOLDER requesting resend of ' + messageKey.id);
+    return this.sendPeerDataOperationMessage({
+      peerDataOperationRequestType: PeerDataOperationRequestType.PLACEHOLDER_MESSAGE_RESEND,
+      placeholderMessageResendRequest: [{ messageKey }]
+    });
+  }
+
+  /**
+   * Ask the phone for older messages in a chat.
+   *
+   * The same channel, a different operation — this is what an on-demand
+   * history sync is built on.
+   */
+  async fetchMessageHistory(count, oldestMsgKey, oldestMsgTimestampMs) {
+    const { PeerDataOperationRequestType } = require('./proto/MessageProto');
+    return this.sendPeerDataOperationMessage({
+      peerDataOperationRequestType: PeerDataOperationRequestType.HISTORY_SYNC_ON_DEMAND,
+      historySyncOnDemandRequest: {
+        chatJid:              oldestMsgKey.remoteJid,
+        oldestMsgId:          oldestMsgKey.id,
+        oldestMsgFromMe:      !!oldestMsgKey.fromMe,
+        onDemandMsgCount:     count,
+        oldestMsgTimestampMs: oldestMsgTimestampMs
+      }
+    });
+  }
+
+  /** Note that a message we asked about has turned up, so nothing is owed. */
+  _resolvePlaceholderResend(msgId) {
+    if (msgId && this._placeholderResendCache.has(msgId)) {
+      this._placeholderResendCache.delete(msgId);
+      _whaDbg('[DBG] PLACEHOLDER resolved ' + msgId);
+    }
+  }
+
+  // ─── WAM — the stats channel WhatsApp Web reports on ──────────────────────
+  //
+  // A WAM buffer is a batch of telemetry events encoded in WhatsApp's own
+  // binary format and posted to `w:stats`. The web client sends these
+  // constantly; a companion session that never does is one more thing that
+  // distinguishes it from a browser.
+  //
+  // Nothing here fires on its own, and that matches the reference client's
+  // library exactly — it builds the same three pieces, exposes the same
+  // `wamBuffer` and the same `sendWAMBuffer`, and never calls the latter
+  // itself. What to report, and when, is the application's decision.
+  //
+  //   const { WAM } = require('whalibmob')
+  //
+  //   client.wamBuffer.sequence = 1
+  //   client.wamBuffer.events = [{
+  //     WamDroppedEvent: {
+  //       props:   { droppedEventCode: 3, droppedEventCount: 1, isFromWamsys: true },
+  //       globals: {}
+  //     }
+  //   }]
+  //   await client.sendWAMBuffer(WAM.encodeWAM(client.wamBuffer))
+  //
+  // The event and field names come from WAM.WEB_EVENTS and WAM.WEB_GLOBALS,
+  // which are the reference client's tables verbatim.
+
+  /** The buffer an application fills in before encoding. */
+  get wamBuffer() {
+    if (!this._wamBuffer) {
+      const { BinaryInfo } = require('./WAM');
+      this._wamBuffer = new BinaryInfo();
+    }
+    return this._wamBuffer;
+  }
+
+  /**
+   * Post an encoded WAM buffer to the server.
+   *
+   * @param   {Buffer} wamBuffer  output of WAM.encodeWAM()
+   * @returns {Promise<object|null>}  the server's IQ result, or null on timeout
+   */
+  async sendWAMBuffer(wamBuffer) {
+    if (!this._socket || !this._connected) throw new Error('Not connected');
+    if (!Buffer.isBuffer(wamBuffer)) {
+      throw new Error('sendWAMBuffer expects a Buffer from WAM.encodeWAM()');
+    }
+    return this._sendIq(new BinaryNode('iq', {
+      id:    this._genMsgId(),
+      to:    's.whatsapp.net',
+      xmlns: 'w:stats'
+    }, [
+      new BinaryNode('add', { t: String(Math.round(Date.now() / 1000)) }, wamBuffer)
+    ]));
+  }
+
   // ─── IQ helper (send + await response) ────────────────────────────────────
 
   _sendIq(node) {