whalibmob 5.14.5 → 5.14.6

package/README.md

@@ -294,6 +294,20 @@ wa registration --request-code 919634847671 --method voice
 wa registration --request-code 919634847671 --method wa_old
 ```
 
+**Set the account's display name while registering** with `--name`. This is the
+name people who have *not* saved your number see next to it — in group
+participant lists, in notifications, and beside your messages. Quote it if it
+contains spaces:
+
+```sh
+wa registration --request-code 919634847671 --name "Ricardo Trade"
+```
+
+The name is stored with the session and announced on every connection from then
+on. Registration itself carries no name — the server learns it when the session
+connects — so a number registered without `--name` has none until one is set.
+It can be given at either registration step, and changed later with `/name`.
+
 **Registering as Android** is the same command with the platform named. Nothing
 else to prepare — see [what it does behind that one command](#registering-as-android).
 
@@ -1378,6 +1392,10 @@ wa> /reg code 919634847671
 wa> /reg code 919634847671 voice
 wa> /reg code 919634847671 wa_old
 
+# register with a display name — what people who have not saved
+# your number see. Quote it if it has spaces.
+wa> /reg code 919634847671 --name "Ricardo Trade"
+
 # confirm the code received
 wa> /reg confirm 919634847671 123456
 registered  session saved to /home/user/.waSession/919634847671/919634847671.json
@@ -1542,8 +1560,8 @@ wa> /quit
 | `/biz <phone\|jid>` | Query business profile of a WhatsApp Business account |
 | **Registration** | |
 | `/reg check <phone>` | Check if number has WhatsApp |
-| `/reg code <phone> [method]` | Request verification code |
-| `/reg confirm <phone> <code>` | Complete registration |
+| `/reg code <phone> [method] [--name "Name"]` | Request verification code, optionally naming the account |
+| `/reg confirm <phone> <code> [--name "Name"]` | Complete registration |
 | **Connection** | |
 | `/connect <phone> [sms\|pair]` | Connect to WhatsApp — asks which method when unset |
 | `/pair <phone> [code]` | Link to an existing account by 8-digit pairing code |
@@ -1578,12 +1596,27 @@ const sessFile = path.join(sessDir, phone + '.json')
 
 fs.mkdirSync(sessDir, { recursive: true })
 
-const store = createNewStore(phone)
+// `name` is the display name the account registers with — what people who have
+// not saved the number see. Omit it and the account has no name until one is
+// set later with client.changeName().
+const store = createNewStore(phone, { name: 'Ricardo Trade' })
 saveStore(store, sessFile)
 
 await requestSmsCode(store, 'sms')   // 'sms' | 'voice' | 'wa_old'
 ```
 
