whalibmob 5.29.1 → 5.29.3

package/README.md

@@ -2473,6 +2473,7 @@ Run it once, type the code into the phone, and it is linked. Run it again and it
 | `client.connectWeb(phone, opts?)` | Open the companion connection. Resolves as soon as the encrypted channel is up when unlinked, or after `<success>` when already linked. |
 | `client.requestPairingCode(phone?, customCode?)` | Ask for an 8-character code. Returns it immediately; the link completes later. Throws if the session is already linked. |
 | `client.disconnect()` | Close the connection. The link survives — reconnect with `connectWeb()`. |
+| `client.logout()` | Unlink this device from the account, the way the Linked Devices screen does, then disconnect. The link does **not** survive — the next `connectWeb()` pairs afresh. Nothing on disk is deleted; remove the session directory yourself if you want the keys gone. |
 
 `connectWeb(phone, opts)` options:
 
@@ -3284,7 +3285,7 @@ connect()
 | `presence` | `{ from, available }` | Contact came online or went offline |
 | `group_update` | `{ type, groupJid, actor, participants, subject, timestamp }` | Member added / removed / promoted / demoted, subject or settings changed |
 | `notification` | node object | Group or contact update notification |
-| `call` | `{ from }` | Incoming call event |
+| `call` | `{ from, id, status, tag, creator, creatorAlt, groupJid, platform, version, reason, ts, node }` | A call stanza. `id` is what `rejectCall()` needs, `creator` is who placed the call (it differs from `from` in a group), and `status` is the stage: `offer`, `offer_notice`, `ringing`, `accept`, `preaccept`, `transport`, `terminate`, `reject` or `unknown` |
 | `chat_read` | `{ jid, read, remote?, synced? }` | Chat marked read (`read: true`) or unread (`read: false`) |
 | `chat_muted` | `{ jid, muted, until, remote?, synced? }` | Chat muted or unmuted; `until` is epoch ms (−1 = indefinite) |
 | `chat_pinned` | `{ jid, pinned, remote?, synced? }` | Chat pinned or unpinned |
@@ -3322,9 +3323,21 @@ The message object contains:
   ts:          number,   // Unix timestamp (seconds)
   node:        object,   // raw XML node — node.attrs.sender_pn holds the real phone JID
   decoded:     object,   // structured payload — shape depends on message type (see below)
+  fromMe:      boolean,  // you sent this from another of your own devices
+  chat:        string,   // the conversation — equals from unless fromMe is true
 }
 ```
 
+> [!NOTE]
+> When you send a message from your phone, WhatsApp echoes a copy of it to every
+> other device on the account, wrapped in a `DeviceSentMessage`. On that copy
+> `from` is **your own JID** — it names the sender, not the chat. Use `chat`,
+> which is the conversation whichever direction the message went, and `fromMe`
+> to tell the two apart. The envelope's own fields are on
+> `decoded.deviceSentMeta` (`destinationJid`, `phash`) if you need them raw.
+> These messages are not answered with a read receipt: nothing was read by
+> receiving your own message back.
+
 > [!NOTE]
 > WhatsApp Multi-Device uses **LID JIDs** internally. The `from` field may be a LID like
 > `112345678901234@s.whatsapp.net` rather than the real phone number. To get the actual
@@ -3766,13 +3779,36 @@ The whole message object is accepted as well as its `decoded` half, so
 
 **Verifying the file**
 
-Pass `{ verify: true }` to check the download against the message's
-`fileEncSha256` before decrypting it. The MAC already proves the plaintext was
-not tampered with; this catches a truncated or substituted download earlier, and
-names that failure separately from a decryption one.
+Three things are checked, and all three by default — the message says what the
+file should be, so there is no reason to take the CDN's word for it:
+
+| check | what it covers |
+|---|---|
+| `fileEncSha256` | the blob as it arrived, before any work is spent decrypting it |
+| the MAC | the ciphertext, under a key derived from `mediaKey` — this is the one that authenticates |
+| `fileSha256` | the decrypted file |
 
 ```js
-const bytes = await client.downloadMedia(d, { verify: true })
+const bytes = await client.downloadMedia(d)                    // all three
+const raw   = await client.downloadMedia(d, { verify: false }) // MAC only
+```
+
+`verify: false` skips the two digests for a caller that wants the bytes whatever
+they are. The MAC is checked either way and is never optional.
+
+**Link preview thumbnails**
+
+A text message that quoted a link carries the preview the sender's client built.
+The small inline image is already on the message as `jpegThumbnail` and needs no
+download. The full-size one is a media file of its own — its own `directPath`,
+its own `mediaKey`, encrypted under a key name of its own — so `downloadMedia`
+cannot reach it:
+
+```js
+if (d.thumbnail) {
+  const preview = await client.downloadThumbnail(d)
+  // d.title, d.description and d.matchedText are the rest of the preview
+}
 ```
 
 **What happens underneath**
@@ -3979,10 +4015,36 @@ const { id, encKey } = await client.sendPoll(
   ['JavaScript', 'Python', 'Rust'],
   1            // voters may pick 1 option (0 = unlimited)
 )
-// encKey (32-byte Buffer) is needed to decrypt incoming poll votes
+// encKey (32-byte Buffer) is what reads the votes — keep it
 // (also returned as `messageSecret`, which is the name the protocol uses)
 ```
 
