whalibmob 5.26.1 → 5.29.0

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

@@ -123,6 +123,23 @@ export interface WhalibmobClientOptions {
   autoFixNumber?: boolean;
   /** Send read receipts for incoming messages. Default `true`. */
   autoRead?: boolean;
+  /**
+   * Refuse every incoming call. Default `true`.
+   *
+   * Turning it off does not answer calls — nothing here can — it leaves the
+   * refusal to you, which is the only way to let some calls ring and reject the
+   * 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. */
@@ -227,8 +244,24 @@ export interface PollSendResult extends SendResult {
   messageSecret: Buffer;
 }
 
+/** What a message was a reply to, and who it mentioned. */
+export interface DecodedContextInfo {
+  /** Id of the quoted message. */
+  stanzaId?: string;
+  /** Who wrote the quoted message. */
+  participant?: Jid;
+  remoteJid?: Jid;
+  mentionedJid?: Jid[];
+  /** The quoted message, decoded the same way as any other. */
+  quotedMessage?: DecodedMessage;
+  /** The quoted message's raw protobuf bytes, for re-encoding it verbatim. */
+  quotedMessageRaw?: Buffer;
+}
+
 export interface DecodedBase {
   type: string;
+  /** Present when the message quoted another or carried mentions. */
+  contextInfo?: DecodedContextInfo;
   /**
    * The message arrived inside a view-once envelope. The content is decoded
    * normally — media included — this only records how it was sent.
@@ -454,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;
@@ -632,7 +695,7 @@ export interface WhalibmobEvents {
   message: (msg: IncomingMessage) => void;
   receipt: (r: { type: string; id: string; from: Jid }) => void;
   presence: (p: { from: Jid; available: boolean }) => void;
-  call: (c: { from: Jid }) => void;
+  call: (c: { from: Jid; id: string | null; status: 'offer' | 'ringing' | 'terminate' | 'unknown'; node: any }) => void;
   notification: (node: any) => void;
   decrypt_error: (e: { id: string; from: Jid; participant?: Jid; err: Error }) => void;
   session_refresh: (e: { node: any }) => void;
@@ -796,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[]>;
@@ -831,6 +934,12 @@ export declare class WhalibmobClient extends EventEmitter {
    */
   requestAppStateKeys(keyIds: string[]): Promise<string | null>;
 
+  /**
+   * Refuse one incoming call. Only reachable when the client was built with
+   * `autoRejectCalls: false`; the id and caller come off the `call` event.
+   */
+  rejectCall(callId: string, from: Jid): boolean;
+
   // ─── Account restriction ─────────────────────────────────────────────────
   fetchReachoutTimelock(): Promise<ReachoutTimelockState>;
   /** The last known state, recomputed; does not ask the server again. */
@@ -903,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>;
@@ -1314,6 +1436,38 @@ export declare const PushClient: LibModule;
 export declare const Fcm: LibModule;
 export declare const FcmMcs: LibModule;
 
+/**
+ * X25519 through Node's own OpenSSL — a drop-in for `curve25519-js`, roughly
+ * 19x faster on `sharedKey` and byte-identical to it.
+ *
+ * `sign` and `verify` are XEdDSA and stay on the JavaScript implementation:
+ * Node's Ed25519 is a different scheme and would produce different bytes.
+ */
+export declare const Curve: LibModule & {
+  generateKeyPair(seed: Buffer | Uint8Array): { private: Buffer; public: Buffer };
+  sharedKey(priv: Buffer | Uint8Array, pub: Buffer | Uint8Array): Buffer;
+  sign(priv: Buffer | Uint8Array, message: Buffer | Uint8Array): Buffer;
+  verify(pub: Buffer | Uint8Array, message: Buffer | Uint8Array, signature: Buffer | Uint8Array): boolean;
+  /** Whether Node's X25519 is in use; `false` means the JavaScript fallback is. */
+  NATIVE: boolean;
+};
+
+/**
+ * HKDF-SHA256 through Node's own OpenSSL — roughly 2.2x faster than the
+ * JavaScript implementation and byte-identical to it. Returns a `Buffer`,
+ * not the `ArrayBuffer` Node's own `hkdfSync` hands back.
+ */
+export declare const Hkdf: LibModule & {
+  hkdfSha256(
+    ikm: Buffer | Uint8Array,
+    salt: Buffer | Uint8Array | string,
+    info: Buffer | Uint8Array | string,
+    length: number
+  ): Buffer;
+  /** Whether Node's HKDF is in use; `false` means the JavaScript fallback is. */
+  NATIVE: boolean;
+};
+
 /** Linking to an account that already exists. */
 export declare const PairingCode: LibModule;
 export declare const CompanionPairing: LibModule;

package/index.js

@@ -129,6 +129,8 @@ const WebVersion       = require('./lib/WebVersion');
 const WebProto         = require('./lib/webproto');
 
 const BinaryNode           = require('./lib/BinaryNode');
+const Curve                = require('./lib/curve');
+const Hkdf                 = require('./lib/hkdf');
 const Noise                = require('./lib/noise');
 const WebSocketStream      = require('./lib/WebSocketStream');
 const Socks                = require('./lib/socks');
@@ -348,6 +350,11 @@ module.exports = {
   FcmMcs,
 
   // Linking to an account that already exists
+  // X25519, through Node's own OpenSSL. Drop-in for curve25519-js.
+  Curve,
+  // HKDF-SHA256, through Node's own OpenSSL.
+  Hkdf,
+
   PairingCode,
   CompanionPairing,
   QrPairing,