zapo-js 0.3.0 → 1.0.0

package/dist/esm/client/WaClient.js

@@ -1,21 +1,18 @@
 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 { createIgnoreKeyFilter, validateIgnoreKey } from './messaging/ignore-key.js';
+import { runHistorySyncNotification } from './persistence/history-sync.js';
+import { persistIncomingMailboxEntities } from './persistence/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 { WA_LOGOUT_REASONS } from '../protocol/stream.js';
+import { WA_DEFAULTS, WA_MESSAGE_TYPES } from '../protocol/constants.js';
+import { normalizeDeviceJid } from '../protocol/jid.js';
+import { WA_DISCONNECT_REASONS, 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 { fetchLatestWaWebVersion } from '../transport/wa-web-version-fetcher.js';
 import { toError } from '../util/primitives.js';
 const SYNC_RELATED_PROTOCOL_TYPES = new Set([
     proto.Message.ProtocolMessage.Type.APP_STATE_SYNC_KEY_REQUEST,
@@ -23,7 +20,59 @@ 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
 ]);
+/**
+ * Top-level WhatsApp client. Owns the transport, auth, signal, and per-feature
+ * coordinators (accessible via getters such as {@link message}, {@link group},
+ * {@link newsletter}, etc.) and re-emits every {@link WaClientEventMap} event.
+ *
+ * Lifecycle: construct with {@link WaClientOptions}, call {@link connect} to
+ * open the socket, react to `connection`/`auth_qr`/`auth_pairing_code` events,
+ * then use the coordinator getters to drive the session. Call {@link disconnect}
+ * to shut down cleanly or {@link logout} to remove the companion device.
+ *
+ * @example
+ * ```ts
+ * import { createPinoLogger, createStore, WaClient } from '../index.js'
+ * import { createSqliteStore } from '@zapo-js/store-sqlite'
+ *
+ * const store = createStore({
+ *     backends: { sqlite: createSqliteStore({ path: '.auth/state.sqlite' }) },
+ *     providers: {
+ *         auth: 'sqlite',
+ *         signal: 'sqlite',
+ *         preKey: 'sqlite',
+ *         session: 'sqlite',
+ *         identity: 'sqlite',
+ *         senderKey: 'sqlite',
+ *         appState: 'sqlite',
+ *         privacyToken: 'sqlite',
+ *         messages: 'sqlite',
+ *         threads: 'sqlite',
+ *         contacts: 'sqlite'
+ *     }
+ * })
+ *
+ * const client = new WaClient(
+ *     { store, sessionId: 'default' },
+ *     await createPinoLogger({ level: 'info', pretty: true })
+ * )
+ *
+ * client.on('auth_qr', ({ qr, ttlMs }) => console.log('scan:', qr, ttlMs))
+ * client.on('connection', (event) => console.log('connection', event))
+ * client.on('message', async (event) => {
+ *     if (event.message?.conversation === 'ping') {
+ *         await client.message.send(event.chatJid!, 'pong')
+ *     }
+ * })
+ *
+ * await client.connect()
+ * ```
+ */
 export class WaClient extends EventEmitter {
+    /**
+     * @param options Client configuration (store, transport, addons, history...).
+     * @param logger  Optional structured logger. Defaults to a `ConsoleLogger('info')`.
+     */
     constructor(options, logger = new ConsoleLogger('info')) {
         super();
         this.connectPromise = null;
@@ -33,38 +82,26 @@ export class WaClient extends EventEmitter {
         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.stores = base.sessionStore;
         this.writeBehind = new WriteBehindPersistence({
-            messageStore: this.messageStore,
-            threadStore: this.threadStore,
-            contactStore: this.contactStore
+            messageStore: this.stores.messages,
+            threadStore: this.stores.threads,
+            contactStore: this.stores.contacts
         }, 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');
+        if (this.options.addons?.autoDecrypt !== false &&
+            this.stores.messageSecret === NOOP_MESSAGE_SECRET_STORE) {
+            this.logger.warn('addons.autoDecrypt is on (default) but messageSecret cache is noop – ' +
+                'addon decryption will only work if secrets are in the message store. ' +
+                'Set addons.autoDecrypt: false to silence this warning.');
         }
         const dependencies = buildWaClientDependencies({
             base,
             runtime: {
-                sendNode: (node) => this.sendNode(node),
-                query: (node, timeoutMs, options) => this.query(node, timeoutMs, options),
+                sendNode: (node) => this.deps.lowLevelCoordinator.sendNode(node),
+                query: (node, timeoutMs, options) => this.deps.lowLevelCoordinator.query(node, timeoutMs, options),
                 queryWithContext: this.queryWithContext.bind(this),
-                syncAppState: () => this.syncAppState().then(() => { }),
-                syncAppStateWithOptions: (syncOptions) => this.syncAppState(syncOptions),
+                syncAppState: () => this.deps.chatCoordinator.sync().then(() => { }),
+                syncAppStateWithOptions: (syncOptions) => this.deps.chatCoordinator.sync(syncOptions),
                 emitEvent: this.emit.bind(this),
                 handleIncomingMessageEvent: this.handleIncomingMessageEvent.bind(this),
                 handleError: this.handleError.bind(this),
@@ -72,11 +109,50 @@ export class WaClient extends EventEmitter {
                 clearStoredState: this.clearStoredState.bind(this),
                 resumeIncomingEvents: () => {
                     this.acceptingIncomingEvents = true;
-                }
+                },
+                subscribeProtocolMessage: (handler) => {
+                    this.on('message_protocol', handler);
+                    return () => {
+                        this.off('message_protocol', handler);
+                    };
+                },
+                persistContact: (record) => this.writeBehind.persistContact(record)
             }
         });
-        Object.assign(this, dependencies);
+        this.deps = dependencies;
+        this.appStateSync = dependencies.appStateSync;
+        this.mediaTransfer = dependencies.mediaTransfer;
         this.bindNodeTransportEvents();
+        this.on('connection', (event) => {
+            if (event.status !== 'close')
+                return;
+            if (!this.options.recoverFromClientTooOld)
+                return;
+            if (event.reason !== WA_DISCONNECT_REASONS.FAILURE_CLIENT_TOO_OLD)
+                return;
+            this.logger.warn('wa rejected the connect with client_too_old: the zapo default WA Web version is outdated. ' +
+                'Auto-recovering by fetching the current version from web.whatsapp.com – ' +
+                'please upgrade zapo so the shipped default catches up.');
+            void this.runClientTooOldRecover();
+        });
+    }
+    async runClientTooOldRecover() {
+        try {
+            if (this.connectPromise) {
+                await this.connectPromise.catch(() => undefined);
+            }
+            const latest = await fetchLatestWaWebVersion();
+            this.logger.info('client_too_old auto-recover: reconnecting', {
+                version: latest.version
+            });
+            this.deps.authClient.setNextConnectVersion(latest.version);
+            await this.connect();
+        }
+        catch (error) {
+            this.logger.warn('client_too_old auto-recover failed', {
+                message: toError(error).message
+            });
+        }
     }
     on(event, listener) {
         return super.on(event, listener);
@@ -90,60 +166,36 @@ export class WaClient extends EventEmitter {
     emit(event, ...args) {
         return super.emit(event, ...args);
     }
+    /**
+     * Returns the current auth state snapshot (credentials, registration,
+     * connection flag) – useful for resuming or inspecting the client.
+     */
     getState() {
-        const connected = this.connectionManager.isConnected();
+        const connected = this.deps.connectionManager.isConnected();
         this.logger.trace('wa client state requested', { connected });
-        return this.authClient.getState(connected);
+        return this.deps.authClient.getState(connected);
     }
+    /**
+     * Returns the credentials persisted for the current session, or `null` if
+     * the client has not been paired yet.
+     */
     getCredentials() {
-        return this.authClient.getCurrentCredentials();
+        return this.deps.authClient.getCurrentCredentials();
     }
+    /**
+     * Returns the measured skew between the local clock and the server, in
+     * milliseconds, or `null` if no handshake has completed yet.
+     */
     getClockSkewMs() {
-        return this.connectionManager.getClockSkewMs();
-    }
-    async sendNode(node) {
-        try {
-            await this.nodeOrchestrator.sendNode(node);
-        }
-        catch (error) {
-            const normalized = toError(error);
-            if (this.receiptQueue.shouldQueue(node, normalized)) {
-                this.receiptQueue.enqueue(node);
-                this.logger.warn('queued dangling receipt after send failure', {
-                    id: node.attrs.id,
-                    to: node.attrs.to,
-                    message: normalized.message,
-                    queueSize: this.receiptQueue.size()
-                });
-                return;
-            }
-            throw normalized;
-        }
-    }
-    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, options);
-    }
-    registerIncomingHandler(registration) {
-        return this.incomingNode.registerIncomingHandler(registration);
-    }
-    unregisterIncomingHandler(registration) {
-        return this.incomingNode.unregisterIncomingHandler(registration);
+        return this.deps.connectionManager.getClockSkewMs();
     }
     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.deps.nodeTransport.on('frame_in', (frame) => this.emit('debug_transport_frame_in', { frame }));
+        this.deps.nodeTransport.on('frame_out', (frame) => this.emit('debug_transport_frame_out', { frame }));
+        this.deps.nodeTransport.on('node_in', (node, frame) => this.emit('debug_transport_node_in', { node, frame }));
+        this.deps.nodeTransport.on('node_out', (node, frame) => this.emit('debug_transport_node_out', { node, frame }));
+        this.deps.nodeTransport.on('decode_error', (error, frame) => {
+            this.emit('debug_transport_decode_error', { error, frame });
             this.handleError(error);
         });
     }
@@ -156,13 +208,23 @@ export class WaClient extends EventEmitter {
             void persistIncomingMailboxEntities({
                 logger: this.logger,
                 writeBehind: this.writeBehind,
-                messageSecretStore: this.messageSecretStore,
+                messageSecretStore: this.stores.messageSecret,
                 event
             });
-            if (this.options.addons?.autoDecrypt && event.message) {
-                void this.tryDecryptAddon(event).catch((err) => {
+            if (this.options.addons?.autoDecrypt !== false && event.message) {
+                void this.deps.messageCoordinator.tryDecryptAddon(event).catch((err) => {
                     this.logger.warn('addon auto-decrypt failed', {
-                        id: event.stanzaId,
+                        id: event.key.id,
+                        message: toError(err).message
+                    });
+                });
+            }
+            // Decode unconditionally – chunks whose parent prompt we never sent
+            // are skipped by the secret-store lookup downstream.
+            if (event.message) {
+                void this.deps.botCoordinator.tryDecryptChunk(event).catch((err) => {
+                    this.logger.warn('bot chunk auto-decrypt failed', {
+                        id: event.key.id,
                         message: toError(err).message
                     });
                 });
@@ -179,36 +241,62 @@ export class WaClient extends EventEmitter {
             const protocolType = protocolMessage.type;
             if (protocolType === null || protocolType === undefined) {
                 this.logger.debug('incoming protocol message without type', {
-                    id: event.stanzaId,
-                    from: event.chatJid
+                    id: event.key.id,
+                    from: event.key.remoteJid
                 });
                 return;
             }
             if (protocolType === proto.Message.ProtocolMessage.Type.APP_STATE_SYNC_KEY_REQUEST) {
-                await this.handleIncomingAppStateSyncKeyRequest(event, protocolMessage);
+                await this.appStateSync.handleIncomingKeyRequest(event.key, protocolMessage);
                 return;
             }
             if (protocolType === proto.Message.ProtocolMessage.Type.APP_STATE_SYNC_KEY_SHARE) {
-                await this.handleIncomingAppStateSyncKeyShare(event, protocolMessage);
+                await this.appStateSync.handleIncomingKeyShare(event.key, 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.history?.enabled !== false &&
+                    protocolMessage.historySyncNotification) {
+                    const peerRemoteJid = event.key.remoteJid;
+                    const peerStanzaId = event.key.id;
+                    await runHistorySyncNotification({
+                        logger: this.logger,
+                        mediaTransfer: this.mediaTransfer,
+                        writeBehind: this.writeBehind,
+                        emitEvent: this.emit.bind(this),
+                        onPrivacyTokens: (conversations) => this.deps.trustedContactToken.hydrateFromHistorySync(conversations),
+                        onNctSalt: (salt) => this.deps.trustedContactToken.hydrateNctSaltFromHistorySync(salt),
+                        onProcessed: peerRemoteJid && peerStanzaId
+                            ? async () => {
+                                try {
+                                    await this.message.sendReceipt(peerRemoteJid, peerStanzaId, {
+                                        type: WA_MESSAGE_TYPES.RECEIPT_TYPE_HISTORY_SYNC
+                                    });
+                                }
+                                catch (err) {
+                                    this.logger.warn('failed to send hist_sync receipt', {
+                                        id: peerStanzaId,
+                                        to: peerRemoteJid,
+                                        message: toError(err).message
+                                    });
+                                }
+                            }
+                            : undefined
+                    }, protocolMessage.historySyncNotification);
                 }
                 return;
             }
             if (SYNC_RELATED_PROTOCOL_TYPES.has(protocolType)) {
                 this.logger.info('incoming sync-related protocol message', {
-                    id: event.stanzaId,
-                    from: event.chatJid,
+                    id: event.key.id,
+                    from: event.key.remoteJid,
                     protocolType
                 });
                 return;
             }
             this.logger.debug('incoming protocol message received', {
-                id: event.stanzaId,
-                from: event.chatJid,
+                id: event.key.id,
+                from: event.key.remoteJid,
                 protocolType
             });
         }
@@ -216,189 +304,60 @@ export class WaClient extends EventEmitter {
             this.leaveIncomingHandler();
         }
     }
-    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) {
-                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 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', {
-                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);
-        return ((!!credentials.meJid && toUserJid(credentials.meJid) === candidateUser) ||
-            (!!credentials.meLid && toUserJid(credentials.meLid) === candidateUser));
-    }
-    async handleHistorySyncNotification(notification) {
-        try {
-            await processHistorySyncNotification({
-                logger: this.logger,
-                mediaTransfer: this.mediaTransfer,
-                writeBehind: this.writeBehind,
-                emitEvent: this.emit.bind(this),
-                onPrivacyTokens: (conversations) => this.trustedContactToken.hydrateFromHistorySync(conversations),
-                onNctSalt: (salt) => this.trustedContactToken.hydrateNctSaltFromHistorySync(salt)
-            }, 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 = {}, options = {}) {
-        return queryNodeWithContext(async (queryNode, queryTimeoutMs) => this.query(queryNode, queryTimeoutMs, options), this.logger, context, node, timeoutMs, contextData);
+        return queryNodeWithContext(async (queryNode, queryTimeoutMs) => this.deps.lowLevelCoordinator.query(queryNode, queryTimeoutMs, options), this.logger, context, node, timeoutMs, contextData);
     }
     async handleIncomingFrame(frame) {
         try {
-            await this.nodeTransport.dispatchIncomingFrame(frame, async (node) => this.incomingNode.handleIncomingNode(node));
+            await this.deps.nodeTransport.dispatchIncomingFrame(frame, async (node) => this.deps.incomingNode.handleIncomingNode(node));
         }
         catch (error) {
             this.handleError(toError(error));
         }
     }
+    /**
+     * Opens the transport and runs the noise/auth handshake. If a connection
+     * is already in flight, the in-flight promise is reused. Resolves once the
+     * client is fully ready; pairing prompts are surfaced via the `auth_qr`
+     * and `auth_pairing_code` events while this awaits.
+     *
+     * **First-time pairing:** the promise stays pending until the user scans a
+     * QR or types the pairing code. Subscribe to `auth_qr` / `auth_pairing_code`
+     * *before* awaiting – they fire while `connect()` is still running.
+     *
+     * @example
+     * ```ts
+     * // QR pairing (default – works headless)
+     * client.on('auth_qr', ({ qr }) => console.log('scan:', qr))
+     * client.on('auth_paired', ({ credentials }) => console.log('paired:', credentials.meJid))
+     * await client.connect()
+     *
+     * // Link-code pairing – call requestPairingCode while connect() is running
+     * void client.connect()
+     * await new Promise((r) => client.once('auth_pairing_required', r))
+     * const code = await client.auth.requestPairingCode('5511999999999')
+     * console.log('enter code on phone:', code)
+     * ```
+     */
     async connect() {
         if (this.connectPromise) {
             this.logger.trace('wa client connect already in-flight');
             return this.connectPromise;
         }
+        this.writeBehind.restart();
         this.acceptingIncomingEvents = true;
-        this.connectPromise = this.connectionManager
+        this.connectPromise = this.deps.connectionManager
             .connect((frame) => this.handleIncomingFrame(frame))
             .then(() => {
+            if (!this.deps.authClient.getCurrentCredentials()?.meJid) {
+                return;
+            }
             this.emit('connection', {
                 status: 'open',
                 reason: 'connected',
                 code: null,
                 isLogout: false,
-                isNewLogin: this.connectionManager.wasNewLogin()
+                isNewLogin: false
             });
         })
             .finally(() => {
@@ -406,6 +365,14 @@ export class WaClient extends EventEmitter {
         });
         return this.connectPromise;
     }
+    /**
+     * Closes the transport gracefully: pauses incoming events, flushes the
+     * write-behind persistence queue, and emits a `connection` close event
+     * with reason `client_disconnected`. Does not clear stored credentials -
+     * call {@link connect} again to resume the same session. There is no
+     * built-in auto-reconnect; subscribe to `connection: { status: 'close' }`
+     * and decide your own backoff.
+     */
     async disconnect() {
         await this.pauseIncomingEventsAndWaitDrain();
         const writeBehindFlush = await this.writeBehind.flush(this.options.writeBehind?.flushTimeoutMs);
@@ -414,7 +381,7 @@ export class WaClient extends EventEmitter {
                 remaining: writeBehindFlush.remaining
             });
         }
-        await this.connectionManager.disconnect();
+        await this.deps.connectionManager.disconnect();
         this.emit('connection', {
             status: 'close',
             reason: 'client_disconnected',
@@ -423,65 +390,112 @@ export class WaClient extends EventEmitter {
             isNewLogin: 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, customCode);
+    /**
+     * Drops matching inbound stanzas before any handler runs. Server still
+     * gets the ack so it stops re-delivering. Returns an `unregister` function.
+     *
+     * Accepts either a declarative descriptor or a predicate. The descriptor
+     * matches by `remoteJid`/`fromMe`/`id`/`participant` (PN ↔ LID alt-attrs
+     * resolved automatically) and throws when no match field is given or
+     * arrays are empty. The predicate receives a parsed
+     * {@link WaIgnoreKeyContext} and returns `true` to drop the stanza.
+     *
+     * @example
+     * ```ts
+     * client.ignoreKey({ remoteJid: spammerJid })
+     * client.ignoreKey({ fromMe: true, only: ['message'] })
+     * client.ignoreKey((m) => m.kind === 'message' && isGroupJid(m.remoteJid ?? ''))
+     * ```
+     */
+    ignoreKey(input) {
+        if (typeof input !== 'function') {
+            validateIgnoreKey(input);
+        }
+        const filter = createIgnoreKeyFilter(input, () => this.deps.authClient.getCurrentCredentials()?.meJid);
+        return this.deps.incomingNode.registerIncomingStanzaFilter(filter);
+    }
+    /** Auth client: pairing, credentials, registration state. */
+    get auth() {
+        return this.deps.authClient;
+    }
+    /** Message coordinator: send/receive, receipts, addons, media download. */
+    get message() {
+        return this.deps.messageCoordinator;
+    }
+    /** Presence coordinator: own/peer presence subscriptions. */
+    get presence() {
+        return this.deps.presenceCoordinator;
+    }
+    /** Low-level coordinator: raw node send/query escape hatch. */
+    get lowlevel() {
+        return this.deps.lowLevelCoordinator;
+    }
+    /** App-state mutation coordinator: chat-side settings (mute, pin, etc.). */
+    get chat() {
+        return this.deps.chatCoordinator;
     }
-    async fetchPairingCountryCodeIso() {
-        if (!this.connectionManager.isConnected() || !this.authClient.getCurrentCredentials()) {
-            throw new Error('client is not connected');
-        }
-        this.logger.trace('wa client fetch pairing country code iso');
-        return this.authClient.fetchPairingCountryCodeIso();
+    /** Group coordinator: create/query/manage WhatsApp groups and communities. */
+    get group() {
+        return this.deps.groupCoordinator;
     }
-    async getLidsByPhoneNumbers(phoneNumbers) {
-        if (!this.connectionManager.isConnected() || !this.authClient.getCurrentCredentials()) {
-            throw new Error('client is not connected');
-        }
-        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
-        });
-        return this.signalDeviceSync.queryLidsByPhoneJids(normalizedPhoneJids);
-    }
-    sendMessage(to, content, options = {}) {
-        return this.messageDispatch.sendMessage(to, content, options);
-    }
-    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
-            }));
-        }
+    /** Status coordinator: status broadcast send and reactions. */
+    get status() {
+        return this.deps.statusCoordinator;
     }
-    get chat() {
-        return this.chatCoordinator;
+    /**
+     * Broadcast-list coordinator: list management and broadcast sends.
+     * **Business-only** - the underlying app-state schema rejects regular
+     * accounts. See {@link WaBroadcastListCoordinator}.
+     */
+    get broadcastList() {
+        return this.deps.broadcastListCoordinator;
     }
-    get group() {
-        return this.groupCoordinator;
+    /** Newsletter coordinator: create/query/follow/admin/send for channels. */
+    get newsletter() {
+        return this.deps.newsletterCoordinator;
     }
+    /** Privacy coordinator: privacy categories, blocklist, disallowed list. */
     get privacy() {
-        return this.privacyCoordinator;
+        return this.deps.privacyCoordinator;
     }
+    /** Profile coordinator: own/peer profile fields (picture, status, username). */
     get profile() {
-        return this.profileCoordinator;
-    }
+        return this.deps.profileCoordinator;
+    }
+    /**
+     * Business coordinator: business profile, verified-name lookups. Reads
+     * work from any account; **writes (`editBusinessProfile`,
+     * `updateCoverPhoto`, `deleteCoverPhoto`) are business-only** and throw
+     * on regular accounts. See {@link WaBusinessCoordinator}.
+     */
     get business() {
-        return this.businessCoordinator;
+        return this.deps.businessCoordinator;
     }
-    get email() {
-        return this.emailCoordinator;
+    /** Bot coordinator: Meta-AI bot profiles, prompt/chunk decryption. */
+    get bot() {
+        return this.deps.botCoordinator;
     }
+    /**
+     * Email coordinator: bind/unbind/verify email on the account.
+     * **Mobile-only** - every method throws unless the client is connected
+     * via `options.mobileTransport`. See {@link WaEmailCoordinator}.
+     */
+    get email() {
+        return this.deps.emailCoordinator;
+    }
+    /**
+     * Unpairs this companion device by removing it server-side. Requires an
+     * authenticated session; throws when no `meJid` is present.
+     *
+     * **Does not** disconnect the socket or clear local stores by itself -
+     * the server initiates the close after accepting the IQ, which surfaces
+     * via a `connection` event with `isLogout: true`. That close handler is
+     * what wipes the persisted state, honoring `options.logoutStoreClear`.
+     * The {@link WaClient} instance is single-shot after logout: create a
+     * fresh one (with a fresh `sessionId` or pre-cleared store) to re-pair.
+     */
     async logout(reason = WA_LOGOUT_REASONS.USER_INITIATED) {
-        const meJid = this.authClient.getCurrentCredentials()?.meJid;
+        const meJid = this.deps.authClient.getCurrentCredentials()?.meJid;
         if (!meJid) {
             throw new Error('cannot logout: client is not authenticated');
         }
@@ -493,201 +507,56 @@ export class WaClient extends EventEmitter {
         });
         assertIqResult(result, 'client.logout');
     }
-    sendReceipt(input) {
-        return this.messageDispatch.sendReceipt(input);
-    }
-    flushAppStateMutations() {
-        return this.chatCoordinator.flushMutations();
-    }
-    flushWriteBehind(timeoutMs) {
-        return this.writeBehind.flush(timeoutMs);
-    }
-    async exportAppState() {
-        return this.appStateSync.exportState();
-    }
-    async syncAppState(options = {}) {
-        if (!this.connectionManager.isConnected()) {
-            throw new Error('client is not connected');
-        }
-        const syncResult = await this.executeAppStateSync(options);
-        const blockedCollections = this.getBlockedAppStateCollections(syncResult);
-        if (blockedCollections.length > 0) {
-            this.logger.warn('app-state sync has blocked collections', {
-                blockedCollections: blockedCollections.join(',')
-            });
-        }
-        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) {
-        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;
-        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 {
-                    this.handleNctSaltMutation(mutation);
-                    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
-                    });
-                }
-            }
-        }
-    }
-    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();
+        const danglingReceipts = this.deps.receiptQueue.take();
         if (danglingReceipts.length > 0) {
             this.logger.debug('cleared dangling receipts while clearing stored state', {
                 count: danglingReceipts.length
             });
         }
         const s = this.options.logoutStoreClear;
-        const shouldClear = (key) => s === undefined || s[key] !== false;
+        const isMailbox = (key) => key === 'messages' || key === 'threads' || key === 'contacts';
+        const shouldClear = (key) => {
+            const explicit = s?.[key];
+            if (explicit !== undefined)
+                return explicit;
+            return !isMailbox(key);
+        };
         if (shouldClear('auth'))
-            await this.authClient.clearStoredCredentials();
+            await this.deps.authClient.clearStoredCredentials();
         if (shouldClear('appState'))
-            await this.appStateStore.clear();
+            await this.stores.appState.clear();
         if (shouldClear('contacts'))
-            await this.contactStore.clear();
+            await this.stores.contacts.clear();
         if (shouldClear('messages'))
-            await this.messageStore.clear();
+            await this.stores.messages.clear();
         if (shouldClear('messageSecret'))
-            await this.messageSecretStore.clear();
-        if (shouldClear('participants'))
-            await this.participantsStore.clear();
+            await this.stores.messageSecret.clear();
+        if (shouldClear('groupMetadata'))
+            await this.stores.groupMetadata.clear();
         if (shouldClear('deviceList'))
-            await this.deviceListStore.clear();
+            await this.stores.deviceList.clear();
         if (shouldClear('retry'))
-            await this.retryStore.clear();
+            await this.stores.retry.clear();
         if (shouldClear('signal'))
-            await this.signalStore.clear();
+            await this.stores.signal.clear();
         if (shouldClear('preKey'))
-            await this.preKeyStore.clear();
+            await this.stores.preKey.clear();
         if (shouldClear('session'))
-            await this.sessionStore.clear();
+            await this.stores.session.clear();
         if (shouldClear('identity'))
-            await this.identityStore.clear();
+            await this.stores.identity.clear();
         if (shouldClear('senderKey'))
-            await this.senderKeyStore.clear();
+            await this.stores.senderKey.clear();
         if (shouldClear('threads'))
-            await this.threadStore.clear();
+            await this.stores.threads.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);
+            await this.stores.privacyToken.clear();
     }
     tryEnterIncomingHandler() {
         if (!this.acceptingIncomingEvents) {
@@ -731,6 +600,6 @@ export class WaClient extends EventEmitter {
     }
     handleError(error) {
         this.logger.error('wa client error', { message: error.message });
-        this.emit('client_error', { error });
+        this.emit('debug_client_error', { error });
     }
 }