whalibmob 5.28.0 → 5.29.1

package/README.md

@@ -262,6 +262,10 @@ npm install -g whalibmob
     - [Read Privacy Settings](#read-privacy-settings)
     - [Update Privacy Settings](#update-privacy-settings)
     - [Update Default Disappearing Mode](#update-default-disappearing-mode)
+  - [Account State](#account-state)
+    - [AB Props](#ab-props)
+    - [Contact Sync](#contact-sync)
+    - [Terms-of-Service Notices](#terms-of-service-notices)
   - [Communities](#communities)
     - [Create a Community](#create-a-community)
     - [Deactivate / Delete a Community](#deactivate--delete-a-community)
@@ -4605,6 +4609,206 @@ await client.changeNewChatsEphemeralTimer(86400)   // 1 day
 await client.changeNewChatsEphemeralTimer(0)       // off
 ```
 
+## Account State
+
+Three things the app speaks on every account and whalibmob did not: the
+server's own feature flags, the address book, and the legal notices an account
+is asked to accept. Each is one IQ family; together they are part of what makes
+a session look like an app rather than a script.
+
+### AB Props
+
+Every WhatsApp client asks the server which experiments and configuration
+values apply to *this* account, then gates behaviour on the answer — how many
+bytes an identity hash is truncated to, whether the LID migration has started
+here, what sampling weight each telemetry event carries. A client that never
+asks runs on guessed defaults wherever the server has an opinion.
+
+This is synced automatically on every connect. You do not have to call it.
+
+```js
+const client = new WhalibmobClient({ sessionDir: './auth' })
+await client.connect()
+
+// Already synced by the time 'connected' fires. Read a value:
+client.abProp(4405)              // '16'   — always a string on the wire
+client.abPropInt(4405, 8)        // 16     — parsed, or 8 if unset/unparseable
+client.abPropBool(5010, false)   // true   — understands "1"/"0" and "true"/"false"
+```
+
+Reading a prop before the first sync gives the fallback rather than throwing,
+so gating on a flag never needs a guard:
+
+```js
+// Safe even on a client that has not connected yet.
+const hashLen = client.abPropInt(4405, 8)
+```
+
+To re-sync by hand, or to look at the whole set:
+
+```js
+const props = await client.queryAbProps({ force: true })
+
+console.log(props.hash)      // 'A1B2…' — rides on the next sync, asking for a delta
+console.log(props.refresh)   // 86400 — seconds the server suggests waiting
+console.log(props.delta)     // false — this reply was the whole table
+console.log(props.props)     // { '4405': '16', '5010': 'true', … }
+console.log(props.sampling)  // { '1200': 100, … }  telemetry weights
+```
+
+The hash is what turns the next request into a delta. A delta is **merged**
+onto what is already held rather than replacing it — otherwise every prop the
+server saw no reason to repeat would be dropped. The hash lives for the session
+only: a fresh process asks for the full set again, which is what a fresh
+install does.
+
+Turn the automatic sync off if you do not want the extra IQ on a short session:
+
+```js
+new WhalibmobClient({ sessionDir: './auth', syncAbPropsOnConnect: false })
+```
+
+Being straight about the scope: nothing inside the library consumes these
+values yet. What you get today is the ability to see what the server thinks
+about an account — useful when one number behaves differently from another and
+you would otherwise be guessing — plus one more request a real client makes.
+
+### Contact Sync
+
+The address-book upload a phone does on first launch, and the delta syncs after
+it. It answers the question worth asking before a first message: **is this
+number on WhatsApp at all?**
+
+```js
+const out = await client.syncContacts([
+  '40712345678',
+  '+55 11 91234-5678',
+  '40799999999'
+])
+
+out.registered    // ['40712345678', '+55 11 91234-5678']  — on WhatsApp
+out.unregistered  // ['40799999999']                       — not on WhatsApp
+out.jids          // { '40712345678': '40712345678@s.whatsapp.net', … }
+```
+
+Numbers come back in the spelling you passed in, however they were written —
+spaces, dashes and a leading `+` are all normalised before sending and restored
+in the answer.
+
+**A number the server did not answer about appears in neither list.** That is
+deliberate. Reporting a timeout as "not on WhatsApp" is the one wrong answer
+available here, because a caller acts on it — skipping the number, or deleting
+it. Silence is not a verdict:
+
+```js
+const asked = phones.length
+const known = out.registered.length + out.unregistered.length
+if (known < asked) {
+  console.log(`${asked - known} numbers went unanswered — try them again later`)
+}
+```
+
+Large books are chunked automatically, and one unanswered chunk does not cost
+the others their answers:
+
+```js
+await client.syncContacts(bigList, { chunkSize: 200 })   // default is 500
+```
+
+The mode says what the sync claims about your address book. `full` is the
+whole book — what the app sends on first launch — and carries the
+`registration` context by default. `delta` is what changed since. `query` is a
+plain lookup that claims nothing:
+
+```js
+await client.syncContacts(phones)                      // mode 'full',  context 'registration'
+await client.syncContacts(phones, { mode: 'delta' })   // mode 'delta', context 'interactive'
+await client.syncContacts(phones, { mode: 'query' })   // a lookup, nothing claimed
+```
+
+This is **not** called automatically on connect. Uploading an address book is
+your decision, not a side effect of connecting.
+
+Where it earns its place is in front of a batch of first messages, together
+with the token path described under
+[tcToken](#tctoken--error-463-defense):
+
+```js
+// 1. Which of these actually exist?
+const { registered } = await client.syncContacts(numbers)
+
+// 2. Warm a trusted-contact token for each, so the first message carries one.
+for (const n of registered) {
+  const jid = `${n.replace(/\D/g, '')}@s.whatsapp.net`
+  await client.ensureTcTokenBeforeSend(jid, jid)
+  await new Promise(r => setTimeout(r, 300))
+}
+
+// 3. Send. No wasted sends to dead numbers, and no anonymous reach-outs.
+for (const n of registered) {
+  await client.sendText(`${n.replace(/\D/g, '')}@s.whatsapp.net`, 'Hello')
+  await new Promise(r => setTimeout(r, 1000))
+}
+```
+
+### Terms-of-Service Notices
+
+WhatsApp gates some surfaces on the account having accepted a given legal
+notice — a Terms update, a privacy-policy change, a regional disclosure. The
+app pulls the acceptance state, shows what is outstanding, and posts back what
+the user accepted.
+
+```js
+const out = await client.queryTosNotices(['20230324', '20240101'])
+
+out.refresh   // 86400 — seconds the server suggests waiting before asking again
+out.notices   // [ { id: '20230324', accepted: true },
+              //   { id: '20240101', accepted: false } ]
+
+// Anything still outstanding:
+const pending = out.notices.filter(n => !n.accepted).map(n => n.id)
+if (pending.length) await client.acceptTosNotices(pending)
+```
+
+Reading one back without asking again:
+
+```js
+client.isTosAccepted('20230324')   // true
+client.isTosAccepted('20240101')   // false
+client.isTosAccepted('unknown-id') // null — this session has not asked
+```
+
+`null` matters: it means *unknown*, not *not accepted*. Code deciding whether
+to accept something needs to be able to tell those apart.
+
+Clearing an acceptance, so the server asks for it again:
+
+```js
+await client.clearTosNotice('20230324')
+```
+
+An acceptance made on another device arrives on its own, inside the same
+`account_sync` notification that carries device and privacy changes:
+
+```js
+client.on('tos_notices', ({ notices }) => {
+  for (const n of notices) {
+    console.log(n.id, n.accepted ? 'accepted' : 'outstanding')
+  }
+})
+```
+
+A note on the wire, because it reads backwards from how it looks: the `state`
+attribute is present and `"false"` for a notice that has **not** been accepted,
+and **absent** for one that has. whalibmob reads it that way. If you parse these
+stanzas yourself, treating a missing attribute as "unknown" would report every
+accepted notice as outstanding.
+
+Scope, honestly: no specific feature has been shown to be blocked by an
+unaccepted notice on a headless account. What this gives you is something to
+check rather than guess at — if a freshly registered number will not do
+something, you can now ask whether it has a notice pending.
+
 ## Groups
 
 ### Create a Group

package/index.d.ts

@@ -131,6 +131,15 @@ export interface WhalibmobClientOptions {
    * rest with `rejectCall()`.
    */
   autoRejectCalls?: boolean;
+  /**
+   * Sync the account's AB props on every connect. Default `true`, because the
+   * app does it on every login and a client that never asks runs on guessed
+   * defaults wherever the server has an opinion.
+   *
+   * Turning it off saves one IQ per connect and costs nothing else: every
+   * reader of these has a fallback.
+   */
+  syncAbPropsOnConnect?: boolean;
   /** Refresh the announced build from the platform's store before every handshake. Default `true`. */
   refreshVersion?: boolean;
   /** `true` enables debug logging; an object is handed to `pino` as-is. */
@@ -478,6 +487,36 @@ export type PrivacyValue =
   | 'on_standard'
   | 'off';
 
+export interface AbProps {
+  /** Hash of the returned set. Sent back on the next sync to ask for a delta. */
+  hash: string | null;
+  abKey: string | null;
+  /** Seconds the server suggests waiting before syncing again. */
+  refresh: number | null;
+  refreshId: string | null;
+  /** Whether this reply named only what changed, rather than the whole table. */
+  delta: boolean;
+  /** Experiment values, keyed by their numeric config code. */
+  props: { [configCode: string]: string };
+  /** Telemetry sampling weights, keyed by their numeric event code. */
+  sampling: { [eventCode: string]: number };
+}
+
+export interface ContactSyncResult {
+  /** Numbers on WhatsApp, in the spelling they were passed in. */
+  registered: string[];
+  /** Numbers the server said are not on WhatsApp. */
+  unregistered: string[];
+  /** Each registered number mapped to the JID the server gave it. */
+  jids: { [phone: string]: string };
+}
+
+export interface TosNoticesResult {
+  /** Seconds the server suggests waiting before asking again. */
+  refresh: number | null;
+  notices: Array<{ id: string; accepted: boolean }>;
+}
+
 export interface PrivacySettings {
   lastSeen: string | null;
   profile: string | null;
@@ -820,6 +859,46 @@ export declare class WhalibmobClient extends EventEmitter {
 
   // ─── Privacy ─────────────────────────────────────────────────────────────
   queryPrivacySettings(opts?: { force?: boolean }): Promise<PrivacySettings>;
+
+  // ─── AB props ────────────────────────────────────────────────────────────
+  //
+  // The per-account feature flags the server hands out. Synced on connect
+  // unless `syncAbPropsOnConnect: false` was passed to the constructor, and
+  // held for the session — a fresh process asks for the full set again, which
+  // is what a fresh install does.
+  //
+  // Values are strings because that is what the wire carries; abPropInt and
+  // abPropBool are the two readings worth having, and both fall back rather
+  // than coerce.
+  queryAbProps(opts?: { force?: boolean; refreshId?: string }): Promise<AbProps>;
+  abProp(code: number | string, fallback?: string | null): string | null;
+  abPropInt(code: number | string, fallback?: number | null): number | null;
+  abPropBool(code: number | string, fallback?: boolean | null): boolean | null;
+
+  // ─── Contact sync ────────────────────────────────────────────────────────
+  //
+  // The address-book upload a phone does on first launch, and the delta syncs
+  // after it. Numbers the server did not answer about appear in neither list:
+  // silence is not a verdict, and reporting a timeout as "not on WhatsApp"
+  // is the one wrong answer available here.
+  syncContacts(
+    phones: string[],
+    opts?: {
+      mode?: 'full' | 'delta' | 'query';
+      context?: string;
+      chunkSize?: number;
+    }
+  ): Promise<ContactSyncResult>;
+
+  // ─── Terms-of-Service notices ────────────────────────────────────────────
+  //
+  // `isTosAccepted` answers `null` for a notice this session has not asked
+  // about, which is not the same as "not accepted".
+  queryTosNotices(noticeIds: string[]): Promise<TosNoticesResult>;
+  acceptTosNotices(noticeIds: string[]): Promise<{ ok: true; raw: any }>;
+  clearTosNotice(noticeId: string): Promise<{ ok: true; raw: any }>;
+  isTosAccepted(noticeId: string): boolean | null;
+
   changePrivacySetting(type: PrivacyType, value: PrivacyValue, excluded?: Jid[]): Promise<PrivacySettings>;
   queryStatusPrivacy(): Promise<StatusPrivacyEntry[]>;
   blockContact(jid: Jid): Promise<Jid[]>;
@@ -933,7 +1012,20 @@ export declare class WhalibmobClient extends EventEmitter {
   getLIDForPN(pn: Jid): Jid | null;
 
   // ─── Lower level ─────────────────────────────────────────────────────────
-  ensureTcTokenBeforeSend(tcJid: Jid, routingToJid: Jid): Promise<any>;
+  /**
+   * Put a trusted-contact token on file *before* the next message is built, so
+   * that message carries a `<tctoken>` like every later one.
+   *
+   * The token comes from the server, not from the contact: nothing here waits
+   * on them replying, on having you in their address book, or on a conversation
+   * existing. Called automatically by every send, so you rarely need it — reach
+   * for it to warm a token ahead of time, before a burst of first messages.
+   *
+   * Returns whether a usable token is on file now. `false` is not a failure to
+   * act on: the send goes ahead without one and the issuance continues in the
+   * background for the next message.
+   */
+  ensureTcTokenBeforeSend(tcJid: Jid, routingToJid: Jid): Promise<boolean>;
   sendPeerDataOperationMessage(pdo: any): Promise<any>;
   requestPlaceholderResend(messageKey: any, msgData?: any): Promise<any>;
   fetchMessageHistory(count: number, oldestMsgKey: any, oldestMsgTimestampMs: number): Promise<any>;

package/lib/Client.js

@@ -508,6 +508,18 @@ class WhalibmobClient extends EventEmitter {
     // Cached privacy settings. Warmed after connect and refreshed whenever the
     // server reports a change; markRead reads it.
     this._privacySettings = null;
+    // The account's AB props, and the hash that turns the next sync into a
+    // delta. Both live for the session: a fresh process asks for the full set,
+    // which is what a fresh install does.
+    this._abProps     = null;
+    this._abPropsHash = null;
+    // Whether to sync AB props on connect. On by default because the app does
+    // it on every login and a client that never does is running on guessed
+    // defaults, but it is one IQ a caller may not want on a short session.
+    this._syncAbPropsOnConnect = opts.syncAbPropsOnConnect !== false;
+    // noticeId → accepted. Absent means this session has not asked, which
+    // isTosAccepted reports as null rather than as "not accepted".
+    this._tosAccepted = new Map();
     if (opts.pino !== undefined) _whaConfigLogger(opts.pino);
   }
 
@@ -1702,6 +1714,16 @@ class WhalibmobClient extends EventEmitter {
     this.queryPrivacySettings({ force: true }).catch(err =>
       _whaDbg('[DBG] PRIVACY_FETCH_FAILED ' + (err && err.message)));
 
+    // Sync the account's AB props, as the app does on every login. On a
+    // reconnect the stored hash makes this a delta rather than the whole
+    // table. A failure is logged and nothing else: every reader of these has a
+    // default to fall back on, so a client that could not fetch them still
+    // works — it just works on the defaults.
+    if (this._syncAbPropsOnConnect) {
+      this.queryAbProps({ force: true }).catch(err =>
+        _whaDbg('[DBG] AB_PROPS_FETCH_FAILED ' + (err && err.message)));
+    }
+
     // ── Reconnect: flush stale device cache + background re-usync ─────────────
     // On first connect _hasConnectedOnce is false — nothing extra to do.
     // On every reconnect (network drop / NAT reset / server restart) we flush the
@@ -3821,6 +3843,11 @@ class WhalibmobClient extends EventEmitter {
       // so a change made on the phone never reached the cache.
       const privacyNode = findChildDeep(node, 'privacy');
       if (privacyNode) this._handlePrivacySettingsNotification(privacyNode);
+      // ...and Terms-of-Service acceptances. Accepting a notice on the phone
+      // arrives here, and it is the only way this side learns about it without
+      // asking.
+      const tosNode = findChildDeep(node, 'tos');
+      if (tosNode) this._handleTosNotification(tosNode);
     }
 
     if (type === 'w:gp2') {
@@ -6527,6 +6554,467 @@ class WhalibmobClient extends EventEmitter {
     return this._sender.deleteMessage(origMsgId, chatJid, fromMe, forEveryone, opts);
   }
 
+  // ─── AB props — the server's own feature flags ────────────────────────────
+  //
+  // Every WhatsApp client asks the server which experiments and configuration
+  // values apply to this account and then gates behaviour on the answer: how
+  // many bytes an identity hash is truncated to, whether the LID migration has
+  // started here, what sampling weight each telemetry event carries. A client
+  // that never asks runs on guessed defaults wherever the server has an
+  // opinion — and never asking is itself unlike the app, which asks on every
+  // login.
+  //
+  //   <iq xmlns="abt" to="s.whatsapp.net" type="get">
+  //     <props protocol="1" [hash="..."] [refresh_id="..."]/>
+  //   </iq>
+  //
+  // The reply carries a hash of the set it returned. Sending that hash back on
+  // the next request asks for a delta rather than the whole table, which is
+  // what the app does once it has synced. The hash is kept for the session
+  // only — a fresh process asks for the full set, exactly as a fresh install
+  // does — so nothing here has to be persisted or migrated.
+  //
+  // Values come back as strings because that is what the wire carries. Typing
+  // them per prop would need a table this side does not have, and guessing
+  // would be wrong more often than it is useful; `abPropInt` and `abPropBool`
+  // are there for the two readings that are worth having.
+
+  /**
+   * Sync this account's AB props.
+   *
+   * Served from the session cache unless `force` is set. A reply the server
+   * marks `delta_update` is merged onto what is already held rather than
+   * replacing it, which is the whole point of sending the hash.
+   *
+   * @param   {object}  [opts]
+   * @param   {boolean} [opts.force]      re-ask even when a set is cached
+   * @param   {string}  [opts.refreshId]  the emergency-push branch. The server
+   *          announces a refresh id when a global update has to propagate at
+   *          once; sending it takes the place of the hash.
+   * @returns {Promise<{hash: string|null, abKey: string|null,
+   *                    refresh: number|null, refreshId: string|null,
+   *                    delta: boolean, props: Object<string,string>,
+   *                    sampling: Object<string,number>}>}
+   */
+  async queryAbProps(opts) {
+    opts = opts || {};
+    if (this._abProps && !opts.force && opts.refreshId == null) return this._abProps;
+
+    const propsAttrs = { protocol: '1' };
+    // One or the other, never both: a refresh id names a specific update to
+    // fetch, and a hash asks for whatever has changed since it. Sending both
+    // asks two different questions in one stanza.
+    if (opts.refreshId != null) propsAttrs.refresh_id = String(opts.refreshId);
+    else if (this._abPropsHash)  propsAttrs.hash       = this._abPropsHash;
+
+    const resp = await this._sendIq(new BinaryNode('iq', {
+      id:    this._genMsgId(),
+      to:    's.whatsapp.net',
+      type:  'get',
+      xmlns: 'abt'
+    }, [new BinaryNode('props', propsAttrs, null)]));
+
+    if (!resp) throw new Error('queryAbProps: 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('queryAbProps: server rejected the request' +
+        (code ? ' (' + code + ')' : ''));
+    }
+
+    const parsed = this._parseAbProps(findChild(resp, 'props'));
+
+    // A delta names only what moved. Replacing the cache with it would drop
+    // every prop the server saw no reason to repeat.
+    if (parsed.delta && this._abProps) {
+      parsed.props    = Object.assign({}, this._abProps.props,    parsed.props);
+      parsed.sampling = Object.assign({}, this._abProps.sampling, parsed.sampling);
+    }
+
+    if (parsed.hash) this._abPropsHash = parsed.hash;
+    this._abProps = parsed;
+    _whaDbg('[DBG] AB_PROPS ' + (parsed.delta ? 'delta' : 'full') +
+      ' props=' + Object.keys(parsed.props).length +
+      ' sampling=' + Object.keys(parsed.sampling).length +
+      (parsed.hash ? ' hash=' + parsed.hash : ''));
+    return parsed;
+  }
+
+  // <props hash ab_key refresh refresh_id delta_update>
+  //   <prop config_code="..." config_value="..."/>     an experiment value
+  //   <prop event_code="..."  sampling_weight="..."/>  a telemetry weight
+  // </props>
+  //
+  // The two shapes share a tag and are told apart by which attributes they
+  // carry, so each child is tried as an experiment first and as a sampling
+  // entry second. A child that is neither is skipped rather than allowed to
+  // fail the whole sync — an unknown shape is a prop this version has not
+  // learned about, not a broken reply.
+  _parseAbProps(propsNode) {
+    const out = {
+      hash:      null,
+      abKey:     null,
+      refresh:   null,
+      refreshId: null,
+      delta:     false,
+      props:     {},
+      sampling:  {}
+    };
+    if (!propsNode || !propsNode.attrs) return out;
+
+    const a = propsNode.attrs;
+    out.hash      = a.hash       ? String(a.hash)       : null;
+    out.abKey     = a.ab_key     ? String(a.ab_key)     : null;
+    out.refreshId = a.refresh_id ? String(a.refresh_id) : null;
+
+    const refresh = Number(a.refresh);
+    if (Number.isFinite(refresh) && refresh > 0) out.refresh = refresh;
+
+    // The server writes this as a string, and "false" is a true string.
+    out.delta = a.delta_update === 'true' || a.delta_update === true || a.delta_update === '1';
+
+    const children = Array.isArray(propsNode.content) ? propsNode.content : [];
+    for (const child of children) {
+      if (!child || child.description !== 'prop' || !child.attrs) continue;
+      const c = child.attrs;
+
+      if (c.config_code != null && c.config_value != null) {
+        out.props[String(c.config_code)] = String(c.config_value);
+        continue;
+      }
+
+      if (c.event_code != null && c.sampling_weight != null) {
+        const code   = Number(c.event_code);
+        const weight = Number(c.sampling_weight);
+        // Bounds the app itself applies. A code below 1 names no event, and a
+        // weight outside the range is not a weight — both mean this entry was
+        // misread rather than that the server sent something exotic.
+        if (Number.isFinite(code) && code >= 1 &&
+            Number.isFinite(weight) && weight >= 0 && weight <= 1000000) {
+          out.sampling[String(code)] = weight;
+        }
+      }
+    }
+    return out;
+  }
+
+  /**
+   * One AB prop as a string, or `fallback` when the server has not set it.
+   *
+   * Props are addressed by their numeric code, which is what the wire uses.
+   * Reading one before `queryAbProps` has run returns the fallback rather than
+   * throwing: a caller gating on a flag wants the default, not an exception.
+   *
+   * @param   {number|string} code
+   * @param   {string|null}   [fallback=null]
+   * @returns {string|null}
+   */
+  abProp(code, fallback) {
+    const value = this._abProps && this._abProps.props[String(code)];
+    return value === undefined || value === null ? (fallback === undefined ? null : fallback) : value;
+  }
+
+  /** The same, read as an integer. Anything unparseable gives the fallback. */
+  abPropInt(code, fallback) {
+    const raw = this.abProp(code, null);
+    const n   = Number(raw);
+    return raw === null || !Number.isFinite(n) ? (fallback === undefined ? null : fallback) : n;
+  }
+
+  /**
+   * The same, read as a flag.
+   *
+   * The wire spells these as "1"/"0" and as "true"/"false" depending on the
+   * prop, so both are understood; anything else gives the fallback rather than
+   * being coerced, since a prop carrying a version string is not a flag.
+   */
+  abPropBool(code, fallback) {
+    const raw = this.abProp(code, null);
+    if (raw === '1' || raw === 'true')  return true;
+    if (raw === '0' || raw === 'false') return false;
+    return fallback === undefined ? null : fallback;
+  }
+
+  // ─── Contact sync — telling the server which numbers are in the book ──────
+  //
+  // The app uploads its address book on first launch and re-syncs deltas
+  // afterwards, which is how it learns who is reachable and how the server
+  // learns who this account knows. whalibmob has had the whole usync machinery
+  // for device discovery all along and never used it for this, so an account
+  // could send to a hundred strangers having never synced a single contact —
+  // a shape nothing on a phone produces.
+  //
+  // This is the same <iq xmlns="usync"> the device path builds, with the
+  // contact protocol on its own and the mode and context that name an address
+  // book upload rather than a lookup.
+
+  /**
+   * Sync contacts, and learn which of them are on WhatsApp.
+   *
+   * @param   {string[]} phones  E.164 numbers. A leading `+` is added when
+   *          missing, since that is the only form the contact protocol takes.
+   * @param   {object}   [opts]
+   * @param   {'full'|'delta'|'query'} [opts.mode]  `full` — the whole book, what
+   *          the app sends on first launch; `delta` — what changed since;
+   *          `query` — a lookup that claims nothing about the book. Defaults to
+   *          `full`.
+   * @param   {string}   [opts.context]  defaults to `registration` for a full
+   *          sync (the app's own first-launch context) and `interactive`
+   *          otherwise.
+   * @param   {number}   [opts.chunkSize=500]  numbers per IQ.
+   * @returns {Promise<{registered: string[], unregistered: string[],
+   *                    jids: Object<string,string>}>}
+   *          `registered` and `unregistered` hold the numbers as passed in;
+   *          `jids` maps each registered number to the JID the server gave it.
+   */
+  async syncContacts(phones, opts) {
+    if (!this._connected) throw new Error('Not connected');
+    // _devMgr is torn down on close and rebuilt on init. Saying so beats the
+    // null dereference a caller would otherwise get from a session that is
+    // connected but has been through a teardown.
+    if (!this._devMgr) throw new Error('syncContacts: no device manager — the session is not initialised');
+    if (!Array.isArray(phones)) throw new Error('syncContacts: phones must be an array');
+
+    opts = opts || {};
+    const mode      = opts.mode || 'full';
+    const context   = opts.context || (mode === 'full' ? 'registration' : 'interactive');
+    const chunkSize = Number(opts.chunkSize) > 0 ? Number(opts.chunkSize) : 500;
+
+    const { USyncQuery, USyncUser } = require('./WAUSync');
+
+    // Normalise once, and keep the caller's spelling to answer in. Duplicates
+    // are dropped here rather than sent: the server counts what it is asked
+    // about, and asking twice about one number in one book is not what a
+    // phone does.
+    const wanted = [];
+    const seen   = new Set();
+    for (const raw of phones) {
+      const digits = String(raw || '').replace(/[^\d]/g, '');
+      if (!digits || seen.has(digits)) continue;
+      seen.add(digits);
+      wanted.push({ input: String(raw), digits });
+    }
+
+    const out = { registered: [], unregistered: [], jids: {} };
+    if (wanted.length === 0) return out;
+
+    for (let i = 0; i < wanted.length; i += chunkSize) {
+      const chunk = wanted.slice(i, i + chunkSize);
+
+      const query = new USyncQuery()
+        .withMode(mode)
+        .withContext(context)
+        .withContactProtocol();
+      for (const c of chunk) query.withUser(new USyncUser().withPhone('+' + c.digits));
+
+      const parsed = await this._devMgr.executeUSyncQuery(query);
+
+      // A chunk the server did not answer leaves its numbers unclassified
+      // rather than marked absent. Reporting "not on WhatsApp" for a timeout
+      // is the one wrong answer here — a caller acts on it.
+      if (!parsed || !Array.isArray(parsed.list)) {
+        _whaDbg('[DBG] CONTACT_SYNC chunk ' + (i / chunkSize) + ' unanswered — ' +
+          chunk.length + ' numbers left unclassified');
+        continue;
+      }
+
+      // The reply is keyed by JID, so match each entry back to the number it
+      // came from by the JID's user part.
+      const byUser = new Map();
+      for (const entry of parsed.list) {
+        if (!entry || !entry.id) continue;
+        const user = String(entry.id).split('@')[0].split(':')[0];
+        byUser.set(user, entry);
+      }
+
+      for (const c of chunk) {
+        const entry = byUser.get(c.digits);
+        if (!entry) continue;                    // unclassified, as above
+        if (entry.contact === true) {
+          out.registered.push(c.input);
+          out.jids[c.input] = String(entry.id);
+        } else {
+          out.unregistered.push(c.input);
+        }
+      }
+    }
+
+    _whaDbg('[DBG] CONTACT_SYNC mode=' + mode + ' context=' + context +
+      ' asked=' + wanted.length + ' on=' + out.registered.length +
+      ' off=' + out.unregistered.length);
+    return out;
+  }
+
+  // ─── Terms-of-Service notices ─────────────────────────────────────────────
+  //
+  // WhatsApp gates some surfaces on the account having accepted a given legal
+  // notice — a Terms update, a privacy-policy change, a regional disclosure.
+  // The app pulls the acceptance state, shows the ones that are outstanding,
+  // and posts back what the user accepted.
+  //
+  //   read    <iq xmlns="tos" type="get"><request><notice id="..."/></request></iq>
+  //   accept  <iq xmlns="tos" type="set"><request type="session_update">
+  //             <notice id="..."/></request></iq>
+  //   clear   <iq xmlns="tos" type="set"><delete id="..."/></iq>
+  //
+  // The reply's `state` attribute reads backwards from how it looks: it is
+  // present and "false" for a notice that has NOT been accepted, and absent
+  // for one that has. Treating a missing attribute as "unknown" would report
+  // every accepted notice as outstanding.
+
+  /**
+   * Read the acceptance state of one or more notices.
+   *
+   * @param   {string[]} noticeIds
+   * @returns {Promise<{refresh: number|null,
+   *                    notices: Array<{id: string, accepted: boolean}>}>}
+   *          `refresh` is how many seconds the server suggests waiting before
+   *          asking again.
+   */
+  async queryTosNotices(noticeIds) {
+    if (!this._connected) throw new Error('Not connected');
+    if (!Array.isArray(noticeIds)) throw new Error('queryTosNotices: noticeIds must be an array');
+
+    const ids = noticeIds.map(id => String(id)).filter(Boolean);
+    const resp = await this._sendIq(new BinaryNode('iq', {
+      id:    this._genMsgId(),
+      to:    's.whatsapp.net',
+      type:  'get',
+      xmlns: 'tos'
+    }, [new BinaryNode('request', {},
+      ids.map(id => new BinaryNode('notice', { id }, null)))]));
+
+    if (!resp) throw new Error('queryTosNotices: 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('queryTosNotices: server rejected the request' +
+        (code ? ' (' + code + ')' : ''));
+    }
+
+    const parsed = this._parseTosNotices(findChild(resp, 'tos'));
+    for (const n of parsed.notices) this._tosAccepted.set(n.id, n.accepted);
+    _whaDbg('[DBG] TOS_QUERY asked=' + ids.length + ' answered=' + parsed.notices.length +
+      ' outstanding=' + parsed.notices.filter(n => !n.accepted).length);
+    return parsed;
+  }
+
+  // <tos refresh="86400"><notice id="..." [state="false"]/>...</tos>
+  _parseTosNotices(tosNode) {
+    const out = { refresh: null, notices: [] };
+    if (!tosNode) return out;
+
+    const refresh = Number(tosNode.attrs && tosNode.attrs.refresh);
+    if (Number.isFinite(refresh) && refresh > 0) out.refresh = refresh;
+
+    const children = Array.isArray(tosNode.content) ? tosNode.content : [];
+    for (const child of children) {
+      if (!child || child.description !== 'notice' || !child.attrs || !child.attrs.id) continue;
+      const state = child.attrs.state;
+      // Only an explicit "false" means not accepted; see the note above.
+      out.notices.push({
+        id:       String(child.attrs.id),
+        accepted: !(state === 'false' || state === false)
+      });
+    }
+    return out;
+  }
+
+  /**
+   * Accept one or more notices.
+   *
+   * @param   {string[]} noticeIds
+   * @returns {Promise<{ok: true, raw: any}>}
+   */
+  async acceptTosNotices(noticeIds) {
+    if (!this._connected) throw new Error('Not connected');
+    if (!Array.isArray(noticeIds) || noticeIds.length === 0) {
+      throw new Error('acceptTosNotices: noticeIds must be a non-empty array');
+    }
+
+    const ids = noticeIds.map(id => String(id)).filter(Boolean);
+    const resp = await this._sendIq(new BinaryNode('iq', {
+      id:    this._genMsgId(),
+      to:    's.whatsapp.net',
+      type:  'set',
+      xmlns: 'tos'
+    }, [new BinaryNode('request', { type: 'session_update' },
+      ids.map(id => new BinaryNode('notice', { id }, null)))]));
+
+    if (!resp) throw new Error('acceptTosNotices: 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('acceptTosNotices: server rejected the request' +
+        (code ? ' (' + code + ')' : ''));
+    }
+
+    for (const id of ids) this._tosAccepted.set(id, true);
+    _whaDbg('[DBG] TOS_ACCEPT ' + ids.join(','));
+    return { ok: true, raw: resp };
+  }
+
+  /**
+   * Clear the accepted state of one notice, so the server asks for it again.
+   *
+   * @param   {string} noticeId
+   * @returns {Promise<{ok: true, raw: any}>}
+   */
+  async clearTosNotice(noticeId) {
+    if (!this._connected) throw new Error('Not connected');
+    const id = String(noticeId || '');
+    if (!id) throw new Error('clearTosNotice: noticeId is required');
+
+    const resp = await this._sendIq(new BinaryNode('iq', {
+      id:    this._genMsgId(),
+      to:    's.whatsapp.net',
+      type:  'set',
+      xmlns: 'tos'
+    }, [new BinaryNode('delete', { id }, null)]));
+
+    if (!resp) throw new Error('clearTosNotice: 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('clearTosNotice: server rejected the request' +
+        (code ? ' (' + code + ')' : ''));
+    }
+
+    this._tosAccepted.set(id, false);
+    _whaDbg('[DBG] TOS_CLEAR ' + id);
+    return { ok: true, raw: resp };
+  }
+
+  /**
+   * Whether a notice is known to have been accepted.
+   *
+   * `null` means this session has not asked about it — which is not the same
+   * as "not accepted", and a caller deciding whether to prompt needs to be
+   * able to tell those apart.
+   *
+   * @param   {string} noticeId
+   * @returns {boolean|null}
+   */
+  isTosAccepted(noticeId) {
+    const known = this._tosAccepted.get(String(noticeId));
+    return known === undefined ? null : known;
+  }
+
+  // The server pushing a notice's state at us, rather than us asking:
+  // <notification type="account_sync"><tos><notice id=".." state=".."/></tos>
+  //
+  // This is how an acceptance made on another device reaches this one. It only
+  // ever adds to what is known — a push naming three notices says nothing
+  // about a fourth.
+  _handleTosNotification(tosNode) {
+    const parsed = this._parseTosNotices(tosNode);
+    if (parsed.notices.length === 0) return;
+    for (const n of parsed.notices) this._tosAccepted.set(n.id, n.accepted);
+    _whaDbg('[DBG] TOS_NOTIFICATION ' + parsed.notices
+      .map(n => n.id + '=' + (n.accepted ? 'accepted' : 'outstanding')).join(' '));
+    this.emit('tos_notices', { notices: parsed.notices });
+  }
+
   // ─── Status / Stories ─────────────────────────────────────────────────────
 
   // Who your Status posts go to.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whalibmob",
-  "version": "5.28.0",
+  "version": "5.29.1",
   "description": "Node.js library for WhatsApp — register a number over SMS, or link as a companion by QR. Signal E2E encryption, media, groups, channels.",
   "author": "Kunboruto20",
   "main": "index.js",
@@ -49,7 +49,7 @@
     "messaging",
     "chatbot",
     "automation",
-    "whatsapp-mobile", 
+    "whatsapp-mobile",
     "media",
     "groups",
     "channels"