zapo-js 1.10.0 → 1.11.0

package/dist/auth/WaAuthClient.d.ts

@@ -146,6 +146,11 @@ export declare class WaAuthClient {
      * call this. The user then enters the returned code in WhatsApp on their
      * phone under *Linked Devices → Link with phone number instead*.
      *
+     * The server binds the code to the connection that requested it. If the
+     * socket drops and reconnects first, the client registers the same code on
+     * the new connection; if that fails, `auth_pairing_required` fires with
+     * `forceManual: true` and a new code must be requested.
+     *
      * @example
      * ```ts
      * // Start the handshake; do NOT await – connect() resolves only after pairing

package/dist/auth/WaAuthClient.js

@@ -307,6 +307,11 @@ class WaAuthClient {
      * call this. The user then enters the returned code in WhatsApp on their
      * phone under *Linked Devices → Link with phone number instead*.
      *
+     * The server binds the code to the connection that requested it. If the
+     * socket drops and reconnects first, the client registers the same code on
+     * the new connection; if that fails, `auth_pairing_required` fires with
+     * `forceManual: true` and a new code must be requested.
+     *
      * @example
      * ```ts
      * // Start the handshake; do NOT await – connect() resolves only after pairing

package/dist/auth/pairing/WaPairingFlow.d.ts

@@ -31,6 +31,7 @@ interface WaPairingFlowOptions {
 export declare class WaPairingFlow {
     private readonly opts;
     private pairingSession;
+    private rearmGeneration;
     private pairSuccessInFlight;
     constructor(options: WaPairingFlowOptions);
     hasPairingSession(): boolean;
@@ -48,6 +49,16 @@ export declare class WaPairingFlow {
     /** Mirrors the `not-authorized` IQ error WhatsApp Web returns on a failed pair-success. */
     private sendPairSuccessValidationError;
     private handlePrimaryHello;
+    private sendCompanionHello;
+    /**
+     * The server delivers `primary_hello` only to the connection that sent the
+     * `companion_hello`, so a code requested on a dropped connection is dead.
+     * Registers the same code again, without a push, like WA Web's code refresh.
+     * The ADV secret is not rotated: the QR just emitted for this connection carries it.
+     * Only the latest pair-device may settle the session, since an older attempt can
+     * outlive its dropped connection until the IQ times out.
+     */
+    private rearmPairingCode;
     private rotateAdvSecret;
     private requireCredentials;
 }

package/dist/auth/pairing/WaPairingFlow.js

@@ -19,6 +19,7 @@ const PAIR_SUCCESS_DEVICE_IDENTITY_MIN_BYTES = 1;
 const PAIR_SUCCESS_DEVICE_IDENTITY_MAX_BYTES = 500;
 class WaPairingFlow {
     constructor(options) {
+        this.rearmGeneration = 0;
         this.pairSuccessInFlight = false;
         this.opts = options;
         this.pairingSession = null;
@@ -38,49 +39,17 @@ class WaPairingFlow {
         const normalizedCustomCode = customCode !== undefined ? (0, pairing_code_crypto_1.normalizeCustomPairingCode)(customCode) : undefined;
         const credentials = this.requireCredentials();
         const phoneJid = (0, jid_1.parsePhoneJid)(phoneNumber);
-        const createdAtSeconds = Math.floor(Date.now() / 1000);
-        const [companionHello, refreshedCredentials] = await Promise.all([
-            (0, pairing_code_crypto_1.createCompanionHello)({ customCode: normalizedCustomCode }),
+        const [session] = await Promise.all([
+            this.sendCompanionHello(phoneJid, shouldShowPushNotification, normalizedCustomCode),
             this.rotateAdvSecret(credentials)
         ]);
-        const browserDisplayName = (0, browser_1.getWaBrowserDisplayName)(this.opts.device.browser);
-        const response = await this.opts.socket.query((0, pairing_1.buildCompanionHelloRequestNode)({
-            phoneJid,
-            shouldShowPushNotification,
-            wrappedCompanionEphemeralPub: companionHello.wrappedCompanionEphemeralPub,
-            companionServerAuthKeyPub: refreshedCredentials.noiseKeyPair.pubKey,
-            companionPlatformId: this.opts.device.platform,
-            companionPlatformDisplay: `${browserDisplayName} (${this.opts.device.osDisplayName})`
-        }), constants_1.WA_DEFAULTS.IQ_TIMEOUT_MS);
-        this.opts.logger.debug('pairing code request response received', {
-            responseTag: response.tag,
-            responseType: response.attrs.type
-        });
-        (0, query_1.assertIqResult)(response, 'companion hello');
-        const linkCodeNode = (0, helpers_1.findNodeChild)(response, constants_1.WA_NODE_TAGS.LINK_CODE_COMPANION_REG);
-        if (!linkCodeNode) {
-            throw new Error('companion hello response missing link_code_companion_reg');
-        }
-        const refNode = (0, helpers_1.findNodeChild)(linkCodeNode, constants_1.WA_NODE_TAGS.LINK_CODE_PAIRING_REF);
-        if (!refNode) {
-            throw new Error('companion hello response missing link_code_pairing_ref');
-        }
-        const ref = (0, helpers_1.decodeNodeContentUtf8OrBytes)(refNode.content, 'link_code_pairing_ref');
-        this.pairingSession = {
-            pairingCode: companionHello.pairingCode,
-            phoneJid,
-            ref,
-            createdAtSeconds,
-            companionEphemeralKeyPair: companionHello.companionEphemeralKeyPair,
-            attempts: 0,
-            finished: false
-        };
-        this.opts.callbacks.emitPairingCode(companionHello.pairingCode);
+        this.pairingSession = session;
+        this.opts.callbacks.emitPairingCode(session.pairingCode);
         this.opts.logger.debug('pairing code emitted', {
             phoneJid,
-            createdAtSeconds: this.pairingSession.createdAtSeconds
+            createdAtSeconds: session.createdAtSeconds
         });
-        return companionHello.pairingCode;
+        return session.pairingCode;
     }
     async fetchPairingCountryCodeIso() {
         this.opts.logger.trace('fetching pairing country code ISO');
@@ -170,6 +139,15 @@ class WaPairingFlow {
         await this.opts.socket.sendNode((0, global_1.buildIqResultNode)(iqNode));
         this.opts.qrFlow.setRefs(refs);
         this.opts.logger.debug('pair-device refs updated', { refsCount: refs.length });
+        // The server sends pair-device once per connection: a pending code belongs to an older one.
+        if (this.pairingSession) {
+            const generation = ++this.rearmGeneration;
+            void this.rearmPairingCode(this.pairingSession, generation).catch((error) => {
+                this.opts.logger.warn('pairing code re-registration failed unexpectedly', {
+                    message: (0, primitives_1.toError)(error).message
+                });
+            });
+        }
     }
     async handlePairSuccess(iqNode, pairSuccessNode) {
         if (this.pairSuccessInFlight) {
@@ -231,7 +209,13 @@ class WaPairingFlow {
             await this.sendPairSuccessValidationError(iqNode);
             throw new Error('pair-success account signature validation failed');
         }
-        const { signedIdentity, keyIndex, responseIdentityBytes } = built;
+        const { signedIdentity, keyIndex, responseIdentityBytes, advDeviceIdentity } = built;
+        this.opts.logger.debug('pair-success adv identity', {
+            envelopeAccountType: wrappedIdentity.accountType ?? null,
+            accountType: advDeviceIdentity.accountType ?? null,
+            deviceType: advDeviceIdentity.deviceType ?? null,
+            keyIndex: advDeviceIdentity.keyIndex ?? null
+        });
         const nextCredentials = {
             ...credentials,
             signedIdentity,
@@ -301,7 +285,8 @@ class WaPairingFlow {
         return {
             signedIdentity,
             keyIndex: advDeviceIdentity.keyIndex ?? 0,
-            responseIdentityBytes
+            responseIdentityBytes,
+            advDeviceIdentity
         };
     }
     /** Mirrors the `not-authorized` IQ error WhatsApp Web returns on a failed pair-success. */
@@ -377,6 +362,78 @@ class WaPairingFlow {
         pairingSession.finished = true;
         this.opts.logger.debug('primary_hello completed with companion_finish success');
     }
+    async sendCompanionHello(phoneJid, shouldShowPushNotification, customCode) {
+        const credentials = this.requireCredentials();
+        const createdAtSeconds = Math.floor(Date.now() / 1000);
+        const companionHello = await (0, pairing_code_crypto_1.createCompanionHello)({ customCode });
+        const browserDisplayName = (0, browser_1.getWaBrowserDisplayName)(this.opts.device.browser);
+        const response = await this.opts.socket.query((0, pairing_1.buildCompanionHelloRequestNode)({
+            phoneJid,
+            shouldShowPushNotification,
+            wrappedCompanionEphemeralPub: companionHello.wrappedCompanionEphemeralPub,
+            companionServerAuthKeyPub: credentials.noiseKeyPair.pubKey,
+            companionPlatformId: this.opts.device.platform,
+            companionPlatformDisplay: `${browserDisplayName} (${this.opts.device.osDisplayName})`
+        }), constants_1.WA_DEFAULTS.IQ_TIMEOUT_MS);
+        this.opts.logger.debug('pairing code request response received', {
+            responseTag: response.tag,
+            responseType: response.attrs.type
+        });
+        (0, query_1.assertIqResult)(response, 'companion hello');
+        const linkCodeNode = (0, helpers_1.findNodeChild)(response, constants_1.WA_NODE_TAGS.LINK_CODE_COMPANION_REG);
+        if (!linkCodeNode) {
+            throw new Error('companion hello response missing link_code_companion_reg');
+        }
+        const refNode = (0, helpers_1.findNodeChild)(linkCodeNode, constants_1.WA_NODE_TAGS.LINK_CODE_PAIRING_REF);
+        if (!refNode) {
+            throw new Error('companion hello response missing link_code_pairing_ref');
+        }
+        return {
+            pairingCode: companionHello.pairingCode,
+            phoneJid,
+            ref: (0, helpers_1.decodeNodeContentUtf8OrBytes)(refNode.content, 'link_code_pairing_ref'),
+            createdAtSeconds,
+            companionEphemeralKeyPair: companionHello.companionEphemeralKeyPair,
+            attempts: 0,
+            finished: false
+        };
+    }
+    /**
+     * The server delivers `primary_hello` only to the connection that sent the
+     * `companion_hello`, so a code requested on a dropped connection is dead.
+     * Registers the same code again, without a push, like WA Web's code refresh.
+     * The ADV secret is not rotated: the QR just emitted for this connection carries it.
+     * Only the latest pair-device may settle the session, since an older attempt can
+     * outlive its dropped connection until the IQ times out.
+     */
+    async rearmPairingCode(previous, generation) {
+        const isCurrent = () => this.pairingSession === previous && this.rearmGeneration === generation;
+        try {
+            const session = await this.sendCompanionHello(previous.phoneJid, false, previous.pairingCode);
+            if (!isCurrent()) {
+                this.opts.logger.debug('pairing code re-registration superseded');
+                return;
+            }
+            this.pairingSession = session;
+            this.opts.logger.info('pairing code re-registered on the new connection', {
+                phoneJid: session.phoneJid
+            });
+        }
+        catch (error) {
+            const message = (0, primitives_1.toError)(error).message;
+            if (!isCurrent()) {
+                this.opts.logger.debug('superseded pairing code re-registration failed', {
+                    message
+                });
+                return;
+            }
+            this.pairingSession = null;
+            this.opts.logger.warn('failed to re-register pairing code on the new connection', {
+                message
+            });
+            this.opts.callbacks.emitPairingRefresh(true);
+        }
+    }
     async rotateAdvSecret(credentials) {
         const nextCredentials = {
             ...credentials,

package/dist/client/WaClient.js

@@ -275,6 +275,8 @@ class WaClientImpl extends node_events_1.EventEmitter {
                         mediaTransfer: this.mediaTransfer,
                         chatMetadataStore: this.stores.chatMetadata,
                         writeBehind: this.writeBehind,
+                        chunkId: event.key.id,
+                        sink: this.options.history?.sink,
                         emitEvent: this.emit.bind(this),
                         onPrivacyTokens: (conversations) => this.deps.trustedContactToken.hydrateFromHistorySync(conversations),
                         onNctSalt: (salt) => this.deps.trustedContactToken.hydrateNctSaltFromHistorySync(salt),

package/dist/client/WaClientFactory.js

@@ -211,7 +211,7 @@ function buildWaClientDependencies(input) {
     let connectionManager = null;
     let passiveTasks = null;
     let mediaConnCacheFallback = null;
-    let scheduleReconnectAfterPairing = () => undefined;
+    let awaitServerRestartAfterPairing = () => undefined;
     const serverClock = (0, clock_1.createServerClock)(() => connectionManager?.getClockSkewMs() ?? null);
     const nodeTransport = new WaNodeTransport_1.WaNodeTransport(logger);
     const nodeOrchestrator = new WaNodeOrchestrator_1.WaNodeOrchestrator({
@@ -338,7 +338,7 @@ function buildWaClientDependencies(input) {
         deviceOsDisplayName: options.deviceOsDisplayName,
         deviceOsVersion: options.deviceOsVersion,
         devicePlatform: options.devicePlatform,
-        requireFullSync: options.requireFullSync,
+        requireFullSync: options.history?.requireFullSync ?? options.requireFullSync,
         version: options.version,
         dangerous: options.dangerous,
         mobileTransport: options.mobileTransport
@@ -358,7 +358,7 @@ function buildWaClientDependencies(input) {
             onPairingRefresh: (forceManual) => runtime.emitEvent('auth_pairing_required', { forceManual }),
             onPaired: (credentials) => {
                 runtime.emitEvent('auth_paired', { credentials });
-                scheduleReconnectAfterPairing();
+                awaitServerRestartAfterPairing();
             },
             onError: (error) => runtime.handleError(error),
             onPasskeyRequired: (hasSigner) => runtime.emitEvent('auth_passkey_required', { hasSigner }),
@@ -671,7 +671,7 @@ function buildWaClientDependencies(input) {
     if (mediaConnCacheFallback !== null) {
         connectionManager.setMediaConnCache(mediaConnCacheFallback);
     }
-    scheduleReconnectAfterPairing = () => connectionManager?.scheduleReconnectAfterPairing();
+    awaitServerRestartAfterPairing = () => connectionManager?.awaitServerRestartAfterPairing();
     const disconnectWithClientSideEffects = async (reason, isLogout, code) => {
         abPropsCoordinator.reset();
         offlineResume.reset();
@@ -712,7 +712,8 @@ function buildWaClientDependencies(input) {
         },
         disconnect: disconnectWithClientSideEffects,
         clearStoredCredentials: clearStoredCredentialsWithClientSideEffects,
-        connect: connectWithClientSideEffects
+        connect: connectWithClientSideEffects,
+        handlePairingRestart: () => connectionManager?.handleServerRestartRequest() ?? false
     });
     const incomingMessageAckOptions = {
         logger,

package/dist/client/connection/WaConnectionManager.d.ts

@@ -33,14 +33,24 @@ export declare class WaConnectionManager {
     private mediaConnCache;
     private connectPromise;
     private pairingReconnectPromise;
-    private pairingReconnectTimeout;
+    private pairRestartTimer;
     private frameHandler;
     private pendingComms;
     private lifecycleGeneration;
     private lifecycleQueue;
     constructor(options: WaConnectionManagerOptions);
     connect(frameHandler: (frame: Uint8Array) => Promise<void>): Promise<void>;
-    scheduleReconnectAfterPairing(): void;
+    /**
+     * Starts the post-pairing restart window: the server ends the unregistered connection
+     * itself (`stream:error` 515, as WA Web waits for), so the socket stays open until that
+     * signal, a server close, or the fallback timer, whichever comes first.
+     */
+    awaitServerRestartAfterPairing(): void;
+    /**
+     * Claims a `stream:error` 515 for the post-pairing restart. Returns `true` while the
+     * window is open or its restart is running, so the generic force-login path must skip it.
+     */
+    handleServerRestartRequest(): boolean;
     disconnect(): Promise<void>;
     clearStoredCredentials(): Promise<void>;
     isConnected(): boolean;
@@ -51,6 +61,8 @@ export declare class WaConnectionManager {
     updateClockSkewFromSuccess(serverUnixSeconds: number): void;
     setClockSkewMs(clockSkewMs: number, source: string): void;
     private connectInternal;
+    private startPairRestart;
+    private clearPairRestartTimer;
     private reconnectAsRegisteredAfterPairing;
     private reconnectAsRegisteredAfterPairingInternal;
     private disconnectInternal;

package/dist/client/connection/WaConnectionManager.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WaConnectionManager = void 0;
+const constants_1 = require("../../protocol/constants");
 const WaComms_1 = require("../../transport/WaComms");
 const primitives_1 = require("../../util/primitives");
 class WaConnectionManager {
@@ -19,7 +20,7 @@ class WaConnectionManager {
         this.mediaConnCache = null;
         this.connectPromise = null;
         this.pairingReconnectPromise = null;
-        this.pairingReconnectTimeout = null;
+        this.pairRestartTimer = null;
         this.frameHandler = null;
         this.pendingComms = null;
         this.lifecycleGeneration = 0;
@@ -43,26 +44,37 @@ class WaConnectionManager {
         this.connectPromise = promise;
         return this.connectPromise;
     }
-    scheduleReconnectAfterPairing() {
-        this.logger.debug('wa client scheduling reconnect after pairing');
-        if (this.pairingReconnectTimeout) {
-            clearTimeout(this.pairingReconnectTimeout);
+    /**
+     * Starts the post-pairing restart window: the server ends the unregistered connection
+     * itself (`stream:error` 515, as WA Web waits for), so the socket stays open until that
+     * signal, a server close, or the fallback timer, whichever comes first.
+     */
+    awaitServerRestartAfterPairing() {
+        const comms = this.comms;
+        if (!comms) {
+            this.logger.trace('pairing restart wait skipped: no active comms');
+            return;
         }
-        this.pairingReconnectTimeout = setTimeout(() => {
-            this.pairingReconnectTimeout = null;
-            void this.reconnectAsRegisteredAfterPairing().catch((error) => {
-                if (this.isLifecycleSupersededError(error)) {
-                    this.logger.trace('pairing reconnect canceled by newer lifecycle');
-                    return;
-                }
-                this.logger.warn('failed to reconnect after pairing', {
-                    meJid: this.authClient.getCurrentCredentials()?.meJid,
-                    message: (0, primitives_1.toError)(error).message
-                });
-            });
-        }, 0);
+        this.clearPairRestartTimer();
+        this.logger.debug('wa client waiting for server restart after pairing', {
+            fallbackMs: constants_1.WA_DEFAULTS.PAIRING_RESTART_WAIT_MS
+        });
+        this.pairRestartTimer = setTimeout(() => this.startPairRestart('fallback_timeout'), constants_1.WA_DEFAULTS.PAIRING_RESTART_WAIT_MS);
+        comms.holdForServerRestart(() => this.startPairRestart('socket_closed'));
+    }
+    /**
+     * Claims a `stream:error` 515 for the post-pairing restart. Returns `true` while the
+     * window is open or its restart is running, so the generic force-login path must skip it.
+     */
+    handleServerRestartRequest() {
+        if (this.pairRestartTimer) {
+            this.startPairRestart('stream_error_515');
+            return true;
+        }
+        return this.pairingReconnectPromise !== null;
     }
     async disconnect() {
+        this.clearPairRestartTimer();
         const lifecycleGeneration = this.nextLifecycleGeneration();
         this.invalidatePendingComms('failed to stop pending comms during disconnect');
         await this.runLifecycleOperation(async () => {
@@ -140,6 +152,30 @@ class WaConnectionManager {
         this.assertLifecycleCurrent(lifecycleGeneration, 'connect');
         this.logger.info('wa client connected');
     }
+    startPairRestart(trigger) {
+        if (!this.pairRestartTimer) {
+            return;
+        }
+        this.clearPairRestartTimer();
+        this.logger.debug('wa client restarting after pairing', { trigger });
+        void this.reconnectAsRegisteredAfterPairing().catch((error) => {
+            if (this.isLifecycleSupersededError(error)) {
+                this.logger.trace('pairing reconnect canceled by newer lifecycle');
+                return;
+            }
+            this.logger.warn('failed to reconnect after pairing', {
+                meJid: this.authClient.getCurrentCredentials()?.meJid,
+                message: (0, primitives_1.toError)(error).message
+            });
+        });
+    }
+    clearPairRestartTimer() {
+        if (!this.pairRestartTimer) {
+            return;
+        }
+        clearTimeout(this.pairRestartTimer);
+        this.pairRestartTimer = null;
+    }
     async reconnectAsRegisteredAfterPairing() {
         if (this.pairingReconnectPromise) {
             this.logger.trace('pairing reconnect already in-flight');
@@ -188,10 +224,7 @@ class WaConnectionManager {
             return;
         }
         this.logger.debug('wa client disconnect start');
-        if (this.pairingReconnectTimeout) {
-            clearTimeout(this.pairingReconnectTimeout);
-            this.pairingReconnectTimeout = null;
-        }
+        this.clearPairRestartTimer();
         this.keepAlive.stop();
         this.nodeOrchestrator.clearPending(new Error('client disconnected'));
         this.clockSkewMs = null;

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

@@ -110,6 +110,13 @@ export interface WaRequestHistorySyncInput {
      */
     readonly count?: number;
 }
+/** Options for {@link WaMessageCoordinator.syncSignalSession}. */
+export interface WaSyncSignalSessionOptions {
+    /** Drops the session, keeping the identity, and fetches a fresh one. */
+    readonly force?: boolean;
+    /** The identity changed: drops the session and fetches with `reason="identity"`. */
+    readonly reasonIdentity?: boolean;
+}
 export interface WaReachoutTimelock {
     readonly isActive: boolean;
     readonly enforcementType: string | null;
@@ -239,11 +246,16 @@ export declare class WaMessageCoordinator {
      */
     getNewChatMessageCapping(type?: WaMessageCappingType): Promise<WaMessageCappingInfo>;
     /**
-     * Force-refreshes the Signal session(s) for `jid`. Set `reasonIdentity` to
-     * `true` when the trigger was an identity change – this also queues a
-     * trusted-contact-token reissue.
+     * Syncs the Signal session of the device `jid` resolves to (a user JID is
+     * device 0). With no options it only ensures a session exists. `force`
+     * rebuilds it, keeping the identity. `reasonIdentity` rebuilds it as an
+     * identity change and reissues the trusted-contact token; it wins over
+     * `force`. Throws for group JIDs and when the key-bundle fetch fails, in
+     * which case the old session is already gone.
      */
-    syncSignalSession(jid: string, reasonIdentity?: boolean): Promise<void>;
+    syncSignalSession(jid: string, options?: WaSyncSignalSessionOptions): Promise<void>;
+    /** @deprecated Pass `{ reasonIdentity: true }` instead. */
+    syncSignalSession(jid: string, reasonIdentity: boolean): Promise<void>;
     /**
      * Sends a message (any {@link WaSendMessageContent} kind – text, media,
      * poll, reaction, edit, revoke, etc.) to `to` and returns the publish

package/dist/client/coordinators/WaMessageCoordinator.js

@@ -292,14 +292,10 @@ class WaMessageCoordinator {
         });
         return parseMessageCappingMexResponse(data);
     }
-    /**
-     * Force-refreshes the Signal session(s) for `jid`. Set `reasonIdentity` to
-     * `true` when the trigger was an identity change – this also queues a
-     * trusted-contact-token reissue.
-     */
-    async syncSignalSession(jid, reasonIdentity = false) {
-        await this.messageDispatch.syncSignalSession(jid, reasonIdentity);
-        if (reasonIdentity) {
+    async syncSignalSession(jid, options = {}) {
+        const normalized = typeof options === 'boolean' ? { reasonIdentity: options } : options;
+        await this.messageDispatch.syncSignalSession(jid, normalized);
+        if (normalized.reasonIdentity) {
             this.trustedContactToken.reissueOnIdentityChange(jid).catch((err) => this.logger.warn('tc token reissue on identity change failed', {
                 jid,
                 message: (0, primitives_1.toError)(err).message

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

@@ -1,5 +1,6 @@
 import type { WaAppStateSyncKey } from '../../appstate/types';
 import type { WaAuthCredentials } from '../../auth/types';
+import type { WaSyncSignalSessionOptions } from '../coordinators/WaMessageCoordinator';
 import type { DeviceFanoutResolver } from '../messaging/fanout';
 import type { GroupMetadataCache } from '../messaging/group-metadata';
 import type { AppStateSyncKeyProtocol } from '../messaging/key-protocol';
@@ -156,7 +157,7 @@ export declare class WaMessageDispatchCoordinator {
      * LID destination.
      */
     private resolvePeerRecipientPn;
-    syncSignalSession(jid: string, reasonIdentity?: boolean): Promise<void>;
+    syncSignalSession(jid: string, { force, reasonIdentity }?: WaSyncSignalSessionOptions): Promise<void>;
     sendReceipt(input: WaSendReceiptInput): Promise<void>;
     publishProtocolMessageToDevice(deviceJid: string, protocolMessage: Proto.Message.IProtocolMessage, options?: {
         readonly id?: string;

package/dist/client/coordinators/WaMessageDispatchCoordinator.js

@@ -483,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/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];
                 }
             }