+**Reading the votes**
+
+A vote arrives as its own message and the ballot inside it is encrypted, so
+nothing about who chose what is visible in the stanza. `decryptPollVote()` opens
+it with the poll's `encKey`:
+
+```js
+const options = ['JavaScript', 'Python', 'Rust']
+
+client.on('message', (msg) => {
+  if (msg.decoded?.type !== 'pollVote') return
+  if (msg.decoded.pollKey.id !== id) return      // a vote on some other poll
+
+  const { selected, votedAt } = client.decryptPollVote(msg, { encKey, options })
+  console.log(msg.participant, 'voted for', selected)   // [ 'Rust' ]
+})
+```
+
+Pass `options` and the choices come back as text. Without them you get
+`selectedHashes` — the SHA-256 of each chosen option, which is how the ballot
+names them on the wire — and match them yourself.
+
+The key is derived from the poll id, the poll's sender and the voter, so a vote
+on someone else's poll needs their `encKey`, which only arrives if they sent the
+poll to you: read it off `msg.decoded.encKey` on the poll message itself.
+
 ### Quoted Reply
 
 Send a text message that quotes (replies to) a specific earlier message. The recipient sees the original message highlighted above your reply.

package/index.d.ts

@@ -271,9 +271,56 @@ export interface DecodedBase {
   ephemeral?: boolean;
   /** The message is the new text of an edit. */
   edited?: boolean;
+  /**
+   * On a text message that quoted a link, the downloadable preview image.
+   * Fetch it with `downloadThumbnail()`.
+   */
+  thumbnail?: LinkThumbnail;
+  /**
+   * Present only on a message this account sent from one of its other devices.
+   * The stanza names us as the sender, so the chat it belongs to is written
+   * here and nowhere else.
+   */
+  deviceSentMeta?: DeviceSentMeta;
   [key: string]: any;
 }
 
+/** The downloadable preview image on a message that quoted a link. */
+export interface LinkThumbnail {
+  directPath: string;
+  mediaKey: Buffer;
+  thumbnailSha256: Buffer | null;
+  thumbnailEncSha256: Buffer | null;
+}
+
+export interface PollVoteOptions {
+  /** The poll's 32-byte message secret — what `sendPoll` returned. */
+  encKey: Buffer;
+  /** Who cast the vote. Defaults to the message's `participant`, then `from`. */
+  voter?: Jid;
+  /** Who sent the poll. Defaults to what the vote's message key names. */
+  pollSender?: Jid;
+  /** The poll's options, so the choices come back as text rather than hashes. */
+  options?: string[];
+}
+
+export interface PollVoteResult {
+  /** The chosen options as text. Empty unless `options` was passed. */
+  selected: string[];
+  /** SHA-256 of each chosen option, always present. */
+  selectedHashes: Buffer[];
+  /** When the vote was cast, in ms, when the sender said. */
+  votedAt: number | null;
+}
+
+/** What a `DeviceSentMessage` envelope said about the message inside it. */
+export interface DeviceSentMeta {
+  /** The chat the message was originally addressed to. */
+  destinationJid?: Jid;
+  /** Hash of the participant list the sending device used, when it set one. */
+  phash?: string;
+}
+
 export interface DecodedText extends DecodedBase {
   type: 'text';
   text: string;
@@ -335,6 +382,39 @@ export type DecodedMessage =
   | DecodedProtocol
   | DecodedBase;
 
+/** The stage a call is at, from the child tag inside the `<call>` stanza. */
+export type CallStatus =
+  | 'offer' | 'offer_notice' | 'ringing' | 'accept'
+  | 'preaccept' | 'transport' | 'terminate' | 'reject' | 'unknown';
+
+/** The payload of the `call` event. */
+export interface CallEvent {
+  /** Who the stanza came from. Equals `creator` on a one-to-one call. */
+  from: Jid;
+  /** The call id — what `rejectCall` needs. `null` on a stanza that names none. */
+  id: string | null;
+  /** `'ringing'` is the `relaylatency` stanza, under the name it has always had. */
+  status: CallStatus;
+  /** The child tag verbatim, so a stage not in `CallStatus` is still readable. */
+  tag: string;
+  /** The account that placed the call. Differs from `from` in a group. */
+  creator: Jid;
+  /** The creator's other name — phone JID for a LID creator, and the reverse. */
+  creatorAlt: Jid | null;
+  /** The group the call is in, when it is a group call. */
+  groupJid: Jid | null;
+  /** The caller's platform, on the stanzas that carry it. */
+  platform: string | null;
+  /** The caller's client version, on the stanzas that carry it. */
+  version: string | null;
+  /** Why the call ended, on a `terminate`. */
+  reason: string | null;
+  /** Unix timestamp, seconds. */
+  ts: number;
+  /** Raw binary node. */
+  node: any;
+}
+
 /**
  * The payload of the `message` event.
  *
@@ -361,6 +441,17 @@ export interface IncomingMessage {
   text?: string | null;
   /** `true` on a group message. */
   isGroup?: boolean;
+  /**
+   * `true` when this account sent the message from another of its devices and
+   * the server echoed it back here.
+   */
+  fromMe?: boolean;
+  /**
+   * The conversation the message belongs to, whichever direction it went. Same
+   * as `from` for anything we received; for one of our own messages it is who
+   * we sent it to, which `from` cannot say.
+   */
+  chat?: Jid;
 }
 
 // ────────────────────────────────────────────────────────────────────────────
