whalibmob 5.24.0 → 5.24.1

package/README.md

@@ -1664,6 +1664,82 @@ Everything the CLI does is available as a Node.js library. The sections below
 cover connecting an account, sending and receiving every message type, groups,
 communities, channels, presence, privacy, history sync, and device emulation.
 
+### What the package exports
+
+Two layers. The first is the flat one the rest of this document uses — the
+eighty-two names the common paths are built from:
+
+```js
+const { WhalibmobClient, createNewStore, requestSmsCode } = require('whalibmob')
+```
+
+The second is everything else. The library is ninety-five modules and close to
+five hundred exported names, and the flat layer picks out under a fifth of
+them. The rest are reachable as **namespaces**, each one a module of `lib/`
+under a name of its own:
+
+```js
+const wa = require('whalibmob')
+
+wa.MediaService.getMediaKeyName('ptt')        // → 'WhatsApp Audio Keys'
+wa.MessageProto.decodeMessageContainer(buf)   // raw bytes → a decoded message
+wa.Messages.MediaRetry.mediaRetryKey(key)     // the retry-receipt key
+wa.Signal.libsignal.SessionCipher             // the vendored libsignal
+wa.AppState.SyncdProto                        // app-state mutation records
+wa.Image.Jpeg                                 // the JPEG header reader
+```
+
+A namespace is named after the module it comes from, and a directory in `lib/`
+becomes one namespace rather than several — so `Signal` is all of
+`lib/signal/`, `AppState` all of `lib/appstate/`, `Messages` all of
+`lib/messages/`. Two names could not be had: **`Devices`** is
+`lib/DeviceManager.js`, because the flat `DeviceManager` is the class rather
+than the module, and **`Proto`** is `lib/proto.js` while the message protobufs
+in `lib/proto/` are **`MessageProto`**.
+
+Deep requires work as well, and always have — the package declares no `exports`
+map, so nothing is sealed off:
+
+```js
+const MediaService = require('whalibmob/lib/MediaService')
+// the same object, by a longer name
+require('whalibmob').MediaService === MediaService   // true
+```
+
+Adding the namespaces renamed and removed nothing: every name the library
+exported before is still exported, still holding what it held.
+
+> [!NOTE]
+> The namespaces are typed as far as the rest of this document goes — media,
+> the message protobufs, media retry. Past that they are `any`, which is what
+> the internals have always been in `index.d.ts`. They are reachable, not
+> described.
+
+### ES modules
+
+The package is CommonJS, and every one of its names can be imported from an ES
+module — a bot written with `"type": "module"` needs no interop dance:
+
+```js
+import { WhalibmobClient, createNewStore, requestSmsCode } from 'whalibmob'
+import { MediaService, MessageProto } from 'whalibmob'
+
+// the default import is the whole export object, if you prefer it
+import wa from 'whalibmob'
+
+// deep imports work too — ESM wants the extension, CommonJS does not
+import { downloadMedia } from 'whalibmob/lib/MediaService.js'
+```
+
+> [!NOTE]
+> `import { … }` used to fail for all but five names. Node reads a CommonJS
+> module's names statically, and the reader gives up at the first property of
+> `module.exports` whose value is not a plain identifier — an inline arrow
+> function five entries in cost the other 116. `require()` and the default
+> import were unaffected, which is why it went unnoticed. Everything is now
+> bound to a name before it is exported, and a test fails if that stops being
+> true.
+
 ## Connecting Account
 
 ### Register a New Number
@@ -3700,6 +3776,55 @@ const bytes = await client.downloadMedia(d, { verify: true })
 with no media, no CDN location, an unsupported type, or a file that does not
 match the message all say so.
 
