zapo-js 1.6.0 → 1.6.2

package/dist/esm/transport/WaComms.js

@@ -78,6 +78,7 @@ export class WaComms {
         this.usedResumeHandshake = false;
         this.noiseSession = null;
         this.lastServerStaticKey = null;
+        this.lastInboundAtMs = 0;
         this.frameProcessingQueue = Promise.resolve();
         this.frameHandlerQueue = new BoundedTaskQueue(WA_FRAME_HANDLER_QUEUE_MAX_SIZE, WA_FRAME_HANDLER_MAX_CONCURRENCY);
     }
@@ -205,6 +206,10 @@ export class WaComms {
         const wire = await this.noiseSession.encryptFrame(payload);
         await this.socket.send(wire);
     }
+    /** Timestamp (`Date.now()` ms) of the last raw payload received from the socket; `0` before any inbound. */
+    getLastInboundAtMs() {
+        return this.lastInboundAtMs;
+    }
     getCommsState() {
         return {
             started: this.started,
@@ -285,6 +290,7 @@ export class WaComms {
         });
     }
     onSocketMessage(payload) {
+        this.lastInboundAtMs = Date.now();
         this.frameProcessingQueue = this.frameProcessingQueue.then(() => this.processSocketPayload(payload), () => this.processSocketPayload(payload));
     }
     async processSocketPayload(payload) {
@@ -522,6 +528,7 @@ export class WaComms {
             this.resumeHandshakeFailures = 0;
         }
         this.noiseSession = null;
+        this.lastInboundAtMs = 0;
         this.clearPendingFrames();
         this.pendingFramesOverflowClosing = false;
         if (options.clearHandlers) {

package/dist/esm/transport/keepalive/WaKeepAlive.js

@@ -5,8 +5,13 @@ const KEEPALIVE_DEFAULT_MIN_JITTER_MS = 250;
 const KEEPALIVE_MAX_JITTER_RATIO = 0.5;
 /**
  * Periodically pings the server with a ping IQ to detect dead sockets and
- * measure clock skew. Skips when the orchestrator has other traffic in
- * flight; recovers a queued/dropped ping via the configured `getComms()`.
+ * measure clock skew. A ping is skipped while another ping is in flight, or
+ * while other queries are pending and the socket shows recent inbound
+ * activity. A socket silent past the dead-socket timeout is pinged even with
+ * queries pending: pending queries on a silent socket are evidence of a dead
+ * connection, so steady outbound traffic must not starve detection. On ping
+ * failure it rejects pending queries and resumes the socket via the
+ * configured `getComms()`.
  */
 export class WaKeepAlive {
     constructor(options) {
@@ -68,14 +73,25 @@ export class WaKeepAlive {
             this.schedule(generation);
             return;
         }
-        if (this.inFlight || this.nodeOrchestrator.hasPending()) {
-            this.logger.trace('keepalive skipped: in-flight or pending queries', {
-                inFlight: this.inFlight,
-                pendingQueries: this.nodeOrchestrator.hasPending()
-            });
+        if (this.inFlight) {
+            this.logger.trace('keepalive skipped: ping already in flight');
             this.schedule(generation);
             return;
         }
+        if (this.nodeOrchestrator.hasPending()) {
+            const inboundIdleMs = Date.now() - comms.getLastInboundAtMs();
+            if (inboundIdleMs < this.timeoutMs) {
+                this.logger.trace('keepalive skipped: pending queries with recent inbound', {
+                    inboundIdleMs
+                });
+                this.schedule(generation);
+                return;
+            }
+            this.logger.debug('keepalive pinging despite pending queries: inbound is silent', {
+                inboundIdleMs,
+                timeoutMs: this.timeoutMs
+            });
+        }
         this.inFlight = true;
         const startedAt = Date.now();
         try {
@@ -108,6 +124,7 @@ export class WaKeepAlive {
             this.logger.warn('keepalive ping failed, reconnecting socket', {
                 message: toError(error).message
             });
+            this.nodeOrchestrator.clearPending(new Error('socket resume requested by keepalive ping failure'));
             try {
                 await comms.closeSocketAndResume();
             }

package/dist/esm/transport/node/builders/privacy.js

@@ -38,11 +38,41 @@ export function buildGetPrivacyDisallowedListIq(category) {
 export function buildGetBlocklistIq() {
     return buildIqNode(WA_IQ_TYPES.GET, WA_DEFAULTS.HOST_DOMAIN, WA_XMLNS.BLOCKLIST);
 }
-export function buildBlocklistChangeIq(jid, action) {
+/**
+ * Builds the blocklist `set` IQ for a block action. LID-migrated targets are
+ * addressed by the LID jid plus an identifier attribute: `pn_jid` when the
+ * phone jid is known, else `unknown_identifier="true"`. Non-migrated targets
+ * are addressed by the phone jid alone. The server rejects a block that
+ * addresses a migrated account by phone jid or omits the identifier
+ * (`400: bad-request`).
+ */
+export function buildBlocklistBlockIq(target) {
+    let attrs;
+    if (target.lidJid !== null) {
+        attrs =
+            target.pnJid !== null
+                ? { action: 'block', jid: target.lidJid, pn_jid: target.pnJid }
+                : { action: 'block', jid: target.lidJid, unknown_identifier: 'true' };
+    }
+    else {
+        attrs = { action: 'block', jid: target.pnJid };
+    }
     return buildIqNode(WA_IQ_TYPES.SET, WA_DEFAULTS.HOST_DOMAIN, WA_XMLNS.BLOCKLIST, [
         {
             tag: 'item',
-            attrs: { jid, action }
+            attrs
+        }
+    ]);
+}
+/**
+ * Builds the blocklist `set` IQ for an unblock action. The server keys
+ * migrated entries by LID, so `jid` must be the LID jid when one exists.
+ */
+export function buildBlocklistUnblockIq(jid) {
+    return buildIqNode(WA_IQ_TYPES.SET, WA_DEFAULTS.HOST_DOMAIN, WA_XMLNS.BLOCKLIST, [
+        {
+            tag: 'item',
+            attrs: { jid, action: 'unblock' }
         }
     ]);
 }

package/dist/signal/api/SignalDeviceSyncApi.d.ts

@@ -29,6 +29,17 @@ export interface SignalLidSyncResult {
      */
     readonly invalid: boolean;
 }
+/** Both addressing forms of a 1:1 user, as far as they could be resolved. */
+export interface SignalUserJidPair {
+    /** LID user jid, or `null` when no LID mapping is known. */
+    readonly lidJid: string | null;
+    /**
+     * Phone-number user jid, or `null` when unknown. When resolved through
+     * the usync fallback this is the server-canonical form, which may differ
+     * from the queried number (e.g. BR 9th digit added).
+     */
+    readonly pnJid: string | null;
+}
 /**
  * Resolves the device list and LID mapping for a set of users via the `usync`
  * protocol. Concurrent calls for the same JIDs are deduplicated.
@@ -56,6 +67,22 @@ export declare class SignalDeviceSyncApi {
      * one entry per input JID with `exists` indicating server-side presence.
      */
     queryLidsByPhoneJids(phoneJids: readonly string[], timeoutMs?: number): Promise<readonly SignalLidSyncResult[]>;
+    /**
+     * Resolves both addressing forms for a 1:1 user jid (PN or LID input),
+     * cache-first via the device-list store (`userJid`/`altUserJid`) with a
+     * one-shot {@link queryLidsByPhoneJids} fallback for PN inputs. LID
+     * inputs have no reverse lookup - their PN side stays `null` on a cache
+     * miss. Store/usync failures are logged at debug and degrade to the
+     * forms already known. Inputs that are neither PN nor LID user jids
+     * resolve to `{ lidJid: null, pnJid: null }`.
+     */
+    resolveUserJidPair(userJid: string, timeoutMs?: number): Promise<SignalUserJidPair>;
+    /**
+     * Returns the device-list snapshot form of `userJid` that satisfies
+     * `matches` (checked against `userJid` then `altUserJid`), or `null` when
+     * the store is absent, misses, or fails.
+     */
+    private findCachedAltForm;
     /**
      * Enriches existing device-list snapshots with the resolved LID equivalents
      * so {@link WaDeviceListStore.findByAnyUserJid} can later match a retry

package/dist/signal/api/SignalDeviceSyncApi.js

@@ -8,6 +8,7 @@ const usync_1 = require("../../transport/node/builders/usync");
 const helpers_1 = require("../../transport/node/helpers");
 const query_1 = require("../../transport/node/query");
 const usync_2 = require("../../transport/node/usync");
+const primitives_1 = require("../../util/primitives");
 /**
  * Resolves the device list and LID mapping for a set of users via the `usync`
  * protocol. Concurrent calls for the same JIDs are deduplicated.
@@ -142,6 +143,66 @@ class SignalDeviceSyncApi {
         await this.propagateAltUserJids(result);
         return result;
     }
+    /**
+     * Resolves both addressing forms for a 1:1 user jid (PN or LID input),
+     * cache-first via the device-list store (`userJid`/`altUserJid`) with a
+     * one-shot {@link queryLidsByPhoneJids} fallback for PN inputs. LID
+     * inputs have no reverse lookup - their PN side stays `null` on a cache
+     * miss. Store/usync failures are logged at debug and degrade to the
+     * forms already known. Inputs that are neither PN nor LID user jids
+     * resolve to `{ lidJid: null, pnJid: null }`.
+     */
+    async resolveUserJidPair(userJid, timeoutMs = this.defaultTimeoutMs) {
+        if ((0, jid_1.isLidJid)(userJid)) {
+            return { lidJid: userJid, pnJid: await this.findCachedAltForm(userJid, jid_1.isUserJid) };
+        }
+        if (!(0, jid_1.isUserJid)(userJid)) {
+            return { lidJid: null, pnJid: null };
+        }
+        const cachedLid = await this.findCachedAltForm(userJid, jid_1.isLidJid);
+        if (cachedLid) {
+            return { lidJid: cachedLid, pnJid: userJid };
+        }
+        try {
+            const results = await this.queryLidsByPhoneJids([userJid], timeoutMs);
+            const match = results.find((entry) => entry.queriedJid === userJid);
+            if (match?.lidJid) {
+                return { lidJid: match.lidJid, pnJid: match.phoneJid };
+            }
+        }
+        catch (error) {
+            this.logger.debug('lid usync resolution failed for jid pair', {
+                jid: userJid,
+                message: (0, primitives_1.toError)(error).message
+            });
+        }
+        return { lidJid: null, pnJid: userJid };
+    }
+    /**
+     * Returns the device-list snapshot form of `userJid` that satisfies
+     * `matches` (checked against `userJid` then `altUserJid`), or `null` when
+     * the store is absent, misses, or fails.
+     */
+    async findCachedAltForm(userJid, matches) {
+        if (!this.deviceListStore)
+            return null;
+        try {
+            const snapshot = await this.deviceListStore.findByAnyUserJid(userJid);
+            if (snapshot) {
+                if (matches(snapshot.userJid))
+                    return snapshot.userJid;
+                if (snapshot.altUserJid && matches(snapshot.altUserJid))
+                    return snapshot.altUserJid;
+            }
+        }
+        catch (error) {
+            this.logger.debug('device-list lookup failed for jid pair', {
+                jid: userJid,
+                message: (0, primitives_1.toError)(error).message
+            });
+        }
+        return null;
+    }
     /**
      * Enriches existing device-list snapshots with the resolved LID equivalents
      * so {@link WaDeviceListStore.findByAnyUserJid} can later match a retry

package/dist/store/createStore.js

@@ -37,6 +37,7 @@ const signal_store_1 = require("./memory/signal.store");
 const thread_store_1 = require("./memory/thread.store");
 const noop_store_1 = require("./noop.store");
 const coercion_1 = require("../util/coercion");
+const primitives_1 = require("../util/primitives");
 const DEFAULT_CACHE_TTLS_MS = Object.freeze({
     retryMs: 60 * 1000,
     groupMetadataMs: 5 * 60 * 1000,
@@ -112,6 +113,7 @@ function createStore(options) {
         messageSecret: (0, coercion_1.resolvePositive)(options.memory?.cacheTtlMs?.messageSecretMs, DEFAULT_CACHE_TTLS_MS.messageSecretMs, 'memory.cacheTtlMs.messageSecretMs')
     });
     const sessions = new Map();
+    const pendingSessionDestroys = new Set();
     let storeDestroyed = false;
     return {
         session(sessionId) {
@@ -151,37 +153,48 @@ function createStore(options) {
                 ? new contact_store_1.WaContactMemoryStore({ maxContacts: ml.contacts })
                 : noop_store_1.NOOP_CONTACT_STORE);
             const rawPrivacyToken = resolveStore(id, backends, providers.privacyToken ?? 'memory', 'privacyToken', 'stores', () => new privacy_token_store_1.WaPrivacyTokenMemoryStore(ml.privacyTokens));
-            const rawRetry = resolveStore(id, backends, cacheProviders.retry ?? 'memory', 'retry', 'caches', () => cacheProviders.retry === 'memory' || !cacheProviders.retry
-                ? new retry_store_1.WaRetryMemoryStore(cacheTtlsMs.retry, {
-                    maxOutboundMessages: ml.retryOutboundMessages,
-                    maxInboundCounters: ml.retryInboundCounters,
-                    logger: memoryLogger?.child({ domain: 'retry', sessionId: id })
-                })
-                : noop_store_1.NOOP_RETRY_STORE);
-            const rawGroupMetadata = resolveStore(id, backends, cacheProviders.groupMetadata ?? 'memory', 'groupMetadata', 'caches', () => cacheProviders.groupMetadata === 'memory' || !cacheProviders.groupMetadata
-                ? new group_metadata_store_1.WaGroupMetadataMemoryStore(cacheTtlsMs.groupMetadata, {
-                    maxGroups: ml.groupMetadataGroups,
-                    logger: memoryLogger?.child({
-                        domain: 'groupMetadata',
-                        sessionId: id
+            const buildCaches = () => ({
+                retry: (0, retry_lock_1.withRetryLock)(resolveStore(id, backends, cacheProviders.retry ?? 'memory', 'retry', 'caches', () => cacheProviders.retry === 'memory' || !cacheProviders.retry
+                    ? new retry_store_1.WaRetryMemoryStore(cacheTtlsMs.retry, {
+                        maxOutboundMessages: ml.retryOutboundMessages,
+                        maxInboundCounters: ml.retryInboundCounters,
+                        logger: memoryLogger?.child({
+                            domain: 'retry',
+                            sessionId: id
+                        })
                     })
-                })
-                : noop_store_1.NOOP_GROUP_METADATA_STORE);
-            const rawDeviceList = resolveStore(id, backends, cacheProviders.deviceList ?? 'memory', 'deviceList', 'caches', () => cacheProviders.deviceList === 'memory'
-                ? new device_list_store_1.WaDeviceListMemoryStore(cacheTtlsMs.deviceList, {
-                    maxUsers: ml.deviceListUsers,
-                    logger: memoryLogger?.child({ domain: 'deviceList', sessionId: id })
-                })
-                : noop_store_1.NOOP_DEVICE_LIST_STORE);
-            const rawMessageSecret = resolveStore(id, backends, cacheProviders.messageSecret ?? 'memory', 'messageSecret', 'caches', () => cacheProviders.messageSecret === 'memory' || !cacheProviders.messageSecret
-                ? new message_secret_store_1.WaMessageSecretMemoryStore(cacheTtlsMs.messageSecret, {
-                    maxSecrets: ml.messageSecrets,
-                    logger: memoryLogger?.child({
-                        domain: 'messageSecret',
-                        sessionId: id
+                    : noop_store_1.NOOP_RETRY_STORE)),
+                groupMetadata: (0, group_metadata_lock_1.withGroupMetadataLock)(resolveStore(id, backends, cacheProviders.groupMetadata ?? 'memory', 'groupMetadata', 'caches', () => cacheProviders.groupMetadata === 'memory' ||
+                    !cacheProviders.groupMetadata
+                    ? new group_metadata_store_1.WaGroupMetadataMemoryStore(cacheTtlsMs.groupMetadata, {
+                        maxGroups: ml.groupMetadataGroups,
+                        logger: memoryLogger?.child({
+                            domain: 'groupMetadata',
+                            sessionId: id
+                        })
                     })
-                })
-                : noop_store_1.NOOP_MESSAGE_SECRET_STORE);
+                    : noop_store_1.NOOP_GROUP_METADATA_STORE)),
+                deviceList: (0, device_list_lock_1.withDeviceListLock)(resolveStore(id, backends, cacheProviders.deviceList ?? 'memory', 'deviceList', 'caches', () => cacheProviders.deviceList === 'memory' || !cacheProviders.deviceList
+                    ? new device_list_store_1.WaDeviceListMemoryStore(cacheTtlsMs.deviceList, {
+                        maxUsers: ml.deviceListUsers,
+                        logger: memoryLogger?.child({
+                            domain: 'deviceList',
+                            sessionId: id
+                        })
+                    })
+                    : noop_store_1.NOOP_DEVICE_LIST_STORE)),
+                messageSecret: (0, message_secret_lock_1.withMessageSecretLock)(resolveStore(id, backends, cacheProviders.messageSecret ?? 'memory', 'messageSecret', 'caches', () => cacheProviders.messageSecret === 'memory' ||
+                    !cacheProviders.messageSecret
+                    ? new message_secret_store_1.WaMessageSecretMemoryStore(cacheTtlsMs.messageSecret, {
+                        maxSecrets: ml.messageSecrets,
+                        logger: memoryLogger?.child({
+                            domain: 'messageSecret',
+                            sessionId: id
+                        })
+                    })
+                    : noop_store_1.NOOP_MESSAGE_SECRET_STORE))
+            });
+            let caches = buildCaches();
             const authStore = (0, auth_lock_1.withAuthLock)(rawAuth);
             const signalStore = (0, signal_lock_1.withSignalLock)(rawSignal);
             const preKeyStore = (0, pre_key_lock_1.withPreKeyLock)(rawPreKey);
@@ -195,41 +208,72 @@ function createStore(options) {
                 ? (0, sender_key_cache_1.withSenderKeyCache)(rawSenderKey, cacheLayer.limits?.senderKey)
                 : rawSenderKey);
             const appStateStore = (0, appstate_lock_1.withAppStateLock)(rawAppState);
-            const retryStore = (0, retry_lock_1.withRetryLock)(rawRetry);
-            const groupMetadataStore = (0, group_metadata_lock_1.withGroupMetadataLock)(rawGroupMetadata);
-            const deviceListStore = (0, device_list_lock_1.withDeviceListLock)(rawDeviceList);
             const messageStore = (0, message_lock_1.withMessageLock)(rawMessages);
-            const messageSecretStore = (0, message_secret_lock_1.withMessageSecretLock)(rawMessageSecret);
             const threadStore = (0, thread_lock_1.withThreadLock)(rawThreads);
             const contactStore = (0, contact_lock_1.withContactLock)(rawContacts);
             const privacyTokenStore = (0, privacy_token_lock_1.withPrivacyTokenLock)(cacheLayer.privacyToken && usesBackend(providers.privacyToken)
                 ? (0, privacy_token_cache_1.withPrivacyTokenCache)(rawPrivacyToken, cacheLayer.limits?.privacyToken)
                 : rawPrivacyToken);
-            let cachesDestroyed = false;
             let sessionDestroyed = false;
-            const destroyCaches = async () => {
-                if (cachesDestroyed)
-                    return;
-                cachesDestroyed = true;
-                await Promise.all([
-                    retryStore.clear(),
-                    groupMetadataStore.clear(),
-                    deviceListStore.clear(),
-                    messageSecretStore.clear()
+            let destroyPromise = null;
+            let cacheLifecycle = Promise.resolve();
+            const teardownCaches = async (target) => {
+                const cleared = await Promise.allSettled([
+                    target.retry.clear(),
+                    target.groupMetadata.clear(),
+                    target.deviceList.clear(),
+                    target.messageSecret.clear()
                 ]);
-                await Promise.all([
-                    destroyIfSupported(retryStore),
-                    destroyIfSupported(groupMetadataStore),
-                    destroyIfSupported(deviceListStore),
-                    destroyIfSupported(messageSecretStore)
+                const destroyed = await Promise.allSettled([
+                    destroyIfSupported(target.retry),
+                    destroyIfSupported(target.groupMetadata),
+                    destroyIfSupported(target.deviceList),
+                    destroyIfSupported(target.messageSecret)
                 ]);
+                const failures = [...cleared, ...destroyed].filter((result) => result.status === 'rejected');
+                if (failures.length > 0) {
+                    storeLogger?.warn('cache teardown had failures', {
+                        sessionId: id,
+                        droppedCount: failures.length,
+                        totalExpected: cleared.length + destroyed.length,
+                        sample: (0, primitives_1.toError)(failures[0].reason).message
+                    });
+                }
+                return failures.length;
+            };
+            const destroyCaches = () => {
+                const run = cacheLifecycle.then(async () => {
+                    if (sessionDestroyed)
+                        return;
+                    const failureCount = await teardownCaches(caches);
+                    caches = buildCaches();
+                    if (failureCount > 0) {
+                        throw new Error(`cache reset finished with ${failureCount} teardown failure(s); ` +
+                            'fresh caches are in place but old persistent entries may remain');
+                    }
+                });
+                cacheLifecycle = run.then(() => undefined, () => undefined);
+                return run;
             };
-            const destroy = async () => {
-                if (sessionDestroyed)
-                    return;
+            const destroy = () => {
+                if (!destroyPromise) {
+                    const pending = destroyInternal().finally(() => pendingSessionDestroys.delete(pending));
+                    destroyPromise = pending;
+                    pendingSessionDestroys.add(pending);
+                }
+                return destroyPromise;
+            };
+            const destroyInternal = async () => {
                 sessionDestroyed = true;
-                await destroyCaches();
-                await Promise.all([
+                if (sessions.get(id) === storeSession) {
+                    sessions.delete(id);
+                }
+                await cacheLifecycle;
+                await teardownCaches(caches);
+                await destroyPersistentStores();
+            };
+            const destroyPersistentStores = async () => {
+                const results = await Promise.allSettled([
                     destroyIfSupported(authStore),
                     destroyIfSupported(signalStore),
                     destroyIfSupported(preKeyStore),
@@ -242,6 +286,15 @@ function createStore(options) {
                     destroyIfSupported(contactStore),
                     destroyIfSupported(privacyTokenStore)
                 ]);
+                const failures = results.filter((result) => result.status === 'rejected');
+                if (failures.length > 0) {
+                    storeLogger?.warn('persistent store teardown had failures', {
+                        sessionId: id,
+                        droppedCount: failures.length,
+                        totalExpected: results.length,
+                        sample: (0, primitives_1.toError)(failures[0].reason).message
+                    });
+                }
             };
             const storeSession = {
                 auth: authStore,
@@ -251,11 +304,19 @@ function createStore(options) {
                 identity: identityStore,
                 senderKey: senderKeyStore,
                 appState: appStateStore,
-                retry: retryStore,
-                groupMetadata: groupMetadataStore,
-                deviceList: deviceListStore,
+                get retry() {
+                    return caches.retry;
+                },
+                get groupMetadata() {
+                    return caches.groupMetadata;
+                },
+                get deviceList() {
+                    return caches.deviceList;
+                },
                 messages: messageStore,
-                messageSecret: messageSecretStore,
+                get messageSecret() {
+                    return caches.messageSecret;
+                },
                 threads: threadStore,
                 contacts: contactStore,
                 privacyToken: privacyTokenStore,
@@ -276,6 +337,7 @@ function createStore(options) {
             const list = Array.from(sessions.values());
             sessions.clear();
             await Promise.all(list.map((s) => s.destroy()));
+            await Promise.all(Array.from(pendingSessionDestroys));
             const uniqueBackends = new Set(Object.values(backends));
             await Promise.all(Array.from(uniqueBackends, (backend) => destroyIfSupported(backend)));
         }

package/dist/store/types.d.ts

@@ -33,12 +33,43 @@ export interface WaStoreSession {
     readonly threads: WaThreadStore;
     readonly contacts: WaContactStore;
     readonly privacyToken: WaPrivacyTokenStore;
+    /**
+     * Tears down the cache domains (retry/groupMetadata/deviceList/
+     * messageSecret) and swaps fresh, empty ones into this bundle. The
+     * session stays usable; the caches rebuild on demand. The swap happens
+     * after the old stores finish tearing down (so a persistent cache
+     * backend is never cleared under the fresh stores), which means cache
+     * operations issued while the reset is in flight may reject. References
+     * to the old cache stores captured before the call (e.g. by a live
+     * client) reject afterwards - recreate the client to pick up the fresh
+     * stores. Rejects when the old generation's teardown had failures - the
+     * fresh caches are still in place, but stale entries may remain in a
+     * persistent cache backend.
+     */
     destroyCaches(): Promise<void>;
+    /**
+     * Final teardown of every domain store in this bundle. The bundle is
+     * single-shot: every operation on it rejects afterwards. The sessionId
+     * is released as soon as destruction starts, so a concurrent
+     * `store.session(id)` builds a fresh bundle instead of returning this
+     * one. Repeat calls return the same in-flight promise. Teardown
+     * failures are logged (warn), never thrown.
+     */
     destroy(): Promise<void>;
 }
 export interface WaStore {
+    /**
+     * Returns the lock-wrapped per-domain store bundle for `sessionId`,
+     * building it on first use and caching it until its `destroy()` (or the
+     * store-wide `destroy()`) releases it.
+     */
     session(sessionId: string): WaStoreSession;
+    /** Runs {@link WaStoreSession.destroyCaches} on every live session. */
     destroyCaches(): Promise<void>;
+    /**
+     * Destroys every live session bundle and the registered backends. The
+     * store is single-shot: `session()` throws afterwards.
+     */
     destroy(): Promise<void>;
 }
 export interface WaStoreBackend {

package/dist/transport/WaComms.d.ts

@@ -30,6 +30,7 @@ export declare class WaComms {
     private usedResumeHandshake;
     private noiseSession;
     private lastServerStaticKey;
+    private lastInboundAtMs;
     private frameProcessingQueue;
     private readonly frameHandlerQueue;
     constructor(config: WaCommsConfig, logger?: Logger);
@@ -41,6 +42,8 @@ export declare class WaComms {
     closeSocketAndResume(): Promise<void>;
     closeSocketAndPreventRetry(): Promise<void>;
     sendFrame(payload: Uint8Array): Promise<void>;
+    /** Timestamp (`Date.now()` ms) of the last raw payload received from the socket; `0` before any inbound. */
+    getLastInboundAtMs(): number;
     getCommsState(): Readonly<WaCommsState>;
     getServerStaticKey(): Uint8Array | null;
     private openSocket;

package/dist/transport/WaComms.js

@@ -81,6 +81,7 @@ class WaComms {
         this.usedResumeHandshake = false;
         this.noiseSession = null;
         this.lastServerStaticKey = null;
+        this.lastInboundAtMs = 0;
         this.frameProcessingQueue = Promise.resolve();
         this.frameHandlerQueue = new BoundedTaskQueue_1.BoundedTaskQueue(WA_FRAME_HANDLER_QUEUE_MAX_SIZE, WA_FRAME_HANDLER_MAX_CONCURRENCY);
     }
@@ -208,6 +209,10 @@ class WaComms {
         const wire = await this.noiseSession.encryptFrame(payload);
         await this.socket.send(wire);
     }
+    /** Timestamp (`Date.now()` ms) of the last raw payload received from the socket; `0` before any inbound. */
+    getLastInboundAtMs() {
+        return this.lastInboundAtMs;
+    }
     getCommsState() {
         return {
             started: this.started,
@@ -288,6 +293,7 @@ class WaComms {
         });
     }
     onSocketMessage(payload) {
+        this.lastInboundAtMs = Date.now();
         this.frameProcessingQueue = this.frameProcessingQueue.then(() => this.processSocketPayload(payload), () => this.processSocketPayload(payload));
     }
     async processSocketPayload(payload) {
@@ -525,6 +531,7 @@ class WaComms {
             this.resumeHandshakeFailures = 0;
         }
         this.noiseSession = null;
+        this.lastInboundAtMs = 0;
         this.clearPendingFrames();
         this.pendingFramesOverflowClosing = false;
         if (options.clearHandlers) {

package/dist/transport/keepalive/WaKeepAlive.d.ts

@@ -5,6 +5,7 @@ interface WaKeepAliveOptions {
     readonly logger: Logger;
     readonly nodeOrchestrator: {
         hasPending(): boolean;
+        clearPending(reason: Error): void;
         query(node: BinaryNode, timeoutMs?: number): Promise<BinaryNode>;
     };
     readonly getComms: () => WaComms | null;
@@ -18,8 +19,13 @@ interface WaKeepAliveOptions {
 }
 /**
  * Periodically pings the server with a ping IQ to detect dead sockets and
- * measure clock skew. Skips when the orchestrator has other traffic in
- * flight; recovers a queued/dropped ping via the configured `getComms()`.
+ * measure clock skew. A ping is skipped while another ping is in flight, or
+ * while other queries are pending and the socket shows recent inbound
+ * activity. A socket silent past the dead-socket timeout is pinged even with
+ * queries pending: pending queries on a silent socket are evidence of a dead
+ * connection, so steady outbound traffic must not starve detection. On ping
+ * failure it rejects pending queries and resumes the socket via the
+ * configured `getComms()`.
  */
 export declare class WaKeepAlive {
     private readonly logger;