@@ -695,7 +786,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; id: string | null; status: 'offer' | 'ringing' | 'terminate' | 'unknown'; node: any }) => void;
+  call: (c: CallEvent) => void;
   notification: (node: any) => void;
   decrypt_error: (e: { id: string; from: Jid; participant?: Jid; err: Error }) => void;
   session_refresh: (e: { node: any }) => void;
@@ -798,6 +889,15 @@ export declare class WhalibmobClient extends EventEmitter {
   /** Ask for an 8-character pairing code. Throws if the session is already linked. */
   requestPairingCode(phoneNumber?: string, customCode?: string): Promise<string>;
   disconnect(opts?: DisconnectOptions): void;
+  /**
+   * Unlink this device from the account, the way the Linked Devices screen on
+   * the phone does, then close the connection.
+   *
+   * Web only. Nothing on disk is deleted — the session it describes no longer
+   * exists, so the next `connectWeb()` pairs afresh. Resolves to whether the
+   * server accepted the removal; the connection drops either way.
+   */
+  logout(): Promise<boolean>;
 
   /** Ask the server whether this session still logs in, and under which number. */
   checkSessionAlive(): Promise<SessionAliveProbe>;
@@ -824,8 +924,30 @@ export declare class WhalibmobClient extends EventEmitter {
   createCallLink(type?: 'audio' | 'video', opts?: { startTime?: number }): Promise<CallLink>;
 
   // ─── Receiving ───────────────────────────────────────────────────────────
-  /** Download and decrypt a media message. Accepts `msg` or `msg.decoded`. */
+  /**
+   * Download and decrypt a media message. Accepts `msg` or `msg.decoded`.
+   *
+   * Both digests the message carried are checked by default, on top of the MAC
+   * that always is. `verify: false` skips the digests only.
+   */
   downloadMedia(decoded: DecodedMessage | IncomingMessage, opts?: { verify?: boolean }): Promise<Buffer>;
+  /**
+   * Download the full-size preview image of a message that quoted a link.
+   *
+   * A link preview's thumbnail is a media file of its own, encrypted under its
+   * own key name, so `downloadMedia` cannot reach it. The small inline preview
+   * needs no download — it is already on the message as `jpegThumbnail`.
+   */
+  downloadThumbnail(decoded: DecodedMessage | IncomingMessage, opts?: { verify?: boolean }): Promise<Buffer>;
+  /**
+   * Read a vote on a poll.
+   *
+   * The ballot is encrypted under a key derived from the poll's message secret:
+   * the `encKey` `sendPoll` returned, or `decoded.encKey` on a poll somebody
+   * else sent. Pass the poll's `options` to get the choices back as text —
+   * without them only the SHA-256 of each choice is available.
+   */
+  decryptPollVote(vote: DecodedMessage | IncomingMessage, opts: PollVoteOptions): PollVoteResult;
   /** Ask the sender's phone to re-upload a file the CDN no longer has. */
   requestMediaRetry(info: { id: string; chatJid: Jid; fromMe: boolean; participant?: Jid }, mediaKey: Buffer): Promise<void>;
   decryptMediaRetry(notification: MediaRetryNotification, mediaKey: Buffer): MediaRetryResult;
@@ -922,6 +1044,15 @@ export declare class WhalibmobClient extends EventEmitter {
 
   /** Pull pins/archives/mutes/stars/contact names changed elsewhere. */
   syncAppState(names?: string[] | null, opts?: { snapshot?: boolean }): Promise<AppStateSyncResult>;
+  /**
+   * Acknowledge a dirty bit so the server stops announcing it.
+   *
+   * Done for you on every `<ib><dirty>` the server sends; this is here for a
+   * bit you want to clear yourself. Pass the `timestamp` the announcement
+   * carried — without it nothing in particular is acknowledged and the server
+   * re-announces on the next connection.
+   */
+  markNotDirty(type: string, timestamp?: number | string): boolean;
   /** Whether an app-state key is available — `false` on an SMS session with no companion. */
   canSyncAppState(): boolean;
   /**
@@ -936,7 +1067,7 @@ export declare class WhalibmobClient extends EventEmitter {
 
   /**
    * Refuse one incoming call. Only reachable when the client was built with
-   * `autoRejectCalls: false`; the id and caller come off the `call` event.
+   * `autoRejectCalls: false`; pass the `id` and `creator` off the `call` event.
    */
   rejectCall(callId: string, from: Jid): boolean;