+### View-once and disappearing messages
+
+Some messages arrive inside an envelope. A photo sent as **view-once** is an
+ordinary `ImageMessage` wrapped in a `ViewOnceMessage`; the same photo in a
+chat with **disappearing messages** turned on is one wrapped in an
+`EphemeralMessage`. Nothing about the photo changes — the envelope only records
+how it was sent.
+
+The decoder opens them, so nothing special is needed on your side. `msg.decoded`
+is the photo, and `downloadMedia()` works on it exactly as it does on any other:
+
+```js
+client.on('message', async (msg) => {
+  const d = msg.decoded
+  if (!d || !d.mediaKey) return
+
+  if (d.viewOnce)  console.log('sent as view-once')
+  if (d.ephemeral) console.log('from a disappearing chat')
+
+  const bytes = await client.downloadMedia(d)   // same call, wrapped or not
+})
+```
+
+Three flags say how the message was sent, and are absent otherwise:
+
+| flag | meaning |
+|---|---|
+| `d.viewOnce` | sent as view-once — `ViewOnceMessage`, `ViewOnceMessageV2` or the V2 extension a voice note uses |
+| `d.ephemeral` | from a chat with disappearing messages on |
+| `d.edited` | the new text of an edited message — the payload is the `protocol` message carrying it |
+
+They stack. A view-once photo in a disappearing chat carries both:
+
+```js
+if (d.viewOnce && d.ephemeral) { /* … */ }
+```
+
+Documents sent with a caption (`DocumentWithCaptionMessage`) are unwrapped the
+same way and decode as a plain `document`, with no flag of their own.
+
+> [!NOTE]
+> Opening the envelope is what makes this media reachable at all. Before it, a
+> view-once photo decoded as `{ type: 'unknown' }` — no `mediaKey`, no
+> `directPath` — and there was nothing for `downloadMedia()` to fetch.
+
+Nothing here changes when the message came through history sync, or when it is
+one of your own echoed back to this device from another: those envelopes nest,
+and are unwrapped down to the message inside.
+
 ### When the file is gone from the CDN
 
 Media is not carried inside the message — the message carries a URL, a hash and

package/index.d.ts