+The name is written to the session, not sent to the registration endpoint — the
+server learns it from the first connection, and from every one after. It can
+also be passed as an option at either step, which is the way to name a session
+that already exists:
+
+```js
+await requestSmsCode(store, 'sms', { name: 'Ricardo Trade' })
+await verifyCode(store, '123456',  { name: 'Ricardo Trade' })
+```
+
+Names are trimmed, collapsed to single spaces and capped at 25 characters.
+
 **Step 2 — verify the code**
 
 ```js

package/cli.js

@@ -1152,6 +1152,17 @@ function requireConn() {
 
 // ─── tokenizer ────────────────────────────────────────────────────────────────
 
+// Pull `--flag value` out of a token list, in place, and hand back the value.
+// Removing it keeps every positional argument at the index the usage line
+// promises, whichever end of the command the flag was typed at.
+function takeFlag(toks, flag) {
+  const i = toks.indexOf(flag);
+  if (i === -1) return null;
+  const value = (i + 1 < toks.length && !toks[i + 1].startsWith('--')) ? toks[i + 1] : null;
+  toks.splice(i, value === null ? 1 : 2);
+  return value;
+}
+
 function tokens(line) {
   const s = String(line || '');
   const t = []; let b = '';
@@ -2167,6 +2178,10 @@ async function handleLine(line) {
       // ── registration ───────────────────────────────────────────────────────
 
       case '/reg': {
+        // --name is pulled out before anything reads a position, so the phone
+        // and the code stay where the usage lines say they are no matter where
+        // the flag was typed. A name with spaces needs quoting: --name "A B".
+        const regName = takeFlag(p, '--name');
         const sub = p[1] && p[1].toLowerCase();
 
         if (sub === 'check') {
@@ -2182,7 +2197,12 @@ async function handleLine(line) {
           const method = (p[3] || 'sms').toLowerCase();
           // email method: /reg code <phone> email <address>
           const emailAddr = method === 'email' ? (p[4] || '') : '';
-          if (!ph) { fail('usage: /reg code <phone> [sms|voice|wa_old|email <address>]'); break; }
+          if (!ph) {
+            fail('usage: /reg code <phone> [sms|voice|wa_old|email <address>] [--name "Your Name"]');
+            out('  --name sets the display name the account registers with — what people');
+            out('  who have not saved your number see. It can be changed later with /name.');
+            break;
+          }
           if (method === 'email' && !emailAddr) {
             fail('email method requires an address — usage: /reg code <phone> email <address>');
             break;
@@ -2191,7 +2211,7 @@ async function handleLine(line) {
           const sessFile = storeFileFor(_sessDir, ph);
           let store = loadStore(sessFile);
           if (!store) {
-            store = initAuthCreds(ph);
+            store = initAuthCreds(ph, { name: regName });
             saveStore(store, sessFile);
           } else if (!store.codePending && !store.registered) {
             // Only check /exist when keys were never used to request a code.
@@ -2200,14 +2220,16 @@ async function handleLine(line) {
             const fresh = await assertRegistrationKeys(store, waVersion);
             if (!fresh) {
               out('  device keys already registered — generating new keys...');
-              store = initAuthCreds(ph);
+              store = initAuthCreds(ph, { name: regName });
               saveStore(store, sessFile);
               out('  new keys saved — proceed with code below');
             }
           }
           const methodLabel = method === 'email' ? ('email → ' + emailAddr) : method;
           out('requesting ' + methodLabel + ' code for +' + ph + '...');
-          const codeOpts = Object.assign(method === 'email' ? { email: emailAddr } : {}, { onProgress: out });
+          const codeOpts = Object.assign(method === 'email' ? { email: emailAddr } : {},
+            { onProgress: out, name: regName });
+          if (regName) out('  registering as "' + (store.name || regName) + '"');
           const r = await requestSmsCode(store, method, codeOpts);
           store.codePending = true;
           saveStore(store, sessFile);
@@ -2218,11 +2240,12 @@ async function handleLine(line) {
         else if (sub === 'confirm') {
           const ph   = normalizePhone(p[2]);
           const code = p[3];
-          if (!ph || !code) { fail('usage: /reg confirm <phone> <code>'); break; }
+          if (!ph || !code) { fail('usage: /reg confirm <phone> <code> [--name "Your Name"]'); break; }
           const file  = storeFileFor(_sessDir, ph);
-          const store = loadStore(file) || initAuthCreds(ph);
+          const store = loadStore(file) || initAuthCreds(ph, { name: regName });
           out('verifying...');
-          const r = await verifyCode(store, code, Object.assign(registrationPrompts(), { onProgress: out }));
+          const r = await verifyCode(store, code,
+            Object.assign(registrationPrompts(), { onProgress: out, name: regName }));
           if (r && (r.status === 'ok' || r.status === 'sent' || r.status === 'verified')) {
             sessionDirFor(_sessDir, ph, { create: true });
             const finalStore = r.store || store;
@@ -2239,6 +2262,11 @@ async function handleLine(line) {
               out('      the session is saved under that number');
             }
             out('registered  session saved to ' + savedFile);
+            if (finalStore.name && finalStore.name !== 'User') {
+              out('  name        ' + finalStore.name + '  (announced on every connect)');
+            } else {
+              out('  name        not set — run /name <text> after connecting');
+            }
             out('now run: /connect ' + savedPhone);
           } else {
             fail('verification failed  ' + JSON.stringify(r));
@@ -2464,8 +2492,8 @@ usage:
   wa connect <phone>                        connect and open interactive shell
   wa pair    <phone> [code]                 link to an existing account (8-digit code)
   wa listen  <phone>                        connect and listen (stay-alive)
-  wa registration --request-code <phone>    request SMS code
-  wa registration --register <phone> --code <code>
+  wa registration --request-code <phone> [--name "Your Name"]
+  wa registration --register <phone> --code <code> [--name "Your Name"]
   wa registration --check <phone>
   wa apk-material <base.apk> [split.apk ...]  read the Android token material
   wa apk-material --download                  fetch that APK from Google Play
@@ -2490,6 +2518,7 @@ debug:
 
   --debug           trace without asking  (same as WA_DEBUG=1)
   --no-debug, -q    stay quiet without asking  (same as WA_DEBUG=0)
+  --name <text>     display name to register with (registration commands only)
   --trace-bytes     also dump the raw encoded bytes of every stanza
 
 after connecting, type /help for all available commands.
@@ -2821,10 +2850,11 @@ async function main() {
       // the base directory stays there, a new one gets a directory of its own.
       sessionDirFor(_sessDir, ph, { create: true });
       const sessFile = storeFileFor(_sessDir, ph);
+      const regName = typeof flags.name === 'string' ? flags.name : null;
       let store = loadStore(sessFile);
       if (!store) {
         // Brand new — generate fresh keys, save immediately, no need to check /exist
-        store = initAuthCreds(ph);
+        store = initAuthCreds(ph, { name: regName });
         saveStore(store, sessFile);
       } else if (!store.codePending && !store.registered) {
         // Existing store but code was never sent and not registered — check if
@@ -2835,7 +2865,7 @@ async function main() {
         const fresh = await assertRegistrationKeys(store, waVersion);
         if (!fresh) {
           out('  device keys already registered — generating new keys...');
-          store = initAuthCreds(ph);
+          store = initAuthCreds(ph, { name: regName });
           saveStore(store, sessFile);
         }
       }
@@ -2844,7 +2874,9 @@ async function main() {
       const methodLabel = method === 'email' ? ('email → ' + emailAddr) : method;
       out('requesting ' + methodLabel + ' code for +' + ph + '...');
       try {
-        const codeOpts = Object.assign(method === 'email' ? { email: emailAddr } : {}, { onProgress: out });
+        const codeOpts = Object.assign(method === 'email' ? { email: emailAddr } : {},
+          { onProgress: out, name: regName });
+        if (regName) out('  registering as "' + (store.name || regName) + '"');
         const r = await requestSmsCode(store, method, codeOpts);
         store.codePending = true;
         saveStore(store, sessFile);
@@ -2866,11 +2898,13 @@ async function main() {
       const code = flags.code;
       if (!ph)   { fail('phone number required'); process.exit(1); }
       if (!code) { fail('--code is required');    process.exit(1); }
+      const regName = typeof flags.name === 'string' ? flags.name : null;
       const file  = storeFileFor(_sessDir, ph);
-      const store = loadStore(file) || initAuthCreds(ph);
+      const store = loadStore(file) || initAuthCreds(ph, { name: regName });
       out('verifying code for +' + ph + '...');
       try {
-        const r = await verifyCode(store, code, Object.assign(registrationPrompts(), { onProgress: out }));
+        const r = await verifyCode(store, code,
+          Object.assign(registrationPrompts(), { onProgress: out, name: regName }));
         if (r && (r.status === 'ok' || r.status === 'sent' || r.status === 'verified')) {
           if (!fs.existsSync(_sessDir)) fs.mkdirSync(_sessDir, { recursive: true });
           const finalStore = r.store || store;

package/lib/Client.js

@@ -676,6 +676,19 @@ class WhalibmobClient extends EventEmitter {
     saveWebStore(this._store, this._webSessionFile);
   }
 
+  // Write the session back to disk, whichever kind it is. A change that only
+  // lives in memory is a change that is gone at the next start.
+  _persistStore() {
+    try {
+      if (this._mode === 'web') { this._saveWebStore(); return; }
+      if (!this._sessionDir || !this._store || !this._store.phoneNumber) return;
+      const { saveStore } = require('./Store');
+      saveStore(this._store, path.join(this._sessionDir, `${this._store.phoneNumber}.json`));
+    } catch (err) {
+      _whaDbg('[DBG] STORE persist failed: ' + (err && err.message));
+    }
+  }
+
   async _connectWebSocket() {
     const { encodeCompanionRegisterPayload, encodeCompanionLoginPayload } =
       require('./webproto');
@@ -1279,6 +1292,26 @@ class WhalibmobClient extends EventEmitter {
     const attrs = node.attrs || {};
     // Debug: log the full success node structure
     _whaDbg('[DBG] SUCCESS node attrs=' + JSON.stringify(attrs));
+
+    // The one place the server ever tells us what it thinks this account is
+    // called. Nothing else answers that question — there is no request that
+    // reads a push name back — so this is both how the local name is kept
+    // honest and the only way to find out whether a rename was accepted.
+    if (attrs.display_name) {
+      const serverName = String(attrs.display_name);
+      if (this._store && this._store.name !== serverName) {
+        _whaDbg('[DBG] SUCCESS display_name="' + serverName + '" — server disagrees with the ' +
+          'stored name "' + this._store.name + '"; taking the server\'s');
+        this._store.name = serverName;
+        if (!this._store.pushName) this._store.pushName = serverName;
+        this._persistStore();
+      } else {
+        _whaDbg('[DBG] SUCCESS display_name="' + serverName + '" — matches the stored name');
+      }
+    } else {
+      _whaDbg('[DBG] SUCCESS carried no display_name — the server did not say what this ' +
+        'account is called');
+    }
     if (Array.isArray(node.content)) {
       for (const child of node.content) {
         if (child && child.description) {
@@ -1725,7 +1758,15 @@ class WhalibmobClient extends EventEmitter {
         }
         case 'pushName': {
           const name = (a.pushNameSetting && a.pushNameSetting.name) || null;
-          if (name && this._store) this._store.pushName = name;
+          // Both fields, and to disk. Only `pushName` was set here, and it is
+          // the one the store does not carry — so a rename made on another
+          // device took effect until the process restarted, and never reached
+          // the handshake, which announces `name`.
+          if (name && this._store) {
+            this._store.name     = name;
+            this._store.pushName = name;
+            this._persistStore();
+          }
           this.emit('push_name_update', { name, remote: true });
           break;
         }
@@ -4546,13 +4587,71 @@ class WhalibmobClient extends EventEmitter {
 
   // Change display name
   // Sends presence node with new name — immediate, no IQ needed.
+  // The push name lives in two places, and only one of them survives.
+  //
+  // The presence node announces it to whoever is looking right now — it is how
+  // a contact who has not saved the number sees a name at all. But it says
+  // nothing lasting: the server treats it as the state of this connection, so a
+  // name sent only that way is gone by the next login, and the account keeps
+  // whatever the profile actually holds.
+  //
+  // What persists is an app state write, filed under 'setting_pushName' in the
+  // critical_block collection. That is the record the phone and every other
+  // linked device read, and the one the profile is served from.
+  //
+  // Both are sent: the presence so the change shows immediately, the patch so
+  // it is still there tomorrow.
+  //
+  // Returns a promise for the patch that resolves true when it was written and
+  // false when app state was not writable (no sync key shared yet) or the
+  // server refused it. It never rejects, so a caller that ignores the return —
+  // as every caller did when this only sent presence — cannot end up with an
+  // unhandled rejection. The connection check still throws synchronously.
   changeName(name) {
     if (!this._socket || !this._connected) throw new Error('Not connected');
+    // A presence node carrying only a name is a name republish: it says what
+    // this account is called without also describing whether it is online.
+    // Carrying a type turns it into an availability update that happens to
+    // mention a name, which is a different thing to ask for and is not what a
+    // rename is. The bare form goes first, on its own.
+    this._socket.sendNode(new BinaryNode('presence', { name }, null));
+
+    // And the same name again on an availability node, unconditionally. The
+    // bare form above is what a browser client sends, but the implementation
+    // with the longest production record only ever sends this one, and ties the
+    // server learning your name to it: announce it at least once after
+    // connecting or other people see a placeholder instead. Making it
+    // conditional on already being marked available would leave a session that
+    // renames before going online with only the form that may be ignored.
     this._socket.sendNode(new BinaryNode('presence', {
       name,
       type: 'available'
     }, null));
-    if (this._store) this._store.pushName = name;
+
+    // `name` is the field the handshake reads when it announces this account,
+    // and it is the one the session file carries. Writing only `pushName` left
+    // the store's `name` at its default, so every login announced that default
+    // again and undid the change — the account went on being called "User" no
+    // matter how often the presence went out. Both are set: `name` because the
+    // handshake and the file are keyed off it, `pushName` because the presence
+    // helper reads that one first.
+    if (this._store) {
+      this._store.name     = name;
+      this._store.pushName = name;
+      this._persistStore();
+    }
+
+    return this._appStatePatchOrFallback(AppMutations.pushNamePatch(name))
+      .then(synced => {
+        _whaDbg(synced
+          ? '[DBG] PUSHNAME persisted in app state: ' + name
+          : '[DBG] PUSHNAME announced but NOT persisted — no app state sync key yet');
+        return synced;
+      })
+      .catch(err => {
+        _whaDbg('[DBG] PUSHNAME app state write failed: ' + (err && err.message));
+        return false;
+      });
   }
 
   // Change bio/about text

package/lib/Registration.js

@@ -1653,9 +1653,21 @@ async function assertRegistrationKeys(store, waVersion) {
 // bites when the server keeps answering with a different reason each time.
 const MAX_CODE_REQUEST_ATTEMPTS = 5;
 
+// The display name a registration is carrying, if the caller gave one. It is
+// never sent to the registration endpoints — those take no name, and adding one
+// would be inventing a field. It is written to the session, and the handshake
+// on the first connection is what announces it.
+function applyRegistrationName(store, opts) {
+  if (!store || !opts || opts.name === undefined || opts.name === null) return;
+  const { normalizePushName } = require('./Store');
+  const clean = normalizePushName(opts.name);
+  if (clean) store.name = clean;
+}
+
 async function requestSmsCode(store, method, opts) {
   method = method || 'sms';
   opts   = opts   || {};
+  applyRegistrationName(store, opts);
   // Before the version is read, since on Android the version comes out of the
   // APK this fetches.
   const _device   = deviceForRegistration(store, opts);
@@ -1792,6 +1804,7 @@ async function requestSmsCode(store, method, opts) {
 
 async function verifyCode(store, code, opts) {
   opts = opts || {};
+  applyRegistrationName(store, opts);
   // Normally already there from the code request, but a confirmation can be run
   // from a fresh shell that never made one.
   const _device   = deviceForRegistration(store, opts);

package/lib/Store.js

@@ -49,7 +49,30 @@ function sign(privKey32, message) {
 // Store creation
 // ─────────────────────────────────────────────────────────
 
-function createNewStore(phoneNumber) {
+// What is safe to announce as a display name. The server takes the value
+// verbatim, so a stray newline or a run of spaces goes out as typed; and 'User'
+// is the placeholder this file writes when no name was given, so accepting it
+// back as a real name would make it indistinguishable from having none.
+const MAX_PUSH_NAME_LENGTH = 25;
+
+function normalizePushName(name) {
+  if (name === null || name === undefined) return null;
+  const clean = String(name).replace(/[\r\n\t]+/g, ' ').trim().replace(/\s{2,}/g, ' ');
+  if (!clean || clean === 'User') return null;
+  return clean.length > MAX_PUSH_NAME_LENGTH ? clean.slice(0, MAX_PUSH_NAME_LENGTH).trim() : clean;
+}
+
+/**
+ * @param {string} phoneNumber  digits, no +
+ * @param {object} [opts]
+ *   name  the display name this account announces to people who have not saved
+ *         the number. Setting it here is what makes the first connection carry
+ *         it: the handshake reads this field, and it only announces a name that
+ *         is not the placeholder below. Left unset, the account stays nameless
+ *         until something calls changeName().
+ */
+function createNewStore(phoneNumber, opts) {
+  opts = opts || {};
   const noiseKeyPair     = generateKeyPair();
   const identityKeyPair  = generateKeyPair();
   const signedPreKeyPair = generateKeyPair();
@@ -89,7 +112,7 @@ function createNewStore(phoneNumber) {
     backupToken,
     registered:    false,
     codePending:   false,  // true after /code request, cleared on successful /register
-    name:          'User',
+    name:          normalizePushName(opts.name) || 'User',
     version,
     device,
     // ADVSignedDeviceIdentity bytes received from server <success> node.
@@ -307,6 +330,8 @@ function fromSixParts(sixParts) {
 
 module.exports = {
   createNewStore,
+  normalizePushName,
+  MAX_PUSH_NAME_LENGTH,
   saveStore,
   loadStore,
   toSixParts,

package/lib/auth-utils.js

@@ -666,7 +666,9 @@ function initAuthCreds(phoneNumber, options) {
   options = options || {};
 
   // The library's own key generation — curve25519, with the right prefixes.
-  const store = createNewStore(phoneNumber);
+  // options.name, when given, is the display name the account registers with:
+  // it is stored here and announced by the first handshake.
+  const store = createNewStore(phoneNumber, { name: options.name });
 
   // ── Extra credential fields ──────────────────────────────────────────────────
   // Not required internally, but commonly expected by application code.

package/lib/noise.js

@@ -546,7 +546,14 @@ class NoiseSocket extends EventEmitter {
       const payload = encodeClientPayload({
         username:           BigInt(this.store.phoneNumber),
         passive:            false,
-        pushName:           this.store.registered ? (this.store.name || null) : null,
+        // A session starts out named "User" because the store needs something
+        // there, not because the account is called that. Announcing it says the
+        // account IS called "User", and the handshake runs on every connect, so
+        // a name set while online was overwritten by the placeholder the moment
+        // the connection came back. Send nothing until there is a real name —
+        // the companion payload has always guarded this the same way.
+        pushName:           (this.store.registered && this.store.name &&
+                             this.store.name !== 'User') ? this.store.name : null,
         shortConnect:       _reconnect,
         // ConnectType is a closed set — 0 CELLULAR_UNKNOWN, 1 WIFI_UNKNOWN,
         // and 100-112 for the named cellular radios. There is no 3, which is

package/package.json

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