zapo-js 1.9.0 → 1.11.0

package/dist/client/coordinators/WaMessageDispatchCoordinator.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WaMessageDispatchCoordinator = void 0;
 exports.restrictGroupHistoryTargets = restrictGroupHistoryTargets;
+exports.resolveOutboundStanzaShape = resolveOutboundStanzaShape;
 const _crypto_1 = require("../../crypto");
 const primitives_1 = require("../../crypto/core/primitives");
 const PromiseDedup_1 = require("../../infra/perf/PromiseDedup");
@@ -73,6 +74,19 @@ function restrictGroupHistoryTargets(message, participantUserJids, senderJid, on
     }
     return targets;
 }
+/**
+ * Resolves the stanza `type` and `enc.mediatype` of an outbound message. A
+ * `<biz>` companion rides a type=text stanza with no mediatype, except on a
+ * group list: there the server nacks with 479 (SMAX_INVALID) unless
+ * type=media, mediatype=list and `<biz><list>` travel together.
+ */
+function resolveOutboundStanzaShape(attrs, isGroup) {
+    const flattensForAddon = attrs.buttonAddonKind !== null && !(isGroup && attrs.buttonAddonKind === 'list');
+    if (flattensForAddon) {
+        return { type: 'text', mediatype: undefined };
+    }
+    return { type: attrs.typeAttr, mediatype: attrs.mediatype ?? undefined };
+}
 class WaMessageDispatchCoordinator {
     constructor(options) {
         this.icdcDedup = new PromiseDedup_1.PromiseDedup();
@@ -403,12 +417,8 @@ class WaMessageDispatchCoordinator {
         const outboundAttrs = (0, content_1.resolveOutboundMessageAttrs)(messageWithIcdc);
         const buttonAddonKind = outboundAttrs.buttonAddonKind;
         const buttonAddonNode = buttonAddonKind ? (0, message_1.buildButtonAddonNode)(buttonAddonKind) : undefined;
-        // when a <biz> companion is attached the stanza must advertise type=text and
-        // omit enc.mediatype; sending type=media + mediatype=list/button alongside the
-        // companion is rejected by the server as SMAX_INVALID (479).
-        const type = buttonAddonKind ? 'text' : outboundAttrs.typeAttr;
+        const { type, mediatype } = resolveOutboundStanzaShape(outboundAttrs, isGroup);
         const edit = outboundAttrs.edit ?? undefined;
-        const mediatype = buttonAddonKind ? undefined : (outboundAttrs.mediatype ?? undefined);
         const metaAttrs = outboundAttrs.metaAttrs;
         const metaNode = metaAttrs ? (0, message_1.buildMetaNode)(metaAttrs) : undefined;
         const customNodes = [];
@@ -473,11 +483,14 @@ class WaMessageDispatchCoordinator {
         const pair = await this.deps.signalDeviceSync.resolveUserJidPair(directRecipientJid);
         return pair.pnJid ?? undefined;
     }
-    async syncSignalSession(jid, reasonIdentity = false) {
+    async syncSignalSession(jid, { force = false, reasonIdentity = false } = {}) {
         const address = (0, jid_1.parseSignalAddressFromJid)(jid);
         if (address.server === constants_1.WA_DEFAULTS.GROUP_SERVER) {
             throw new Error('syncSignalSession supports only direct chats');
         }
+        if (force || reasonIdentity) {
+            await this.deps.sessionStore.deleteSession(address);
+        }
         await this.deps.sessionResolver.ensureSession(address, jid, undefined, reasonIdentity);
     }
     async sendReceipt(input) {

package/dist/client/coordinators/WaProfileCoordinator.d.ts

@@ -158,7 +158,11 @@ export interface WaProfileCoordinator {
      * @throws when `pin` is not exactly 4 digits, before any round-trip.
      */
     readonly setUsernameKey: (pin: string) => Promise<boolean>;
-    /** Resolves LIDs for a list of phone numbers (handles normalization). */
+    /**
+     * Resolves LIDs for a list of phone numbers (handles normalization). Check
+     * `status`: `'out'` means no WhatsApp account, `'unanswered'` or `'error'` mean
+     * the server gave no verdict (see `error` for the reason).
+     */
     readonly getLidsByPhoneNumbers: (phoneNumbers: readonly string[]) => Promise<readonly SignalLidSyncResult[]>;
 }
 interface WaProfileCoordinatorOptions {

package/dist/client/coordinators/WaStreamControlCoordinator.d.ts

@@ -10,6 +10,8 @@ interface WaStreamControlCoordinatorOptions {
     readonly disconnect: (reason: WaDisconnectReason, isLogout: boolean, code: WaConnectionCode | null) => Promise<void>;
     readonly clearStoredCredentials: () => Promise<void>;
     readonly connect: (reason: WaConnectionOpenReason) => Promise<void>;
+    /** Returns `true` when a pairing restart already owns the force-login `stream:error`. */
+    readonly handlePairingRestart: () => boolean;
 }
 export interface WaStreamControlHandler {
     readonly handleStreamControlResult: (result: WaStreamControlNodeResult) => Promise<void>;

package/dist/client/coordinators/WaStreamControlCoordinator.js

@@ -4,7 +4,7 @@ exports.createStreamControlHandler = createStreamControlHandler;
 const constants_1 = require("../../protocol/constants");
 const primitives_1 = require("../../util/primitives");
 function createStreamControlHandler(options) {
-    const { logger, getComms, clearPendingQueries, clearMediaConnCache, disconnect, clearStoredCredentials, connect } = options;
+    const { logger, getComms, clearPendingQueries, clearMediaConnCache, disconnect, clearStoredCredentials, connect, handlePairingRestart } = options;
     let lifecyclePromise = null;
     const runStreamControlLifecycle = (reason, action) => {
         if (lifecyclePromise) {
@@ -88,6 +88,11 @@ function createStreamControlHandler(options) {
                     logger.info('received xmlstreamend stanza');
                     return;
                 case 'stream_error_code':
+                    if (result.code === constants_1.WA_STREAM_SIGNALING.FORCE_LOGIN_CODE &&
+                        handlePairingRestart()) {
+                        logger.info('stream:error force login claimed by the pairing restart');
+                        return;
+                    }
                     logger.warn('received stream:error with code', { code: result.code });
                     if (result.code >= 500 && result.code < 600) {
                         if (result.code === constants_1.WA_STREAM_SIGNALING.FORCE_LOGIN_CODE) {

package/dist/client/messaging/ignore-key.d.ts

@@ -1,3 +1,4 @@
+import type { WaAuthCredentials } from '../../auth/types';
 import type { WaIgnoreKey, WaIgnoreKeyContext, WaIgnoreKeyPredicate, WaIncomingStanzaFilter } from '../types';
 import type { BinaryNode } from '../../transport/types';
 export declare function validateIgnoreKey(d: WaIgnoreKey): void;
@@ -8,4 +9,4 @@ export declare function validateIgnoreKey(d: WaIgnoreKey): void;
 export declare function extractIgnoreKeyContext(node: BinaryNode, meJid: string | null | undefined): WaIgnoreKeyContext | null;
 /** Pure matcher. Exported for direct testing without a coordinator. */
 export declare function matchesIgnoreKey(node: BinaryNode, d: WaIgnoreKey, meJid: string | null | undefined): boolean;
-export declare function createIgnoreKeyFilter(input: WaIgnoreKey | WaIgnoreKeyPredicate, getMeJid: () => string | null | undefined): WaIncomingStanzaFilter;
+export declare function createIgnoreKeyFilter(input: WaIgnoreKey | WaIgnoreKeyPredicate, getMe: () => Pick<WaAuthCredentials, 'meJid' | 'meLid'> | null | undefined): WaIncomingStanzaFilter;

package/dist/client/messaging/ignore-key.js

@@ -123,12 +123,33 @@ function matchesIgnoreKey(node, d, meJid) {
         return false;
     return true;
 }
-function createIgnoreKeyFilter(input, getMeJid) {
+/**
+ * A `category='peer'` message from our own account is traffic between our own
+ * devices (app-state key share, history sync, PDO responses), not a chat
+ * message, so it has no key to ignore by. Dropping it starves the protocol:
+ * app-state collections stay blocked on a key whose share never gets through.
+ * The own-account check keeps a foreign sender from dodging a filter by
+ * stamping the attribute.
+ */
+function isOwnPeerMessage(node, me) {
+    if (node.tag !== message_1.WA_MESSAGE_TAGS.MESSAGE || node.attrs.category !== 'peer' || !me) {
+        return false;
+    }
+    const from = node.attrs.from;
+    return !!from && tryParseJid(from) !== null && (0, jid_1.isOwnAccountJid)(from, me.meJid, me.meLid);
+}
+function createIgnoreKeyFilter(input, getMe) {
     if (typeof input === 'function') {
         return (node) => {
-            const ctx = extractIgnoreKeyContext(node, getMeJid());
+            const me = getMe();
+            if (isOwnPeerMessage(node, me))
+                return false;
+            const ctx = extractIgnoreKeyContext(node, me?.meJid);
             return ctx !== null && input(ctx);
         };
     }
-    return (node) => matchesIgnoreKey(node, input, getMeJid());
+    return (node) => {
+        const me = getMe();
+        return !isOwnPeerMessage(node, me) && matchesIgnoreKey(node, input, me?.meJid);
+    };
 }

package/dist/client/messaging/messages.js

@@ -228,6 +228,27 @@ async function buildMediaMessageContent(options, content, ctx) {
     if (typeof content === 'string') {
         return { message: { conversation: content } };
     }
+    if ((0, content_1.isSendTypedMessage)(content)) {
+        return withMessageContextInfo(await buildTypedMessageContent(options, content, ctx), content.messageContextInfo);
+    }
+    if (!content || typeof content !== 'object') {
+        throw new Error('invalid message content');
+    }
+    return { message: content };
+}
+/** Adds the caller's `messageContextInfo` under the built one: fields the builder set win. */
+function withMessageContextInfo(built, messageContextInfo) {
+    if (!messageContextInfo)
+        return built;
+    return {
+        ...built,
+        message: {
+            ...built.message,
+            messageContextInfo: { ...messageContextInfo, ...built.message.messageContextInfo }
+        }
+    };
+}
+async function buildTypedMessageContent(options, content, ctx) {
     if ((0, content_1.isSendTextMessage)(content)) {
         if (options.linkPreviewResolver) {
             try {
@@ -267,13 +288,7 @@ async function buildMediaMessageContent(options, content, ctx) {
     if ((0, content_1.isSendEventResponseMessage)(content)) {
         return { message: await buildEventResponseMessage(content, options.serverClock, ctx) };
     }
-    if ((0, content_1.isSendMediaMessage)(content)) {
-        return buildMediaMessage(options, content);
-    }
-    if (!content || typeof content !== 'object') {
-        throw new Error('invalid message content');
-    }
-    return { message: content };
+    return buildMediaMessage(options, content);
 }
 async function getMediaConn(options, forceRefresh = false) {
     const cached = options.getMediaConnCache();
@@ -394,7 +409,8 @@ async function buildMediaMessage(options, content) {
                 if (key !== 'type' &&
                     key !== 'media' &&
                     key !== 'fileLength' &&
-                    key !== 'mimetype') {
+                    key !== 'mimetype' &&
+                    key !== 'messageContextInfo') {
                     result[key] = c[key];
                 }
             }

package/dist/client/persistence/history-sync.d.ts

@@ -1,5 +1,5 @@
 import type { WriteBehindPersistence } from '../persistence/WriteBehindPersistence';
-import type { WaClientEventMap } from '../types';
+import type { WaClientEventMap, WaHistorySyncSink } from '../types';
 import type { Logger } from '../../infra/log/types';
 import type { WaMediaTransferClient } from '../../media/transfer/WaMediaTransferClient';
 import { type Proto } from '../../proto';
@@ -27,6 +27,9 @@ interface WaHistorySyncDeps {
     readonly logger: Logger;
     readonly mediaTransfer: WaMediaTransferClient;
     readonly writeBehind: WriteBehindPersistence;
+    /** Id of the protocol message that carried the notification; empty when the caller has none. */
+    readonly chunkId?: string;
+    readonly sink?: WaHistorySyncSink;
     readonly chatMetadataStore?: WaChatMetadataStore;
     readonly emitEvent: <K extends keyof WaClientEventMap>(event: K, ...args: Parameters<WaClientEventMap[K]>) => void;
     readonly onPrivacyTokens?: (conversations: readonly WaHistorySyncPrivacyTokenConversation[]) => Promise<void>;
@@ -41,6 +44,7 @@ export declare function runHistorySyncNotification(deps: WaHistorySyncDeps, noti
  * Applies one history sync chunk while it downloads, descending into
  * `conversations` so peak memory tracks the largest single message and not the
  * chunk. Chunk-wide records settle after the stream, once every LID mapping is in.
+ * `INITIAL_STATUS_V3` is processed only for a sink and never emits `history_sync_chunk`.
  */
 export declare function processHistorySyncNotification(deps: WaHistorySyncDeps, notification: Proto.Message.IHistorySyncNotification): Promise<void>;
 export {};

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

@@ -40,6 +40,26 @@ exports.HISTORY_SYNC_FIELDS = Object.freeze({
     NCT_SALT: 19,
     INLINE_CONTACTS: 20
 });
+const HISTORY_SYNC_SINK_KEYS = new Map([
+    [3, 'statusV3Messages'],
+    [5, 'chunkOrder'],
+    [6, 'progress'],
+    [7, 'pushnames'],
+    [8, 'globalSettings'],
+    [9, 'threadIdUserSecret'],
+    [10, 'threadDsTimeframeOffset'],
+    [11, 'recentStickers'],
+    [12, 'pastParticipants'],
+    [13, 'callLogRecords'],
+    [14, 'aiWaitListState'],
+    [15, 'phoneNumberToLidMappings'],
+    [16, 'companionMetaNonce'],
+    [17, 'shareableChatIdentifierEncryptionKey'],
+    [18, 'accounts'],
+    [19, 'nctSalt'],
+    [20, 'inlineContacts'],
+    [21, 'inlineContactsProvided']
+]);
 exports.CONVERSATION_FIELDS = Object.freeze({
     ID: 1,
     MESSAGES: 2
@@ -60,6 +80,7 @@ async function runHistorySyncNotification(deps, notification) {
  * Applies one history sync chunk while it downloads, descending into
  * `conversations` so peak memory tracks the largest single message and not the
  * chunk. Chunk-wide records settle after the stream, once every LID mapping is in.
+ * `INITIAL_STATUS_V3` is processed only for a sink and never emits `history_sync_chunk`.
  */
 async function processHistorySyncNotification(deps, notification) {
     const syncType = notification.syncType;
@@ -67,15 +88,17 @@ async function processHistorySyncNotification(deps, notification) {
         deps.logger.debug('skipping history sync notification without syncType');
         return;
     }
-    if (!HANDLED_SYNC_TYPES.has(syncType)) {
+    const isStatusV3 = syncType === _proto_1.proto.Message.HistorySyncType.INITIAL_STATUS_V3;
+    if (!HANDLED_SYNC_TYPES.has(syncType) && !(isStatusV3 && deps.sink)) {
         deps.logger.debug('skipping unhandled history sync type', { syncType });
-        if (syncType === _proto_1.proto.Message.HistorySyncType.INITIAL_STATUS_V3 && deps.onProcessed) {
+        if (isStatusV3 && deps.onProcessed) {
             await deps.onProcessed(syncType);
         }
         return;
     }
     const blob = await (0, history_blob_1.openHistoryBlobStream)(deps.mediaTransfer, notification, 'history', 'history sync', notification.initialHistBootstrapInlinePayload);
     const state = {
+        chunk: { id: deps.chunkId ?? '', syncType },
         nowMs: Date.now(),
         pendingWrites: [],
         pushnames: [],
@@ -88,6 +111,23 @@ async function processHistorySyncNotification(deps, notification) {
         conversationsCount: 0,
         messagesCount: 0
     };
+    let event;
+    try {
+        event = await applyHistorySyncChunk(deps, blob, state);
+    }
+    catch (error) {
+        const failure = (0, primitives_1.toError)(error);
+        await abortHistorySink(deps, state.chunk, failure);
+        throw failure;
+    }
+    if (!isStatusV3) {
+        deps.emitEvent('history_sync_chunk', event);
+    }
+    if (deps.onProcessed) {
+        await deps.onProcessed(syncType);
+    }
+}
+async function applyHistorySyncChunk(deps, blob, state) {
     try {
         await consumeHistorySyncStream(deps, blob.inflated, state);
     }
@@ -100,7 +140,7 @@ async function processHistorySyncNotification(deps, notification) {
     await blob.verified;
     await settleHistorySyncChunk(deps, state);
     deps.logger.info('decoded history sync chunk', {
-        syncType,
+        syncType: state.chunk.syncType,
         chunkOrder: state.chunkOrder,
         progress: state.progress,
         conversations: state.conversationsCount,
@@ -109,7 +149,8 @@ async function processHistorySyncNotification(deps, notification) {
         inlineContacts: state.inlineContacts.length
     });
     const event = {
-        syncType,
+        id: state.chunk.id,
+        syncType: state.chunk.syncType,
         messagesCount: state.messagesCount,
         conversationsCount: state.conversationsCount,
         pushnamesCount: state.pushnames.length,
@@ -118,15 +159,53 @@ async function processHistorySyncNotification(deps, notification) {
         progress: state.progress ?? undefined
     };
     await (0, history_blob_1.flushPendingWrites)(state.pendingWrites);
-    deps.emitEvent('history_sync_chunk', event);
-    if (deps.onProcessed) {
-        await deps.onProcessed(syncType);
+    if (deps.sink?.commit) {
+        await deps.sink.commit(event);
     }
+    return event;
+}
+/** A throwing `abort` is logged so it never hides the failure that triggered it. */
+async function abortHistorySink(deps, chunk, error) {
+    if (!deps.sink?.abort) {
+        return;
+    }
+    try {
+        await deps.sink.abort(chunk, error);
+    }
+    catch (abortError) {
+        deps.logger.warn('history sync sink abort failed', {
+            id: chunk.id,
+            message: (0, primitives_1.toError)(abortError).message
+        });
+    }
+}
+/** Only a thenable result is surfaced, so a synchronous sink never adds an await. */
+function deliverHistoryItem(sink, chunk, item) {
+    const result = sink.item(item, chunk);
+    return typeof result?.then === 'function'
+        ? Promise.resolve(result)
+        : undefined;
+}
+function deliverHistoryValue(sink, chunk, key, value) {
+    return deliverHistoryItem(sink, chunk, { kind: key, value });
+}
+/**
+ * Delivers a `HistorySync` field the stores do not consume. The field is decoded
+ * from a copy because the reader buffer is reused and `bytes` values are views of
+ * their input; one occurrence of a repeated field yields a single element.
+ */
+function deliverHistoryField(sink, chunk, key, event) {
+    const decoded = _proto_1.proto.HistorySync.decode(event.raw.slice())[key];
+    const value = Array.isArray(decoded) ? decoded[0] : decoded;
+    return value === null || value === undefined
+        ? undefined
+        : deliverHistoryValue(sink, chunk, key, value);
 }
 async function consumeHistorySyncStream(deps, inflated, state) {
     let headerParts = null;
     let threadJid = null;
     let parked = null;
+    const sink = deps.sink;
     const onEvent = (event) => {
         if (event.kind === proto_stream_1.PROTO_STREAM_EVENT_KINDS.ENTER) {
             headerParts = [];
@@ -147,20 +226,37 @@ async function consumeHistorySyncStream(deps, inflated, state) {
         if (event.depth === 1) {
             if (event.fieldNumber === exports.CONVERSATION_FIELDS.MESSAGES &&
                 event.wireType === protoscan_1.PROTO_WIRE_TYPES.LEN) {
-                const message = readHistoryMessage(event.value);
-                if (!message) {
+                const record = _proto_1.proto.HistorySyncMsg.decode(sink ? event.value.slice() : event.value);
+                const webMsg = record.message;
+                if (!webMsg && !sink) {
                     return undefined;
                 }
+                const stored = webMsg ? toStoredHistoryMessage(webMsg) : null;
                 if (!threadJid) {
+                    if (!stored && !sink) {
+                        return undefined;
+                    }
                     parked ?? (parked = []);
                     if (parked.length >= HISTORY_SYNC_MAX_PARKED_MESSAGES) {
                         throw new Error(`history sync parked ${parked.length} messages with no thread jid, exceeding the ${HISTORY_SYNC_MAX_PARKED_MESSAGES} limit`);
                     }
-                    parked[parked.length] = message;
+                    parked[parked.length] = { stored, record: sink ? record : null };
                     return undefined;
                 }
-                persistHistoryMessage(deps, state, message, threadJid);
-                return maybeFlush(state);
+                if (stored) {
+                    persistHistoryMessage(deps, state, stored, threadJid);
+                }
+                const delivery = sink
+                    ? deliverHistoryItem(sink, state.chunk, {
+                        kind: 'conversations.messages',
+                        conversationId: threadJid,
+                        value: record
+                    })
+                    : undefined;
+                const flush = maybeFlush(state);
+                return delivery && flush
+                    ? Promise.all([delivery, flush]).then(() => undefined)
+                    : (delivery ?? flush);
             }
             if (headerParts) {
                 if (event.fieldNumber === exports.CONVERSATION_FIELDS.ID &&
@@ -177,35 +273,52 @@ async function consumeHistorySyncStream(deps, inflated, state) {
         if (event.wireType === protoscan_1.PROTO_WIRE_TYPES.VARINT) {
             if (event.fieldNumber === exports.HISTORY_SYNC_FIELDS.CHUNK_ORDER) {
                 state.chunkOrder = event.varintValue;
+                return sink
+                    ? deliverHistoryValue(sink, state.chunk, 'chunkOrder', event.varintValue)
+                    : undefined;
             }
             else if (event.fieldNumber === exports.HISTORY_SYNC_FIELDS.PROGRESS) {
                 state.progress = event.varintValue;
+                return sink
+                    ? deliverHistoryValue(sink, state.chunk, 'progress', event.varintValue)
+                    : undefined;
             }
-            return undefined;
         }
-        if (event.wireType !== protoscan_1.PROTO_WIRE_TYPES.LEN) {
-            return undefined;
-        }
-        if (event.fieldNumber === exports.HISTORY_SYNC_FIELDS.PUSHNAMES) {
-            state.pushnames[state.pushnames.length] = _proto_1.proto.Pushname.decode(event.value);
-        }
-        else if (event.fieldNumber === exports.HISTORY_SYNC_FIELDS.PHONE_NUMBER_TO_LID_MAPPINGS) {
-            const map = _proto_1.proto.PhoneNumberToLIDMapping.decode(event.value);
-            if (map.pnJid && map.lidJid) {
-                state.pnToLid.set(map.pnJid, map.lidJid);
+        else if (event.wireType === protoscan_1.PROTO_WIRE_TYPES.LEN) {
+            if (event.fieldNumber === exports.HISTORY_SYNC_FIELDS.PUSHNAMES) {
+                const pushname = _proto_1.proto.Pushname.decode(sink ? event.value.slice() : event.value);
+                state.pushnames[state.pushnames.length] = pushname;
+                return sink
+                    ? deliverHistoryValue(sink, state.chunk, 'pushnames', pushname)
+                    : undefined;
             }
-        }
-        else if (event.fieldNumber === exports.HISTORY_SYNC_FIELDS.INLINE_CONTACTS) {
-            const contact = _proto_1.proto.InlineContact.decode(event.value);
-            state.inlineContacts[state.inlineContacts.length] = contact;
-            if (contact.pnJid && contact.lidJid) {
-                state.pnToLid.set(contact.pnJid, contact.lidJid);
+            else if (event.fieldNumber === exports.HISTORY_SYNC_FIELDS.PHONE_NUMBER_TO_LID_MAPPINGS) {
+                const mapping = _proto_1.proto.PhoneNumberToLIDMapping.decode(sink ? event.value.slice() : event.value);
+                if (mapping.pnJid && mapping.lidJid) {
+                    state.pnToLid.set(mapping.pnJid, mapping.lidJid);
+                }
+                return sink
+                    ? deliverHistoryValue(sink, state.chunk, 'phoneNumberToLidMappings', mapping)
+                    : undefined;
+            }
+            else if (event.fieldNumber === exports.HISTORY_SYNC_FIELDS.INLINE_CONTACTS) {
+                const contact = _proto_1.proto.InlineContact.decode(sink ? event.value.slice() : event.value);
+                state.inlineContacts[state.inlineContacts.length] = contact;
+                if (contact.pnJid && contact.lidJid) {
+                    state.pnToLid.set(contact.pnJid, contact.lidJid);
+                }
+                return sink
+                    ? deliverHistoryValue(sink, state.chunk, 'inlineContacts', contact)
+                    : undefined;
+            }
+            else if (event.fieldNumber === exports.HISTORY_SYNC_FIELDS.NCT_SALT) {
+                const salt = event.value.slice();
+                state.nctSalt = salt;
+                return sink ? deliverHistoryValue(sink, state.chunk, 'nctSalt', salt) : undefined;
             }
         }
-        else if (event.fieldNumber === exports.HISTORY_SYNC_FIELDS.NCT_SALT) {
-            state.nctSalt = event.value.slice();
-        }
-        return undefined;
+        const key = sink ? HISTORY_SYNC_SINK_KEYS.get(event.fieldNumber) : undefined;
+        return sink && key ? deliverHistoryField(sink, state.chunk, key, event) : undefined;
     };
     await (0, proto_stream_1.streamProtoFields)(inflated, onEvent, {
         shouldDescend: (fieldNumber, depth) => depth === 0 && fieldNumber === exports.HISTORY_SYNC_FIELDS.CONVERSATIONS,
@@ -284,8 +397,30 @@ async function closeConversation(deps, state, headerParts, threadJid, parked) {
             }));
         }
     }
-    for (const message of parked ?? []) {
-        persistHistoryMessage(deps, state, message, resolvedJid);
+    const sink = deps.sink;
+    for (const entry of parked ?? []) {
+        if (entry.stored) {
+            persistHistoryMessage(deps, state, entry.stored, resolvedJid);
+        }
+        if (sink && entry.record) {
+            const delivery = deliverHistoryItem(sink, state.chunk, {
+                kind: 'conversations.messages',
+                conversationId: resolvedJid,
+                value: entry.record
+            });
+            if (delivery) {
+                await delivery;
+            }
+        }
+    }
+    if (sink) {
+        const delivery = deliverHistoryItem(sink, state.chunk, {
+            kind: 'conversations',
+            value: conversation
+        });
+        if (delivery) {
+            await delivery;
+        }
     }
     await maybeFlush(state);
 }
@@ -367,9 +502,8 @@ async function settleHistorySyncChunk(deps, state) {
     }
 }
 /** `null` for content-less stubs, which duplicate live notification stanzas. */
-function readHistoryMessage(record) {
-    const webMsg = _proto_1.proto.HistorySyncMsg.decode(record).message;
-    if (!webMsg?.key?.id || !webMsg.message) {
+function toStoredHistoryMessage(webMsg) {
+    if (!webMsg.key?.id || !webMsg.message) {
         return null;
     }
     const timestampMs = (0, primitives_1.longToNumber)(webMsg.messageTimestamp) * 1000;

package/dist/client/types.d.ts

@@ -148,11 +148,12 @@ export interface WaClientOptions extends WaAuthClientOptions, WaAuthSocketOption
      * History-sync behavior. By default chunks pushed via
      * `historySyncNotification` (both the initial bootstrap and the
      * 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;
-     * `groupBundles: true` opts into the group-history bundle a member may
-     * share after somebody joins a group.
+     * downloaded, written to the stores and emitted as `history_sync_chunk`
+     * events. `sink` streams the decoded content to your own callback, with
+     * or without stores. Set `enabled: false` to drop the chunks;
+     * `requireFullSync: true` asks the 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;
     /**
@@ -313,11 +314,22 @@ export interface WaHistorySyncOptions {
      * Whether to process the `historySyncNotification` protocol messages
      * that WhatsApp pushes on first connect (initial bootstrap) and via
      * `message.requestHistorySync` (on-demand). On by default - set to
-     * `false` to drop the chunks silently (useful when you do not persist
-     * mailbox/threads/contacts and the conversation download would just
-     * burn bandwidth).
+     * `false` to drop the chunks silently (and skip `sink`): the primary is
+     * still acked, but nothing is downloaded or delivered.
      */
     readonly enabled?: boolean;
+    /**
+     * Receives every field of the decoded history as it streams, awaited per item,
+     * even with every store off; it alone receives the `INITIAL_STATUS_V3` chunk,
+     * which is otherwise only acked and never emits `history_sync_chunk`. A slow
+     * sink pauses the download: the media timeout ends at the headers.
+     */
+    readonly sink?: WaHistorySyncSink;
+    /**
+     * When `true`, request a full history download from the primary device on
+     * pairing instead of just recent messages. Takes precedence over the
+     * top-level `requireFullSync`; has no effect on an already-paired session.
+     */
     readonly requireFullSync?: boolean;
     /**
      * Whether to download and process the group-history bundle a member may
@@ -1101,9 +1113,51 @@ export interface WaGroupEvent extends WaIncomingBaseEvent {
     /** Decoded payload bag for actions without dedicated fields above. */
     readonly details?: Readonly<Record<string, unknown>>;
 }
-export interface WaHistorySyncChunkEvent {
+/** Identifies one history-sync chunk; chunks can be processed concurrently. */
+export interface WaHistorySyncChunkRef {
+    /** Id of the protocol message that carried the notification. */
+    readonly id: string;
     /** Numeric value of `proto.Message.HistorySyncType` (`RECENT`, `ON_DEMAND`, …). */
     readonly syncType: number;
+}
+type WaHistorySyncElement<T> = T extends readonly (infer E)[] ? E : T;
+type WaHistorySyncKey = Exclude<keyof Proto.IHistorySync, 'syncType' | 'conversations' | '$unknowns'>;
+/**
+ * One decoded record of a history-sync chunk. `kind` is the `HistorySync` field it
+ * came from, one element per item for repeated fields; `syncType` rides on the chunk ref.
+ * Conversation messages precede their metadata on the wire, so they stream out first as
+ * `conversations.messages` and the conversation arrives at its close, without `messages`.
+ */
+export type WaHistorySyncItem = {
+    [K in WaHistorySyncKey]-?: {
+        readonly kind: K;
+        readonly value: NonNullable<WaHistorySyncElement<NonNullable<Proto.IHistorySync[K]>>>;
+    };
+}[WaHistorySyncKey] | {
+    readonly kind: 'conversations';
+    readonly value: Omit<Proto.IConversation, 'messages'>;
+} | {
+    readonly kind: 'conversations.messages';
+    readonly conversationId: string;
+    /** Includes stubs and records without content, which the stores skip. */
+    readonly value: Proto.IHistorySyncMsg;
+};
+export interface WaHistorySyncSink {
+    /**
+     * Called per record in wire order. A returned promise pauses the stream until
+     * it settles; a throw or rejection aborts the chunk. Items arrive before the
+     * chunk MAC is verified.
+     */
+    item(item: WaHistorySyncItem, chunk: WaHistorySyncChunkRef): void | Promise<void>;
+    /** Called once the chunk verified and applied; the receipt goes out after it resolves. */
+    commit?(chunk: WaHistorySyncChunkEvent): void | Promise<void>;
+    /**
+     * Called when the chunk fails after items may have been delivered. The primary
+     * resends it, so items repeat: dedupe by `key.id`.
+     */
+    abort?(chunk: WaHistorySyncChunkRef, error: Error): void | Promise<void>;
+}
+export interface WaHistorySyncChunkEvent extends WaHistorySyncChunkRef {
     readonly messagesCount: number;
     readonly conversationsCount: number;
     readonly pushnamesCount: number;
@@ -1209,7 +1263,8 @@ export interface WaClientEventMap {
     }) => void;
     /**
      * The server is ready to receive pairing input. `forceManual: true` means
-     * the QR refresh budget was exhausted and the user must request a fresh
+     * the QR refresh budget was exhausted, or a pending pairing code could not
+     * be registered again after a reconnect, and the user must request a fresh
      * one (e.g. via the link-code flow).
      */
     readonly auth_pairing_required: (event: {