zapo-js 0.1.0

package/dist/esm/client/WaClient.js

@@ -0,0 +1,745 @@
+import { EventEmitter } from 'node:events';
+import { downloadExternalBlobReference } from '../appstate/utils.js';
+import { parseChatEventFromAppStateMutation } from './events/chat.js';
+import { processHistorySyncNotification } from './history-sync.js';
+import { persistIncomingMailboxEntities } from './mailbox.js';
+import { buildWaClientDependencies, resolveWaClientBase } from './WaClientFactory.js';
+import { ConsoleLogger } from '../infra/log/ConsoleLogger.js';
+import { proto } from '../proto.js';
+import { WA_APP_STATE_COLLECTION_STATES, WA_DEFAULTS, WA_MESSAGE_TAGS } from '../protocol/constants.js';
+import { normalizeDeviceJid, toUserJid } from '../protocol/jid.js';
+import { queryWithContext as queryNodeWithContext } from '../transport/node/query.js';
+import { WaComms } from '../transport/WaComms.js';
+import { decodeProtoBytes } from '../util/base64.js';
+import { bytesToHex } 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,
+    proto.Message.ProtocolMessage.Type.APP_STATE_FATAL_EXCEPTION_NOTIFICATION,
+    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.clockSkewMs = null;
+        this.mediaConnCache = null;
+        this.comms = null;
+        this.pairingReconnectPromise = null;
+        this.connectPromise = null;
+        this.danglingReceipts = [];
+        this.appStateKeyShareWaiters = new Set();
+        this.appStateKeyShareVersion = 0;
+        this.appStateBootstrapKeyShareWaitDone = false;
+        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.participantsStore = base.sessionStore.participants;
+        this.deviceListStore = base.sessionStore.deviceList;
+        this.retryStore = base.sessionStore.retry;
+        this.signalStore = base.sessionStore.signal;
+        this.senderKeyStore = base.sessionStore.senderKey;
+        this.threadStore = base.sessionStore.threads;
+        const host = {
+            sendNode: (node) => this.sendNode(node),
+            query: (node, timeoutMs) => this.query(node, timeoutMs),
+            queryWithContext: this.queryWithContext.bind(this),
+            syncAppState: () => this.syncAppState().then(() => { }),
+            emitEvent: this.emit.bind(this),
+            handleIncomingMessageEvent: this.handleIncomingMessageEvent.bind(this),
+            handleError: this.handleError.bind(this),
+            scheduleReconnectAfterPairing: this.scheduleReconnectAfterPairing.bind(this),
+            updateClockSkewFromSuccess: this.updateClockSkewFromSuccess.bind(this),
+            getComms: () => this.comms,
+            getMediaConnCache: () => this.mediaConnCache,
+            setMediaConnCache: (mediaConn) => {
+                this.mediaConnCache = mediaConn;
+            },
+            disconnect: this.disconnect.bind(this),
+            clearStoredState: this.clearStoredState.bind(this),
+            connect: this.connect.bind(this),
+            shouldQueueDanglingReceipt: (node, error) => this.shouldQueueDanglingReceipt(node, error),
+            enqueueDanglingReceipt: this.enqueueDanglingReceipt.bind(this),
+            takeDanglingReceipts: () => this.danglingReceipts.splice(0)
+        };
+        const dependencies = buildWaClientDependencies({
+            base,
+            host
+        });
+        Object.assign(this, dependencies);
+        this.bindNodeTransportEvents();
+    }
+    on(event, listener) {
+        return super.on(event, listener);
+    }
+    once(event, listener) {
+        return super.once(event, listener);
+    }
+    off(event, listener) {
+        return super.off(event, listener);
+    }
+    emit(event, ...args) {
+        return super.emit(event, ...args);
+    }
+    getState() {
+        const connected = this.comms !== null && this.comms.getCommsState().connected;
+        this.logger.trace('wa client state requested', { connected });
+        return this.authClient.getState(connected);
+    }
+    getCredentials() {
+        return this.authClient.getCurrentCredentials();
+    }
+    getClockSkewMs() {
+        return this.clockSkewMs;
+    }
+    async sendNode(node) {
+        try {
+            await this.nodeOrchestrator.sendNode(node);
+        }
+        catch (error) {
+            const normalized = toError(error);
+            if (this.shouldQueueDanglingReceipt(node, normalized)) {
+                this.enqueueDanglingReceipt(node);
+                this.logger.warn('queued dangling receipt after send failure', {
+                    id: node.attrs.id,
+                    to: node.attrs.to,
+                    message: normalized.message,
+                    queueSize: this.danglingReceipts.length
+                });
+                return;
+            }
+            throw normalized;
+        }
+    }
+    async query(node, timeoutMs = this.options.iqTimeoutMs ?? WA_DEFAULTS.IQ_TIMEOUT_MS) {
+        if (!this.comms || !this.comms.getCommsState().connected) {
+            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);
+    }
+    registerIncomingHandler(registration) {
+        return this.incomingNode.registerIncomingHandler(registration);
+    }
+    unregisterIncomingHandler(registration) {
+        return this.incomingNode.unregisterIncomingHandler(registration);
+    }
+    bindNodeTransportEvents() {
+        this.nodeTransport.on('frame_in', (frame) => this.emit('transport_frame_in', { frame }));
+        this.nodeTransport.on('frame_out', (frame) => this.emit('transport_frame_out', { frame }));
+        this.nodeTransport.on('node_in', (node, frame) => this.emit('transport_node_in', { node, frame }));
+        this.nodeTransport.on('node_out', (node, frame) => this.emit('transport_node_out', { node, frame }));
+        this.nodeTransport.on('decode_error', (error, frame) => {
+            this.emit('transport_decode_error', { error, frame });
+            this.handleError(error);
+        });
+    }
+    async handleIncomingMessageEvent(event) {
+        this.emit('message', event);
+        void persistIncomingMailboxEntities({
+            logger: this.logger,
+            contactStore: this.contactStore,
+            messageStore: this.messageStore,
+            event
+        });
+        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
+        });
+    }
+    async handleIncomingAppStateSyncKeyShare(event, protocolMessage) {
+        const share = protocolMessage.appStateSyncKeyShare;
+        if (!share) {
+            this.logger.warn('incoming app-state key share protocol message without payload', {
+                id: event.stanzaId,
+                from: event.chatJid
+            });
+            return;
+        }
+        try {
+            const imported = await this.appStateSync.importSyncKeyShare(share);
+            this.logger.info('imported app-state sync key share from protocol message', {
+                id: event.stanzaId,
+                from: event.chatJid,
+                imported
+            });
+            if (imported > 0) {
+                const hadWaiters = this.appStateKeyShareWaiters.size > 0;
+                this.appStateKeyShareVersion += 1;
+                this.notifyAppStateKeyShareWaiters(true);
+                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,
+                        from: event.chatJid,
+                        message: toError(error).message
+                    });
+                });
+            }
+        }
+        catch (error) {
+            this.logger.warn('failed to import app-state sync key share from protocol message', {
+                id: event.stanzaId,
+                from: event.chatJid,
+                message: toError(error).message
+            });
+        }
+    }
+    async handleIncomingAppStateSyncKeyRequest(event, protocolMessage) {
+        const request = protocolMessage.appStateSyncKeyRequest;
+        if (!request) {
+            this.logger.warn('incoming app-state key request protocol message without payload', {
+                id: event.stanzaId,
+                from: event.chatJid
+            });
+            return;
+        }
+        const requesterRaw = event.senderJid ?? event.chatJid;
+        if (!requesterRaw) {
+            this.logger.warn('incoming app-state key request missing sender jid', {
+                id: event.stanzaId
+            });
+            return;
+        }
+        let requesterDeviceJid;
+        try {
+            requesterDeviceJid = normalizeDeviceJid(requesterRaw);
+        }
+        catch (error) {
+            this.logger.warn('incoming app-state key request has malformed sender jid', {
+                id: event.stanzaId,
+                from: requesterRaw,
+                message: toError(error).message
+            });
+            return;
+        }
+        if (!this.isOwnAccountDeviceJid(requesterDeviceJid)) {
+            this.logger.warn('incoming app-state key request ignored: sender is not own account', {
+                id: event.stanzaId,
+                from: requesterDeviceJid
+            });
+            return;
+        }
+        const requestedKeyIds = this.extractAppStateSyncKeyRequestIds(request);
+        if (requestedKeyIds.length === 0) {
+            this.logger.warn('incoming app-state key request has no valid key ids', {
+                id: event.stanzaId,
+                from: requesterDeviceJid
+            });
+            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);
+        try {
+            await this.messageDispatch.sendAppStateSyncKeyShare(requesterDeviceJid, availableKeys, missingKeyIds);
+            this.logger.info('responded to app-state key request', {
+                id: event.stanzaId,
+                to: requesterDeviceJid,
+                requested: requestedKeyIds.length,
+                shared: availableKeys.length,
+                missing: missingKeyIds.length
+            });
+        }
+        catch (error) {
+            this.logger.warn('failed to respond to app-state key request', {
+                id: event.stanzaId,
+                to: requesterDeviceJid,
+                requested: requestedKeyIds.length,
+                shared: availableKeys.length,
+                missing: missingKeyIds.length,
+                message: toError(error).message
+            });
+        }
+    }
+    extractAppStateSyncKeyRequestIds(request) {
+        const deduped = new Map();
+        for (const key of request.keyIds ?? []) {
+            try {
+                const keyId = decodeProtoBytes(key.keyId, 'appStateSyncKeyRequest.keyIds[].keyId');
+                const keyHex = bytesToHex(keyId);
+                if (deduped.has(keyHex)) {
+                    continue;
+                }
+                deduped.set(keyHex, keyId);
+            }
+            catch (error) {
+                this.logger.trace('ignoring malformed app-state key id request entry', {
+                    message: toError(error).message
+                });
+            }
+        }
+        return [...deduped.values()];
+    }
+    isOwnAccountDeviceJid(candidateJid) {
+        const credentials = this.authClient.getCurrentCredentials();
+        if (!credentials) {
+            return false;
+        }
+        const candidateUser = toUserJid(candidateJid);
+        const meUsers = [credentials.meJid, credentials.meLid]
+            .filter((value) => !!value)
+            .map((jid) => toUserJid(jid));
+        return meUsers.includes(candidateUser);
+    }
+    async handleHistorySyncNotification(notification) {
+        try {
+            await processHistorySyncNotification({
+                logger: this.logger,
+                mediaTransfer: this.mediaTransfer,
+                contactStore: this.contactStore,
+                messageStore: this.messageStore,
+                threadStore: this.threadStore,
+                emitEvent: this.emit.bind(this)
+            }, notification);
+        }
+        catch (error) {
+            this.logger.warn('failed to process history sync notification', {
+                syncType: notification.syncType,
+                chunkOrder: notification.chunkOrder,
+                message: toError(error).message
+            });
+        }
+    }
+    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 handleIncomingFrame(frame) {
+        try {
+            await this.nodeTransport.dispatchIncomingFrame(frame, async (node) => this.incomingNode.handleIncomingNode(node));
+        }
+        catch (error) {
+            this.handleError(toError(error));
+        }
+    }
+    async connect() {
+        if (this.connectPromise) {
+            this.logger.trace('wa client connect already in-flight');
+            return this.connectPromise;
+        }
+        this.connectPromise = this.connectInternal().finally(() => {
+            this.connectPromise = null;
+        });
+        return this.connectPromise;
+    }
+    async connectInternal() {
+        if (this.comms) {
+            this.logger.trace('wa client connect skipped: comms already created');
+            return;
+        }
+        this.logger.info('wa client connect start');
+        let credentials = await this.authClient.loadOrCreateCredentials();
+        try {
+            await this.startCommsWithCredentials(credentials);
+        }
+        catch (error) {
+            if (credentials.routingInfo) {
+                this.logger.warn('connect failed with routing info, retrying without routing info', {
+                    message: toError(error).message
+                });
+                await this.disconnect();
+                credentials = await this.authClient.clearRoutingInfo();
+                await this.startCommsWithCredentials(credentials);
+            }
+            else {
+                await this.disconnect();
+                throw error;
+            }
+        }
+        this.logger.info('wa client connected');
+        this.emit('connection_open', {});
+    }
+    scheduleReconnectAfterPairing() {
+        this.logger.debug('wa client scheduling reconnect after pairing');
+        setTimeout(() => {
+            void this.reconnectAsRegisteredAfterPairing().catch((error) => {
+                this.handleError(toError(error));
+            });
+        }, 0);
+    }
+    async reconnectAsRegisteredAfterPairing() {
+        if (this.pairingReconnectPromise) {
+            this.logger.trace('pairing reconnect already in-flight');
+            return this.pairingReconnectPromise;
+        }
+        this.pairingReconnectPromise = this.reconnectAsRegisteredAfterPairingInternal().finally(() => {
+            this.pairingReconnectPromise = null;
+        });
+        return this.pairingReconnectPromise;
+    }
+    async reconnectAsRegisteredAfterPairingInternal() {
+        const credentials = this.authClient.getCurrentCredentials();
+        if (!credentials?.meJid) {
+            this.logger.trace('pairing reconnect skipped: still unregistered');
+            return;
+        }
+        const currentComms = this.comms;
+        if (!currentComms) {
+            this.logger.trace('pairing reconnect skipped: no active comms');
+            return;
+        }
+        this.logger.info('pairing completed, restarting comms as registered');
+        this.keepAlive.stop();
+        this.nodeOrchestrator.clearPending(new Error('restarting comms after pairing'));
+        this.clearCommsBinding();
+        try {
+            await currentComms.stopComms();
+        }
+        catch (error) {
+            this.logger.warn('failed to stop pre-registration comms', {
+                message: toError(error).message
+            });
+        }
+        try {
+            await this.startCommsWithCredentials(credentials);
+        }
+        catch (error) {
+            this.logger.warn('pairing reconnect failed while starting registered comms', {
+                message: toError(error).message
+            });
+            throw error;
+        }
+    }
+    async disconnect() {
+        this.logger.info('wa client disconnect start');
+        this.keepAlive.stop();
+        this.notifyAppStateKeyShareWaiters(false);
+        this.appStateBootstrapKeyShareWaitDone = false;
+        await this.authClient.clearTransientState();
+        this.nodeOrchestrator.clearPending(new Error('client disconnected'));
+        this.clockSkewMs = null;
+        this.mediaConnCache = null;
+        this.passiveTasks.resetInFlightState();
+        const comms = this.comms;
+        this.clearCommsBinding();
+        if (comms) {
+            await comms.stopComms();
+            this.logger.info('wa client disconnected');
+            this.emit('connection_close', {});
+        }
+    }
+    async requestPairingCode(phoneNumber, shouldShowPushNotification = false) {
+        if (!this.comms || !this.authClient.getCurrentCredentials()) {
+            throw new Error('client is not connected');
+        }
+        this.logger.debug('wa client request pairing code');
+        return this.authClient.requestPairingCode(phoneNumber, shouldShowPushNotification);
+    }
+    async fetchPairingCountryCodeIso() {
+        if (!this.comms || !this.authClient.getCurrentCredentials()) {
+            throw new Error('client is not connected');
+        }
+        this.logger.trace('wa client fetch pairing country code iso');
+        return this.authClient.fetchPairingCountryCodeIso();
+    }
+    async sendMessage(to, content, options = {}) {
+        return this.messageDispatch.sendMessage(to, content, options);
+    }
+    async syncSignalSession(jid, reasonIdentity = false) {
+        await this.messageDispatch.syncSignalSession(jid, reasonIdentity);
+    }
+    async sendReceipt(input) {
+        await this.messageDispatch.sendReceipt(input);
+    }
+    async exportAppState() {
+        return this.appStateSync.exportState();
+    }
+    async syncAppState(options = {}) {
+        if (!this.comms) {
+            throw new Error('client is not connected');
+        }
+        const shouldWaitForKeyShare = (await this.appStateStore.getActiveSyncKey()) === null;
+        if (shouldWaitForKeyShare && !this.appStateBootstrapKeyShareWaitDone) {
+            this.appStateBootstrapKeyShareWaitDone = true;
+            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.waitForAppStateKeyShare(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.appStateKeyShareVersion;
+        while (blockedCollections.length > 0 &&
+            retryCount < WA_APP_STATE_KEY_SHARE_MAX_RETRIES) {
+            const hasFreshShare = this.appStateKeyShareVersion !== 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.waitForAppStateKeyShare(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.appStateKeyShareVersion;
+            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);
+        }
+        if (blockedCollections.length > 0) {
+            this.logger.warn('app-state bootstrap still blocked after waiting for key share', {
+                blockedCollections: blockedCollections.join(','),
+                retries: retryCount
+            });
+        }
+        this.emitChatEventsFromAppStateSyncResult(syncResult);
+        return syncResult;
+    }
+    async executeAppStateSync(options) {
+        return options.downloadExternalBlob
+            ? this.appStateSync.sync(options)
+            : this.appStateSync.sync({
+                ...options,
+                downloadExternalBlob: async (_collection, _kind, reference) => downloadExternalBlobReference(this.mediaTransfer, reference)
+            });
+    }
+    getBlockedAppStateCollections(syncResult) {
+        return syncResult.collections
+            .filter((entry) => entry.state === WA_APP_STATE_COLLECTION_STATES.BLOCKED)
+            .map((entry) => entry.collection);
+    }
+    async waitForAppStateKeyShare(timeoutMs) {
+        return new Promise((resolve) => {
+            let settled = false;
+            let timeoutHandle = null;
+            const waiter = (received) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                if (timeoutHandle) {
+                    clearTimeout(timeoutHandle);
+                    timeoutHandle = null;
+                }
+                this.appStateKeyShareWaiters.delete(waiter);
+                resolve(received);
+            };
+            this.appStateKeyShareWaiters.add(waiter);
+            timeoutHandle = setTimeout(() => {
+                waiter(false);
+            }, timeoutMs);
+        });
+    }
+    notifyAppStateKeyShareWaiters(received) {
+        if (this.appStateKeyShareWaiters.size === 0) {
+            return;
+        }
+        const waiters = [...this.appStateKeyShareWaiters.values()];
+        this.appStateKeyShareWaiters.clear();
+        for (const waiter of waiters) {
+            waiter(received);
+        }
+    }
+    emitChatEventsFromAppStateSyncResult(syncResult) {
+        const shouldEmitSnapshotMutations = this.options.chatEvents?.emitSnapshotMutations === true;
+        for (const collectionResult of syncResult.collections) {
+            const mutations = collectionResult.mutations ?? [];
+            const lastMutationIndexByKey = new Map();
+            for (let mutationIndex = 0; mutationIndex < mutations.length; mutationIndex += 1) {
+                const mutation = mutations[mutationIndex];
+                if (!shouldEmitSnapshotMutations && mutation.source === 'snapshot') {
+                    continue;
+                }
+                lastMutationIndexByKey.set(`${mutation.collection}\u0001${mutation.index}`, mutationIndex);
+            }
+            for (let mutationIndex = 0; mutationIndex < mutations.length; mutationIndex += 1) {
+                const mutation = mutations[mutationIndex];
+                if (!shouldEmitSnapshotMutations && mutation.source === 'snapshot') {
+                    continue;
+                }
+                const coalesceKey = `${mutation.collection}\u0001${mutation.index}`;
+                if (lastMutationIndexByKey.get(coalesceKey) !== mutationIndex) {
+                    continue;
+                }
+                try {
+                    const event = parseChatEventFromAppStateMutation(mutation);
+                    if (!event) {
+                        continue;
+                    }
+                    this.emit('chat_event', event);
+                }
+                catch (error) {
+                    this.logger.debug('failed to parse chat event from app-state mutation', {
+                        collection: mutation.collection,
+                        source: mutation.source,
+                        index: mutation.index,
+                        message: toError(error).message
+                    });
+                }
+            }
+        }
+    }
+    async startCommsWithCredentials(credentials) {
+        this.logger.debug('starting comms with credentials', {
+            registered: credentials.meJid !== null && credentials.meJid !== undefined
+        });
+        const commsConfig = this.authClient.buildCommsConfig(this.options);
+        const comms = new WaComms(commsConfig, this.logger);
+        this.mediaConnCache = null;
+        this.nodeTransport.bindComms(comms);
+        try {
+            comms.startComms(async (frame) => this.handleIncomingFrame(frame));
+            await comms.waitForConnection(commsConfig.connectTimeoutMs);
+            this.comms = comms;
+            this.logger.info('comms connected');
+            comms.startHandlingRequests();
+            if (credentials.meJid) {
+                this.keepAlive.start();
+            }
+            else {
+                this.keepAlive.stop();
+            }
+            const serverStaticKey = comms.getServerStaticKey();
+            if (!serverStaticKey) {
+                this.logger.trace('no server static key available to persist');
+            }
+            else {
+                await this.authClient.persistServerStaticKey(serverStaticKey);
+                this.logger.debug('persisted server static key after comms connect');
+            }
+            this.passiveTasks.startPassiveTasksAfterConnect();
+        }
+        catch (error) {
+            this.clearCommsBinding();
+            try {
+                await comms.stopComms();
+            }
+            catch (stopError) {
+                this.logger.warn('failed to cleanup comms after connection start failure', {
+                    message: toError(stopError).message
+                });
+            }
+            throw error;
+        }
+    }
+    shouldQueueDanglingReceipt(node, error) {
+        if (node.tag !== WA_MESSAGE_TAGS.RECEIPT) {
+            return false;
+        }
+        const normalized = error.message.trim().toLowerCase();
+        return (normalized === 'comms is not connected' ||
+            normalized === 'websocket is not connected' ||
+            normalized === 'noise session socket closed' ||
+            normalized.startsWith('socket closed ('));
+    }
+    enqueueDanglingReceipt(node) {
+        if (this.danglingReceipts.length >= WA_DEFAULTS.MAX_DANGLING_RECEIPTS) {
+            this.danglingReceipts.shift();
+        }
+        this.danglingReceipts.push(node.content === undefined
+            ? {
+                tag: node.tag,
+                attrs: { ...node.attrs }
+            }
+            : {
+                tag: node.tag,
+                attrs: { ...node.attrs },
+                content: node.content
+            });
+    }
+    async clearStoredState() {
+        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();
+    }
+    handleError(error) {
+        this.logger.error('wa client error', { message: error.message });
+        this.emit('client_error', { error });
+    }
+    clearCommsBinding() {
+        this.notifyAppStateKeyShareWaiters(false);
+        this.comms = null;
+        this.nodeTransport.bindComms(null);
+    }
+    updateClockSkewFromSuccess(serverUnixSeconds) {
+        const serverMs = serverUnixSeconds * 1000;
+        const nowMs = Date.now();
+        this.clockSkewMs = serverMs - nowMs;
+        this.logger.debug('updated clock skew from success', {
+            serverUnixSeconds,
+            clockSkewMs: this.clockSkewMs
+        });
+    }
+}