whalibmob 5.21.0 → 5.22.0

package/README.md

@@ -132,6 +132,8 @@ npm install -g whalibmob
       - [Client Options](#client-options)
   - [Linking to an Existing Account (Pairing Code or QR)](#linking-to-an-existing-account-pairing-code-or-qr)
     - [Requesting a Pairing Code](#requesting-a-pairing-code)
+    - [Linking by QR Code](#linking-by-qr-code)
+    - [After the Link — Same for Both Paths](#after-the-link--same-for-both-paths)
     - [Reconnecting a Linked Session](#reconnecting-a-linked-session)
     - [Choosing Your Own Code](#choosing-your-own-code)
     - [Options](#options)
@@ -153,13 +155,20 @@ npm install -g whalibmob
   - [The Number WhatsApp Files Your Account Under](#the-number-whatsapp-files-your-account-under)
   - [When Registration Is Refused for Consent](#when-registration-is-refused-for-consent)
   - [The Push Token](#the-push-token)
+    - [Receiving the Code over Push](#receiving-the-code-over-push-without-typing-it)
   - [Routing Traffic Through a Proxy](#routing-traffic-through-a-proxy)
+    - [What Goes Through It](#what-goes-through-it)
   - [Saving & Restoring Sessions](#saving--restoring-sessions)
+    - [Keeping the Announced Version Current](#keeping-the-announced-version-current)
+    - [One-time Pre-keys](#one-time-pre-keys)
+    - [Where the Folder Comes From](#where-the-folder-comes-from)
+    - [Working Out the Paths Yourself](#working-out-the-paths-yourself)
   - [Signal Store Utilities](#signal-store-utilities)
     - [makeCacheableSignalKeyStore](#makecacheablesignalkeystore)
     - [addTransactionCapability](#addtransactioncapability)
     - [assertMeId](#assertmeid)
     - [initAuthCreds](#initauthcreds)
+    - [Recommended Stacking Pattern](#recommended-stacking-pattern)
   - [Handling Events](#handling-events)
     - [Example to Start](#example-to-start)
     - [All Events](#all-events)
@@ -248,11 +257,13 @@ npm install -g whalibmob
     - [Query Metadata](#query-metadata)
     - [Get Request Join List](#get-request-join-list)
     - [Approve / Reject Request Join](#approve--reject-request-join)
-    - [Personal Invitations](#personal-invitations)
+    - [Personal Invitations](#personal-invitations-1)
     - [Toggle Ephemeral in Group](#toggle-ephemeral-in-group)
 - [WhatsApp IDs](#whatsapp-ids)
 - [Transport](#transport)
 - [Media Encryption](#media-encryption)
+  - [Sending (Upload Flow)](#sending-upload-flow)
+  - [Receiving (Download + Decrypt Flow)](#receiving-download--decrypt-flow)
 - [Device Emulation](#device-emulation)
   - [Quick Start](#device-quick-start)
   - [iOS Profiles](#ios-profiles)
@@ -261,6 +272,7 @@ npm install -g whalibmob
   - [Version & Token Overrides](#version--token-overrides)
   - [When the server answers 405 on connect](#when-the-server-answers-405-on-connect)
   - [Finding out what a 405 objects to](#finding-out-what-a-405-objects-to)
+- [License](#license)
 
 ---
 
@@ -1616,6 +1628,10 @@ wa> /quit
 
 ## Library API
 
+Everything the CLI does is available as a Node.js library. The sections below
+cover connecting an account, sending and receiving every message type, groups,
+communities, channels, presence, privacy, history sync, and device emulation.
+
 ## Connecting Account
 
 ### Register a New Number

package/lib/Client.js

@@ -574,10 +574,24 @@ class WhalibmobClient extends EventEmitter {
     const source   = android ? 'Play Store listing' : 'App Store listing';
 
     try {
-      const { compareVersions } = require('./Registration');
+      const { compareVersions, fetchAndroidVersionLive } = require('./Registration');
       const before = this._store.version;
+      // Connecting and registering ask different questions, and they must not
+      // share an answer.
+      //
+      // Registration announces the build its token was computed from, which is
+      // the APK material and nothing else — see fetchWaVersion().
+      //
+      // Connecting announces the build the store is serving *now*, because a
+      // version the server no longer recognises is what a 405 is. The material
+      // is the wrong source for that: it ages the moment Play moves on, and a
+      // session pinned to it would keep announcing an older build forever
+      // without anything looking broken.
+      //
+      // fetchAndroidVersionLive asks Play's own API first and only falls back
+      // to the store page, which no longer carries a version worth reading.
       const live   = android
-        ? await fetchAndroidVersion(business)
+        ? await fetchAndroidVersionLive(business)
         : await fetchIosVersion(business);
       if (!live) return;
 

package/lib/Registration.js

@@ -553,6 +553,7 @@ const VERSION_CACHE_TTL_MS = 6 * 60 * 60 * 1000;
 
 const _cachedIosVersion     = {};
 const _cachedAndroidVersion = {};
+const _cachedPlayVersion    = {};
 
 function _cachedVersion(cache, key) {
   const entry = cache[key];
@@ -578,6 +579,84 @@ function _cacheVersion(cache, key, value) {
 function clearVersionCache() {
   for (const k of Object.keys(_cachedIosVersion))     delete _cachedIosVersion[k];
   for (const k of Object.keys(_cachedAndroidVersion)) delete _cachedAndroidVersion[k];
+  for (const k of Object.keys(_cachedPlayVersion))    delete _cachedPlayVersion[k];
+}
+
+// How long to let the Play lookup run before giving up on it. This is on the
+// connect path, so a slow answer has to become "no answer" rather than a
+// connection that hangs; the caller keeps whatever version it already had.
+const PLAY_VERSION_TIMEOUT_MS = 20000;
+
+/**
+ * The version Google Play is actually serving, read through Play's own API.
+ *
+ * This is the Android counterpart of the iTunes lookup, and the only Android
+ * source that can be trusted. The store *page* stopped carrying a version to
+ * scrape: fetchAndroidVersion() below now usually returns the pinned fallback,
+ * and when it does find a number on the page it can be the wrong one — a live
+ * run had it read 2.26.27.85 off a listing that was serving 2.26.31.77, which
+ * is older than the fallback it was supposed to improve on.
+ *
+ * Play's device-facing API answers with the real thing. It needs a Google
+ * account, which the Aurora dispenser hands out anonymously — a free
+ * third-party service that rate-limits, hence the six-hour memoisation shared
+ * with the other lookups and the timeout above. A failure here is not an
+ * error: the caller falls back to the scrape and then to the pinned version.
+ *
+ * @param {boolean} business  the w4b package rather than the consumer one
+ * @returns {Promise<string|null>} e.g. "2.26.31.77", or null if Play did not answer
+ */
+async function fetchPlayVersion(business) {
+  const key = business ? 'business' : 'personal';
+  const hit = _cachedVersion(_cachedPlayVersion, key);
+  if (hit) return hit;
+
+  const packageName = business ? WHATSAPP_BUSINESS_PACKAGE : WHATSAPP_PACKAGE;
+  const PlayStore   = require('./PlayStore');
+
+  const lookup = (async () => {
+    const auth    = await PlayStore.fetchAnonymousAuth();
+    const headers = PlayStore.buildFdfeHeaders(auth);
+    const info    = await PlayStore.fetchVersion(packageName, headers);
+    return info && info.versionName ? info.versionName : null;
+  })();
+
+  let timer;
+  const deadline = new Promise((resolve) => {
+    timer = setTimeout(() => resolve(null), PLAY_VERSION_TIMEOUT_MS);
+  });
+
+  let version = null;
+  try {
+    version = await Promise.race([lookup, deadline]);
+  } catch (err) {
+    _whaDbg('[DBG] PLAY_VERSION lookup failed: ' + (err && err.message));
+    version = null;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+  // The race leaves the lookup running when the deadline wins; it must not take
+  // the process down if it rejects after nobody is waiting on it any more.
+  lookup.catch(() => {});
+
+  if (!version) return null;
+  _whaDbg('[DBG] PLAY_VERSION ' + packageName + ' -> ' + version);
+  return _cacheVersion(_cachedPlayVersion, key, version);
+}
+
+/**
+ * The current Android version for a client that is connecting, best source
+ * first: Play's API, then the store page, then the pinned fallback.
+ *
+ * Registration does not come through here — it reads the version off the APK
+ * material it computed its token from, and the two must not be confused. See
+ * fetchWaVersion().
+ */
+async function fetchAndroidVersionLive(business) {
+  const fromPlay = await fetchPlayVersion(business);
+  if (fromPlay) return fromPlay;
+  _whaDbg('[DBG] PLAY_VERSION unavailable — falling back to the store page');
+  return fetchAndroidVersion(business);
 }
 
 async function fetchIosVersion(business) {
@@ -2098,7 +2177,7 @@ async function verifyCode(store, code, opts) {
   throw new Error(`Verification failed: ${reason || JSON.stringify(result)}`);
 }
 
-module.exports = { checkIfRegistered, checkNumberStatus, requestSmsCode, verifyCode, fetchIosVersion, fetchAndroidVersion, fetchWaVersion, currentVersionFor, refreshSessionVersion, clearVersionCache, tryLoadAndroidMaterial, compareVersions, parsePhone, getCountryMeta, assertRegistrationKeys, parseSocksProxy, socksProxyUrl };
+module.exports = { checkIfRegistered, checkNumberStatus, requestSmsCode, verifyCode, fetchIosVersion, fetchAndroidVersion, fetchPlayVersion, fetchAndroidVersionLive, fetchWaVersion, currentVersionFor, refreshSessionVersion, clearVersionCache, tryLoadAndroidMaterial, compareVersions, parsePhone, getCountryMeta, assertRegistrationKeys, parseSocksProxy, socksProxyUrl };
 
 // The HTTP reader, exposed for tests. Not part of the public API.
 module.exports._http = { readHttpResponse, parseHttpResponse, decodeChunkedBody };

package/lib/constants.js

@@ -48,7 +48,7 @@ const IOS_BUSINESS_STATIC_TOKEN = 'USUDuDYDeQhY4RF2fCSp5m3F6kJ1M2J8wS7bbNA2';
 // reason nothing in the error names. Keep them within a few releases of what
 // the stores are actually serving; the live lookup is what normally decides.
 const IOS_VERSION_FALLBACK     = '2.26.9.75';
-const ANDROID_VERSION_FALLBACK = '2.26.29.73';
+const ANDROID_VERSION_FALLBACK = '2.26.31.77';
 
 // Safari UA for the iTunes lookup only.
 const IOS_USER_AGENT = 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_4_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4.1 Mobile/15E148 Safari/604.1';

package/package.json

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