whalibmob 5.13.3 → 5.14.1

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)
@@ -165,7 +165,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 +200,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 +357,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
 ```
 
@@ -395,12 +395,16 @@ wa +919634847671>
 > [!TIP]
 > **The shell never exits on its own.** It stays open until you type `/quit` or press Ctrl+C. This is true for every command — registration, connection, sending messages — everything.
 
-Use a custom session directory with `--session`:
+Use a different authentication folder with `--session`:
 
 ```sh
 wa connect 919634847671 --session /data/my-sessions
 ```
 
+The CLI asks what to call it once, on a first run, and remembers the answer in
+`~/.whalibmob.json`. Each number gets its own folder inside — see
+[Saving & Restoring Sessions](#saving--restoring-sessions).
+
 > [!IMPORTANT]
 > **If this is refused with `405`, do not re-register the number.** The account
 > is fine; the server declined the version the connect announced. Check for a
@@ -1375,7 +1379,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
 ```
 
@@ -2414,19 +2418,110 @@ If `socks` is not installed, or a proxy is unreachable, you get a message saying
 
 ## Saving & Restoring Sessions
 
-Sessions are automatically persisted to disk as JSON files under the `sessionDir` you provide. The file is named `<phone>.json`. On the next `client.init()` call the session is restored and no re-registration is needed.
+Sessions are persisted to disk under the `sessionDir` you provide — the
+authentication folder. Pass any path you like; nothing is hardcoded.
 
 ```js
 const client = new WhalibmobClient({
-  sessionDir: path.join(process.env.HOME, '.waSession')
+  sessionDir: path.join(process.env.HOME, 'whalibmob_auth')
 })
 
 // no need to register again — just connect
 await client.init('919634847671')
 ```
 
+**Each number gets a folder of its own inside it**, holding every file that
+number owns:
+
+```
+whalibmob_auth/
+├── android-apk-material.json            ← shared by every Android registration
+├── android-apk-material-business.json
+├── 919634847671/
+│   ├── 919634847671.json                ← the store: keys, device, version
+│   ├── 919634847671.signal.json         ← Signal sessions
+│   ├── 919634847671.sk.json             ← sender keys
+│   ├── 919634847671.tctoken.json
+│   ├── 919634847671.device-cache.json
+│   ├── 919634847671.lid-mapping.json
+│   ├── 919634847671.lid-reverse-mapping.json
+│   ├── 919634847671.appState.json
+│   ├── 919634847671.appStateKeys.json
+│   ├── 919634847671.history.json
+│   └── 919634847671.messages.json
+└── 5568936182750/
+    └── …
+```
+
+A companion link for the same number lives beside it as `<phone>.web.json` and
+friends, in the same folder.
+
+One account is then one directory: copy it to move a number to another machine,
+delete it to be rid of one, archive it to keep it. Nothing has to be picked out
+of a pile by prefix.
+
 > [!NOTE]
-> Each phone number uses its own session file. The library handles Signal Protocol key persistence automatically.
+> **Sessions written by earlier versions keep working where they are.** The
+> layout is decided per number: a number whose files sit loose in the base
+> directory is left exactly as it is, and only new numbers get a folder. Nothing
+> is moved unless you ask — `wa migrate-sessions` does that, one number or all
+> of them, and re-running it is safe.
+
+### Where the folder comes from
+
+| order | source |
+|---|---|
+| 1 | `sessionDir` passed to `WhalibmobClient` (library), or `--session <dir>` (CLI) |
+| 2 | `WA_SESSION_DIR` in the environment |
+| 3 | the answer remembered in `~/.whalibmob.json`, which the CLI asks for once on a first run |
+| 4 | `~/.waSession` |
+
+The CLI asks only when none of the above has decided it and the default folder
+is empty, so an existing installation is never asked to rename anything, and a
+non-interactive run — a script, a cron — never blocks on the question.
+
+```
+  where should sessions be kept? each number gets its own folder inside.
+  a bare name goes under your home directory; enter for /home/you/.waSession
+  authentication folder:  whalibmob_auth
+  sessions will be kept in /home/you/whalibmob_auth
+```
+
+A bare name is created under your home directory; an absolute path or one
+starting with `~` is taken as given.
+
+### Working out the paths yourself
+
+`lib/SessionPaths` is the same resolver the library and the CLI use, so a
+caller that wants to read or move a session's files does not have to guess the
+layout:
+
+```js
+// exported from the package itself, or from lib/SessionPaths directly
+const {
+  defaultBaseDir, sessionDirFor, storeFileFor, webStoreFileFor,
+  listSessions, migrateSession, SessionPaths
+} = require('whalibmob')
+
+const { isLegacyLayout, SESSION_SUFFIXES } = SessionPaths
+
+const base = path.join(process.env.HOME, 'whalibmob_auth')
+
+sessionDirFor(base, '919634847671')                  // …/whalibmob_auth/919634847671
+sessionDirFor(base, '919634847671', { create: true }) // and makes it
+storeFileFor(base, '919634847671')                   // …/919634847671/919634847671.json
+webStoreFileFor(base, '919634847671')                // …/919634847671/919634847671.web.json
+
+listSessions(base)
+// [ { phone, dir, storeFile, webStoreFile, legacy, hasMobile, hasWeb }, … ]
+//   covers both layouts, so it is what to iterate over
+
+migrateSession(base, '919634847671')
+// { phone, from, to, moved: [...], skipped: [...] }   moves one number into its folder
+```
+
+`SESSION_SUFFIXES` is every per-number file the library writes — the list to
+copy or delete against if you are moving an account by hand.
 
 ## Signal Store Utilities
 
