whalibmob 5.29.2 → 5.29.4

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:
 
@@ -3778,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)                    // 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
-const bytes = await client.downloadMedia(d, { verify: true })
+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**
@@ -3991,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.
@@ -5457,6 +5507,30 @@ These variables override individual fields on top of the selected profile:
 | `WA_DEVICE_OS_VERSION` | OS version string (e.g. `14`) |
 | `WA_DEVICE_BUILD` | Build fingerprint (e.g. `UP1A.231005.007`) |
 | `WA_DEVICE_MODEL_ID` | Model ID slug (e.g. `samsung-sm-s928b`) |
+| `WA_DEVICE_RAM` | Usable RAM in GiB, as Android reports it (e.g. `7.53`). Each named profile carries its own; set this only for a different memory variant of the same model. |
+
+### Declaring your SIM
+
+Registration sends `sim_mcc` / `sim_mnc` to say which network the SIM belongs
+to. The built-in table can only name **one operator per country** — Romania is
+always Orange, Brazil always Vivo — and it cannot do better, because number
+portability broke the prefix→operator link years ago. Guessing from the number
+would be wrong more often than the table is.
+
+So say which SIM is in the phone:
+
+```js
+const store = createNewStore('40712345678', { simMcc: '226', simMnc: '01' })
+```
+
+| Variable | Description |
+|---|---|
+| `WA_SIM_MCC` | Mobile country code of the SIM (e.g. `226`) |
+| `WA_SIM_MNC` | Mobile network code. **Width matters** — `10` and `010` are different networks to the server, so write it exactly as your operator does. |
+
+Either half can be given on its own; the other keeps the table's value, and the
+country's language and locale are unaffected either way. Leave both unset and
+nothing changes from before.
 
 ### Version & Token Overrides
 
@@ -5641,6 +5715,24 @@ registered, no code is requested, and the session is never written to.
 the problem.** The difference is then in what the CLI reads and this tool does
 not — `WA_VERSION`, from `.env`. Go back to the top of this section.
 
+## Support this project
+
+If whalibmob saves you time, you can support its development.
+
+**USDT — TRC-20 (Tron network only)**
+
+```
+TNxxWvAc5m5YS89uz5uSrbXC9EKPuS27aP
+```
+
+> [!WARNING]
+> This address is **TRC-20 on the Tron network**. Send **only USDT on TRC-20** to
+> it. USDT sent on any other network — ERC-20 (Ethereum), BEP-20 (BSC), Polygon,
+> or anything else — will be **lost and cannot be recovered**. Always double-check
+> the network in your wallet before sending, and copy the address in full.
+
+The **Sponsor** button at the top of the repository leads back here.
+
 ## License
 
 MIT

package/index.d.ts

@@ -271,6 +271,11 @@ 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
@@ -280,6 +285,34 @@ export interface DecodedBase {
   [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. */
@@ -856,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>;
@@ -882,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;
@@ -980,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;
   /**
@@ -1155,7 +1228,17 @@ export declare function fetchWaWebVersion(): Promise<{ version: [number, number,
 // Stores
 // ────────────────────────────────────────────────────────────────────────────
 
-export declare function createNewStore(phoneNumber: string, opts?: { name?: string }): WhalibmobStore;
+export declare function createNewStore(phoneNumber: string, opts?: {
+  name?: string;
+  /**
+   * The MCC of the SIM actually in the phone. Without it the country table's
+   * one-operator-per-country guess stands — number portability means the
+   * number's prefix cannot tell you. Also settable as `WA_SIM_MCC`.
+   */
+  simMcc?: string;
+  /** The matching MNC. Width matters: `10` and `010` are different networks. */
+  simMnc?: string;
+}): WhalibmobStore;
 /** What the CLI uses for every new SMS session; prefer it over `createNewStore`. */
 export declare function initAuthCreds(phoneNumber: string, opts?: { name?: string }): WhalibmobStore;
 export declare function saveStore(store: WhalibmobStore, filePath: string): void;