whalibmob 5.14.0 → 5.14.2

package/README.md

@@ -86,8 +86,8 @@ npm install -g whalibmob
     - [Pin / Unpin](#pin--unpin)
     - [Archive / Unarchive](#archive--unarchive)
     - [Star / Unstar a Message](#star--unstar-a-message-cli)
-    - [Sync App State (CLI)](#cli-app-state)
-    - [Account Restriction Countdown](#cli-restriction)
+    - [Sync App State (CLI)](#sync-app-state)
+    - [Account Restriction Countdown](#account-restriction-countdown)
     - [Disappearing Messages](#cli-disappearing-messages)
     - [Default Disappearing Timer](#default-disappearing-timer)
     - [Block / Unblock](#block--unblock)
@@ -109,7 +109,7 @@ npm install -g whalibmob
     - [List Group Participants](#list-group-participants)
     - [Pending Join Requests](#pending-join-requests)
     - [Approve / Reject Join Requests](#approve--reject-join-requests)
-    - [Personal Invitations (CLI)](#cli-personal-invitations)
+    - [Personal Invitations (CLI)](#personal-invitations)
     - [Group Settings](#group-settings)
   - [Community Commands](#community-commands-cli)
   - [Newsletter / Channel Commands](#newsletter--channel-commands)
@@ -127,6 +127,7 @@ npm install -g whalibmob
       - [Reading it out of an APK you already have](#reading-it-out-of-an-apk-you-already-have)
     - [Device Attestation with Frida (optional)](#device-attestation-with-frida-optional)
     - [Connect](#connect)
+      - [Client Options](#client-options)
   - [Linking to an Existing Account (Pairing Code)](#linking-to-an-existing-account-pairing-code)
     - [Requesting a Pairing Code](#requesting-a-pairing-code)
     - [Reconnecting a Linked Session](#reconnecting-a-linked-session)
@@ -165,7 +166,7 @@ npm install -g whalibmob
     - [Persistent Files Written to Disk](#persistent-files-written-to-disk)
     - [Reading the History Store](#reading-the-history-store)
     - [tcToken — Error 463 Defense](#tctoken--error-463-defense)
-    - [When 463 Means the Account Is Restricted](#account-restriction)
+    - [When 463 Means the Account Is Restricted](#when-463-means-the-account-is-restricted)
     - [What Is Automatic vs What You Need to Do](#what-is-automatic-vs-what-you-need-to-do)
   - [Receiving Media](#receiving-media)
   - [Sending Messages](#sending-messages)
@@ -200,7 +201,7 @@ npm install -g whalibmob
     - [Mark a Chat Read / Unread](#mark-a-chat-read--unread)
     - [Pin / Unpin a Chat](#pin--unpin-a-chat)
     - [Star / Unstar a Message](#star--unstar-a-message)
-    - [Reading Changes Made Elsewhere](#app-state-sync)
+    - [Reading Changes Made Elsewhere](#reading-changes-made-elsewhere)
     - [Disappearing Messages](#disappearing-messages)
   - [User Queries](#user-queries)
     - [Check If a Number Has WhatsApp](#check-if-a-number-has-whatsapp)
@@ -357,7 +358,7 @@ wa> /reg confirm 919634847671 123456
 On success you will see:
 
 ```
-registered  session saved to /home/user/.waSession/919634847671.json
+registered  session saved to /home/user/.waSession/919634847671/919634847671.json
 now run: /connect 919634847671
 ```
 
@@ -1379,7 +1380,7 @@ wa> /reg code 919634847671 wa_old
 
 # confirm the code received
 wa> /reg confirm 919634847671 123456
-registered  session saved to /home/user/.waSession/919634847671.json
+registered  session saved to /home/user/.waSession/919634847671/919634847671.json
 now run: /connect 919634847671
 ```
 
@@ -1928,6 +1929,37 @@ client.on('connected', () => {
 await client.init('919634847671')
 ```
 
+#### Client Options
+
+Every option is optional; `sessionDir` is the only one most senders ever set.
+
+| Option | Default | What it does |
+|---|---|---|
+| `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. |
+| `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. |
+
+```js
+const client = new WhalibmobClient({
+  sessionDir:      path.join(process.env.HOME, '.waSession'),
+  sentCacheSize:   10000,
+  maxRetryResends: 8
+})
+```
+
+**When to raise the last two.** A recipient's device that cannot decrypt a message asks for it again, and whalibmob answers by rebuilding the Signal session and re-sending. Answering requires the original text, which is why sent messages are held: a receipt naming a message no longer in the cache cannot be answered at all, and that message — already acked by the server — silently never arrives.
+
+The defaults cover an ordinary sender. Raise `sentCacheSize` if you push messages faster than replies come back, which is easy to do when several recipients are being worked through at once: your own replies age out of the cache while the recipient is still asking for them. The symptom is this line in the debug log:
+
+```
+[DBG] RETRY_RECV msgId=... — no cached plaintext, skipping resend
+```
+
+If you see it, the cache is smaller than your in-flight window. An entry holds the encoded message, not the media it points at, so entries are small and raising the bound costs little memory.
+
 ## Linking to an Existing Account (Pairing Code)
 
 Registering a number over SMS makes whalibmob that number's **own device**. Sometimes that is not what you want — the number is already in use on a phone, or the verification SMS never arrives. For those cases whalibmob can instead connect over a **WebSocket** and link itself to an account that already exists, exactly the way the WhatsApp Web and desktop clients do.
@@ -2760,11 +2792,11 @@ connect()
 | `chat_removed` | `{ jid, kind, remote }` | A chat was cleared or deleted on another device |
 | `contact_update` | `{ jid, name, firstName, lid, username, removed, remote }` | A contact was renamed or removed elsewhere |
 | `push_name_update` | `{ name, remote }` | Your own display name changed on another device |
-| `app_state_sync` | `{ collections, applied }` | An app-state sync finished; see [Reading Changes Made Elsewhere](#app-state-sync) |
+| `app_state_sync` | `{ collections, applied }` | An app-state sync finished; see [Reading Changes Made Elsewhere](#reading-changes-made-elsewhere) |
 | `app_state_mutation` | `{ collection, index, action, removed }` | An app-state change this library does not model |
 | `app_state_key_missing` | `{ collection, keyId }` | App state cannot be read until your phone shares this key |
 | `app_state_keys` | `{ keys }` | Your phone shared app-state sync keys; a sync starts automatically |
-| `account_restriction` | `{ active, remaining, remainingMs, endsAtDate, enforcementType, reason, source }` | The account was restricted or the restriction was lifted — see [When 463 Means the Account Is Restricted](#account-restriction) |
+| `account_restriction` | `{ active, remaining, remainingMs, endsAtDate, enforcementType, reason, source }` | The account was restricted or the restriction was lifted — see [When 463 Means the Account Is Restricted](#when-463-means-the-account-is-restricted) |
 | `mex_notification` | `{ opName, data }` | A server push over `w:mex` this library does not model |
 
 `remote: true` on a chat event means the change was made on your phone or another
@@ -4729,9 +4761,10 @@ writes.
 From Node, the same thing:
 
 ```js
-const { refreshSessionVersion, currentVersionFor } = require('whalibmob')
+const { refreshSessionVersion, currentVersionFor, storeFileFor } = require('whalibmob')
 
-await refreshSessionVersion('/home/you/.waSession/5568936182750.json')
+const base = path.join(process.env.HOME, '.waSession')
+await refreshSessionVersion(storeFileFor(base, '5568936182750'))
 await currentVersionFor({ os: 'android' })   // { version, source }
 ```
 

package/lib/Client.js

@@ -29,7 +29,19 @@ const {
 // How many times a message may be re-sent in answer to retry receipts before
 // the client stops. Each resend can itself draw retries, so this is what keeps
 // an undecryptable message from turning into a flood.
-const MAX_RETRY_RESENDS = 2;
+//
+// Matched to the cap on retries we ask for ourselves (5, in _sendRetryRequest):
+// a device that keeps failing is worth the same number of rounds in either
+// direction. Two rounds gave up while the recipient was still asking.
+const MAX_RETRY_RESENDS = 5;
+
+// How many sent messages keep their plaintext for answering a retry receipt.
+// A receipt naming a message no longer held here cannot be answered at all —
+// the message is acked by the server and then silently never arrives. The
+// bound exists for memory, and an entry is small (the encoded Message, not the
+// media it points at), so it is set well above a busy sender's in-flight window
+// rather than at the smallest number that usually works.
+const SENT_CACHE_SIZE = 2000;
 const { NodeCache }       = require('@cacheable/node-cache');
 
 // Group metadata cache lifetime — matches DeviceManager's device cache.
@@ -369,6 +381,11 @@ class WhalibmobClient extends EventEmitter {
     // the second sender's pkmsg arrives after the key was consumed and deleted.
     this._retryAdvertisedPreKeys = new Set();
     this._sentMsgCache     = new Map();   // msgId → {plaintext, toJid, msgId, mediaType, options, recipientPhone}
+    // A sender that keeps more messages in flight than the cache holds outruns
+    // its own ability to answer retries, so both bounds are open to being
+    // raised for that kind of load.
+    this._sentCacheSize    = Number(opts.sentCacheSize)  > 0 ? Number(opts.sentCacheSize)  : SENT_CACHE_SIZE;
+    this._maxRetryResends  = Number(opts.maxRetryResends) > 0 ? Number(opts.maxRetryResends) : MAX_RETRY_RESENDS;
     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)
@@ -2415,7 +2432,7 @@ class WhalibmobClient extends EventEmitter {
     // another send and floods the chat. Give up after a few rounds and leave
     // the message undelivered rather than keep spamming.
     const depth = (cached.retryDepth || 0) + 1;
-    if (depth > MAX_RETRY_RESENDS) {
+    if (depth > this._maxRetryResends) {
       _whaDbg('[DBG] RETRY_RECV msgId=' + msgId + ' — giving up after ' +
         cached.retryDepth + ' resends\n');
       return;
@@ -2432,23 +2449,49 @@ class WhalibmobClient extends EventEmitter {
       : fromStr;
     const recipientPhone = targetJid.split('@')[0].split(':')[0].split('.')[0];
 
-    _whaDbg('[DBG] RETRY_RECV msgId=' + msgId + ' from=' + fromStr + ' — clearing session + resending\n');
+    // The retry names the device under one address family, but a contact holds
+    // a session under each: a Signal address is (user, device) with the server
+    // stripped, and the LID user and the phone user are different strings, so
+    // one session is not reachable under the other's name. Purging only the
+    // family the receipt happened to arrive in left the other one in place —
+    // the resend picked it straight back up and produced the same ciphertext
+    // the device had just said it could not read, so the message stayed
+    // undecryptable until something else rebuilt the session.
+    //
+    // This is what made a reply sent after a companion-device exchange stick on
+    // "Waiting for this message" on the primary: the receipt came in one family,
+    // the stale session sat in the other, and every resend re-used it.
+    const recipientUsers = new Set([recipientPhone]);
+    const mappedPn  = this._lidToPn && this._lidToPn.get(recipientPhone);
+    const mappedLid = this._pnToLid && this._pnToLid.get(recipientPhone);
+    if (mappedPn)  recipientUsers.add(mappedPn);
+    if (mappedLid) recipientUsers.add(mappedLid);
+
+    _whaDbg('[DBG] RETRY_RECV msgId=' + msgId + ' from=' + fromStr +
+      ' users=[' + [...recipientUsers].join(',') + '] — clearing session + resending\n');
 
     // Delete all Signal sessions for the recipient's devices so next send creates fresh pkmsg
     const sigStore = this._signal && this._signal.store;
     if (sigStore && sigStore._sessions) {
       const sessions = sigStore._sessions;
       Object.keys(sessions).forEach(addr => {
-        if (addr.startsWith(recipientPhone + '.')) {
+        // Match on the user segment rather than a bare prefix: "4071.0" must
+        // not be cleared by a retry for "407".
+        const user = addr.slice(0, addr.lastIndexOf('.'));
+        if (recipientUsers.has(user)) {
           _whaDbg('[DBG] RETRY deleting session for ' + addr);
           delete sessions[addr];
         }
       });
     }
 
-    // Clear device manager cache so we re-fetch devices on next send
+    // Clear device manager cache so we re-fetch devices on next send. LID device
+    // lists are filed under a "lid:" key, so clearing the bare user only ever
+    // dropped the phone-side list.
     if (this._devMgr) {
-      this._devMgr.clearCache([recipientPhone]);
+      const cacheKeys = [];
+      for (const u of recipientUsers) cacheKeys.push(u, 'lid:' + u);
+      this._devMgr.clearCache(cacheKeys);
     }
 
     // Re-send the message — will create fresh pre-key (pkmsg) sessions.
@@ -2697,6 +2740,18 @@ class WhalibmobClient extends EventEmitter {
     this._retryPending.delete(msgId);
   }
 
+  // Hold a sent message's plaintext so a retry receipt naming it can be
+  // answered. Both send paths file their entry here so the bound lives in one
+  // place instead of being repeated as a literal at each call site.
+  _cacheSentMessage(entry) {
+    if (!this._sentMsgCache || !entry || !entry.msgId) return;
+    this._sentMsgCache.set(entry.msgId, entry);
+    // Map preserves insertion order, so the first key is the oldest entry.
+    while (this._sentMsgCache.size > this._sentCacheSize) {
+      this._sentMsgCache.delete(this._sentMsgCache.keys().next().value);
+    }
+  }
+
   _sendRetryRequest(msgId, origNode) {
     const existing = this._retryPending.get(msgId);
     const count    = existing ? existing.count + 1 : 1;

package/lib/messages/MessageSender.js

@@ -1091,17 +1091,10 @@ class MessageSender {
     }
 
     // Cache plaintext so Client can re-send with fresh session on recipient retry
-    if (this._client._sentMsgCache) {
-      this._client._sentMsgCache.set(msgId, {
-        plaintext, toJid, msgId, mediaType, options, recipientPhone,
-        retryDepth: options._retryDepth || 0
-      });
-      // Keep cache bounded — evict oldest entries beyond 200
-      if (this._client._sentMsgCache.size > 200) {
-        const firstKey = this._client._sentMsgCache.keys().next().value;
-        this._client._sentMsgCache.delete(firstKey);
-      }
-    }
+    this._client._cacheSentMessage({
+      plaintext, toJid, msgId, mediaType, options, recipientPhone,
+      retryDepth: options._retryDepth || 0
+    });
 
     const dispatchResult = await this._dispatchAndAck(msgNode, msgId);
 
@@ -1436,16 +1429,10 @@ class MessageSender {
     // does, and without this the client had nothing to re-send and dropped it
     // with "no cached plaintext" — so the message was acked by the server and
     // then silently never arrived.
-    if (this._client._sentMsgCache) {
-      this._client._sentMsgCache.set(msgId, {
-        plaintext, toJid: groupJid, msgId, mediaType, options, isGroup: true,
-        retryDepth: options._retryDepth || 0
-      });
-      if (this._client._sentMsgCache.size > 200) {
-        const firstKey = this._client._sentMsgCache.keys().next().value;
-        this._client._sentMsgCache.delete(firstKey);
-      }
-    }
+    this._client._cacheSentMessage({
+      plaintext, toJid: groupJid, msgId, mediaType, options, isGroup: true,
+      retryDepth: options._retryDepth || 0
+    });
 
     const msgNode = new BinaryNode('message', stanzaAttrs, msgContent);
     const dispatchResult = await this._dispatchAndAck(msgNode, msgId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whalibmob",
-  "version": "5.14.0",
+  "version": "5.14.2",
   "description": "WhatsApp library for interaction with WhatsApp Mobile API and web ",
   "author": "Kunboruto20",
   "main": "index.js",