whalibmob 5.9.2 → 5.10.0

package/README.md

@@ -98,6 +98,7 @@ npm install -g whalibmob
     - [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)
     - [Disappearing Messages](#cli-disappearing-messages)
     - [Default Disappearing Timer](#default-disappearing-timer)
     - [Block / Unblock](#block--unblock)
@@ -169,6 +170,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)
     - [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)
@@ -1113,6 +1115,8 @@ connect()
 | `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) |
+| `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
 linked device rather than by this session. Your own calls carry `synced` instead,
@@ -1390,6 +1394,61 @@ whalibmob implements the full lifecycle to prevent this:
 
 Token storage uses the **LID JID** of the contact (e.g. `112345678901234@lid`) as the key — never the phone-number JID — matching WhatsApp's internal convention.
 
+<a id="account-restriction"></a>
+
+### When 463 Means the Account Is Restricted
+
+A `463` has two causes that look identical on the wire, and telling them apart matters because only one of them is worth retrying.
+
+- **No privacy token for that one contact.** The library issues one and re-sends. This is the common case and it resolves itself.
+- **The account is restricted.** WhatsApp has decided you are starting too many chats with people who never reply, and refuses *all* new conversations until the restriction expires. Existing chats keep working, which is why the account otherwise looks healthy. No retry helps — and sending more counts as further reach-outs, which makes it longer.
+
+The expiry is never pushed to a client that has not asked. `fetchReachoutTimelock()` is the only way to learn it:
+
+```js
+const r = await client.fetchReachoutTimelock()
+
+if (r.active) {
+  console.log('restricted:', r.reason)
+  console.log('ends at:   ', r.endsAtDate.toISOString())
+  console.log('remaining: ', r.remaining)      // '04:59:20'
+} else {
+  console.log('not restricted')
+}
+```
+
+```js
+{
+  active:          true,
+  remaining:       '04:59:20',   // HH:MM:SS, hours not wrapped at 24
+  remainingMs:     17960000,
+  endsAt:          1800018000000,
+  endsAtDate:      Date,
+  enforcementType: 'BIZ_QUALITY',
+  reason:          'too many people you messaged blocked or reported you',
+  expiryUnknown:   false,        // true when the server withheld the end time
+  checkedAt:       1800000040000
+}
+```
+
+`getReachoutTimelock()` returns the same shape from what was last learned, without asking again — the countdown is recomputed on every call, so it is what a once-a-second display reads.
+
+**You rarely need to call either.** A send refused with 463 triggers a check on its own (rate-limited to once a minute), and the server pushes an update both when a restriction starts and when it is lifted:
+
+```js
+client.on('account_restriction', (r) => {
+  if (r.active) console.log('restricted for', r.remaining, '—', r.reason)
+  else          console.log('restriction lifted')
+})
+```
+
+`r.source` is `'notification'` when the server announced it and `'query'` when we asked.
+
+> [!NOTE]
+> A first restriction is usually around five hours. Repeats get longer. Nothing
+> client-side shortens it; the only thing that helps is not sending more
+> unanswered first messages while it is on.
+
 ### What Is Automatic vs What You Need to Do
 
 **Everything in the "Automatic" column requires zero code from you.**
@@ -1412,6 +1471,8 @@ Token storage uses the **LID JID** of the contact (e.g. `112345678901234@lid`) a
 | Handle incoming `privacy_token` notifications | ✅ | |
 | Re-issue tcToken after peer identity change | ✅ | |
 | Recover from error 463 with automatic retry | ✅ | |
+| Check for an account restriction after a 463 | ✅ | Rate-limited to once a minute |
+| Track restriction start / lift pushed by the server | ✅ | Raised as `account_restriction` |
 | Populate in-memory LID↔PN maps | ✅ | |
 | Listen to `history_sync` event | 🔵 Optional | Only if your app needs to react to history data |
 | Read `<phone>.history.json` | 🔵 Optional | Only if your app needs chat/contact data at rest |
@@ -3150,6 +3211,60 @@ Changes that arrive on their own are printed as they land:
 If your phone has not yet shared a sync key with this session, the command says
 so — leave WhatsApp open on the phone for a moment and try again.
 
+<a id="cli-restriction"></a>
+
+#### Account Restriction Countdown
+
+When WhatsApp restricts an account, new chats are refused with error 463 until
+it expires — usually about five hours the first time. `/restriction` asks the
+server how long is left and then counts it down, once a second, in place:
+
+```sh
+wa> /restriction
+checking account restriction...
+  ──────────────────────────────────────────────────
+  status                RESTRICTED
+  reason                too many people you messaged blocked or reported you
+  type                  BIZ_QUALITY
+  ends at               2026-07-28 19:41:12 UTC
+  remaining             04:59:22
+  ──────────────────────────────────────────────────
+  New chats with people you have never messaged are refused with
+  error 463 until this expires. Existing conversations keep working,
+  and sending more only makes the restriction longer.
+
+  press any key to stop watching
+  restricted — 04:59:20 remaining
+```
+
+The last line rewrites itself every second — `04:59:20`, `04:59:19`, … — and
+stops on its own the moment the restriction lifts. Any key ends the watch; the
+restriction is unaffected either way. `/limit` is the same command.
+
+For the numbers without the countdown:
+
+```sh
+wa> /restriction --once
+```
+
+An account that is fine says so and returns immediately:
+
+```sh
+wa> /restriction
+checking account restriction...
+  ──────────────────────────────────────────────────
+  status                not restricted — you can start new chats
+  ──────────────────────────────────────────────────
+```
+
+You do not have to run it to find out. A refused send checks by itself, and the
+shell prints the change as it happens:
+
+```sh
+  ACCOUNT RESTRICTED — too many people you messaged blocked or reported you, 04:59:58 remaining
+  run /restriction to watch the countdown
+```
+
 #### CLI Disappearing Messages
 
 | Duration | Seconds |
@@ -3647,6 +3762,9 @@ wa> /quit
 | `/unstar <jid> <msgId> [me]` | Unstar a message |
 | `/appstate [collection...]` | Pull pins/archives/mutes/stars from your phone |
 | `/appstate --snapshot` | Re-read all app state from scratch |
+| `/restriction` | Account restriction status with a live countdown |
+| `/restriction --once` | Restriction status without the countdown |
+| `/limit` | Alias for `/restriction` |
 | `/ephemeral <jid> <seconds>` | Set disappearing messages timer for a chat |
 | `/ephemeral-default <seconds>` | Set global default ephemeral timer for new chats |
 | `/block <jid>` | Block a contact |

package/cli.js

@@ -303,6 +303,55 @@ function participantLine(p) {
 // A chat setting either reached app state — and so every other device — or it
 // did not, and stayed here. Saying which costs one word and saves the user
 // wondering why their phone did not follow.
+// A live HH:MM:SS countdown, redrawn in place once a second.
+//
+// The restriction's end is a fixed moment, so every tick recomputes from it
+// rather than decrementing a counter — a tick that arrives late, or a laptop
+// that slept, then shows the truth instead of drifting further behind.
+//
+// Returns a promise that settles when the time runs out or the user stops it.
+function countdown(client, initial) {
+  return new Promise((resolve) => {
+    const tty = process.stdout.isTTY;
+    let done  = false;
+
+    const finish = (why) => {
+      if (done) return;
+      done = true;
+      clearInterval(timer);
+      process.stdin.removeListener('data', onKey);
+      if (tty) process.stdout.write('\n');
+      resolve(why);
+    };
+
+    const draw = () => {
+      const s = client.getReachoutTimelock();
+      if (!s.active) { 
+        if (tty) process.stdout.write('\r\x1b[2K');
+        out('  the restriction has been lifted — you can start new chats again');
+        return finish('lifted');
+      }
+      const line = '  restricted — ' + s.remaining + ' remaining' +
+        (s.expiryUnknown ? '  (server did not give an end time; re-checking)' : '');
+      if (tty) process.stdout.write('\r\x1b[2K' + line);
+      else     out(line);
+    };
+
+    // Any keypress stops the countdown; the restriction is unaffected either
+    // way, so there is nothing to confirm.
+    const onKey = () => finish('stopped');
+    if (tty && process.stdin.isTTY) {
+      process.stdin.resume();
+      process.stdin.once('data', onKey);
+    }
+
+    if (tty) out('  press any key to stop watching');
+    void initial;
+    draw();
+    const timer = setInterval(draw, 1000);
+  });
+}
+
 function chatResult(label, synced) {
   return label + (synced ? '' : '  (this session only — no app state key)');
 }
@@ -427,6 +476,8 @@ const HELP = `
     /unstar    <jid> <msgId> [me]            unstar a message
     /appstate  [collection...]               pull pins/archives/mutes/stars from your phone
     /appstate  --snapshot                    re-read all of it from scratch
+    /restriction                             account restriction + live countdown
+    /restriction --once                      just the numbers, no countdown
     /ephemeral         <jid> <seconds>        set disappearing timer for chat
     /ephemeral-default <seconds>             set default timer for ALL new chats
     /block     <jid>                         block contact
@@ -600,6 +651,20 @@ function attachEvents(client) {
     _rl && (_rl.resume(), _rl.prompt(true));
   });
 
+  // The server announces a restriction starting and being lifted, so a session
+  // that is just sitting there still finds out.
+  client.on('account_restriction', (r) => {
+    if (r.source !== 'notification') return;
+    _rl && _rl.pause();
+    if (r.active) {
+      out('  ACCOUNT RESTRICTED — ' + r.reason + ', ' + r.remaining + ' remaining');
+      out('  run /restriction to watch the countdown');
+    } else {
+      out('  account restriction lifted — you can start new chats again');
+    }
+    _rl && (_rl.resume(), _rl.prompt(true));
+  });
+
   client.on('app_state_keys', (e) => {
     _rl && _rl.pause();
     out('  app state: received ' + e.keys.length + ' sync key(s) from your phone —' +
@@ -1412,6 +1477,36 @@ async function handleLine(line) {
         out('marked read');
         break;
 
+      case '/restriction':
+      case '/limit': {
+        requireConn();
+        const watch = !p.includes('--once');
+        out('checking account restriction...');
+        const st = await _client.fetchReachoutTimelock();
+        hr();
+        if (!st.active) {
+          kv('status', 'not restricted — you can start new chats');
+          hr();
+          break;
+        }
+        kv('status',    'RESTRICTED');
+        kv('reason',    st.reason);
+        kv('type',      st.enforcementType);
+        kv('ends at',   st.endsAtDate ? st.endsAtDate.toISOString().replace('T', ' ').replace(/\.\d+Z$/, ' UTC') : 'unknown');
+        kv('remaining', st.remaining);
+        hr();
+        out('  New chats with people you have never messaged are refused with');
+        out('  error 463 until this expires. Existing conversations keep working,');
+        out('  and sending more only makes the restriction longer.');
+        out('');
+        if (watch) {
+          _rl && _rl.pause();
+          await countdown(_client, st);
+          _rl && _rl.resume();
+        }
+        break;
+      }
+
       case '/appstate': {
         requireConn();
         const snapshot = p.includes('--snapshot');

package/index.js

@@ -13,6 +13,7 @@ const { encryptMedia, decryptMedia, uploadMedia, downloadMedia } = require('./li
 const { MessageSender, makeJid, generateMessageId } = require('./lib/messages/MessageSender');
 const { GroupParticipantResult, GroupJoinRequest } = require('./lib/GroupParticipant');
 const { AppStateStore, COLLECTIONS: APP_STATE_COLLECTIONS } = require('./lib/appstate/AppStateStore');
+const ReachoutTimelock = require('./lib/ReachoutTimelock');
 const AppStateSync = require('./lib/appstate/AppStateSync');
 const { PATCH_INTEGRITY: LT_HASH } = require('./lib/appstate/LTHash');
 const {
@@ -110,6 +111,8 @@ module.exports = {
   AppStateSync,
   APP_STATE_COLLECTIONS,
   LT_HASH,
+  // Account restriction
+  ReachoutTimelock,
   // Auth utilities
   makeCacheableSignalKeyStore,
   addTransactionCapability,

package/lib/Client.js

@@ -13,6 +13,7 @@ const { getDeviceConfig } = require('./DeviceConfig');
 const { createNewStore, saveStore, loadStore, toSixParts, fromSixParts } = require('./Store');
 const { BinaryNode }      = require('./BinaryNode');
 const { AppStateStore, COLLECTIONS } = require('./appstate/AppStateStore');
+const ReachoutTimelock = require('./ReachoutTimelock');
 const AppStateSync  = require('./appstate/AppStateSync');
 const SyncdProto    = require('./appstate/SyncdProto');
 const AppMutations  = require('./appstate/Mutations');
@@ -50,6 +51,12 @@ const CALL_VIDEO_PREFIX = 'https://call.whatsapp.com/video/';
 // The one prefix group invite codes are wrapped in.
 const INVITE_LINK_PREFIX = 'https://chat.whatsapp.com/';
 
+// The w:mex query that reports whether this account is restricted and until
+// when. The id is the server's handle for that stored GraphQL document; there
+// is no way to derive it, and a wrong one is answered with an error rather than
+// with a different query.
+const MEX_QUERY_REACHOUT_TIMELOCK = '23983697327930364';
+
 // The names privacy settings actually go by on the wire, and the friendly
 // aliases this library has always accepted for them. The wire names are the
 // right-hand column.
@@ -246,6 +253,9 @@ class WhalibmobClient extends EventEmitter {
     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)
+    // Last known account restriction, or null until one is fetched or pushed.
+    this._reachoutTimelock        = null;
+    this._reachoutTimelockInFlight = null;
     // Blue-tick every message as it arrives. Set to false to make read receipts
     // explicit, sent only by a markRead() call.
     this.autoRead = opts.autoRead !== false;
@@ -2596,6 +2606,10 @@ class WhalibmobClient extends EventEmitter {
       this._processGroupUpdate(node);
     }
 
+    if (type === 'mex') {
+      this._handleMexNotification(node);
+    }
+
     if (type === 'privacy_token') {
       // Incoming trusted-contact token from a conversation partner — store it
       // so we can attach it on next DM send (prevents error 463).
@@ -4833,6 +4847,152 @@ class WhalibmobClient extends EventEmitter {
     return this._sendIq(node);
   }
 
+  // ──────────────────────────────────────────────────────────────────────────
+  // ACCOUNT RESTRICTION (reachout timelock)
+  // ──────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Ask the server whether this account is currently restricted, and until when.
+   *
+   * A restriction is what error 463 means when it will not go away: WhatsApp
+   * has decided the account is starting too many chats with people who never
+   * reply, and refuses new ones until it expires. Existing chats keep working,
+   * which is why the account otherwise looks fine.
+   *
+   * The expiry is not pushed to the client — this is the only way to learn it.
+   *
+   * @returns {Promise<object>} { active, remaining, remainingMs, endsAtDate,
+   *                              enforcementType, reason, expiryUnknown }
+   */
+  async fetchReachoutTimelock() {
+    const payload = await this._mexQuery(MEX_QUERY_REACHOUT_TIMELOCK, {},
+      'xwa2_fetch_account_reachout_timelock');
+    return this._setReachoutTimelock(
+      ReachoutTimelock.parseTimelockPayload(payload || {}), 'query');
+  }
+
+  /**
+   * What we last learned about the restriction, without asking again.
+   *
+   * The countdown is computed fresh on every call, so this is what a ticking
+   * display reads once a second. Returns an inactive state when nothing has
+   * been fetched yet — call fetchReachoutTimelock() for that.
+   */
+  getReachoutTimelock() {
+    return ReachoutTimelock.describe(this._reachoutTimelock);
+  }
+
+  /**
+   * Refresh the restriction after a send was refused, at most once a minute.
+   *
+   * A 463 has two causes that look identical on the wire: a contact we simply
+   * hold no privacy token for, which the resend recovers from, and an account
+   * restriction, which no resend will fix. Asking the server tells the two
+   * apart, and it is the only way to learn when the restriction ends.
+   *
+   * Rate-limited because a burst of refused sends would otherwise fire one
+   * query each, and a restricted account is exactly where a burst happens.
+   */
+  _refreshReachoutTimelockAfter463() {
+    if (!this._connected) return;
+    const last = this._reachoutTimelock && this._reachoutTimelock.checkedAt;
+    if (last && Date.now() - last < 60000) return;
+    if (this._reachoutTimelockInFlight) return;
+
+    this._reachoutTimelockInFlight = this.fetchReachoutTimelock()
+      .then(state => {
+        if (state.active) {
+          _whaDbg('[DBG] ACCOUNT_RESTRICTED for ' + state.remaining +
+            ' (' + state.enforcementType + ')');
+        }
+      })
+      .catch(err => _whaDbg('[DBG] REACHOUT_TIMELOCK fetch failed: ' + (err && err.message)))
+      .then(() => { this._reachoutTimelockInFlight = null; });
+  }
+
+  _setReachoutTimelock(state, source) {
+    this._reachoutTimelock = Object.assign({}, state, { checkedAt: Date.now() });
+    const described = ReachoutTimelock.describe(this._reachoutTimelock);
+    this.emit('account_restriction', Object.assign({ source }, described));
+    return described;
+  }
+
+  /**
+   * One w:mex GraphQL call.
+   *
+   * The reply is JSON inside <result>. GraphQL reports failures in the body
+   * with a 200-shaped envelope, so an errors array has to be checked for
+   * separately — otherwise a refused query reads as an empty result and the
+   * caller concludes the account is fine.
+   */
+  async _mexQuery(queryId, variables, dataPath) {
+    const resp = await this._sendIq(new BinaryNode('iq', {
+      id:    this._genMsgId(),
+      to:    's.whatsapp.net',
+      type:  'get',
+      xmlns: 'w:mex'
+    }, [
+      new BinaryNode('query', { query_id: String(queryId) },
+        Buffer.from(JSON.stringify({ variables: variables || {} }), 'utf8'))
+    ]));
+
+    if (!resp) throw new Error('mex query ' + queryId + ': no reply from server (IQ timed out)');
+    if (resp.attrs && resp.attrs.type === 'error') {
+      const errNode = findChild(resp, 'error');
+      const code    = errNode && errNode.attrs && errNode.attrs.code;
+      throw new Error('mex query ' + queryId + ': server rejected the request' +
+        (code ? ' (' + code + ')' : ''));
+    }
+
+    const resultNode = findChild(resp, 'result');
+    const buf        = resultNode ? getNodeContent(resultNode) : null;
+    if (!buf) throw new Error('mex query ' + queryId + ': reply carried no result');
+
+    let json;
+    try { json = JSON.parse(buf.toString('utf8')); }
+    catch (_) { throw new Error('mex query ' + queryId + ': reply was not JSON'); }
+
+    if (json.errors && json.errors.length) {
+      throw new Error('mex query ' + queryId + ': ' +
+        json.errors.map(e => (e && e.message) || 'unknown error').join(', '));
+    }
+    return dataPath ? (json.data && json.data[dataPath]) : json.data;
+  }
+
+  /**
+   * <notification type="mex"> — a GraphQL push rather than a reply.
+   *
+   * The restriction is the one that matters here: the server announces both
+   * when it starts and when it is lifted, so a client that listens does not
+   * have to poll to know it can send again.
+   */
+  _handleMexNotification(node) {
+    const update = findChild(node, 'update');
+    if (!update) return;
+    const opName = (update.attrs && update.attrs.op_name) || '';
+    const buf    = getNodeContent(update);
+    if (!buf) return;
+
+    let json;
+    try { json = JSON.parse(buf.toString('utf8')); }
+    catch (_) { _whaDbg('[DBG] MEX_NOTIF ' + opName + ' — body was not JSON'); return; }
+    if (json.errors && json.errors.length) return;
+    const data = json.data;
+    if (!data) return;
+
+    if (opName === 'NotificationUserReachoutTimelockUpdate') {
+      const payload = data.xwa2_notify_account_reachout_timelock;
+      if (!payload) return;
+      const state = ReachoutTimelock.parseTimelockPayload(payload);
+      _whaDbg('[DBG] MEX_NOTIF restriction ' + (state.active ? 'set' : 'lifted'));
+      this._setReachoutTimelock(state, 'notification');
+      return;
+    }
+
+    // Anything else the server pushes this way, passed on rather than dropped.
+    this.emit('mex_notification', { opName, data });
+  }
+
   // Internal: parse newsletter response from w:mex IQ result
   _parseNewsletterResponse(resp) {
     try {

package/lib/ReachoutTimelock.js

@@ -0,0 +1,133 @@
+'use strict';
+
+// The "reachout timelock" — the temporary restriction WhatsApp puts on an
+// account that has started too many chats with people who have never replied.
+//
+// While it is on, messages to a contact you have no history with are refused
+// with error 463 and nothing you do client-side gets them through. The
+// restriction is not permanent: the server holds an expiry, and once it passes
+// the account goes back to normal on its own. Five hours is the usual first
+// one; repeat offences get longer.
+//
+// The expiry is not on any stanza the client is sent by default — it has to be
+// asked for, over the GraphQL-style w:mex transport.
+
+// The reason a restriction was applied. DEFAULT is the one that means "no
+// restriction", which is also what the server sends when it is lifting one.
+const ENFORCEMENT_TYPES = new Set([
+  'DEFAULT',
+  'BIZ_QUALITY',
+  'WEB_COMPANION_ONLY',
+  'BIZ_COMMERCE_VIOLATION_ALCOHOL',
+  'BIZ_COMMERCE_VIOLATION_ADULT',
+  'BIZ_COMMERCE_VIOLATION_ANIMALS',
+  'BIZ_COMMERCE_VIOLATION_BODY_PARTS_FLUIDS',
+  'BIZ_COMMERCE_VIOLATION_DATING',
+  'BIZ_COMMERCE_VIOLATION_DIGITAL_SERVICES_PRODUCTS',
+  'BIZ_COMMERCE_VIOLATION_DRUGS',
+  'BIZ_COMMERCE_VIOLATION_DRUGS_ONLY_OTC',
+  'BIZ_COMMERCE_VIOLATION_GAMBLING',
+  'BIZ_COMMERCE_VIOLATION_HEALTHCARE',
+  'BIZ_COMMERCE_VIOLATION_REAL_FAKE_CURRENCY',
+  'BIZ_COMMERCE_VIOLATION_SUPPLEMENTS',
+  'BIZ_COMMERCE_VIOLATION_TOBACCO',
+  'BIZ_COMMERCE_VIOLATION_VIOLENT_CONTENT',
+  'BIZ_COMMERCE_VIOLATION_WEAPONS'
+]);
+
+// Plain-language reasons for the ones a normal account actually meets.
+const ENFORCEMENT_REASONS = {
+  DEFAULT:            'no restriction',
+  BIZ_QUALITY:        'too many people you messaged blocked or reported you',
+  WEB_COMPANION_ONLY: 'restricted to the linked-device app'
+};
+
+// When the server says a restriction is on but does not say when it ends, it
+// means "ask again shortly" rather than "forever". A minute is what WhatsApp
+// Web assumes in the same spot.
+const UNKNOWN_EXPIRY_MS = 60 * 1000;
+
+function normalizeEnforcementType(value) {
+  return (typeof value === 'string' && ENFORCEMENT_TYPES.has(value)) ? value : 'DEFAULT';
+}
+
+/**
+ * Turn what the server sent into the shape the rest of the library uses.
+ *
+ * `time_enforcement_ends` is unix *seconds* as a string, and "0" is the
+ * server's way of saying there is no expiry to report — treating it as a date
+ * would put the restriction at 1970 and make it look long expired.
+ */
+function parseTimelockPayload(payload, opts) {
+  const p = payload || {};
+  const active = !!p.is_active;
+
+  if (!active) {
+    return { active: false, endsAt: null, enforcementType: 'DEFAULT', reason: ENFORCEMENT_REASONS.DEFAULT };
+  }
+
+  const raw = p.time_enforcement_ends;
+  const ts  = (raw != null && String(raw) !== '0') ? parseInt(String(raw), 10) : NaN;
+  const endsAt = Number.isFinite(ts) && ts > 0
+    ? ts * 1000
+    : ((opts && opts.now ? opts.now : Date.now()) + UNKNOWN_EXPIRY_MS);
+
+  const enforcementType = normalizeEnforcementType(p.enforcement_type);
+  return {
+    active: true,
+    endsAt,
+    enforcementType,
+    reason: ENFORCEMENT_REASONS[enforcementType] || 'account restricted',
+    // The server did not tell us when it ends, so this is a guess and the
+    // caller should ask again rather than trust the countdown.
+    expiryUnknown: !(Number.isFinite(ts) && ts > 0)
+  };
+}
+
+/** Milliseconds left, floored at zero. */
+function remainingMs(state, now) {
+  if (!state || !state.active || !state.endsAt) return 0;
+  return Math.max(0, state.endsAt - (now == null ? Date.now() : now));
+}
+
+/**
+ * HH:MM:SS, which is how long a restriction is worth showing to a person.
+ * Hours are not wrapped at 24 — a two-day restriction reads "48:00:00" rather
+ * than looking like a fresh one.
+ */
+function formatRemaining(ms) {
+  const total = Math.max(0, Math.ceil(ms / 1000));
+  const h = Math.floor(total / 3600);
+  const m = Math.floor((total % 3600) / 60);
+  const s = total % 60;
+  const pad = n => String(n).padStart(2, '0');
+  return pad(h) + ':' + pad(m) + ':' + pad(s);
+}
+
+/** A state object with the derived fields filled in, for handing to a caller. */
+function describe(state, now) {
+  const base = state || { active: false, endsAt: null, enforcementType: 'DEFAULT' };
+  const left = remainingMs(base, now);
+  return {
+    active:          !!base.active && left > 0,
+    endsAt:          base.endsAt || null,
+    endsAtDate:      base.endsAt ? new Date(base.endsAt) : null,
+    remainingMs:     left,
+    remaining:       formatRemaining(left),
+    enforcementType: base.enforcementType || 'DEFAULT',
+    reason:          base.reason || ENFORCEMENT_REASONS.DEFAULT,
+    expiryUnknown:   !!base.expiryUnknown,
+    checkedAt:       base.checkedAt || null
+  };
+}
+
+module.exports = {
+  parseTimelockPayload,
+  remainingMs,
+  formatRemaining,
+  describe,
+  normalizeEnforcementType,
+  ENFORCEMENT_TYPES,
+  ENFORCEMENT_REASONS,
+  UNKNOWN_EXPIRY_MS
+};

package/lib/messages/MessageSender.js

@@ -1513,6 +1513,13 @@ class MessageSender {
           // token attached. Uses a separate _inFlight463Recoveries Set so
           // concurrent 463 recoveries and proactive issuances don't clash.
           if (error === '463' && !_isRetry) {
+            // A 463 is either a missing privacy token for this one contact,
+            // which the resend below fixes, or an account-wide restriction,
+            // which it cannot. Ask the server which it is — that answer also
+            // carries when a restriction ends, which nothing else reports.
+            if (typeof client._refreshReachoutTimelockAfter463 === 'function') {
+              client._refreshReachoutTimelockAfter463();
+            }
             const ackFrom = ackAttrs.from ? String(ackAttrs.from) : '';
             const tcJid   = client._resolveTcTokenJid(
               ackFrom || String(node.attrs && node.attrs.to || '')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whalibmob",
-  "version": "5.9.2",
+  "version": "5.10.0",
   "description": "WhatsApp library for interaction with WhatsApp Mobile API no web",
   "author": "Kunboruto50",
   "main": "index.js",