zapo-js 0.1.2 → 0.3.0

package/dist/esm/client/WaClient.js

@@ -3,14 +3,19 @@ import { downloadExternalBlobReference } from '../appstate/utils.js';
 import { parseChatEventFromAppStateMutation } from './events/chat.js';
 import { processHistorySyncNotification } from './history-sync.js';
 import { persistIncomingMailboxEntities } from './mailbox.js';
+import { WriteBehindPersistence } from './persistence/WriteBehindPersistence.js';
 import { buildWaClientDependencies, resolveWaClientBase } from './WaClientFactory.js';
 import { ConsoleLogger } from '../infra/log/ConsoleLogger.js';
+import { buildAddonAdditionalData, decodeAddonPlaintext, decryptAddonPayload, identifyEncryptedAddon, resolveParentMessageSecret, resolvePollOptionNames, shouldUseAddonAdditionalData } from '../message/addon-crypto.js';
 import { proto } from '../proto.js';
 import { WA_APP_STATE_COLLECTION_STATES, WA_DEFAULTS } from '../protocol/constants.js';
 import { normalizeDeviceJid, parsePhoneJid, toUserJid } from '../protocol/jid.js';
-import { queryWithContext as queryNodeWithContext } from '../transport/node/query.js';
-import { decodeProtoBytes } from '../util/bytes.js';
-import { bytesToHex } from '../util/bytes.js';
+import { WA_LOGOUT_REASONS } from '../protocol/stream.js';
+import { NOOP_MESSAGE_SECRET_STORE } from '../store/noop.store.js';
+import { buildRemoveCompanionDeviceIq } from '../transport/node/builders/device.js';
+import { buildPresenceNode } from '../transport/node/builders/presence.js';
+import { assertIqResult, queryWithContext as queryNodeWithContext } from '../transport/node/query.js';
+import { bytesToHex, decodeProtoBytes } from '../util/bytes.js';
 import { toError } from '../util/primitives.js';
 const SYNC_RELATED_PROTOCOL_TYPES = new Set([
     proto.Message.ProtocolMessage.Type.APP_STATE_SYNC_KEY_REQUEST,
@@ -18,29 +23,45 @@ const SYNC_RELATED_PROTOCOL_TYPES = new Set([
     proto.Message.ProtocolMessage.Type.PEER_DATA_OPERATION_REQUEST_MESSAGE,
     proto.Message.ProtocolMessage.Type.PEER_DATA_OPERATION_REQUEST_RESPONSE_MESSAGE
 ]);
-const WA_APP_STATE_KEY_SHARE_WAIT_TIMEOUT_MS = 15000;
-const WA_APP_STATE_KEY_SHARE_MAX_RETRIES = 2;
 export class WaClient extends EventEmitter {
     constructor(options, logger = new ConsoleLogger('info')) {
         super();
         this.connectPromise = null;
+        this.acceptingIncomingEvents = true;
+        this.activeIncomingHandlers = 0;
+        this.incomingHandlersDrainedWaiters = [];
         const base = resolveWaClientBase(options, logger);
         this.options = base.options;
         this.logger = base.logger;
         this.appStateStore = base.sessionStore.appState;
         this.contactStore = base.sessionStore.contacts;
         this.messageStore = base.sessionStore.messages;
+        this.messageSecretStore = base.sessionStore.messageSecret;
         this.participantsStore = base.sessionStore.participants;
+        this.privacyTokenStore = base.sessionStore.privacyToken;
         this.deviceListStore = base.sessionStore.deviceList;
         this.retryStore = base.sessionStore.retry;
         this.signalStore = base.sessionStore.signal;
+        this.preKeyStore = base.sessionStore.preKey;
+        this.sessionStore = base.sessionStore.session;
+        this.identityStore = base.sessionStore.identity;
         this.senderKeyStore = base.sessionStore.senderKey;
         this.threadStore = base.sessionStore.threads;
+        this.writeBehind = new WriteBehindPersistence({
+            messageStore: this.messageStore,
+            threadStore: this.threadStore,
+            contactStore: this.contactStore
+        }, this.logger, this.options.writeBehind);
+        if (this.options.addons?.autoDecrypt &&
+            this.messageSecretStore === NOOP_MESSAGE_SECRET_STORE) {
+            this.logger.warn('addons.autoDecrypt is enabled but messageSecret cache is noop — ' +
+                'addon decryption will only work if secrets are in the message store');
+        }
         const dependencies = buildWaClientDependencies({
             base,
             runtime: {
                 sendNode: (node) => this.sendNode(node),
-                query: (node, timeoutMs) => this.query(node, timeoutMs),
+                query: (node, timeoutMs, options) => this.query(node, timeoutMs, options),
                 queryWithContext: this.queryWithContext.bind(this),
                 syncAppState: () => this.syncAppState().then(() => { }),
                 syncAppStateWithOptions: (syncOptions) => this.syncAppState(syncOptions),
@@ -48,7 +69,10 @@ export class WaClient extends EventEmitter {
                 handleIncomingMessageEvent: this.handleIncomingMessageEvent.bind(this),
                 handleError: this.handleError.bind(this),
                 handleIncomingFrame: this.handleIncomingFrame.bind(this),
-                clearStoredState: this.clearStoredState.bind(this)
+                clearStoredState: this.clearStoredState.bind(this),
+                resumeIncomingEvents: () => {
+                    this.acceptingIncomingEvents = true;
+                }
             }
         });
         Object.assign(this, dependencies);
@@ -96,12 +120,16 @@ export class WaClient extends EventEmitter {
             throw normalized;
         }
     }
-    async query(node, timeoutMs = this.options.iqTimeoutMs ?? WA_DEFAULTS.IQ_TIMEOUT_MS) {
+    async sendPresence(type) {
+        const credentials = this.authClient.getCurrentCredentials();
+        await this.nodeOrchestrator.sendNode(buildPresenceNode({ type, name: credentials?.meDisplayName ?? undefined }), false);
+    }
+    async query(node, timeoutMs = this.options.iqTimeoutMs ?? WA_DEFAULTS.IQ_TIMEOUT_MS, options = {}) {
         if (!this.connectionManager.isConnected()) {
             throw new Error('client is not connected');
         }
         this.logger.debug('wa client query', { tag: node.tag, id: node.attrs.id, timeoutMs });
-        return this.nodeOrchestrator.query(node, timeoutMs);
+        return this.nodeOrchestrator.query(node, timeoutMs, options);
     }
     registerIncomingHandler(registration) {
         return this.incomingNode.registerIncomingHandler(registration);
@@ -119,63 +147,74 @@ export class WaClient extends EventEmitter {
             this.handleError(error);
         });
     }
-    getMailboxPersistenceDeps() {
-        return {
-            logger: this.logger,
-            contactStore: this.contactStore,
-            messageStore: this.messageStore
-        };
-    }
     async handleIncomingMessageEvent(event) {
-        this.emit('message', event);
-        void persistIncomingMailboxEntities({
-            ...this.getMailboxPersistenceDeps(),
-            event
-        });
-        const protocolMessage = event.message?.protocolMessage;
-        if (!protocolMessage) {
+        if (!this.tryEnterIncomingHandler()) {
             return;
         }
-        const protocolEvent = {
-            ...event,
-            protocolMessage
-        };
-        this.emit('message_protocol', protocolEvent);
-        const protocolType = protocolMessage.type;
-        if (protocolType === null || protocolType === undefined) {
-            this.logger.debug('incoming protocol message without type', {
-                id: event.stanzaId,
-                from: event.chatJid
+        try {
+            this.emit('message', event);
+            void persistIncomingMailboxEntities({
+                logger: this.logger,
+                writeBehind: this.writeBehind,
+                messageSecretStore: this.messageSecretStore,
+                event
             });
-            return;
-        }
-        if (protocolType === proto.Message.ProtocolMessage.Type.APP_STATE_SYNC_KEY_REQUEST) {
-            await this.handleIncomingAppStateSyncKeyRequest(event, protocolMessage);
-            return;
-        }
-        if (protocolType === proto.Message.ProtocolMessage.Type.APP_STATE_SYNC_KEY_SHARE) {
-            await this.handleIncomingAppStateSyncKeyShare(event, protocolMessage);
-            return;
-        }
-        if (protocolType === proto.Message.ProtocolMessage.Type.HISTORY_SYNC_NOTIFICATION) {
-            if (this.options.history?.enabled && protocolMessage.historySyncNotification) {
-                await this.handleHistorySyncNotification(protocolMessage.historySyncNotification);
+            if (this.options.addons?.autoDecrypt && event.message) {
+                void this.tryDecryptAddon(event).catch((err) => {
+                    this.logger.warn('addon auto-decrypt failed', {
+                        id: event.stanzaId,
+                        message: toError(err).message
+                    });
+                });
             }
-            return;
-        }
-        if (SYNC_RELATED_PROTOCOL_TYPES.has(protocolType)) {
-            this.logger.info('incoming sync-related protocol message', {
+            const protocolMessage = event.message?.protocolMessage;
+            if (!protocolMessage) {
+                return;
+            }
+            const protocolEvent = {
+                ...event,
+                protocolMessage
+            };
+            this.emit('message_protocol', protocolEvent);
+            const protocolType = protocolMessage.type;
+            if (protocolType === null || protocolType === undefined) {
+                this.logger.debug('incoming protocol message without type', {
+                    id: event.stanzaId,
+                    from: event.chatJid
+                });
+                return;
+            }
+            if (protocolType === proto.Message.ProtocolMessage.Type.APP_STATE_SYNC_KEY_REQUEST) {
+                await this.handleIncomingAppStateSyncKeyRequest(event, protocolMessage);
+                return;
+            }
+            if (protocolType === proto.Message.ProtocolMessage.Type.APP_STATE_SYNC_KEY_SHARE) {
+                await this.handleIncomingAppStateSyncKeyShare(event, protocolMessage);
+                return;
+            }
+            if (protocolType === proto.Message.ProtocolMessage.Type.HISTORY_SYNC_NOTIFICATION) {
+                if (this.options.history?.enabled && protocolMessage.historySyncNotification) {
+                    await this.handleHistorySyncNotification(protocolMessage.historySyncNotification);
+                }
+                return;
+            }
+            if (SYNC_RELATED_PROTOCOL_TYPES.has(protocolType)) {
+                this.logger.info('incoming sync-related protocol message', {
+                    id: event.stanzaId,
+                    from: event.chatJid,
+                    protocolType
+                });
+                return;
+            }
+            this.logger.debug('incoming protocol message received', {
                 id: event.stanzaId,
                 from: event.chatJid,
                 protocolType
             });
-            return;
         }
-        this.logger.debug('incoming protocol message received', {
-            id: event.stanzaId,
-            from: event.chatJid,
-            protocolType
-        });
+        finally {
+            this.leaveIncomingHandler();
+        }
     }
     async handleIncomingAppStateSyncKeyShare(event, protocolMessage) {
         const share = protocolMessage.appStateSyncKeyShare;
@@ -194,16 +233,6 @@ export class WaClient extends EventEmitter {
                 imported
             });
             if (imported > 0) {
-                const hadWaiters = this.keyShareCoordinator.hasWaiters();
-                this.keyShareCoordinator.notifyReceived();
-                if (hadWaiters) {
-                    this.logger.debug('app-state key share imported and waiters released', {
-                        id: event.stanzaId,
-                        from: event.chatJid,
-                        imported
-                    });
-                    return;
-                }
                 void this.syncAppState().catch((error) => {
                     this.logger.warn('failed to sync app-state after key share import', {
                         id: event.stanzaId,
@@ -264,9 +293,18 @@ export class WaClient extends EventEmitter {
             });
             return;
         }
-        const requestedKeys = await Promise.all(requestedKeyIds.map((keyId) => this.appStateStore.getSyncKey(keyId)));
-        const availableKeys = requestedKeys.filter((key) => key !== null);
-        const missingKeyIds = requestedKeyIds.filter((_, index) => requestedKeys[index] === null);
+        const requestedKeys = await this.appStateStore.getSyncKeysBatch(requestedKeyIds);
+        const availableKeys = [];
+        const missingKeyIds = [];
+        for (let i = 0; i < requestedKeys.length; i += 1) {
+            const key = requestedKeys[i];
+            if (key !== null) {
+                availableKeys.push(key);
+            }
+            else {
+                missingKeyIds.push(requestedKeyIds[i]);
+            }
+        }
         try {
             await this.messageDispatch.sendAppStateSyncKeyShare(requesterDeviceJid, availableKeys, missingKeyIds);
             this.logger.info('responded to app-state key request', {
@@ -313,18 +351,18 @@ export class WaClient extends EventEmitter {
             return false;
         }
         const candidateUser = toUserJid(candidateJid);
-        const meUsers = [credentials.meJid, credentials.meLid]
-            .filter((value) => !!value)
-            .map((jid) => toUserJid(jid));
-        return meUsers.includes(candidateUser);
+        return ((!!credentials.meJid && toUserJid(credentials.meJid) === candidateUser) ||
+            (!!credentials.meLid && toUserJid(credentials.meLid) === candidateUser));
     }
     async handleHistorySyncNotification(notification) {
         try {
             await processHistorySyncNotification({
-                ...this.getMailboxPersistenceDeps(),
+                logger: this.logger,
                 mediaTransfer: this.mediaTransfer,
-                threadStore: this.threadStore,
-                emitEvent: this.emit.bind(this)
+                writeBehind: this.writeBehind,
+                emitEvent: this.emit.bind(this),
+                onPrivacyTokens: (conversations) => this.trustedContactToken.hydrateFromHistorySync(conversations),
+                onNctSalt: (salt) => this.trustedContactToken.hydrateNctSaltFromHistorySync(salt)
             }, notification);
         }
         catch (error) {
@@ -335,8 +373,8 @@ export class WaClient extends EventEmitter {
             });
         }
     }
-    async queryWithContext(context, node, timeoutMs = this.options.iqTimeoutMs ?? WA_DEFAULTS.IQ_TIMEOUT_MS, contextData = {}) {
-        return queryNodeWithContext(async (queryNode, queryTimeoutMs) => this.query(queryNode, queryTimeoutMs), this.logger, context, node, timeoutMs, contextData);
+    async queryWithContext(context, node, timeoutMs = this.options.iqTimeoutMs ?? WA_DEFAULTS.IQ_TIMEOUT_MS, contextData = {}, options = {}) {
+        return queryNodeWithContext(async (queryNode, queryTimeoutMs) => this.query(queryNode, queryTimeoutMs, options), this.logger, context, node, timeoutMs, contextData);
     }
     async handleIncomingFrame(frame) {
         try {
@@ -351,10 +389,17 @@ export class WaClient extends EventEmitter {
             this.logger.trace('wa client connect already in-flight');
             return this.connectPromise;
         }
+        this.acceptingIncomingEvents = true;
         this.connectPromise = this.connectionManager
             .connect((frame) => this.handleIncomingFrame(frame))
             .then(() => {
-            this.emit('connection_open', {});
+            this.emit('connection', {
+                status: 'open',
+                reason: 'connected',
+                code: null,
+                isLogout: false,
+                isNewLogin: this.connectionManager.wasNewLogin()
+            });
         })
             .finally(() => {
             this.connectPromise = null;
@@ -362,16 +407,28 @@ export class WaClient extends EventEmitter {
         return this.connectPromise;
     }
     async disconnect() {
-        this.keyShareCoordinator.notifyDisconnected();
+        await this.pauseIncomingEventsAndWaitDrain();
+        const writeBehindFlush = await this.writeBehind.flush(this.options.writeBehind?.flushTimeoutMs);
+        if (writeBehindFlush.remaining > 0) {
+            this.logger.warn('disconnect continuing with pending write-behind entries', {
+                remaining: writeBehindFlush.remaining
+            });
+        }
         await this.connectionManager.disconnect();
-        this.emit('connection_close', {});
+        this.emit('connection', {
+            status: 'close',
+            reason: 'client_disconnected',
+            code: null,
+            isLogout: false,
+            isNewLogin: false
+        });
     }
-    async requestPairingCode(phoneNumber, shouldShowPushNotification = false) {
+    async requestPairingCode(phoneNumber, shouldShowPushNotification = false, customCode) {
         if (!this.connectionManager.isConnected() || !this.authClient.getCurrentCredentials()) {
             throw new Error('client is not connected');
         }
         this.logger.debug('wa client request pairing code');
-        return this.authClient.requestPairingCode(phoneNumber, shouldShowPushNotification);
+        return this.authClient.requestPairingCode(phoneNumber, shouldShowPushNotification, customCode);
     }
     async fetchPairingCountryCodeIso() {
         if (!this.connectionManager.isConnected() || !this.authClient.getCurrentCredentials()) {
@@ -384,7 +441,10 @@ export class WaClient extends EventEmitter {
         if (!this.connectionManager.isConnected() || !this.authClient.getCurrentCredentials()) {
             throw new Error('client is not connected');
         }
-        const normalizedPhoneJids = phoneNumbers.map(parsePhoneJid);
+        const normalizedPhoneJids = new Array(phoneNumbers.length);
+        for (let index = 0; index < phoneNumbers.length; index += 1) {
+            normalizedPhoneJids[index] = parsePhoneJid(phoneNumbers[index]);
+        }
         this.logger.trace('wa client query lids by phone numbers', {
             phones: normalizedPhoneJids.length
         });
@@ -393,41 +453,54 @@ export class WaClient extends EventEmitter {
     sendMessage(to, content, options = {}) {
         return this.messageDispatch.sendMessage(to, content, options);
     }
-    syncSignalSession(jid, reasonIdentity = false) {
-        return this.messageDispatch.syncSignalSession(jid, reasonIdentity);
-    }
-    sendReceipt(input) {
-        return this.messageDispatch.sendReceipt(input);
-    }
-    setChatMute(chatJid, muted, muteEndTimestampMs) {
-        return this.appStateMutations.setChatMute(chatJid, muted, muteEndTimestampMs);
+    async syncSignalSession(jid, reasonIdentity = false) {
+        await this.messageDispatch.syncSignalSession(jid, reasonIdentity);
+        if (reasonIdentity) {
+            this.trustedContactToken.reissueOnIdentityChange(jid).catch((err) => this.logger.warn('tc token reissue on identity change failed', {
+                jid,
+                message: toError(err).message
+            }));
+        }
     }
-    setChatRead(chatJid, read) {
-        return this.appStateMutations.setChatRead(chatJid, read);
+    get chat() {
+        return this.chatCoordinator;
     }
-    setChatPin(chatJid, pinned) {
-        return this.appStateMutations.setChatPin(chatJid, pinned);
+    get group() {
+        return this.groupCoordinator;
     }
-    setChatArchive(chatJid, archived) {
-        return this.appStateMutations.setChatArchive(chatJid, archived);
+    get privacy() {
+        return this.privacyCoordinator;
     }
-    clearChat(chatJid, options = {}) {
-        return this.appStateMutations.clearChat(chatJid, options);
+    get profile() {
+        return this.profileCoordinator;
     }
-    deleteChat(chatJid, options = {}) {
-        return this.appStateMutations.deleteChat(chatJid, options);
+    get business() {
+        return this.businessCoordinator;
     }
-    setChatLock(chatJid, locked) {
-        return this.appStateMutations.setChatLock(chatJid, locked);
+    get email() {
+        return this.emailCoordinator;
     }
-    setMessageStar(message, starred) {
-        return this.appStateMutations.setMessageStar(message, starred);
+    async logout(reason = WA_LOGOUT_REASONS.USER_INITIATED) {
+        const meJid = this.authClient.getCurrentCredentials()?.meJid;
+        if (!meJid) {
+            throw new Error('cannot logout: client is not authenticated');
+        }
+        const deviceJid = normalizeDeviceJid(meJid);
+        const node = buildRemoveCompanionDeviceIq(deviceJid, reason);
+        const result = await this.queryWithContext('client.logout', node, undefined, {
+            jid: deviceJid,
+            reason
+        });
+        assertIqResult(result, 'client.logout');
     }
-    deleteMessageForMe(message, options = {}) {
-        return this.appStateMutations.deleteMessageForMe(message, options);
+    sendReceipt(input) {
+        return this.messageDispatch.sendReceipt(input);
     }
     flushAppStateMutations() {
-        return this.appStateMutations.flushMutations();
+        return this.chatCoordinator.flushMutations();
+    }
+    flushWriteBehind(timeoutMs) {
+        return this.writeBehind.flush(timeoutMs);
     }
     async exportAppState() {
         return this.appStateSync.exportState();
@@ -436,60 +509,11 @@ export class WaClient extends EventEmitter {
         if (!this.connectionManager.isConnected()) {
             throw new Error('client is not connected');
         }
-        const shouldWaitForKeyShare = (await this.appStateStore.getActiveSyncKey()) === null;
-        if (shouldWaitForKeyShare && !this.keyShareCoordinator.isBootstrapDone()) {
-            this.keyShareCoordinator.markBootstrapDone();
-            this.logger.info('app-state bootstrap pre-sync waiting for key share', {
-                timeoutMs: WA_APP_STATE_KEY_SHARE_WAIT_TIMEOUT_MS
-            });
-            const received = await this.keyShareCoordinator.waitForShare(WA_APP_STATE_KEY_SHARE_WAIT_TIMEOUT_MS);
-            if (received) {
-                this.logger.info('app-state bootstrap pre-sync received key share, continuing sync');
-            }
-            else {
-                this.logger.warn('app-state bootstrap pre-sync key share wait timed out, continuing sync', {
-                    timeoutMs: WA_APP_STATE_KEY_SHARE_WAIT_TIMEOUT_MS
-                });
-            }
-        }
-        let syncResult = await this.executeAppStateSync(options);
-        let blockedCollections = this.getBlockedAppStateCollections(syncResult);
-        if (!shouldWaitForKeyShare || blockedCollections.length === 0) {
-            this.emitChatEventsFromAppStateSyncResult(syncResult);
-            return syncResult;
-        }
-        let retryCount = 0;
-        let observedKeyShareVersion = this.keyShareCoordinator.getVersion();
-        while (blockedCollections.length > 0 && retryCount < WA_APP_STATE_KEY_SHARE_MAX_RETRIES) {
-            const hasFreshShare = this.keyShareCoordinator.getVersion() !== observedKeyShareVersion;
-            if (!hasFreshShare) {
-                this.logger.info('app-state bootstrap waiting for key share', {
-                    blockedCollections: blockedCollections.join(','),
-                    timeoutMs: WA_APP_STATE_KEY_SHARE_WAIT_TIMEOUT_MS,
-                    retryCount: retryCount + 1
-                });
-                const received = await this.keyShareCoordinator.waitForShare(WA_APP_STATE_KEY_SHARE_WAIT_TIMEOUT_MS);
-                if (!received) {
-                    this.logger.warn('app-state bootstrap key share wait timed out', {
-                        blockedCollections: blockedCollections.join(','),
-                        timeoutMs: WA_APP_STATE_KEY_SHARE_WAIT_TIMEOUT_MS
-                    });
-                    break;
-                }
-            }
-            observedKeyShareVersion = this.keyShareCoordinator.getVersion();
-            retryCount += 1;
-            this.logger.info('app-state bootstrap retrying sync after key share', {
-                retryCount,
-                blockedCollections: blockedCollections.join(',')
-            });
-            syncResult = await this.executeAppStateSync(options);
-            blockedCollections = this.getBlockedAppStateCollections(syncResult);
-        }
+        const syncResult = await this.executeAppStateSync(options);
+        const blockedCollections = this.getBlockedAppStateCollections(syncResult);
         if (blockedCollections.length > 0) {
-            this.logger.warn('app-state bootstrap still blocked after waiting for key share', {
-                blockedCollections: blockedCollections.join(','),
-                retries: retryCount
+            this.logger.warn('app-state sync has blocked collections', {
+                blockedCollections: blockedCollections.join(',')
             });
         }
         this.emitChatEventsFromAppStateSyncResult(syncResult);
@@ -504,9 +528,13 @@ export class WaClient extends EventEmitter {
             });
     }
     getBlockedAppStateCollections(syncResult) {
-        return syncResult.collections
-            .filter((entry) => entry.state === WA_APP_STATE_COLLECTION_STATES.BLOCKED)
-            .map((entry) => entry.collection);
+        const blocked = [];
+        for (const entry of syncResult.collections) {
+            if (entry.state === WA_APP_STATE_COLLECTION_STATES.BLOCKED) {
+                blocked.push(entry.collection);
+            }
+        }
+        return blocked;
     }
     emitChatEventsFromAppStateSyncResult(syncResult) {
         const shouldEmitSnapshotMutations = this.options.chatEvents?.emitSnapshotMutations === true;
@@ -530,6 +558,7 @@ export class WaClient extends EventEmitter {
                     continue;
                 }
                 try {
+                    this.handleNctSaltMutation(mutation);
                     const event = parseChatEventFromAppStateMutation(mutation);
                     if (!event) {
                         continue;
@@ -547,23 +576,158 @@ export class WaClient extends EventEmitter {
             }
         }
     }
+    handleNctSaltMutation(mutation) {
+        const nctAction = mutation.value?.nctSaltSyncAction;
+        if (!nctAction) {
+            return;
+        }
+        if (mutation.operation === 'set' && nctAction.salt) {
+            this.trustedContactToken.handleNctSaltSync(nctAction.salt).catch((err) => this.logger.warn('nct salt sync set failed', {
+                message: toError(err).message
+            }));
+        }
+        else if (mutation.operation === 'remove') {
+            this.trustedContactToken.handleNctSaltSync(null).catch((err) => this.logger.warn('nct salt sync remove failed', {
+                message: toError(err).message
+            }));
+        }
+    }
     async clearStoredState() {
+        await this.pauseIncomingEventsAndWaitDrain();
+        const writeBehindDestroy = await this.writeBehind.destroy(this.options.writeBehind?.flushTimeoutMs);
+        if (writeBehindDestroy.remaining > 0) {
+            throw new Error(`clear stored state aborted: write-behind did not fully drain (remaining=${writeBehindDestroy.remaining})`);
+        }
         const danglingReceipts = this.receiptQueue.take();
         if (danglingReceipts.length > 0) {
             this.logger.debug('cleared dangling receipts while clearing stored state', {
                 count: danglingReceipts.length
             });
         }
-        await this.authClient.clearStoredCredentials();
-        await this.appStateStore.clear();
-        await this.contactStore.clear();
-        await this.messageStore.clear();
-        await this.participantsStore.clear();
-        await this.deviceListStore.clear();
-        await this.retryStore.clear();
-        await this.signalStore.clear();
-        await this.senderKeyStore.clear();
-        await this.threadStore.clear();
+        const s = this.options.logoutStoreClear;
+        const shouldClear = (key) => s === undefined || s[key] !== false;
+        if (shouldClear('auth'))
+            await this.authClient.clearStoredCredentials();
+        if (shouldClear('appState'))
+            await this.appStateStore.clear();
+        if (shouldClear('contacts'))
+            await this.contactStore.clear();
+        if (shouldClear('messages'))
+            await this.messageStore.clear();
+        if (shouldClear('messageSecret'))
+            await this.messageSecretStore.clear();
+        if (shouldClear('participants'))
+            await this.participantsStore.clear();
+        if (shouldClear('deviceList'))
+            await this.deviceListStore.clear();
+        if (shouldClear('retry'))
+            await this.retryStore.clear();
+        if (shouldClear('signal'))
+            await this.signalStore.clear();
+        if (shouldClear('preKey'))
+            await this.preKeyStore.clear();
+        if (shouldClear('session'))
+            await this.sessionStore.clear();
+        if (shouldClear('identity'))
+            await this.identityStore.clear();
+        if (shouldClear('senderKey'))
+            await this.senderKeyStore.clear();
+        if (shouldClear('threads'))
+            await this.threadStore.clear();
+        if (shouldClear('privacyToken'))
+            await this.privacyTokenStore.clear();
+    }
+    async tryDecryptAddon(event) {
+        const message = event.message;
+        if (!message)
+            return;
+        const addon = identifyEncryptedAddon(message);
+        if (!addon)
+            return;
+        const targetMessageId = addon.targetMessageKey.id;
+        if (!targetMessageId)
+            return;
+        const parentEntry = await resolveParentMessageSecret(targetMessageId, this.messageSecretStore, this.messageStore);
+        if (!parentEntry) {
+            this.logger.debug('addon parent message secret not found', {
+                id: event.stanzaId,
+                targetId: targetMessageId
+            });
+            return;
+        }
+        const parentMsgOriginalSender = parentEntry.senderJid;
+        const modificationSender = event.senderJid ?? '';
+        const plaintext = await decryptAddonPayload({
+            messageSecret: parentEntry.secret,
+            stanzaId: targetMessageId,
+            parentMsgOriginalSender,
+            modificationSender,
+            modificationType: addon.modificationType,
+            ciphertext: addon.encPayload,
+            iv: addon.encIv,
+            additionalData: shouldUseAddonAdditionalData(addon.modificationType)
+                ? buildAddonAdditionalData(targetMessageId, modificationSender)
+                : undefined
+        });
+        let decrypted = decodeAddonPlaintext(addon.kind, plaintext);
+        if (decrypted.kind === 'poll_vote' && decrypted.pollVote.selectedOptions) {
+            const names = await resolvePollOptionNames(decrypted.pollVote.selectedOptions, targetMessageId, this.messageStore);
+            if (names) {
+                decrypted = { ...decrypted, selectedOptionNames: names };
+            }
+        }
+        const addonEvent = {
+            rawNode: event.rawNode,
+            stanzaId: event.stanzaId,
+            chatJid: event.chatJid,
+            stanzaType: event.stanzaType,
+            kind: addon.kind,
+            targetMessageId,
+            senderJid: modificationSender,
+            decrypted,
+            raw: message
+        };
+        this.emit('message_addon', addonEvent);
+    }
+    tryEnterIncomingHandler() {
+        if (!this.acceptingIncomingEvents) {
+            return false;
+        }
+        this.activeIncomingHandlers += 1;
+        if (this.acceptingIncomingEvents) {
+            return true;
+        }
+        this.leaveIncomingHandler();
+        return false;
+    }
+    leaveIncomingHandler() {
+        if (this.activeIncomingHandlers <= 0) {
+            return;
+        }
+        this.activeIncomingHandlers -= 1;
+        if (this.activeIncomingHandlers === 0) {
+            this.notifyIncomingHandlersDrained();
+        }
+    }
+    async pauseIncomingEventsAndWaitDrain() {
+        this.acceptingIncomingEvents = false;
+        if (this.activeIncomingHandlers === 0) {
+            return;
+        }
+        await new Promise((resolve) => {
+            this.incomingHandlersDrainedWaiters[this.incomingHandlersDrainedWaiters.length] =
+                resolve;
+        });
+    }
+    notifyIncomingHandlersDrained() {
+        if (this.incomingHandlersDrainedWaiters.length === 0) {
+            return;
+        }
+        const waitersLength = this.incomingHandlersDrainedWaiters.length;
+        for (let index = 0; index < waitersLength; index += 1) {
+            this.incomingHandlersDrainedWaiters[index]();
+        }
+        this.incomingHandlersDrainedWaiters.length = 0;
     }
     handleError(error) {
         this.logger.error('wa client error', { message: error.message });