@@ -2665,11 +2760,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
@@ -4634,9 +4729,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/cli.js

@@ -60,6 +60,8 @@ const {
 } = require('./lib/Client');
 
 const { assertMeId, initAuthCreds } = require('./lib/auth-utils');
+const { defaultBaseDir, sessionDirFor, storeFileFor, webStoreFileFor,
+        listSessions, migrateSession, isLegacyLayout } = require('./lib/SessionPaths');
 
 // ─── Wire trace implementation ────────────────────────────────────────────────
 // Everything below is CLI-only instrumentation; the library is untouched.
@@ -389,8 +391,88 @@ function printParticipantResults(verb, results) {
 
 // ─── helpers ──────────────────────────────────────────────────────────────────
 
+// Where the authentication folder is remembered between runs, so the question
+// below is asked once rather than every time.
+function configPath() {
+  return path.join(os.homedir(), '.whalibmob.json');
+}
+
+function readConfig() {
+  try { return JSON.parse(fs.readFileSync(configPath(), 'utf8')) || {}; }
+  catch (_) { return {}; }
+}
+
+function writeConfig(patch) {
+  const merged = Object.assign(readConfig(), patch);
+  try { fs.writeFileSync(configPath(), JSON.stringify(merged, null, 2)); } catch (_) {}
+  return merged;
+}
+
 function defaultSessionDir() {
-  return path.join(os.homedir(), '.waSession');
+  return readConfig().sessionDir || defaultBaseDir();
+}
+
+// A folder name typed by a person, turned into somewhere to write.
+//
+//   ""  or blank      null, and the caller falls back to the default
+//   whalibmob_auth    under the home directory — what a bare name means
+//   ~/anything        under the home directory
+//   /data/sessions    taken as given
+//   project/auth      relative to where the command is being run, as a shell
+//                     would read it
+//
+// Returning null rather than a path for a blank answer keeps the "just press
+// enter" case in one place: the caller owns what the default is.
+function resolveAuthFolder(name) {
+  const raw = String(name || '').trim();
+  if (!raw) return null;
+  if (raw.startsWith('~')) return path.join(os.homedir(), raw.slice(1).replace(/^[\/\\]/, ''));
+  if (path.isAbsolute(raw)) return raw;
+  if (/[\/\\]/.test(raw)) return path.resolve(raw);
+  return path.join(os.homedir(), raw);
+}
+
+// Ask what to call the authentication folder, once, and remember the answer.
+//
+// Skipped entirely when --session or WA_SESSION_DIR already say where it is,
+// when a previous run answered, when the default folder already holds sessions
+// (an existing installation is not asked to rename anything), and when stdin is
+// not a terminal, so scripts and cron never block on it.
+function askSessionDir(cmd, explicit) {
+  const OFFLINE = ['version', '--version', '-v', 'help', '--help', '-h'];
+  if (explicit) return Promise.resolve(explicit);
+  if (cmd && OFFLINE.includes(cmd)) return Promise.resolve(defaultSessionDir());
+  if (process.env.WA_SESSION_DIR) return Promise.resolve(process.env.WA_SESSION_DIR);
+
+  const remembered = readConfig().sessionDir;
+  if (remembered) return Promise.resolve(remembered);
+
+  const fallback = defaultBaseDir();
+  // An installation that already has sessions keeps them where they are.
+  if (listSessions(fallback).length) return Promise.resolve(fallback);
+  if (!process.stdin.isTTY) return Promise.resolve(fallback);
+
+  return new Promise(resolve => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    out('');
+    out('  where should sessions be kept? each number gets its own folder inside.');
+    out('  a bare name goes under your home directory; enter for ' + fallback);
+    rl.question('  authentication folder:  ', (answer) => {
+      rl.close();
+      const dir = resolveAuthFolder(answer) || fallback;
+      try {
+        fs.mkdirSync(dir, { recursive: true });
+        writeConfig({ sessionDir: dir });
+        out('  sessions will be kept in ' + dir);
+        out('');
+      } catch (e) {
+        warn('could not create ' + dir + ' (' + e.message + ') — using ' + fallback);
+        resolve(fallback);
+        return;
+      }
+      resolve(dir);
+    });
+  });
 }
 
 function normalizePhone(s) {
@@ -817,11 +899,11 @@ function openShell(prompt) {
 // already on disk that one wins, and a non-interactive stdin never blocks on a
 // question nobody is there to answer.
 function hasMobileSession(phone) {
-  return fs.existsSync(path.join(_sessDir, phone + '.json'));
+  return fs.existsSync(storeFileFor(_sessDir, phone));
 }
 
 function hasWebSession(phone) {
-  const f = path.join(_sessDir, phone + '.web.json');
+  const f = webStoreFileFor(_sessDir, phone);
   if (!fs.existsSync(f)) return false;
   try {
     const j = JSON.parse(fs.readFileSync(f, 'utf8'));
@@ -2076,8 +2158,8 @@ async function handleLine(line) {
             fail('email method requires an address — usage: /reg code <phone> email <address>');
             break;
           }
-          if (!fs.existsSync(_sessDir)) fs.mkdirSync(_sessDir, { recursive: true });
-          const sessFile = path.join(_sessDir, `${ph}.json`);
+          sessionDirFor(_sessDir, ph, { create: true });
+          const sessFile = storeFileFor(_sessDir, ph);
           let store = loadStore(sessFile);
           if (!store) {
             store = initAuthCreds(ph);
@@ -2108,19 +2190,19 @@ async function handleLine(line) {
           const ph   = normalizePhone(p[2]);
           const code = p[3];
           if (!ph || !code) { fail('usage: /reg confirm <phone> <code>'); break; }
-          const file  = path.join(_sessDir, `${ph}.json`);
+          const file  = storeFileFor(_sessDir, ph);
           const store = loadStore(file) || initAuthCreds(ph);
           out('verifying...');
           const r = await verifyCode(store, code, Object.assign(registrationPrompts(), { onProgress: out }));
           if (r && (r.status === 'ok' || r.status === 'sent' || r.status === 'verified')) {
-            if (!fs.existsSync(_sessDir)) fs.mkdirSync(_sessDir, { recursive: true });
+            sessionDirFor(_sessDir, ph, { create: true });
             const finalStore = r.store || store;
             finalStore.registered  = true;
             finalStore.codePending = false;
             // Save under the number WhatsApp filed the account as, not the one
             // that was typed — they differ often enough to matter.
             const savedPhone = String(finalStore.phoneNumber || ph);
-            const savedFile  = path.join(_sessDir, `${savedPhone}.json`);
+            const savedFile  = storeFileFor(_sessDir, savedPhone);
             saveStore(finalStore, savedFile);
             if (r.canonicalPhoneNumber) {
               out('note: WhatsApp knows this account as +' + r.canonicalPhoneNumber +
@@ -2359,10 +2441,11 @@ usage:
   wa apk-material <base.apk> [split.apk ...]  read the Android token material
   wa apk-material --download                  fetch that APK from Google Play
   wa refresh-version <phone>                  update the version a session announces
+  wa migrate-sessions [phone]                 move old flat sessions into folders
   wa version
 
 options:
-  --session <dir>   session directory  (default: ~/.waSession)
+  --session <dir>   authentication folder (default: remembered, else ~/.waSession)
   --out <file>      where apk-material writes  (default: <session dir>/android-apk-material.json)
   --sms             connect by registering this number over SMS
   --pair            connect by linking to an existing account (8-digit code)
@@ -2399,7 +2482,7 @@ function askDebugMode(cmd) {
   // trace to show, and stopping a maintenance command to ask is what makes
   // `wa apk-material --download && wa refresh-version --all` prompt twice.
   const OFFLINE = ['version', '--version', '-v', 'help', '--help', '-h',
-                   'apk-material', 'refresh-version'];
+                   'apk-material', 'refresh-version', 'migrate-sessions'];
   if (cmd && OFFLINE.includes(cmd)) return Promise.resolve();
   if (!process.stdin.isTTY) return Promise.resolve();
 
@@ -2425,7 +2508,7 @@ function askDonation(cmd) {
   // trace to show, and stopping a maintenance command to ask is what makes
   // `wa apk-material --download && wa refresh-version --all` prompt twice.
   const OFFLINE = ['version', '--version', '-v', 'help', '--help', '-h',
-                   'apk-material', 'refresh-version'];
+                   'apk-material', 'refresh-version', 'migrate-sessions'];
   if (cmd && OFFLINE.includes(cmd)) return Promise.resolve();
   if (!process.stdin.isTTY) return Promise.resolve();
   if (process.env.WA_NO_DONATE === '1') return Promise.resolve();
@@ -2455,11 +2538,14 @@ function askDonation(cmd) {
 async function main() {
   const { cmd, sub, flags, pos } = parseArgs(process.argv);
 
+  // The authentication folder first: it decides where everything this run
+  // touches lives, and asking it after the other two made the answer to the
+  // first question land in the wrong prompt.
+  _sessDir = await askSessionDir(cmd, flags.session);
+
   await askDebugMode(cmd);
   await askDonation(cmd);
 
-  _sessDir = flags.session || defaultSessionDir();
-
   // `--business` is the flag form of WA_BUSINESS, mapped onto the environment
   // before anything reads a device profile. The device config is env-driven, so
   // this is the whole of it: the profile, the token material, the version
@@ -2483,6 +2569,42 @@ async function main() {
     return;
   }
 
+  // Move sessions out of the old flat layout into a folder each.
+  //
+  // Nothing forces this: a number whose files sit loose in the base directory
+  // keeps working exactly where it is. This is for anyone who wants the tidier
+  // shape for what they already have.
+  if (cmd === 'migrate-sessions') {
+    const one = normalizePhone(sub || '');
+    const all = listSessions(_sessDir);
+    const legacy = all.filter(x => x.legacy && (!one || x.phone === one));
+
+    if (!legacy.length) {
+      out(one
+        ? 'nothing to move for +' + one + ' — it is already in a folder of its own'
+        : 'nothing to move — every session in ' + _sessDir + ' already has its own folder');
+      return;
+    }
+
+    out('moving ' + legacy.length + ' session(s) into folders under ' + _sessDir);
+    out('');
+    let files = 0, skipped = 0;
+    for (const entry of legacy) {
+      try {
+        const r = migrateSession(_sessDir, entry.phone);
+        files   += r.moved.length;
+        skipped += r.skipped.length;
+        out('  +' + entry.phone.padEnd(18) + r.moved.length + ' file(s)' +
+            (r.skipped.length ? '   ' + r.skipped.length + ' left (already there)' : ''));
+      } catch (e) {
+        fail('+' + entry.phone + ': ' + e.message);
+      }
+    }
+    out('');
+    out('  ' + files + ' file(s) moved' + (skipped ? ', ' + skipped + ' skipped' : ''));
+    return;
+  }
+
   // Bring a session's stored version up to date.
   //
   // A session announces the version it registered with, forever — nothing else
@@ -2502,13 +2624,13 @@ async function main() {
     let files;
     if (flags.all) {
       try {
-        files = fs.readdirSync(_sessDir)
-          .filter(f => /^\d+\.json$/.test(f))
-          .map(f => path.join(_sessDir, f));
+        files = listSessions(_sessDir)
+          .filter(x => x.hasMobile)
+          .map(x => x.storeFile);
       } catch (_) { files = []; }
       if (!files.length) { fail('no sessions in ' + _sessDir); process.exit(1); }
     } else {
-      files = [path.join(_sessDir, one + '.json')];
+      files = [storeFileFor(_sessDir, one)];
     }
 
     if (process.env.WA_VERSION) {

package/index.js

@@ -3,6 +3,7 @@
 const { WhalibmobClient, checkNumberStatus, fetchIosVersion, fetchWaVersion, assertRegistrationKeys } = require('./lib/Client');
 const { getDeviceConfig } = require('./lib/DeviceConfig');
 const { fetchAndroidVersion, currentVersionFor, refreshSessionVersion } = require('./lib/Registration');
+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');
@@ -69,6 +70,15 @@ module.exports = {
   // session that registered long enough ago to have gone stale.
   currentVersionFor,
   refreshSessionVersion,
+  // Where a session's files live: one folder per number inside the
+  // authentication folder. The same resolver the CLI uses.
+  SessionPaths,
+  defaultBaseDir:  SessionPaths.defaultBaseDir,
+  sessionDirFor:   SessionPaths.sessionDirFor,
+  storeFileFor:    SessionPaths.storeFileFor,
+  webStoreFileFor: SessionPaths.webStoreFileFor,
+  listSessions:    SessionPaths.listSessions,
+  migrateSession:  SessionPaths.migrateSession,
   // Device config — reads WA_OS / WA_DEVICE / WA_DEVICE_* from process.env
   getDeviceConfig,
   // Store helpers

package/lib/Client.js

@@ -9,6 +9,8 @@ const crypto        = require('crypto');
 const { NoiseSocket }     = require('./noise');
 const { MessageSender, generateMessageId, makeJid, buildOrGetAdvIdentity } = require('./messages/MessageSender');
 const { checkIfRegistered, checkNumberStatus, requestSmsCode, verifyCode, assertRegistrationKeys, fetchIosVersion, fetchWaVersion } = require('./Registration');
+const { defaultBaseDir, sessionDirFor, isLegacyLayout,
+        SESSION_SUFFIXES } = require('./SessionPaths');
 const { getDeviceConfig } = require('./DeviceConfig');
 const { prepareProfilePicture, probeImageSize, canDecodeImage } = require('./MediaThumbnail');
 const { createNewStore, saveStore, loadStore, toSixParts, fromSixParts } = require('./Store');
@@ -320,7 +322,13 @@ class WhalibmobClient extends EventEmitter {
     this._sender        = null;
     this._signal        = null;
     this._devMgr        = null;
-    this._sessionDir    = opts.sessionDir || process.env.HOME + '/.waSession';
+    // The authentication folder the caller chose. `_sessionDir` below is the
+    // directory this one number's files live in, which is a directory inside
+    // it — see SessionPaths. Both are kept: the base is what listing and
+    // renaming work against, the per-number one is what every file path is
+    // built from.
+    this._baseDir       = opts.sessionDir || defaultBaseDir();
+    this._sessionDir    = this._baseDir;
     // 'mobile' — registered over SMS as the account's primary device (default,
     // and what every existing caller gets). 'web' — linked to an existing
     // account as a companion, via pairing code.
@@ -410,6 +418,8 @@ class WhalibmobClient extends EventEmitter {
     // entry points reset it — the reconnect loop must not clear its own guard.
     this._fatal = false;
 
+    this._sessionDir = sessionDirFor(this._baseDir, phoneNumber);
+
     const sessionFile = path.join(this._sessionDir, `${phoneNumber}.json`);
     this._store = loadStore(sessionFile);
     if (!this._store) {
@@ -588,6 +598,7 @@ class WhalibmobClient extends EventEmitter {
     const { createNewWebStore, loadWebStore, saveWebStore, webSessionPath } =
       require('./WebStore');
 
+    this._sessionDir = sessionDirFor(this._baseDir, phoneNumber, { create: true });
     this._webSessionFile = webSessionPath(this._sessionDir, phoneNumber);
     this._store = loadWebStore(this._webSessionFile) || createNewWebStore(phoneNumber);
 
@@ -1095,14 +1106,24 @@ class WhalibmobClient extends EventEmitter {
     if (wasConnected) this.disconnect();
 
     // Every per-session file shares the phone number as its stem.
-    const SUFFIXES = ['.json', '.signal.json', '.sk.json', '.tctoken.json',
-                      '.device-cache.json', '.lid-mapping.json',
-                      '.lid-reverse-mapping.json', '.history.json', '.messages.json',
-                      '.appState.json', '.appStateKeys.json'];
+    // Both layouts: the files are renamed where they sit, and when they sit in
+    // a directory named after the old number that directory is renamed too —
+    // otherwise +<canonical> would live in a folder called +<current> and the
+    // next lookup would not find it.
+    const fromDir = this._sessionDir;
+    const toDir   = isLegacyLayout(this._baseDir, current)
+      ? this._baseDir
+      : path.join(this._baseDir, canonical);
+
+    if (toDir !== fromDir && fs.existsSync(toDir)) {
+      throw new Error('Cannot rename session: ' + toDir +
+        ' already exists. Move it aside first.');
+    }
+
     const moved = [];
-    for (const suffix of SUFFIXES) {
-      const from = path.join(this._sessionDir, current + suffix);
-      const to   = path.join(this._sessionDir, canonical + suffix);
+    for (const suffix of SESSION_SUFFIXES) {
+      const from = path.join(fromDir, current + suffix);
+      const to   = path.join(fromDir, canonical + suffix);
       if (!fs.existsSync(from)) continue;
       if (fs.existsSync(to)) {
         throw new Error('Cannot rename session: ' + canonical + suffix +
@@ -1113,6 +1134,11 @@ class WhalibmobClient extends EventEmitter {
     }
     if (!moved.length) throw new Error('No session files found for ' + current);
 
+    if (toDir !== fromDir) {
+      fs.renameSync(fromDir, toDir);
+      this._sessionDir = toDir;
+    }
+
     // The number is inside the store as well as in the filename.
     const sessionFile = path.join(this._sessionDir, canonical + '.json');
     const store = loadStore(sessionFile);
@@ -2406,23 +2432,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.

package/lib/Registration.js

@@ -959,6 +959,37 @@ function getAccessSessionId(store) {
 // Cobalt's "000" placeholder), and advertising_id / backup_token come from the
 // store.
 
+// How long the server said to wait, in seconds, or null when it did not say.
+//
+// The wait comes back in a field named after the delivery method, and there are
+// seven of them. Reading only `sms_wait` meant a rate-limited voice or wa_old
+// request reported no wait at all — which is the one number that matters in a
+// `too_recent`, because without it the only advice left is "wait a few minutes"
+// and people re-run the command instead, spending attempts and extending the
+// very cooldown they are trying to get out of.
+//
+// The method's own field wins; the longest of the others is the fallback, since
+// the server sometimes answers about a method other than the one asked for.
+const WAIT_FIELDS = ['sms_wait', 'voice_wait', 'wa_old_wait', 'flash_wait',
+                     'email_otp_wait', 'send_sms_wait', 'silent_auth_wait'];
+
+function waitHint(response, method) {
+  if (!response) return null;
+
+  const preferred = Number(response[method + '_wait']);
+  if (preferred > 0) return preferred;
+
+  let max = null;
+  for (const key of WAIT_FIELDS) {
+    const v = Number(response[key]);
+    if (v > 0 && (max === null || v > max)) max = v;
+  }
+  if (max !== null) return max;
+
+  const retry = Number(response.retry_after);
+  return retry > 0 ? retry : null;
+}
+
 function buildClientMetrics(attempt) {
   const json = '{"attempts":' + (attempt || 1)
     + ',"app_campaign_download_source":"google-play|unknown"'
@@ -1619,27 +1650,19 @@ async function requestSmsCode(store, method, opts) {
   store.version = waVersion;
   store.device  = _device;
 
-  // Email method: request code via email instead of SMS/voice.
-  // Sends method=email + email=<address> in the /code request.
-  // No auto-fallback for email — it either works or fails.
-  if (method === 'email') {
-    const emailAddr = opts.email || '';
-    if (!emailAddr) throw new Error('requestSmsCode: email method requires opts.email address');
-    const { cc: _regCc } = parsePhone(store.phoneNumber);
-    const _regMeta       = getCountryMeta(_regCc);
-    const extra = [
-      ...getRequestVerificationCodeParameters(store, 'email', _regMeta, _device, 1),
-      'email', emailAddr
-    ];
-    const result = await sendRequest('/code', store, waVersion, true, extra);
-    const status = result.status;
-    if (status === 'ok' || status === 'sent') return result;
-    const reason = result.reason || status || '';
-    throw new Error(`Registration email error: ${reason} — raw: ${JSON.stringify(result)}`);
+  // The email OTP carries the address alongside the usual parameters. It goes
+  // through the same request path as every other method rather than around it:
+  // it used to have its own branch, which meant a rate-limited email request
+  // reported no wait, a block screen was reported as a raw reason, and none of
+  // the funnel events the other methods emit were sent.
+  const emailAddr = method === 'email' ? (opts.email || '') : '';
+  if (method === 'email' && !emailAddr) {
+    throw new Error('requestSmsCode: email method requires opts.email address');
   }
 
   // Auto-fallback: if the primary method gets no_routes, try the alternate once.
-  // sms → wa_old, wa_old → sms, voice → sms
+  // sms → wa_old, wa_old → sms, voice → sms. Never for email: falling back
+  // would send an SMS to somebody who asked for an email.
   const fallbackMethod = method === 'wa_old' ? 'sms' : (method === 'sms' ? 'wa_old' : 'sms');
   let autoFallbackDone = false;
 
@@ -1661,6 +1684,7 @@ async function requestSmsCode(store, method, opts) {
     while (true) {
       // Rebuilt per attempt so client_metrics carries the current attempt count.
       const extra = getRequestVerificationCodeParameters(store, m, _regMeta, _device, attemptNum);
+      if (m === 'email') extra.push('email', emailAddr);
 
       // The screen a later event belongs to is named after the method asked
       // for here, so record it before the request rather than after.
@@ -1681,7 +1705,7 @@ async function requestSmsCode(store, method, opts) {
       // isTooRecent() — throw immediately, no point retrying
       if (/too_recent|too_many|too_many_guesses|too_many_all_methods/i.test(reason) ||
           /too_recent|too_many|too_many_guesses|too_many_all_methods/i.test(status)) {
-        const waitSec = result.sms_wait || result.retry_after || null;
+        const waitSec = waitHint(result, m);
         const waitMsg = waitSec ? ` (wait ${Math.ceil(waitSec / 60)} min, ${waitSec}s)` : '';
         throw new Error(`code already sent recently — check your phone or wait a few minutes (${reason})${waitMsg}`);
       }
@@ -1712,19 +1736,32 @@ async function requestSmsCode(store, method, opts) {
   let result = await _tryMethod(method);
 
   // Auto-fallback on no_routes
-  if (result && result._noRoutes && !autoFallbackDone) {
+  if (result && result._noRoutes && !autoFallbackDone && method !== 'email') {
     autoFallbackDone = true;
     process.stderr.write(`[REG] ${method} returned no_routes — auto-trying ${fallbackMethod}\n`);
     result = await _tryMethod(fallbackMethod);
   }
 
-  // Final no_routes — give up with useful message
+  // Final no_routes — give up, and say what actually changes the answer.
+  //
+  // no_routes is the server declining to deliver, and what it weighs is the
+  // requester: the reputation of the IP, the history the number carries, and
+  // whether the platform has a route for it. None of that is in the client, so
+  // the advice has to point outside it. The old text suggested a VoIP number,
+  // which is backwards — virtual numbers are among the most refused.
   if (result && result._noRoutes) {
-    const tried = autoFallbackDone ? `${method} and ${fallbackMethod}` : method;
+    const tried = autoFallbackDone ? `${method}, then ${fallbackMethod}` : method;
     throw new Error(
-      `Registration blocked (no_routes) for both methods (${tried}).\n` +
-      `  • If the number IS on WhatsApp → re-install the app or wait 24h\n` +
-      `  • If the number is NEW → try a different carrier or use a VoIP number`
+      `Registration blocked (no_routes) — WhatsApp has no route to deliver the ` +
+      `code (tried: ${tried}).\n` +
+      `  • Most often the IP: datacenter, VPS and VPN addresses are refused. ` +
+      `Use a residential connection, or SOCKS_PROXY=socks5://…\n` +
+      `  • Try another method: --method voice\n` +
+      `  • Try the other platform: WA_OS=ios (routes differ per platform)\n` +
+      `  • wa_old only works if the number is already active on WhatsApp\n` +
+      `  • Real SIM numbers fare better than virtual or VoIP ones\n` +
+      `  • Leave the number alone for 24h rather than retrying — every attempt ` +
+      `counts against it`
     );
   }
 
@@ -1836,5 +1873,5 @@ module.exports._token = { computeToken, androidMaterialPath, registrationHeaders
 // Challenge / two-factor internals, exposed for tests. Not part of the public API.
 module.exports._verify = {
   hasChallenge, is2FARequired, decodeOrNull, isSuccessful,
-  normalizeCodeResult, currentVerifyScreen, adoptCanonicalNumber, funnelEnabled
+  normalizeCodeResult, currentVerifyScreen, adoptCanonicalNumber, funnelEnabled, waitHint
 };

package/lib/SessionPaths.js

@@ -0,0 +1,218 @@
+'use strict';
+
+// Where a session's files live.
+//
+// Everything a number owns — the store, the Signal sessions, the sender keys,
+// the app state, the device cache, the LID maps, the history — used to sit
+// side by side in one directory, named after the number:
+//
+//   ~/.waSession/40756469325.json
+//   ~/.waSession/40756469325.signal.json
+//   ~/.waSession/40756469325.sk.json
+//   ...  × 11 files × every number
+//
+// Fifty numbers made that five hundred files in one place, with no way to move,
+// back up or delete one account without picking its files out of the pile by
+// prefix. A number now gets a directory of its own:
+//
+//   <base>/40756469325/40756469325.json
+//   <base>/40756469325/40756469325.signal.json
+//   ...
+//
+// The file names inside are unchanged, so every path built as
+// `join(sessionDir, phone + suffix)` keeps working — what changes is which
+// directory `sessionDir` points at. Callers ask sessionDirFor() for it.
+//
+// A directory laid out the old way keeps working exactly as it was. The layout
+// is decided per number, by looking for the file that must exist either way, so
+// an existing installation is never asked to move anything and a number that
+// has been moved is picked up on its own.
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+// The file every session has, in either layout, and the one whose presence
+// decides which layout a number is on.
+const STORE_SUFFIX     = '.json';
+const WEB_STORE_SUFFIX = '.web.json';
+
+// Every per-number file whalibmob writes. Kept here so that moving a session
+// moves all of it — a list that goes out of date silently leaves a number's
+// Signal sessions behind and looks like a working move until the first message
+// fails to decrypt.
+const SESSION_SUFFIXES = [
+  '.json',
+  '.signal.json',
+  '.sk.json',
+  '.tctoken.json',
+  '.device-cache.json',
+  '.lid-mapping.json',
+  '.lid-reverse-mapping.json',
+  '.history.json',
+  '.messages.json',
+  '.appState.json',
+  '.appStateKeys.json',
+  // The companion (pairing-code) half of the same number.
+  '.web.json',
+  '.web.signal.json',
+  '.web.sk.json',
+  '.web.tctoken.json',
+  '.web.device-cache.json',
+  '.web.lid-mapping.json',
+  '.web.lid-reverse-mapping.json',
+  '.web.history.json',
+  '.web.messages.json',
+  '.web.appState.json',
+  '.web.appStateKeys.json'
+];
+
+// Files that belong to the installation rather than to any number, and stay at
+// the top of the base directory.
+const SHARED_FILES = [
+  'android-apk-material.json',
+  'android-apk-material-business.json'
+];
+
+function defaultBaseDir() {
+  return process.env.WA_SESSION_DIR || path.join(os.homedir(), '.waSession');
+}
+
+function _isDir(p) {
+  try { return fs.statSync(p).isDirectory(); } catch (_) { return false; }
+}
+
+function _exists(p) {
+  try { fs.accessSync(p); return true; } catch (_) { return false; }
+}
+
+/**
+ * Whether this number's files sit loose in the base directory rather than in
+ * one of its own.
+ *
+ * Only true for a number that is already there in the old shape: a number with
+ * no files at all is not legacy, it is new, and new numbers get a directory.
+ */
+function isLegacyLayout(baseDir, phone) {
+  phone = String(phone).replace(/\D/g, '');
+  if (_exists(path.join(baseDir, phone, phone + STORE_SUFFIX)) ||
+      _exists(path.join(baseDir, phone, phone + WEB_STORE_SUFFIX))) {
+    return false;
+  }
+  return _exists(path.join(baseDir, phone + STORE_SUFFIX)) ||
+         _exists(path.join(baseDir, phone + WEB_STORE_SUFFIX));
+}
+
+/**
+ * The directory a number's files belong in.
+ *
+ * @param {string} baseDir  the authentication folder
+ * @param {string} phone    digits
+ * @param {object} [opts]   { create } to make the directory if it is missing
+ */
+function sessionDirFor(baseDir, phone, opts) {
+  phone = String(phone).replace(/\D/g, '');
+  if (isLegacyLayout(baseDir, phone)) return baseDir;
+
+  const dir = path.join(baseDir, phone);
+  if (opts && opts.create) fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/** The store file for a number, wherever it lives. */
+function storeFileFor(baseDir, phone) {
+  phone = String(phone).replace(/\D/g, '');
+  return path.join(sessionDirFor(baseDir, phone), phone + STORE_SUFFIX);
+}
+
+/** The companion store file for a number, wherever it lives. */
+function webStoreFileFor(baseDir, phone) {
+  phone = String(phone).replace(/\D/g, '');
+  return path.join(sessionDirFor(baseDir, phone), phone + WEB_STORE_SUFFIX);
+}
+
+/**
+ * Every number the base directory holds, in either layout.
+ *
+ * @returns {Array<{phone, dir, storeFile, webStoreFile, legacy, hasMobile, hasWeb}>}
+ */
+function listSessions(baseDir) {
+  let entries;
+  try { entries = fs.readdirSync(baseDir); } catch (_) { return []; }
+
+  const found = new Map();
+
+  const note = (phone, dir, legacy) => {
+    if (!found.has(phone)) {
+      found.set(phone, {
+        phone,
+        dir,
+        storeFile:    path.join(dir, phone + STORE_SUFFIX),
+        webStoreFile: path.join(dir, phone + WEB_STORE_SUFFIX),
+        legacy,
+        hasMobile: _exists(path.join(dir, phone + STORE_SUFFIX)),
+        hasWeb:    _exists(path.join(dir, phone + WEB_STORE_SUFFIX))
+      });
+    }
+  };
+
+  // A directory named after a number, holding that number's store.
+  for (const entry of entries) {
+    if (!/^\d+$/.test(entry)) continue;
+    const dir = path.join(baseDir, entry);
+    if (!_isDir(dir)) continue;
+    if (_exists(path.join(dir, entry + STORE_SUFFIX)) ||
+        _exists(path.join(dir, entry + WEB_STORE_SUFFIX))) {
+      note(entry, dir, false);
+    }
+  }
+
+  // Loose files from the old layout, for numbers not already found above.
+  for (const entry of entries) {
+    const m = /^(\d+)(\.web)?\.json$/.exec(entry);
+    if (!m) continue;
+    note(m[1], baseDir, true);
+  }
+
+  return [...found.values()].sort((a, b) => a.phone.localeCompare(b.phone));
+}
+
+/**
+ * Move a number out of the old flat layout into a directory of its own.
+ *
+ * Every file listed in SESSION_SUFFIXES that exists is moved; anything already
+ * present at the destination is left alone and reported rather than
+ * overwritten, so a half-finished move can be run again safely.
+ *
+ * @returns {{phone, from, to, moved: string[], skipped: string[]}}
+ */
+function migrateSession(baseDir, phone) {
+  phone = String(phone).replace(/\D/g, '');
+  const to = path.join(baseDir, phone);
+
+  const moved = [], skipped = [];
+  fs.mkdirSync(to, { recursive: true });
+
+  for (const suffix of SESSION_SUFFIXES) {
+    const from = path.join(baseDir, phone + suffix);
+    if (!_exists(from)) continue;
+    const dest = path.join(to, phone + suffix);
+    if (_exists(dest)) { skipped.push(phone + suffix); continue; }
+    fs.renameSync(from, dest);
+    moved.push(phone + suffix);
+  }
+
+  return { phone, from: baseDir, to, moved, skipped };
+}
+
+module.exports = {
+  defaultBaseDir,
+  isLegacyLayout,
+  sessionDirFor,
+  storeFileFor,
+  webStoreFileFor,
+  listSessions,
+  migrateSession,
+  SESSION_SUFFIXES,
+  SHARED_FILES
+};

package/package.json

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