@@ -229,6 +229,15 @@ export interface PollSendResult extends SendResult {
 
 export interface DecodedBase {
   type: string;
+  /**
+   * The message arrived inside a view-once envelope. The content is decoded
+   * normally — media included — this only records how it was sent.
+   */
+  viewOnce?: boolean;
+  /** The message belongs to a chat with disappearing messages turned on. */
+  ephemeral?: boolean;
+  /** The message is the new text of an edit. */
+  edited?: boolean;
   [key: string]: any;
 }
 
@@ -586,9 +595,22 @@ export interface MediaRetryNotification {
 }
 
 export interface MediaRetryResult {
+  /** `true` only when the phone actually re-uploaded the file. */
   ok: boolean;
-  directPath?: string;
-  url?: string;
+  /**
+   * `MediaRetryNotification.result` — `1` is SUCCESS. `null` when the phone
+   * answered with an error rather than a payload.
+   */
+  result: number | null;
+  /**
+   * Where the file was put back. **`null`, not absent**, whenever `ok` is
+   * false — check it against `null`, or just read `ok`.
+   */
+  directPath: string | null;
+  /** The message the retry was for. Absent when the phone answered an error. */
+  stanzaId?: string;
+  /** Set instead of a location when the phone no longer has the file either. */
+  error?: any;
   [key: string]: any;
 }
 
@@ -1112,3 +1134,199 @@ export declare const WEB_EVENTS: any;
 export declare const WEB_GLOBALS: any;
 export declare function decodeArgo(buf: Buffer): any;
 export declare function tryDecodeArgo(buf: Buffer): any;
+
+// ────────────────────────────────────────────────────────────────────────────
+// Namespaces
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Everything above this line is a name picked out of a module by hand.
+ * Everything below is the rest of the library: each module of `lib/`, whole,
+ * under a name of its own. Nothing above is renamed or removed by any of it.
+ *
+ * `wa.MediaService` is the object `require('whalibmob/lib/MediaService')`
+ * returns — deep requires work too, and always have. Four namespaces are
+ * gathered from the several modules of a directory rather than being one
+ * module: `Signal`, `Signal.libsignal`, `AppState` and `Image`.
+ *
+ * The members declared on each namespace below are typed. The rest of a module
+ * is reachable and untyped, the same way `MessageSender` and `SignalProtocol`
+ * are above — this file has never claimed to describe the internals, and a
+ * namespace does not change that.
+ */
+export interface LibModule {
+  [name: string]: any;
+}
+
+/**
+ * `whalibmob/lib/MediaService` — the encryption, upload and download beneath
+ * `client.downloadMedia()`. Everything it exports is typed.
+ */
+export declare const MediaService: {
+  /** Upload path and HKDF info string per media type. */
+  MEDIA_PATH: Record<string, { path: string; keyName: string }>;
+  encryptMedia(plaintext: Buffer, mediaKey: Buffer, keyName: string): EncryptedMedia;
+  decryptMedia(encryptedWithMac: Buffer, mediaKey: Buffer, keyName: string): Buffer;
+  uploadMedia(...args: any[]): Promise<any>;
+  /** `opts.fileEncSha256` checks the blob as it arrived, before decrypting. */
+  downloadMedia(
+    url: string,
+    mediaKey: Buffer,
+    keyName: string,
+    opts?: { web?: boolean; fileEncSha256?: Buffer }
+  ): Promise<Buffer>;
+  /** Plain GET, no decryption — profile pictures are served in the clear. */
+  httpGetBuffer(url: string, opts?: { web?: boolean }): Promise<Buffer>;
+  /** HKDF-SHA256 over the media key: 112 bytes of IV, cipher key and MAC key. */
+  deriveMediaKeyData(mediaKey: Buffer, keyName: string): Buffer;
+  /** `'image'` → `'WhatsApp Image Keys'`. `null` for a type it does not know. */
+  getMediaKeyName(mediaType: string): string | null;
+  /** The absolute URL, built from `directPath` when there is no `url`. */
+  resolveMediaUrl(url: string | null, directPath: string | null): string | null;
+};
+
+/** `whalibmob/lib/proto/MessageProto` — the message protobufs. */
+export declare const MessageProto: LibModule & {
+  /**
+   * Raw decrypted bytes into a `DecodedMessage`. Envelopes — view-once,
+   * ephemeral, deviceSent, documentWithCaption, edited — are opened, so what
+   * comes back is the message inside with `viewOnce` / `ephemeral` / `edited`
+   * recorded on it. `depth` is internal; leave it unset.
+   */
+  decodeMessageContainer(buf: Buffer, depth?: number): DecodedMessage;
+  /** The generic protobuf field walker, keyed by field number. */
+  decodeFields(buf: Buffer): Record<number, any>;
+  encodeMessage(...args: any[]): Buffer;
+  encodeImageMessage(opts: Record<string, any>): Buffer;
+  encodeVideoMessage(opts: Record<string, any>): Buffer;
+  encodeAudioMessage(opts: Record<string, any>): Buffer;
+  encodeDocumentMessage(opts: Record<string, any>): Buffer;
+  encodeStickerMessage(opts: Record<string, any>): Buffer;
+  encodePollCreationMessage(opts: Record<string, any>):
+    { payload: Buffer; messageSecret: Buffer; encKey: Buffer };
+};
+
+/** `whalibmob/lib/messages/` — sending, and the receipts that go with it. */
+export declare const Messages: {
+  MessageSender: LibModule;
+  /**
+   * Asking the sender's phone to upload a file again. `client
+   * .requestMediaRetry()` and `client.decryptMediaRetry()` are these, wired up.
+   */
+  MediaRetry: {
+    /** HKDF-SHA256(mediaKey, "WhatsApp Media Retry Notification"), 32 bytes. */
+    mediaRetryKey(mediaKey: Buffer): Buffer;
+    encryptRetryReceipt(msgId: string, mediaKey: Buffer):
+      { ciphertext: Buffer; iv: Buffer };
+    decryptRetryNotification(
+      notif: MediaRetryNotification, mediaKey: Buffer): MediaRetryResult;
+    buildRetryReceiptNode(
+      info: { id: string; chatJid: Jid; fromMe: boolean; participant?: Jid },
+      mediaKey: Buffer, ownJid: Jid, BinaryNode: any): any;
+    /** `null` when the node is not a media-retry notification. */
+    parseRetryNotification(node: any, helpers: {
+      findChild: (node: any, tag: string) => any;
+      getContent: (node: any) => Buffer | null;
+    }): MediaRetryNotification | null;
+    RETRY_KEY_INFO: string;
+  };
+  ReportingToken: LibModule;
+  TcTokenStore: LibModule;
+};
+
+/**
+ * `whalibmob/lib/signal/` — SignalProtocol.js, SignalStore.js and SenderKey.js
+ * gathered into one namespace, with the two vendored libraries under their own.
+ */
+export declare const Signal: LibModule & {
+  SignalProtocol: any;
+  SignalStore: any;
+  SenderKeyStore: any;
+  SenderKeyCrypto: any;
+  /** Group ciphers and sender-key records. */
+  WaSignalGroup: LibModule;
+  /**
+   * The vendored libsignal. Its own barrel leaves six modules out; they are
+   * here — `BaseKeyType`, `ChainType`, `protobufs`, `queueJob`,
+   * `FingerprintGenerator`, `textsecure`.
+   */
+  libsignal: LibModule;
+};
+
+/** `whalibmob/lib/appstate/` — the synced state a companion keeps in step. */
+export declare const AppState: LibModule & {
+  AppStateStore: any;
+  COLLECTIONS: string[];
+  AppStateSync: LibModule;
+  LTHash: LibModule;
+  Mutations: LibModule;
+  SyncdProto: LibModule;
+};
+
+/**
+ * `whalibmob/lib/image/` — the decoders behind the inline thumbnails, and the
+ * JPEG encoder that writes them. No native dependency; sharp or jimp are used
+ * when installed and this is what runs when they are not.
+ */
+export declare const Image: LibModule & {
+  /** Width and height from the file header, for every format below. */
+  decodeImage(buf: Buffer): any;
+  canDecode(buf: Buffer): boolean;
+  toSquareJpeg(...args: any[]): Buffer | null;
+  toScaledJpeg(...args: any[]): Buffer | null;
+  encodeJpeg(...args: any[]): Buffer;
+  Jpeg: LibModule;
+  JpegEncoder: LibModule;
+  Png: LibModule;
+  Gif: LibModule;
+  Bmp: LibModule;
+};
+
+/** Registration, sessions, and the device a session presents itself as. */
+export declare const Client: LibModule;
+export declare const Registration: LibModule;
+export declare const Store: LibModule;
+export declare const WebStore: LibModule;
+export declare const DeviceConfig: LibModule;
+/**
+ * `whalibmob/lib/DeviceManager` — the module, not the class. The flat
+ * `DeviceManager` export is the class; this is what it comes from, so
+ * `makeDeviceJid`, `phoneFromJid` and `jidStrToObj` can be reached too.
+ */
+export declare const Devices: LibModule;
+export declare const PlayStore: LibModule;
+export declare const PlayStoreDevice: LibModule;
+export declare const AndroidApk: LibModule;
+export declare const Attestation: LibModule;
+export declare const Tokens: LibModule;
+export declare const PushClient: LibModule;
+export declare const Fcm: LibModule;
+export declare const FcmMcs: LibModule;
+
+/** Linking to an account that already exists. */
+export declare const PairingCode: LibModule;
+export declare const CompanionPairing: LibModule;
+export declare const QrPairing: LibModule;
+export declare const WebVersion: LibModule;
+export declare const WebProto: LibModule;
+
+/** The wire. */
+export declare const BinaryNode: LibModule;
+export declare const Noise: LibModule;
+export declare const WebSocketStream: LibModule;
+export declare const Socks: LibModule;
+export declare const OfflineNodeProcessor: LibModule;
+export declare const Constants: LibModule;
+export declare const Logger: LibModule;
+/**
+ * `whalibmob/lib/proto.js` — the handshake payloads. The message protobufs are
+ * the directory of the same name, and are `MessageProto`.
+ */
+export declare const Proto: LibModule;
+
+export declare const MediaThumbnail: LibModule;
+export declare const GroupParticipant: LibModule;
+export declare const HistorySyncHandler: LibModule;
+export declare const AuthUtils: LibModule;
+export declare const Argo: LibModule;
+export declare const WAUSync: LibModule;

package/index.js

@@ -55,27 +55,159 @@ const {
   HistorySyncTypeName
 } = require('./lib/HistorySyncHandler');
 
+// ─── Everything below is bound to a name before it is exported ───────────────
+//
+// Not for tidiness. Node reads a CommonJS module's names statically when
+// something imports it as ESM, and the reader it uses gives up at the first
+// property of module.exports whose value is not a plain identifier. There used
+// to be an arrow function five entries in, and everything after it — a hundred
+// and sixteen of the hundred and twenty-one names — could not be imported by
+// name at all:
+//
+//   import { createNewStore } from 'whalibmob'
+//   SyntaxError: Named export 'createNewStore' not found.
+//
+// The default import always worked and still does, so this broke no CommonJS
+// caller and no `import wa from 'whalibmob'`. It broke `import { … }`, which is
+// how a bot written as an ES module reaches for anything.
+//
+// So: functions defined here get a name first, member accesses get a name
+// first, and the modules below get a name first. The object at the bottom is
+// nothing but identifiers, and test/public-surface.test.js fails if any name
+// stops being importable that way.
+
+// Receive the verification code as a silent push, without an SMS — opens the
+// listener the native client of that platform keeps open. See "Receiving the
+// code over push" in the README.
+//
+// Routed through the push client for the device's platform: Android opens the
+// Firebase MCS stream, iOS resolves null because APNs is not implemented and
+// an iOS session holds no Firebase identity to listen with.
+const receivePushCode = (store, device, opts) => {
+  const dev = device || (store && store.device);
+  return require('./lib/PushClient')
+    .pushClientFor(dev)
+    .receivePushCode(store, dev, opts);
+};
+
+// Whether the device profile can do push verification at all.
+const supportsPush = (device) => require('./lib/PushClient').supportsPush(device);
+
+// Where a session's files live: one folder per number inside the
+// authentication folder. The same resolver the CLI uses.
+const {
+  defaultBaseDir, sessionDirFor, storeFileFor, webStoreFileFor,
+  listSessions, migrateSession
+} = SessionPaths;
+
+const { encodeWAM, BinaryInfo, WEB_EVENTS, WEB_GLOBALS } = WAM;
+
+// ─── The namespaces ──────────────────────────────────────────────────────────
+//
+// Every module of lib/, whole, under a name of its own — see the note at the
+// foot of module.exports for what the names mean and why they are these.
+
+const Client           = require('./lib/Client');
+const Registration     = require('./lib/Registration');
+const Store            = require('./lib/Store');
+const WebStore         = require('./lib/WebStore');
+const DeviceConfig     = require('./lib/DeviceConfig');
+const Devices          = require('./lib/DeviceManager');
+const PlayStore        = require('./lib/PlayStore');
+const PlayStoreDevice  = require('./lib/playstore-device');
+const AndroidApk       = require('./lib/AndroidApk');
+const Attestation      = require('./lib/Attestation');
+const Tokens           = require('./lib/tokens');
+const PushClient       = require('./lib/PushClient');
+const Fcm              = require('./lib/fcm');
+const FcmMcs           = require('./lib/fcm-mcs');
+
+const PairingCode      = require('./lib/PairingCode');
+const CompanionPairing = require('./lib/CompanionPairing');
+const QrPairing        = require('./lib/QrPairing');
+const WebVersion       = require('./lib/WebVersion');
+const WebProto         = require('./lib/webproto');
+
+const BinaryNode           = require('./lib/BinaryNode');
+const Noise                = require('./lib/noise');
+const WebSocketStream      = require('./lib/WebSocketStream');
+const Socks                = require('./lib/socks');
+const OfflineNodeProcessor = require('./lib/OfflineNodeProcessor');
+const Constants            = require('./lib/constants');
+const Logger               = require('./lib/logger');
+// lib/proto.js — the handshake payloads. The message protobufs are the
+// directory of the same name, and are MessageProto.
+const Proto                = require('./lib/proto.js');
+
+const MessageProto     = require('./lib/proto/MessageProto');
+const MediaService     = require('./lib/MediaService');
+const MediaThumbnail   = require('./lib/MediaThumbnail');
+const GroupParticipant = require('./lib/GroupParticipant');
+
+const Messages = {
+  MessageSender:  require('./lib/messages/MessageSender'),
+  MediaRetry:     require('./lib/messages/MediaRetry'),
+  ReportingToken: require('./lib/messages/ReportingToken'),
+  TcTokenStore:   require('./lib/messages/TcTokenStore')
+};
+
+// The decoders behind the inline thumbnails, and the encoder that makes them.
+// lib/image/index.js is the whole story for most callers; the per-format
+// modules are here for the rest.
+const Image = Object.assign({}, require('./lib/image'), {
+  Jpeg:        require('./lib/image/Jpeg'),
+  JpegEncoder: require('./lib/image/JpegEncoder'),
+  Png:         require('./lib/image/Png'),
+  Gif:         require('./lib/image/Gif'),
+  Bmp:         require('./lib/image/Bmp')
+});
+
+const HistorySyncHandler = require('./lib/HistorySyncHandler');
+const AuthUtils          = require('./lib/auth-utils');
+const Argo               = require('./lib/argo/ArgoDecoder');
+const WAUSync            = require('./lib/WAUSync');
+
+// Signal — lib/signal/. SignalProtocol.js, SignalStore.js and SenderKey.js have
+// no name in common, so the three are one namespace. The two vendored libraries
+// keep theirs, being libraries.
+const Signal = Object.assign({},
+  require('./lib/signal/SignalProtocol'),
+  require('./lib/signal/SignalStore'),
+  require('./lib/signal/SenderKey'),
+  {
+    WaSignalGroup: require('./lib/signal/WaSignalGroup'),
+    // libsignal's own barrel leaves six of its modules out. They are added to a
+    // copy of it here rather than written into it, so
+    // require('whalibmob/lib/signal/libsignal') stays exactly what it was.
+    libsignal: Object.assign({}, require('./lib/signal/libsignal'), {
+      BaseKeyType: require('./lib/signal/libsignal/base_key_type'),
+      ChainType:   require('./lib/signal/libsignal/chain_type'),
+      protobufs:   require('./lib/signal/libsignal/protobufs'),
+      queueJob:    require('./lib/signal/libsignal/queue_job'),
+      FingerprintGenerator:
+        require('./lib/signal/libsignal/numeric_fingerprint').FingerprintGenerator,
+      textsecure:
+        require('./lib/signal/libsignal/WhisperTextProtocol').textsecure
+    })
+  });
+
+// App state — lib/appstate/. AppStateStore.js is spread because the flat
+// AppStateStore is its class; the other three are whole.
+const AppState = Object.assign({}, require('./lib/appstate/AppStateStore'), {
+  AppStateSync: require('./lib/appstate/AppStateSync'),
+  LTHash:       require('./lib/appstate/LTHash'),
+  Mutations:    require('./lib/appstate/Mutations'),
+  SyncdProto:   require('./lib/appstate/SyncdProto')
+});
+
 module.exports = {
   WhalibmobClient,
   checkNumberStatus,
   checkIfRegistered,
   requestSmsCode,
   verifyCode,
-  // Receive the verification code as a silent push, without an SMS — opens the
-  // listener the native client of that platform keeps open. See "Receiving the
-  // code over push" in the README.
-  //
-  // Routed through the push client for the device's platform: Android opens the
-  // Firebase MCS stream, iOS resolves null because APNs is not implemented and
-  // an iOS session holds no Firebase identity to listen with.
-  receivePushCode: (store, device, opts) => {
-    const dev = device || (store && store.device);
-    return require('./lib/PushClient')
-      .pushClientFor(dev)
-      .receivePushCode(store, dev, opts);
-  },
-  // Whether the device profile can do push verification at all.
-  supportsPush: (device) => require('./lib/PushClient').supportsPush(device),
+  receivePushCode,
+  supportsPush,
   assertRegistrationKeys,
   // Version fetch — use fetchWaVersion for device-aware (iOS or Android) fetching.
   // fetchIosVersion is kept for backward compatibility.
@@ -89,12 +221,12 @@ module.exports = {
   // Where a session's files live: one folder per number inside the
   // authentication folder. The same resolver the CLI uses.
   SessionPaths,
-  defaultBaseDir:  SessionPaths.defaultBaseDir,
-  sessionDirFor:   SessionPaths.sessionDirFor,
-  storeFileFor:    SessionPaths.storeFileFor,
-  webStoreFileFor: SessionPaths.webStoreFileFor,
-  listSessions:    SessionPaths.listSessions,
-  migrateSession:  SessionPaths.migrateSession,
+  defaultBaseDir,
+  sessionDirFor,
+  storeFileFor,
+  webStoreFileFor,
+  listSessions,
+  migrateSession,
   // Device config — reads WA_OS / WA_DEVICE / WA_DEVICE_* from process.env
   getDeviceConfig,
   // Store helpers
@@ -123,10 +255,10 @@ module.exports = {
   // encoder and the BinaryInfo holder, all as the reference client defines
   // them. See client.wamBuffer / client.sendWAMBuffer().
   WAM,
-  encodeWAM:  WAM.encodeWAM,
-  BinaryInfo: WAM.BinaryInfo,
-  WEB_EVENTS: WAM.WEB_EVENTS,
-  WEB_GLOBALS: WAM.WEB_GLOBALS,
+  encodeWAM,
+  BinaryInfo,
+  WEB_EVENTS,
+  WEB_GLOBALS,
   // Signal / encryption internals
   SignalProtocol,
   SignalStore,
@@ -171,5 +303,79 @@ module.exports = {
   decryptHistoryBlob,
   deriveHistoryKeys,
   HistorySyncType,
-  HistorySyncTypeName
+  HistorySyncTypeName,
+
+  // ─── Namespaces ────────────────────────────────────────────────────────────
+  //
+  // Everything above is a name picked out of a module by hand — eighty-two of
+  // the four hundred and ninety-five the library actually has. What follows is
+  // the rest: every module, whole, under a name of its own. Nothing above is
+  // renamed, moved or removed by any of it.
+  //
+  // The rule is that a namespace is named after the module it comes from, and a
+  // directory in lib/ becomes one namespace rather than several. Two names
+  // could not be had: Devices is lib/DeviceManager.js, because the flat export
+  // of that name is the class rather than the module, and Proto is lib/proto.js,
+  // because lib/proto/ would want the same name and is MessageProto.
+  //
+  // Most are the very object a deep require returns —
+  // wa.MediaService === require('whalibmob/lib/MediaService') — which is worth
+  // knowing because deep requires work and always have: the package declares no
+  // `exports` map, so nothing here is the only way in. The four built with
+  // Object.assign (Signal, AppState, Image, Signal.libsignal) are new objects
+  // holding the same functions, gathered from the several modules of a
+  // directory. Nothing is copied out of a module and nothing is written back
+  // into one.
+  //
+  // test/public-surface.test.js walks lib/ and fails if any module has an
+  // export that none of this reaches, so the coverage is checked rather than
+  // claimed.
+
+  // Registration, sessions and the device a session presents itself as
+  Client,
+  Registration,
+  Store,
+  WebStore,
+  DeviceConfig,
+  Devices,
+  PlayStore,
+  PlayStoreDevice,
+  AndroidApk,
+  Attestation,
+  Tokens,
+  PushClient,
+  Fcm,
+  FcmMcs,
+
+  // Linking to an account that already exists
+  PairingCode,
+  CompanionPairing,
+  QrPairing,
+  WebVersion,
+  WebProto,
+
+  // The wire
+  BinaryNode,
+  Noise,
+  WebSocketStream,
+  Socks,
+  OfflineNodeProcessor,
+  Constants,
+  Logger,
+  Proto,
+
+  // Messages and media
+  MessageProto,
+  Messages,
+  MediaService,
+  MediaThumbnail,
+  GroupParticipant,
+  Image,
+
+  HistorySyncHandler,
+  AuthUtils,
+  Argo,
+  WAUSync,
+  Signal,
+  AppState
 };

package/lib/messages/MediaRetry.js

@@ -116,8 +116,14 @@ function encryptRetryReceipt(msgId, mediaKey) {
  *
  * @param {object} notif    { messageId, ciphertext, iv } off the wire
  * @param {Buffer} mediaKey the same media key the receipt was sent with
- * @returns {{result: number, directPath: string|null, url: string|null,
- *            handle: string|null, ciphertextSha256: Buffer|null}}
+ * @returns {{result: number|null, ok: boolean, directPath: string|null,
+ *            stanzaId: string}}
+ *          directPath is null rather than absent when the phone declined, so
+ *          `ok` — or a check against null — is what tells the two apart.
+ *
+ *          This used to promise a url, a handle and a ciphertextSha256. None of
+ *          the three has ever been returned; the notification does not carry
+ *          them.
  */
 function decryptRetryNotification(notif, mediaKey) {
   const { messageId, ciphertext, iv } = notif;

package/lib/proto/MessageProto.js

@@ -534,17 +534,67 @@ function _dbl(buf) {
   return buf.readDoubleLE(0);
 }
 
-function decodeMessageContainer(buf) {
+// ─── Envelopes ───────────────────────────────────────────────────────────────
+//
+// Several entries in Message carry no content of their own. They hold another
+// Message and exist only to say something about it: that a photo may be opened
+// once, that a message belongs to a disappearing chat, that a document was sent
+// with a caption. The inner message is an ordinary ImageMessage or
+// DocumentMessage — nothing about it changes.
+//
+// A decoder that does not open the envelope sees a field it has no branch for
+// and calls the whole thing unknown. That is why view-once and disappearing
+// media could not be downloaded at all: the mediaKey never reached the caller,
+// and downloadMedia had no message to work from.
+//
+// Every one of these but DeviceSentMessage is a FutureProofMessage — one shape,
+// { message = 1 }, under several names.
+//
+//   field  inner  what it is
+//     31     2    DeviceSentMessage { destinationJid=1, message=2, phash=3 }
+//     37     1    viewOnceMessage
+//     55     1    viewOnceMessageV2
+//     59     1    viewOnceMessageV2Extension
+//     40     1    ephemeralMessage
+//     53     1    documentWithCaptionMessage
+//     58     1    editedMessage
+//
+// All three view-once fields are read, not just the current one: V2 is what
+// today's clients produce for a photo or a video and the extension what they
+// produce for a voice note, but the original 37 is still what older senders and
+// history sync deliver.
+const MESSAGE_WRAPPERS = [
+  { field: 31, inner: 2, flag: null },
+  { field: 37, inner: 1, flag: 'viewOnce' },
+  { field: 55, inner: 1, flag: 'viewOnce' },
+  { field: 59, inner: 1, flag: 'viewOnce' },
+  { field: 40, inner: 1, flag: 'ephemeral' },
+  { field: 53, inner: 1, flag: null },
+  { field: 58, inner: 1, flag: 'edited' }
+];
+
+// Real messages nest two or three deep at the most — a view-once photo inside a
+// disappearing chat, echoed to our own devices. Each level is a length-
+// delimited field of the one above it, so the buffer strictly shrinks and this
+// cannot run away; the bound is only here so a malformed payload cannot recurse
+// deep enough to exhaust the stack.
+const MAX_WRAPPER_DEPTH = 8;
+
+// The Message inside an envelope, or null when the field is absent, is not an
+// envelope after all, or holds nothing.
+function _unwrap(envelope, innerField) {
+  if (!envelope || !Buffer.isBuffer(envelope)) return null;
+  try {
+    const inner = _decodeFields(envelope)[innerField];
+    return (Buffer.isBuffer(inner) && inner.length) ? inner : null;
+  } catch (_) { return null; }
+}
+
+function decodeMessageContainer(buf, depth) {
   if (!buf || buf.length === 0) return { type: 'unknown' };
   try {
     const f = _decodeFields(buf);
-
-    // Field 31: deviceSentMessage — wraps the real message at field 2
-    // (sent to our own linked devices). Unwrap and re-decode.
-    if (f[31]) {
-      const dsm = _decodeFields(f[31]);
-      if (dsm[2]) return decodeMessageContainer(dsm[2]);
-    }
+    const level = depth || 0;
 
     // Field 2: senderKeyDistributionMessage — used to set up sender keys.
     // In WhatsApp Multi-Device, SKDM is bundled WITH the first real message in a new
@@ -578,6 +628,29 @@ function decodeMessageContainer(buf) {
     // Decode the actual message payload (independent of SKDM).
     // We use a helper so we can attach skdmInfo to every result.
     let msgResult = null;
+    // What the envelopes said about it, raised on the result below.
+    let envelopeFlags = null;
+
+    // An envelope is opened before anything else is looked at: whatever is
+    // inside it is the message, and the fields beside it here are the
+    // envelope's own. A distribution or a message secret riding on this level
+    // still belongs to what comes out, which is why both are read first and
+    // carried onto the result — unwrapping used to return straight out of here
+    // and lose them.
+    if (level < MAX_WRAPPER_DEPTH) {
+      for (const w of MESSAGE_WRAPPERS) {
+        const inner = _unwrap(f[w.field], w.inner);
+        if (!inner) continue;
+        const decoded = decodeMessageContainer(inner, level + 1);
+        // Nothing this decoder knows was in there. Leave msgResult unset so the
+        // branches below still get their turn, rather than reporting an empty
+        // envelope as the whole message.
+        if (!decoded || decoded.type === 'unknown') continue;
+        msgResult = decoded;
+        if (w.flag) envelopeFlags = Object.assign({}, envelopeFlags, { [w.flag]: true });
+        break;
+      }
+    }
 
     // Field 1: conversation — plain text
     if (!msgResult && f[1] && Buffer.isBuffer(f[1])) {
@@ -841,10 +914,24 @@ function decodeMessageContainer(buf) {
       msgResult = { type: 'pollVote' };
     }
 
-    // If we found a real message, attach skdmInfo / messageSecret and return
+    // If we found a real message, attach skdmInfo / messageSecret and return.
+    //
+    // Anything the inner message already carries stays as it is: a nested
+    // envelope has set its own flags and read its own secret on the way up, and
+    // this level only fills in what is still missing.
     if (msgResult) {
-      if (messageSecret) msgResult = Object.assign({}, msgResult, { messageSecret });
-      return skdmInfo ? Object.assign({}, msgResult, { skdm: skdmInfo }) : msgResult;
+      if (envelopeFlags) msgResult = Object.assign({}, msgResult, envelopeFlags);
+      if (messageSecret && !msgResult.messageSecret) {
+        msgResult = Object.assign({}, msgResult, { messageSecret });
+      }
+      // A poll inside an envelope keeps its messageContextInfo out here, beside
+      // the envelope rather than beside the poll. Its votes cannot be decrypted
+      // without that secret, so it is taken from whichever level carried it.
+      if (msgResult.type === 'poll' && !msgResult.encKey && messageSecret) {
+        msgResult = Object.assign({}, msgResult, { encKey: messageSecret });
+      }
+      if (skdmInfo && !msgResult.skdm) msgResult = Object.assign({}, msgResult, { skdm: skdmInfo });
+      return msgResult;
     }
 
     // If we only have an SKDM (no other message content), return senderKeyDistribution
@@ -900,6 +987,10 @@ module.exports = {
   encodeVarint,
   // The generic field walker, for the protobufs that live outside this file.
   decodeFields: _decodeFields,
+  // Exported so a test can check the bound at its edge rather than guess where
+  // the edge is: a test that hardcodes the number goes on passing after the
+  // constant moves, which is the same as not testing it.
+  MAX_WRAPPER_DEPTH,
   field,
   varint,
   str,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whalibmob",
-  "version": "5.24.0",
+  "version": "5.24.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",
@@ -21,7 +21,7 @@
   "type": "commonjs",
   "scripts": {
     "test": "node --test",
-    "test:types": "tsc --noEmit --strict --skipLibCheck index.d.ts",
+    "test:types": "tsc --noEmit --strict --skipLibCheck index.d.ts && tsc --noEmit --strict --skipLibCheck --types node types/usage-check.ts",
     "test:all": "npm test && npm run test:types"
   },
   "license": "MIT",