zapo-js 1.6.2 → 1.7.1

package/dist/client/persistence/history-sync.js

@@ -1,13 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanHistorySyncBlob = scanHistorySyncBlob;
+exports.scanConversationJidPair = scanConversationJidPair;
 exports.runHistorySyncNotification = runHistorySyncNotification;
 exports.processHistorySyncNotification = processHistorySyncNotification;
 const node_util_1 = require("node:util");
 const node_zlib_1 = require("node:zlib");
+const history_blob_1 = require("../persistence/history-blob");
 const _proto_1 = require("../../proto");
 const jid_1 = require("../../protocol/jid");
+const message_1 = require("../../protocol/message");
 const bytes_1 = require("../../util/bytes");
 const primitives_1 = require("../../util/primitives");
+const protoscan_1 = require("../../util/protoscan");
 const unzipAsync = (0, node_util_1.promisify)(node_zlib_1.unzip);
 const HANDLED_SYNC_TYPES = new Set([
     _proto_1.proto.Message.HistorySyncType.INITIAL_BOOTSTRAP,
@@ -18,6 +23,90 @@ const HANDLED_SYNC_TYPES = new Set([
     _proto_1.proto.Message.HistorySyncType.NON_BLOCKING_DATA
 ]);
 const HISTORY_SYNC_MAX_PENDING_WRITES = 1024;
+const HISTORY_SYNC_FIELDS = Object.freeze({
+    CONVERSATIONS: 2,
+    CHUNK_ORDER: 5,
+    PROGRESS: 6,
+    PUSHNAMES: 7,
+    PHONE_NUMBER_TO_LID_MAPPINGS: 15,
+    NCT_SALT: 19,
+    INLINE_CONTACTS: 20
+});
+const CONVERSATION_JID_FIELDS = Object.freeze({
+    PN_JID: 39,
+    LID_JID: 42,
+    ACCOUNT_LID: 49
+});
+function scanHistorySyncBlob(bytes) {
+    const conversationRanges = [];
+    const pushnames = [];
+    const inlineContacts = [];
+    const phoneNumberToLidMappings = [];
+    let nctSalt = null;
+    let chunkOrder = null;
+    let progress = null;
+    (0, protoscan_1.scanProtoFields)(bytes, 0, bytes.length, (field) => {
+        if (field.wireType === protoscan_1.PROTO_WIRE_TYPES.LEN) {
+            if (field.fieldNumber === HISTORY_SYNC_FIELDS.CONVERSATIONS) {
+                conversationRanges[conversationRanges.length] = {
+                    start: field.valueStart,
+                    end: field.valueEnd
+                };
+            }
+            else if (field.fieldNumber === HISTORY_SYNC_FIELDS.PUSHNAMES) {
+                pushnames[pushnames.length] = _proto_1.proto.Pushname.decode(bytes.subarray(field.valueStart, field.valueEnd));
+            }
+            else if (field.fieldNumber === HISTORY_SYNC_FIELDS.PHONE_NUMBER_TO_LID_MAPPINGS) {
+                phoneNumberToLidMappings[phoneNumberToLidMappings.length] =
+                    _proto_1.proto.PhoneNumberToLIDMapping.decode(bytes.subarray(field.valueStart, field.valueEnd));
+            }
+            else if (field.fieldNumber === HISTORY_SYNC_FIELDS.INLINE_CONTACTS) {
+                inlineContacts[inlineContacts.length] = _proto_1.proto.InlineContact.decode(bytes.subarray(field.valueStart, field.valueEnd));
+            }
+            else if (field.fieldNumber === HISTORY_SYNC_FIELDS.NCT_SALT) {
+                nctSalt = bytes.slice(field.valueStart, field.valueEnd);
+            }
+            return;
+        }
+        if (field.wireType === protoscan_1.PROTO_WIRE_TYPES.VARINT) {
+            if (field.fieldNumber === HISTORY_SYNC_FIELDS.CHUNK_ORDER) {
+                chunkOrder = field.varintValue;
+            }
+            else if (field.fieldNumber === HISTORY_SYNC_FIELDS.PROGRESS) {
+                progress = field.varintValue;
+            }
+        }
+    });
+    return {
+        conversationRanges,
+        pushnames,
+        inlineContacts,
+        phoneNumberToLidMappings,
+        nctSalt,
+        chunkOrder,
+        progress
+    };
+}
+function scanConversationJidPair(bytes, range) {
+    let pnJid = null;
+    let lidJid = null;
+    let accountLid = null;
+    (0, protoscan_1.scanProtoFields)(bytes, range.start, range.end, (field) => {
+        if (field.wireType !== protoscan_1.PROTO_WIRE_TYPES.LEN) {
+            return;
+        }
+        if (field.fieldNumber === CONVERSATION_JID_FIELDS.PN_JID) {
+            pnJid = bytes_1.TEXT_DECODER.decode(bytes.subarray(field.valueStart, field.valueEnd));
+        }
+        else if (field.fieldNumber === CONVERSATION_JID_FIELDS.LID_JID) {
+            lidJid = bytes_1.TEXT_DECODER.decode(bytes.subarray(field.valueStart, field.valueEnd));
+        }
+        else if (field.fieldNumber === CONVERSATION_JID_FIELDS.ACCOUNT_LID) {
+            accountLid = bytes_1.TEXT_DECODER.decode(bytes.subarray(field.valueStart, field.valueEnd));
+        }
+    });
+    return { pnJid, lidJid: lidJid ?? accountLid };
+}
 async function runHistorySyncNotification(deps, notification) {
     try {
         await processHistorySyncNotification(deps, notification);
@@ -47,14 +136,17 @@ async function processHistorySyncNotification(deps, notification) {
     }
     const blob = await downloadHistorySyncBlob(deps, notification);
     const decompressed = (0, bytes_1.toBytesView)(await unzipAsync(blob));
-    const historySync = _proto_1.proto.HistorySync.decode(decompressed);
+    // Conversations are decoded one record at a time in the loop below so the
+    // full message graph never coexists in memory; the scan only records their
+    // byte ranges and decodes the small metadata fields.
+    const scan = scanHistorySyncBlob(decompressed);
     deps.logger.info('decoded history sync chunk', {
         syncType,
-        chunkOrder: historySync.chunkOrder,
-        progress: historySync.progress,
-        conversations: historySync.conversations.length,
-        pushnames: historySync.pushnames.length,
-        inlineContacts: historySync.inlineContacts?.length ?? 0
+        chunkOrder: scan.chunkOrder,
+        progress: scan.progress,
+        conversations: scan.conversationRanges.length,
+        pushnames: scan.pushnames.length,
+        inlineContacts: scan.inlineContacts.length
     });
     const nowMs = Date.now();
     const pendingWrites = [];
@@ -63,24 +155,23 @@ async function processHistorySyncNotification(deps, notification) {
     // pushnames and mappings land on a single canonical (LID-form) contact
     // row instead of two mirror rows (one keyed by PN, one keyed by LID).
     const pnToLid = new Map();
-    for (const map of historySync.phoneNumberToLidMappings ?? []) {
+    for (const map of scan.phoneNumberToLidMappings) {
         if (map.pnJid && map.lidJid) {
             pnToLid.set(map.pnJid, map.lidJid);
         }
     }
-    for (const c of historySync.inlineContacts ?? []) {
+    for (const c of scan.inlineContacts) {
         if (c.pnJid && c.lidJid) {
             pnToLid.set(c.pnJid, c.lidJid);
         }
     }
-    for (const conversation of historySync.conversations) {
-        const pnJid = conversation.pnJid;
-        const lidJid = conversation.lidJid ?? conversation.accountLid;
-        if (pnJid && lidJid) {
-            pnToLid.set(pnJid, lidJid);
+    for (const range of scan.conversationRanges) {
+        const pair = scanConversationJidPair(decompressed, range);
+        if (pair.pnJid && pair.lidJid) {
+            pnToLid.set(pair.pnJid, pair.lidJid);
         }
     }
-    for (const pn of historySync.pushnames) {
+    for (const pn of scan.pushnames) {
         if (!pn.id) {
             continue;
         }
@@ -98,10 +189,10 @@ async function processHistorySyncNotification(deps, notification) {
                 lastUpdatedMs: nowMs
             });
         if (pendingWrites.length >= HISTORY_SYNC_MAX_PENDING_WRITES) {
-            await flushPendingWrites(pendingWrites);
+            await (0, history_blob_1.flushPendingWrites)(pendingWrites);
         }
     }
-    for (const c of historySync.inlineContacts ?? []) {
+    for (const c of scan.inlineContacts) {
         const jid = c.lidJid ?? c.pnJid;
         if (!jid) {
             continue;
@@ -117,16 +208,55 @@ async function processHistorySyncNotification(deps, notification) {
             lastUpdatedMs: nowMs
         });
         if (pendingWrites.length >= HISTORY_SYNC_MAX_PENDING_WRITES) {
-            await flushPendingWrites(pendingWrites);
+            await (0, history_blob_1.flushPendingWrites)(pendingWrites);
         }
     }
     let messagesCount = 0;
-    for (const conversation of historySync.conversations) {
+    const tokenConversations = [];
+    for (const range of scan.conversationRanges) {
+        let conversation;
+        try {
+            conversation = _proto_1.proto.Conversation.decode(decompressed.subarray(range.start, range.end));
+        }
+        catch (error) {
+            await Promise.allSettled(pendingWrites);
+            throw (0, primitives_1.toError)(error);
+        }
         const threadJid = conversation.id;
         if (!threadJid) {
             deps.logger.debug('skipping history sync conversation without thread jid');
             continue;
         }
+        if (deps.onPrivacyTokens &&
+            (conversation.tcToken ||
+                conversation.tcTokenTimestamp ||
+                conversation.tcTokenSenderTimestamp)) {
+            tokenConversations[tokenConversations.length] = {
+                jid: threadJid,
+                tcToken: conversation.tcToken ? new Uint8Array(conversation.tcToken) : undefined,
+                tcTokenTimestamp: (0, primitives_1.longToNumber)(conversation.tcTokenTimestamp) || undefined,
+                tcTokenSenderTimestamp: (0, primitives_1.longToNumber)(conversation.tcTokenSenderTimestamp) || undefined
+            };
+        }
+        const ephemeralExpiration = conversation.ephemeralExpiration ?? undefined;
+        const ephemeralSettingTimestamp = (0, message_1.normalizeEphemeralSettingSeconds)((0, primitives_1.longToNumber)(conversation.ephemeralSettingTimestamp)) || undefined;
+        if (deps.chatMetadataStore && ephemeralExpiration !== undefined) {
+            pendingWrites[pendingWrites.length] = deps.chatMetadataStore
+                .upsertChatMetadata({
+                chatJid: threadJid,
+                ephemeralExpiration,
+                ...(ephemeralSettingTimestamp !== undefined
+                    ? { ephemeralSettingTimestamp }
+                    : {}),
+                updatedAtMs: nowMs
+            })
+                .catch((error) => {
+                deps.logger.debug('failed to cache history sync chat metadata', {
+                    jid: threadJid,
+                    message: (0, primitives_1.toError)(error).message
+                });
+            });
+        }
         pendingWrites[pendingWrites.length] = deps.writeBehind.persistThreadAsync({
             jid: threadJid,
             name: conversation.name ?? undefined,
@@ -135,10 +265,11 @@ async function processHistorySyncNotification(deps, notification) {
             pinned: conversation.pinned ?? undefined,
             muteEndMs: (0, primitives_1.longToNumber)(conversation.muteEndTime) || undefined,
             markedAsUnread: conversation.markedAsUnread ?? undefined,
-            ephemeralExpiration: conversation.ephemeralExpiration ?? undefined
+            ephemeralExpiration,
+            ephemeralSettingTimestamp
         });
         if (pendingWrites.length >= HISTORY_SYNC_MAX_PENDING_WRITES) {
-            await flushPendingWrites(pendingWrites);
+            await (0, history_blob_1.flushPendingWrites)(pendingWrites);
         }
         if ((0, jid_1.isUserJid)(threadJid) || (conversation.lidJid ?? conversation.accountLid)) {
             const contactDisplay = conversation.displayName || conversation.username || undefined;
@@ -153,7 +284,7 @@ async function processHistorySyncNotification(deps, notification) {
                     lastUpdatedMs: nowMs
                 });
                 if (pendingWrites.length >= HISTORY_SYNC_MAX_PENDING_WRITES) {
-                    await flushPendingWrites(pendingWrites);
+                    await (0, history_blob_1.flushPendingWrites)(pendingWrites);
                 }
             }
         }
@@ -176,7 +307,7 @@ async function processHistorySyncNotification(deps, notification) {
                 messageBytes: _proto_1.proto.Message.encode(webMsg.message).finish()
             });
             if (pendingWrites.length >= HISTORY_SYNC_MAX_PENDING_WRITES) {
-                await flushPendingWrites(pendingWrites);
+                await (0, history_blob_1.flushPendingWrites)(pendingWrites);
             }
             messagesCount += 1;
         }
@@ -191,70 +322,33 @@ async function processHistorySyncNotification(deps, notification) {
             lastUpdatedMs: nowMs
         });
         if (pendingWrites.length >= HISTORY_SYNC_MAX_PENDING_WRITES) {
-            await flushPendingWrites(pendingWrites);
+            await (0, history_blob_1.flushPendingWrites)(pendingWrites);
         }
     }
-    if (deps.onPrivacyTokens) {
-        const tokenConversations = [];
-        for (const conversation of historySync.conversations) {
-            if (!conversation.id)
-                continue;
-            if (conversation.tcToken ||
-                conversation.tcTokenTimestamp ||
-                conversation.tcTokenSenderTimestamp) {
-                tokenConversations[tokenConversations.length] = {
-                    jid: conversation.id,
-                    tcToken: conversation.tcToken,
-                    tcTokenTimestamp: (0, primitives_1.longToNumber)(conversation.tcTokenTimestamp) || undefined,
-                    tcTokenSenderTimestamp: (0, primitives_1.longToNumber)(conversation.tcTokenSenderTimestamp) || undefined
-                };
-            }
-        }
-        if (tokenConversations.length > 0) {
-            pendingWrites[pendingWrites.length] = deps.onPrivacyTokens(tokenConversations);
-        }
+    if (deps.onPrivacyTokens && tokenConversations.length > 0) {
+        pendingWrites[pendingWrites.length] = deps.onPrivacyTokens(tokenConversations);
     }
-    if (deps.onNctSalt && historySync.nctSalt) {
-        pendingWrites[pendingWrites.length] = deps.onNctSalt(historySync.nctSalt);
+    if (deps.onNctSalt && scan.nctSalt) {
+        pendingWrites[pendingWrites.length] = deps.onNctSalt(scan.nctSalt);
     }
     const event = {
         syncType,
         messagesCount,
-        conversationsCount: historySync.conversations.length,
-        pushnamesCount: historySync.pushnames.length,
-        inlineContactsCount: historySync.inlineContacts?.length ?? 0,
-        chunkOrder: historySync.chunkOrder ?? undefined,
-        progress: historySync.progress ?? undefined
+        conversationsCount: scan.conversationRanges.length,
+        pushnamesCount: scan.pushnames.length,
+        inlineContactsCount: scan.inlineContacts.length,
+        chunkOrder: scan.chunkOrder ?? undefined,
+        progress: scan.progress ?? undefined
     };
-    await flushPendingWrites(pendingWrites);
+    await (0, history_blob_1.flushPendingWrites)(pendingWrites);
     deps.emitEvent('history_sync_chunk', event);
     if (deps.onProcessed) {
         await deps.onProcessed(syncType);
     }
 }
-async function flushPendingWrites(pendingWrites) {
-    if (pendingWrites.length === 0) {
-        return;
-    }
-    const settled = Promise.all(pendingWrites);
-    pendingWrites.length = 0;
-    await settled;
-}
 async function downloadHistorySyncBlob(deps, notification) {
     if (notification.initialHistBootstrapInlinePayload) {
         return (0, bytes_1.decodeProtoBytes)(notification.initialHistBootstrapInlinePayload, 'initialHistBootstrapInlinePayload');
     }
-    if (!notification.directPath) {
-        throw new Error('history sync notification missing directPath');
-    }
-    const mediaKey = (0, bytes_1.decodeProtoBytes)(notification.mediaKey, 'history sync mediaKey');
-    const fileSha256 = (0, bytes_1.decodeProtoBytes)(notification.fileSha256, 'history sync fileSha256');
-    const fileEncSha256 = (0, bytes_1.decodeProtoBytes)(notification.fileEncSha256, 'history sync fileEncSha256');
-    return deps.mediaTransfer.downloadAndDecrypt({
-        directPath: notification.directPath,
-        mediaType: 'history',
-        mediaKey,
-        fileSha256,
-        fileEncSha256
-    });
+    return (0, history_blob_1.downloadHistoryBlob)(deps.mediaTransfer, notification, 'history', 'history sync');
 }

package/dist/client/plugins/types.d.ts

@@ -63,10 +63,18 @@ type ExposedOf<P> = P extends {
  * `{ readonly voip: WaVoipCoordinator }`.
  */
 export type WaClientExposedFromPlugins<P extends readonly unknown[]> = UnionToIntersection<ExposedOf<P[number]>>;
-/** Event map a plugin contributes, carried as a phantom marker on its definition. */
+/**
+ * Event map a plugin contributes, carried as a phantom marker on its definition.
+ *
+ * The marker is optional (it never exists at runtime), so under
+ * `exactOptionalPropertyTypes` the inferred `E` keeps the `| undefined` the
+ * declaration emits. `Exclude` drops it before the union reaches
+ * {@link UnionToIntersection}, which would otherwise collapse
+ * `Events | undefined` to `never` and type every client listener as `never`.
+ */
 type EventsOf<P> = P extends {
     readonly __pluginEvents?: infer E;
-} ? unknown extends E ? {} : E : {};
+} ? unknown extends E ? {} : Exclude<E, undefined> : {};
 /**
  * Client events contributed by a tuple of plugin definitions, derived from the
  * plugin values (no global augmentation). Threaded into the client's

package/dist/client/types.d.ts

@@ -2,8 +2,10 @@ import type { AppStateCollectionName } from '../appstate/types';
 import type { DataForKey, WaAppstateActionKey, WaAppstateIndexArgs } from '../appstate-spec';
 import type { WaShortcakeAssertionSigner } from '../auth/pairing/WaShortcakeFlow';
 import type { WaAuthClientOptions, WaAuthCredentials, WaAuthDangerousOptions, WaAuthSocketOptions } from '../auth/types';
+import type { WaPrivacyAccountSyncResult } from './coordinators/WaPrivacyCoordinator';
 import type { WaCallGroupParticipant, WaCallType } from './events/call';
 import type { IncomingPresenceType, PresenceLastSeen } from './events/presence';
+import type { WaBlocklistResult } from './events/privacy';
 import type { CompanionHostPersistence } from './persistence/companion-host';
 import type { WaClientPluginDefinition } from './plugins/types';
 import type { WaMediaProcessor } from '../media/processor';
@@ -148,7 +150,9 @@ export interface WaClientOptions extends WaAuthClientOptions, WaAuthSocketOption
      * on-demand backfill triggered by `message.requestHistorySync`) are
      * downloaded and emitted as `history_sync_chunk` events. Set
      * `enabled: false` to drop them; `requireFullSync: true` asks the
-     * primary device for a full history download instead of just recent.
+     * primary device for a full history download instead of just recent;
+     * `groupBundles: true` opts into the group-history bundle a member may
+     * share after somebody joins a group.
      */
     readonly history?: WaHistorySyncOptions;
     /**
@@ -315,6 +319,14 @@ export interface WaHistorySyncOptions {
      */
     readonly enabled?: boolean;
     readonly requireFullSync?: boolean;
+    /**
+     * Whether to download and process the group-history bundle a member may
+     * share after somebody joins a group, emitting `group_history_bundle`.
+     * **Off by default** - a bundle is media a third party pushes at this
+     * account unprompted, so fetching it is opt-in. Bundles addressed to
+     * other members are dropped either way.
+     */
+    readonly groupBundles?: boolean;
 }
 export interface WaSignalMessagePublishInput {
     readonly to: string;
@@ -375,9 +387,23 @@ export interface WaSendMessageOptions extends WaMessagePublishOptions {
      */
     readonly expirationSeconds?: number;
     /**
-     * Skip the automatic `ephemeralSettingTimestamp`/`expiration` injection
-     * applied to messages sent into groups with disappearing-mode on (the cached
-     * group ephemeral is otherwise fetched and applied for you). Off by default.
+     * Unix seconds when disappearing-mode was enabled, sent as
+     * `contextInfo.ephemeralSettingTimestamp`. 1:1 only – groups never carry it.
+     * Overrides the value the auto-inject resolves from the thread store; omit
+     * it unless you have a reason, since a missing timestamp makes the peer warn
+     * that the message will not disappear.
+     */
+    readonly ephemeralSettingTimestamp?: number;
+    /**
+     * Overrides `contextInfo.disappearingMode.trigger`. The 1:1 auto-inject
+     * already sets `CHAT_SETTING`.
+     */
+    readonly disappearingModeTrigger?: Proto.DisappearingMode.Trigger;
+    /**
+     * Skip the automatic disappearing-message injection on **group** sends, which
+     * would otherwise stamp `contextInfo.expiration` and `disappearingMode` from
+     * the group metadata cache. Has no effect on 1:1 – see
+     * {@link disableDirectEphemeralAutoInject}. Off by default.
      *
      * Relationship with {@link expirationSeconds}: a non-undefined
      * `expirationSeconds` already short-circuits the auto-inject, so this flag is
@@ -385,6 +411,17 @@ export interface WaSendMessageOptions extends WaMessagePublishOptions {
      * auto-inject AND not set any expiration yourself.
      */
     readonly disableGroupEphemeralAutoInject?: boolean;
+    /**
+     * Skip the automatic disappearing-message injection on **1:1** sends, which
+     * would otherwise stamp `contextInfo.expiration`,
+     * `ephemeralSettingTimestamp` and `disappearingMode` from the chat metadata
+     * cache. Also skips the cache lookup itself. Has no effect on groups – see
+     * {@link disableGroupEphemeralAutoInject}. Off by default.
+     *
+     * Same relationship with {@link expirationSeconds} as the group flag: a
+     * non-undefined `expirationSeconds` already short-circuits the auto-inject.
+     */
+    readonly disableDirectEphemeralAutoInject?: boolean;
     /** Raw child nodes appended to the `<message>` stanza. Escape hatch for protocol features the typed API doesn't cover. */
     readonly customNodes?: readonly BinaryNode[];
     /** Wrap the outgoing message as view-once. Only valid for image/video/audio content. */
@@ -788,19 +825,26 @@ export interface WaIncomingUnhandledStanzaEvent extends WaIncomingBaseEvent {
     readonly reason: string;
 }
 /**
- * Why an incoming message arrived as a content-less placeholder. `view_once`:
- * a view-once already consumed elsewhere. `hosted`: a hosted/bot message that
- * could not be fanned out. `other`: an `unavailable` marker the lib does not
- * categorize yet.
+ * Why an incoming message arrived as a content-less placeholder. `view_once`: a
+ * view-once already consumed elsewhere. `hosted`: a hosted account whose message
+ * could not be fanned out. `bot`: a bot message whose fanout never ran. `other`:
+ * a plain fanout placeholder – the only kind the primary device resends.
  */
-export type WaUnavailableMessageKind = 'view_once' | 'hosted' | 'other';
+export type WaUnavailableMessageKind = 'view_once' | 'hosted' | 'bot' | 'other';
 export interface WaIncomingUnavailableMessageEvent extends Omit<WaIncomingBaseEvent, 'chatJid' | 'stanzaId'> {
     /** Which flavour of content the server signalled as unavailable. */
     readonly kind: WaUnavailableMessageKind;
+    /**
+     * `true` when a resend was queued for the primary device; the payload then
+     * arrives as a `message` event with the same key. Best-effort, like wa-web:
+     * the request is not persisted, so a failed peer message is not retried.
+     * `false` for the unrecoverable flavours, messages past the server age
+     * window, and mobile-primary sessions.
+     */
+    readonly resendRequested: boolean;
     /**
      * The message key (chat, stanza id, author, addressing metadata) – same
-     * shape the `message` event carries, so it can be stored or correlated. There
-     * is no decrypted `message`: the payload is unavailable and cannot be fetched.
+     * shape the `message` event carries, so it can be stored or correlated.
      */
     readonly key: WaIncomingMessageKey;
     /** Stanza `t` attr (seconds since epoch). */
@@ -1032,6 +1076,32 @@ export interface WaHistorySyncChunkEvent {
     /** Server-reported progress, 0–100. */
     readonly progress?: number;
 }
+/**
+ * A group-history bundle shared with this account after it joined a group,
+ * already downloaded, filtered and persisted. Emitted once per bundle, only
+ * when `history.groupBundles` is enabled.
+ */
+export interface WaGroupHistoryBundleEvent {
+    readonly groupJid: string;
+    /** Member who shared the history. */
+    readonly senderJid?: string;
+    /** Stanza id of the message that carried the bundle. */
+    readonly bundleMessageId?: string;
+    /** Messages persisted from this bundle, after filtering. */
+    readonly messagesCount: number;
+    /** Pinned messages older than the shared window, exempt from the age cutoff. */
+    readonly outOfWindowPinsCount: number;
+    /** Entries skipped as stubs, foreign-chat, ephemeral-expired or too old. */
+    readonly droppedCount: number;
+    /** Oldest persisted message timestamp, in ms. */
+    readonly oldestTimestampMs?: number;
+    /**
+     * Members the sender addressed the bundle to (PN or LID form). Copied out
+     * of the decoded payload, so mutating it cannot corrupt the message proto
+     * the `message` event handed to the same listener.
+     */
+    readonly historyReceivers: readonly string[];
+}
 export type WaAppStateMutationSource = 'snapshot' | 'patch' | 'local';
 type MutationEventBase = {
     readonly source: WaAppStateMutationSource;
@@ -1168,11 +1238,11 @@ export interface WaClientEventMap {
      */
     readonly message_protocol: (event: WaIncomingProtocolMessageEvent) => void;
     /**
-     * A message the server delivered as a content-less placeholder: the payload
-     * is unavailable and cannot be recovered (a view-once already consumed, or a
-     * hosted/bot message that could not be fanned out). The lib acks it and emits
-     * this instead of a `message` event for the same stanza. Branch on
-     * `event.kind`.
+     * A message the server delivered as a content-less placeholder. The lib acks
+     * it and emits this instead of a `message` event for the same stanza. A plain
+     * fanout placeholder is asked back from the primary device and arrives later
+     * as a `message` event (see `event.resendRequested`); a consumed view-once or
+     * a hosted/bot message that could not be fanned out is never resent.
      */
     readonly message_unavailable: (event: WaIncomingUnavailableMessageEvent) => void;
     /**
@@ -1205,6 +1275,28 @@ export interface WaClientEventMap {
     readonly business: (event: WaBusinessEvent) => void;
     /** Profile/group/community picture change notification – the new picture must still be fetched explicitly. */
     readonly picture: (event: WaPictureEvent) => void;
+    /**
+     * The account's privacy, refetched after the primary or another companion
+     * changed it: the full category set plus any disallowed list the server
+     * reported. The two halves are read by separate queries, so a change
+     * landing mid-refresh can leave them describing slightly different server
+     * states - the payload is exactly what
+     * {@link WaPrivacyCoordinator.refreshFromAccountSync} returns.
+     *
+     * Two paths trigger it: the live `account_sync` notification (debounced,
+     * so a burst of changes on the phone collapses into one refresh) and the
+     * `account_sync` dirty bit that catches a session up after being offline.
+     * Neither is trusted for its payload - the values always come from a
+     * fresh read. Categories the library does not model are dropped.
+     */
+    readonly privacy: (event: WaPrivacyAccountSyncResult) => void;
+    /**
+     * The account blocklist after a block/unblock made on another device -
+     * same refetch path as `privacy`, from its own account-sync protocol. The
+     * payload is the full list ({@link WaPrivacyCoordinator.getBlocklist}'s
+     * shape), never a delta.
+     */
+    readonly blocklist: (event: WaBlocklistResult) => void;
     /**
      * A parsed app-state mutation arriving from a sync – chat mute/star/read/
      * pin/archive/contact/label/etc. changed on another device. Inbound only;
@@ -1228,12 +1320,24 @@ export interface WaClientEventMap {
      * Skipped only when `history.enabled` is explicitly `false`.
      */
     readonly history_sync_chunk: (event: WaHistorySyncChunkEvent) => void;
+    /**
+     * A group-history bundle another member shared with this account after it
+     * joined a group, already downloaded and persisted. Requires
+     * `history.groupBundles: true` - the download is opt-in because a third
+     * party triggers it.
+     */
+    readonly group_history_bundle: (event: WaGroupHistoryBundleEvent) => void;
     /**
      * Offline-message queue progress after a reconnect (`'resuming'` ticks
      * with `remainingStanzas`, then `'complete'`). Useful to defer UI updates
      * until the catch-up finishes.
      */
     readonly offline_resume: (event: WaOfflineResumeEvent) => void;
+    /**
+     * Preview manifest of the offline queue, sent just before the flush. Not
+     * guaranteed to arrive - use `offline_resume` for progress, never this.
+     */
+    readonly offline_thread_metadata: (event: WaOfflineThreadMetadataEvent) => void;
     /**
      * Fatal stream-level error from the server (e.g. logged out from another
      * device, stream conflict). The connection will close right after.
@@ -1314,6 +1418,36 @@ export interface WaOfflineResumeEvent {
     /** `true` when triggered by an explicit catch-up request rather than auto-resume on reconnect. */
     readonly forced: boolean;
 }
+export interface WaOfflineThreadPreview {
+    /** User (`@lid`/`@s.whatsapp.net`) or group (`@g.us`) jid. */
+    readonly jid: string;
+    /** Unix seconds of the most recent queued stanza for this thread. */
+    readonly timestampSeconds: number;
+}
+export interface WaOfflineThreadReadWatermark {
+    readonly jid: string;
+    /** Unix seconds up to which the peer has already read this thread. */
+    readonly readTimestampSeconds: number;
+}
+/**
+ * Which threads have queued traffic, announced right before the offline flush.
+ * Informational only - every listed thread still delivers its stanzas
+ * normally. All fields but `threads` depend on server gating and are commonly
+ * absent.
+ */
+export interface WaOfflineThreadMetadataEvent {
+    readonly threads: readonly WaOfflineThreadPreview[];
+    readonly readWatermarks?: readonly WaOfflineThreadReadWatermark[];
+    /** Status-update backlog still queued behind this flush. */
+    readonly pendingStatusMessages?: {
+        readonly count: number;
+        readonly jids: readonly string[];
+    };
+    /** Notification backlog still queued behind this flush. */
+    readonly pendingNotifications?: {
+        readonly count: number;
+    };
+}
 export interface WaPrivacyTokenUpdateEvent {
     /** Peer whose trusted-contact-token (TC token) changed. */
     readonly jid: string;

package/dist/crypto/core/index.d.ts

@@ -7,5 +7,5 @@ export { hkdf, hkdfSplit } from '../core/hkdf';
 export { toSerializedPubKey, toRawPubKey, prependVersion, readVersionedContent } from '../core/keys';
 export { writeNonceCounter } from '../core/nonce';
 export { randomBytesAsync, randomFillAsync, randomIntAsync } from '../core/random';
-export { sha1, sha256, sha512, md5Bytes, aesGcmEncrypt, aesGcmDecrypt, aesCbcEncrypt, aesCbcDecrypt, aesCtrEncrypt, aesCtrDecrypt, hmacSha256Sign, hmacSha512Sign, pbkdf2Sha256 } from '../core/primitives';
+export { sha1, sha256, sha512, md5Bytes, aesGcmEncrypt, aesGcmDecrypt, aesCbcEncrypt, aesCbcEncryptWithTrailer, aesCbcDecrypt, aesCtrEncrypt, aesCtrDecrypt, hmacSha256Sign, hmacSha512Sign, pbkdf2Sha256 } from '../core/primitives';
 export { xeddsaSign, xeddsaVerify } from '../core/xeddsa';

package/dist/crypto/core/index.js

@@ -3,7 +3,7 @@
  * Cryptographic utilities
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.xeddsaVerify = exports.xeddsaSign = exports.pbkdf2Sha256 = exports.hmacSha512Sign = exports.hmacSha256Sign = exports.aesCtrDecrypt = exports.aesCtrEncrypt = exports.aesCbcDecrypt = exports.aesCbcEncrypt = exports.aesGcmDecrypt = exports.aesGcmEncrypt = exports.md5Bytes = exports.sha512 = exports.sha256 = exports.sha1 = exports.randomIntAsync = exports.randomFillAsync = exports.randomBytesAsync = exports.writeNonceCounter = exports.readVersionedContent = exports.prependVersion = exports.toRawPubKey = exports.toSerializedPubKey = exports.hkdfSplit = exports.hkdf = exports.X25519 = exports.Ed25519 = void 0;
+exports.xeddsaVerify = exports.xeddsaSign = exports.pbkdf2Sha256 = exports.hmacSha512Sign = exports.hmacSha256Sign = exports.aesCtrDecrypt = exports.aesCtrEncrypt = exports.aesCbcDecrypt = exports.aesCbcEncryptWithTrailer = exports.aesCbcEncrypt = exports.aesGcmDecrypt = exports.aesGcmEncrypt = exports.md5Bytes = exports.sha512 = exports.sha256 = exports.sha1 = exports.randomIntAsync = exports.randomFillAsync = exports.randomBytesAsync = exports.writeNonceCounter = exports.readVersionedContent = exports.prependVersion = exports.toRawPubKey = exports.toSerializedPubKey = exports.hkdfSplit = exports.hkdf = exports.X25519 = exports.Ed25519 = void 0;
 var Ed25519_1 = require("../curves/Ed25519");
 Object.defineProperty(exports, "Ed25519", { enumerable: true, get: function () { return Ed25519_1.Ed25519; } });
 var X25519_1 = require("../curves/X25519");
@@ -30,6 +30,7 @@ Object.defineProperty(exports, "md5Bytes", { enumerable: true, get: function ()
 Object.defineProperty(exports, "aesGcmEncrypt", { enumerable: true, get: function () { return primitives_1.aesGcmEncrypt; } });
 Object.defineProperty(exports, "aesGcmDecrypt", { enumerable: true, get: function () { return primitives_1.aesGcmDecrypt; } });
 Object.defineProperty(exports, "aesCbcEncrypt", { enumerable: true, get: function () { return primitives_1.aesCbcEncrypt; } });
+Object.defineProperty(exports, "aesCbcEncryptWithTrailer", { enumerable: true, get: function () { return primitives_1.aesCbcEncryptWithTrailer; } });
 Object.defineProperty(exports, "aesCbcDecrypt", { enumerable: true, get: function () { return primitives_1.aesCbcDecrypt; } });
 Object.defineProperty(exports, "aesCtrEncrypt", { enumerable: true, get: function () { return primitives_1.aesCtrEncrypt; } });
 Object.defineProperty(exports, "aesCtrDecrypt", { enumerable: true, get: function () { return primitives_1.aesCtrDecrypt; } });