zapo-js 1.6.0 → 1.6.1

package/dist/client/WaClientFactory.js

@@ -375,7 +375,8 @@ function buildWaClientDependencies(input) {
         logger
     });
     const privacyCoordinator = (0, WaPrivacyCoordinator_1.createPrivacyCoordinator)({
-        queryWithContext: runtime.queryWithContext
+        queryWithContext: runtime.queryWithContext,
+        resolveUserJidPair: (userJid) => signalDeviceSync.resolveUserJidPair(userJid)
     });
     const businessCoordinator = (0, WaBusinessCoordinator_1.createBusinessCoordinator)({
         queryWithContext: runtime.queryWithContext,

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

@@ -80,8 +80,8 @@ export declare class WaMessageDispatchCoordinator {
     sendMessage(to: string, content: WaSendMessageContent, options?: WaSendMessageOptions): Promise<WaMessagePublishResult>;
     /**
      * For a 1:1 recipient passed in PN form, returns the LID-addressed user JID
-     * (cache-first; falls back to a one-shot `queryLidsByPhoneJids`). Switching
-     * to LID before fanout ensures the envelope, eligible-requester list, and
+     * (via {@link SignalDeviceSyncApi.resolveUserJidPair}). Switching to LID
+     * before fanout ensures the envelope, eligible-requester list, and
      * retry-receipt addressing all agree, which keeps the retry tracker from
      * rejecting receipts that arrive in LID form. Returns the original PN if
      * no LID is known/resolvable. Inputs already in LID form pass through.

package/dist/client/coordinators/WaMessageDispatchCoordinator.js

@@ -300,8 +300,8 @@ class WaMessageDispatchCoordinator {
     }
     /**
      * For a 1:1 recipient passed in PN form, returns the LID-addressed user JID
-     * (cache-first; falls back to a one-shot `queryLidsByPhoneJids`). Switching
-     * to LID before fanout ensures the envelope, eligible-requester list, and
+     * (via {@link SignalDeviceSyncApi.resolveUserJidPair}). Switching to LID
+     * before fanout ensures the envelope, eligible-requester list, and
      * retry-receipt addressing all agree, which keeps the retry tracker from
      * rejecting receipts that arrive in LID form. Returns the original PN if
      * no LID is known/resolvable. Inputs already in LID form pass through.
@@ -309,26 +309,8 @@ class WaMessageDispatchCoordinator {
     async resolveDirectRecipientLid(pnUserJid) {
         if ((0, jid_1.isLidJid)(pnUserJid))
             return pnUserJid;
-        const cached = await this.deps.deviceListStore.findByAnyUserJid(pnUserJid);
-        if (cached) {
-            if ((0, jid_1.isLidJid)(cached.userJid))
-                return cached.userJid;
-            if (cached.altUserJid && (0, jid_1.isLidJid)(cached.altUserJid))
-                return cached.altUserJid;
-        }
-        try {
-            const results = await this.deps.signalDeviceSync.queryLidsByPhoneJids([pnUserJid]);
-            const match = results.find((entry) => entry.queriedJid === pnUserJid);
-            if (match?.lidJid)
-                return match.lidJid;
-        }
-        catch (error) {
-            this.deps.logger.debug('lid resolution failed for direct recipient', {
-                pnUserJid,
-                message: (0, primitives_2.toError)(error).message
-            });
-        }
-        return pnUserJid;
+        const pair = await this.deps.signalDeviceSync.resolveUserJidPair(pnUserJid);
+        return pair.lidJid ?? pnUserJid;
     }
     /**
      * Resolves the `peer_recipient_pn` cross-reference for a 1:1 send, or
@@ -344,20 +326,8 @@ class WaMessageDispatchCoordinator {
             return undefined;
         if ((0, jid_1.isUserJid)(recipientUserJid))
             return recipientUserJid;
-        try {
-            const snapshot = await this.deps.deviceListStore.findByAnyUserJid(directRecipientJid);
-            if (snapshot?.userJid && (0, jid_1.isUserJid)(snapshot.userJid))
-                return snapshot.userJid;
-            if (snapshot?.altUserJid && (0, jid_1.isUserJid)(snapshot.altUserJid))
-                return snapshot.altUserJid;
-        }
-        catch (error) {
-            this.deps.logger.trace('peer_recipient_pn store lookup failed', {
-                lid: directRecipientJid,
-                message: (0, primitives_2.toError)(error).message
-            });
-        }
-        return undefined;
+        const pair = await this.deps.signalDeviceSync.resolveUserJidPair(directRecipientJid);
+        return pair.pnJid ?? undefined;
     }
     async syncSignalSession(jid, reasonIdentity = false) {
         const address = (0, jid_1.parseSignalAddressFromJid)(jid);

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

@@ -1,4 +1,5 @@
 import { type WaPrivacyDisallowedListSettingName, type WaPrivacySettingName, type WaPrivacySettingValueMap } from '../../protocol/privacy';
+import type { SignalUserJidPair } from '../../signal/api/SignalDeviceSyncApi';
 import type { BinaryNode } from '../../transport/types';
 export type WaPrivacySettings = {
     readonly [K in WaPrivacySettingName]?: WaPrivacySettingValueMap[K];
@@ -36,17 +37,29 @@ export interface WaPrivacyCoordinator {
     /** Returns the current account-wide blocklist. */
     readonly getBlocklist: () => Promise<WaBlocklistResult>;
     /**
-     * Blocks `jid` (account-wide blocklist). After this, the peer can no
-     * longer message/call you and cannot see your last seen/online/photo/
-     * status. The block is symmetric only from the peer's read perspective -
-     * they don't get an explicit "you were blocked" notification.
+     * Blocks a user (account-wide blocklist). Accepts a phone-number jid, a
+     * LID jid, or a bare phone number (digits only). After this, the peer can
+     * no longer
+     * message/call you and cannot see your last seen/online/photo/status. The
+     * block is symmetric only from the peer's read perspective - they don't
+     * get an explicit "you were blocked" notification.
+     *
+     * The server keys blocklist entries by LID for migrated accounts, so a
+     * phone-number input is resolved to its LID first (device-list cache,
+     * then a usync query). Non-migrated accounts fall back to the plain
+     * phone-jid form.
      */
     readonly blockUser: (jid: string) => Promise<void>;
-    /** Removes `jid` from the blocklist. */
+    /**
+     * Removes a user from the blocklist. Accepts the same inputs as
+     * {@link blockUser} and performs the same LID resolution - unblocking a
+     * migrated entry by phone jid is rejected by the server.
+     */
     readonly unblockUser: (jid: string) => Promise<void>;
 }
 interface WaPrivacyCoordinatorOptions {
     readonly queryWithContext: (context: string, node: BinaryNode, timeoutMs?: number, contextData?: Readonly<Record<string, unknown>>) => Promise<BinaryNode>;
+    readonly resolveUserJidPair: (userJid: string) => Promise<SignalUserJidPair>;
 }
 /** Builds a {@link WaPrivacyCoordinator} backed by the given IQ query function. */
 export declare function createPrivacyCoordinator(options: WaPrivacyCoordinatorOptions): WaPrivacyCoordinator;

package/dist/client/coordinators/WaPrivacyCoordinator.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createPrivacyCoordinator = createPrivacyCoordinator;
+const jid_1 = require("../../protocol/jid");
 const nodes_1 = require("../../protocol/nodes");
 const privacy_1 = require("../../protocol/privacy");
 const privacy_2 = require("../../transport/node/builders/privacy");
@@ -88,6 +89,23 @@ function parseBlocklist(result) {
     jids.length = jidsCount;
     return { jids, dhash };
 }
+/**
+ * Resolves a blocklist input into both addressing forms via
+ * `resolveUserJidPair` (device-list cache first, usync fallback for phone
+ * jids). Resolution failures degrade to the single known form instead of
+ * throwing - the server then decides whether that form is acceptable.
+ */
+async function resolveBlocklistTarget(options, jid) {
+    const normalized = (0, jid_1.normalizeRecipientJid)(jid);
+    if (!(0, jid_1.isLidJid)(normalized) && !(0, jid_1.isUserJid)(normalized)) {
+        throw new Error(`blocklist target must be a user jid: ${jid}`);
+    }
+    const pair = await options.resolveUserJidPair(normalized);
+    if (pair.lidJid !== null) {
+        return { lidJid: pair.lidJid, pnJid: pair.pnJid };
+    }
+    return { lidJid: null, pnJid: pair.pnJid ?? normalized };
+}
 /** Builds a {@link WaPrivacyCoordinator} backed by the given IQ query function. */
 function createPrivacyCoordinator(options) {
     const { queryWithContext } = options;
@@ -123,13 +141,20 @@ function createPrivacyCoordinator(options) {
             return parseBlocklist(result);
         },
         blockUser: async (jid) => {
-            const node = (0, privacy_2.buildBlocklistChangeIq)(jid, 'block');
-            const result = await queryWithContext('privacy.blockUser', node, undefined, { jid });
+            const target = await resolveBlocklistTarget(options, jid);
+            const node = (0, privacy_2.buildBlocklistBlockIq)(target);
+            const result = await queryWithContext('privacy.blockUser', node, undefined, {
+                jid: target.lidJid ?? target.pnJid
+            });
             (0, query_1.assertIqResult)(result, 'privacy.blockUser');
         },
         unblockUser: async (jid) => {
-            const node = (0, privacy_2.buildBlocklistChangeIq)(jid, 'unblock');
-            const result = await queryWithContext('privacy.unblockUser', node, undefined, { jid });
+            const target = await resolveBlocklistTarget(options, jid);
+            const unblockJid = target.lidJid ?? target.pnJid;
+            const node = (0, privacy_2.buildBlocklistUnblockIq)(unblockJid);
+            const result = await queryWithContext('privacy.unblockUser', node, undefined, {
+                jid: unblockJid
+            });
             (0, query_1.assertIqResult)(result, 'privacy.unblockUser');
         }
     };

package/dist/esm/client/WaClientFactory.js

@@ -371,7 +371,8 @@ export function buildWaClientDependencies(input) {
         logger
     });
     const privacyCoordinator = createPrivacyCoordinator({
-        queryWithContext: runtime.queryWithContext
+        queryWithContext: runtime.queryWithContext,
+        resolveUserJidPair: (userJid) => signalDeviceSync.resolveUserJidPair(userJid)
     });
     const businessCoordinator = createBusinessCoordinator({
         queryWithContext: runtime.queryWithContext,

package/dist/esm/client/coordinators/WaMessageDispatchCoordinator.js

@@ -297,8 +297,8 @@ export class WaMessageDispatchCoordinator {
     }
     /**
      * For a 1:1 recipient passed in PN form, returns the LID-addressed user JID
-     * (cache-first; falls back to a one-shot `queryLidsByPhoneJids`). Switching
-     * to LID before fanout ensures the envelope, eligible-requester list, and
+     * (via {@link SignalDeviceSyncApi.resolveUserJidPair}). Switching to LID
+     * before fanout ensures the envelope, eligible-requester list, and
      * retry-receipt addressing all agree, which keeps the retry tracker from
      * rejecting receipts that arrive in LID form. Returns the original PN if
      * no LID is known/resolvable. Inputs already in LID form pass through.
@@ -306,26 +306,8 @@ export class WaMessageDispatchCoordinator {
     async resolveDirectRecipientLid(pnUserJid) {
         if (isLidJid(pnUserJid))
             return pnUserJid;
-        const cached = await this.deps.deviceListStore.findByAnyUserJid(pnUserJid);
-        if (cached) {
-            if (isLidJid(cached.userJid))
-                return cached.userJid;
-            if (cached.altUserJid && isLidJid(cached.altUserJid))
-                return cached.altUserJid;
-        }
-        try {
-            const results = await this.deps.signalDeviceSync.queryLidsByPhoneJids([pnUserJid]);
-            const match = results.find((entry) => entry.queriedJid === pnUserJid);
-            if (match?.lidJid)
-                return match.lidJid;
-        }
-        catch (error) {
-            this.deps.logger.debug('lid resolution failed for direct recipient', {
-                pnUserJid,
-                message: toError(error).message
-            });
-        }
-        return pnUserJid;
+        const pair = await this.deps.signalDeviceSync.resolveUserJidPair(pnUserJid);
+        return pair.lidJid ?? pnUserJid;
     }
     /**
      * Resolves the `peer_recipient_pn` cross-reference for a 1:1 send, or
@@ -341,20 +323,8 @@ export class WaMessageDispatchCoordinator {
             return undefined;
         if (isUserJid(recipientUserJid))
             return recipientUserJid;
-        try {
-            const snapshot = await this.deps.deviceListStore.findByAnyUserJid(directRecipientJid);
-            if (snapshot?.userJid && isUserJid(snapshot.userJid))
-                return snapshot.userJid;
-            if (snapshot?.altUserJid && isUserJid(snapshot.altUserJid))
-                return snapshot.altUserJid;
-        }
-        catch (error) {
-            this.deps.logger.trace('peer_recipient_pn store lookup failed', {
-                lid: directRecipientJid,
-                message: toError(error).message
-            });
-        }
-        return undefined;
+        const pair = await this.deps.signalDeviceSync.resolveUserJidPair(directRecipientJid);
+        return pair.pnJid ?? undefined;
     }
     async syncSignalSession(jid, reasonIdentity = false) {
         const address = parseSignalAddressFromJid(jid);

package/dist/esm/client/coordinators/WaPrivacyCoordinator.js

@@ -1,6 +1,7 @@
+import { isLidJid, isUserJid, normalizeRecipientJid } from '../../protocol/jid.js';
 import { WA_NODE_TAGS } from '../../protocol/nodes.js';
 import { WA_PRIVACY_CATEGORY_TO_SETTING, WA_PRIVACY_SETTING_TO_CATEGORY, WA_PRIVACY_TAGS, WA_PRIVACY_VALUES } from '../../protocol/privacy.js';
-import { buildBlocklistChangeIq, buildGetBlocklistIq, buildGetPrivacyDisallowedListIq, buildGetPrivacySettingsIq, buildSetPrivacyCategoryIq } from '../../transport/node/builders/privacy.js';
+import { buildBlocklistBlockIq, buildBlocklistUnblockIq, buildGetBlocklistIq, buildGetPrivacyDisallowedListIq, buildGetPrivacySettingsIq, buildSetPrivacyCategoryIq } from '../../transport/node/builders/privacy.js';
 import { findNodeChild, getNodeChildren, getNodeChildrenByTag } from '../../transport/node/helpers.js';
 import { assertIqResult } from '../../transport/node/query.js';
 const IGNORED_SERVER_CATEGORIES = new Set([
@@ -85,6 +86,23 @@ function parseBlocklist(result) {
     jids.length = jidsCount;
     return { jids, dhash };
 }
+/**
+ * Resolves a blocklist input into both addressing forms via
+ * `resolveUserJidPair` (device-list cache first, usync fallback for phone
+ * jids). Resolution failures degrade to the single known form instead of
+ * throwing - the server then decides whether that form is acceptable.
+ */
+async function resolveBlocklistTarget(options, jid) {
+    const normalized = normalizeRecipientJid(jid);
+    if (!isLidJid(normalized) && !isUserJid(normalized)) {
+        throw new Error(`blocklist target must be a user jid: ${jid}`);
+    }
+    const pair = await options.resolveUserJidPair(normalized);
+    if (pair.lidJid !== null) {
+        return { lidJid: pair.lidJid, pnJid: pair.pnJid };
+    }
+    return { lidJid: null, pnJid: pair.pnJid ?? normalized };
+}
 /** Builds a {@link WaPrivacyCoordinator} backed by the given IQ query function. */
 export function createPrivacyCoordinator(options) {
     const { queryWithContext } = options;
@@ -120,13 +138,20 @@ export function createPrivacyCoordinator(options) {
             return parseBlocklist(result);
         },
         blockUser: async (jid) => {
-            const node = buildBlocklistChangeIq(jid, 'block');
-            const result = await queryWithContext('privacy.blockUser', node, undefined, { jid });
+            const target = await resolveBlocklistTarget(options, jid);
+            const node = buildBlocklistBlockIq(target);
+            const result = await queryWithContext('privacy.blockUser', node, undefined, {
+                jid: target.lidJid ?? target.pnJid
+            });
             assertIqResult(result, 'privacy.blockUser');
         },
         unblockUser: async (jid) => {
-            const node = buildBlocklistChangeIq(jid, 'unblock');
-            const result = await queryWithContext('privacy.unblockUser', node, undefined, { jid });
+            const target = await resolveBlocklistTarget(options, jid);
+            const unblockJid = target.lidJid ?? target.pnJid;
+            const node = buildBlocklistUnblockIq(unblockJid);
+            const result = await queryWithContext('privacy.unblockUser', node, undefined, {
+                jid: unblockJid
+            });
             assertIqResult(result, 'privacy.unblockUser');
         }
     };

package/dist/esm/signal/api/SignalDeviceSyncApi.js

@@ -1,10 +1,11 @@
 import { PromiseDedup } from '../../infra/perf/PromiseDedup.js';
 import { WA_DEFAULTS, WA_NODE_TAGS, WA_USYNC_CONTEXTS } from '../../protocol/constants.js';
-import { buildDeviceJid, isHostedDeviceId, parsePhoneJid, splitJid, toUserJid } from '../../protocol/jid.js';
+import { buildDeviceJid, isHostedDeviceId, isLidJid, isUserJid, parsePhoneJid, splitJid, toUserJid } from '../../protocol/jid.js';
 import { buildUsyncIq, iterateUsyncUsers, parseUsyncResultEnvelope } from '../../transport/node/builders/usync.js';
 import { findNodeChild, getNodeChildrenByTag, getNodeTextContent } from '../../transport/node/helpers.js';
 import { assertIqResult } from '../../transport/node/query.js';
 import { createUsyncSidGenerator, logUsyncProtocolErrors } from '../../transport/node/usync.js';
+import { toError } from '../../util/primitives.js';
 /**
  * Resolves the device list and LID mapping for a set of users via the `usync`
  * protocol. Concurrent calls for the same JIDs are deduplicated.
@@ -139,6 +140,66 @@ export 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 (isLidJid(userJid)) {
+            return { lidJid: userJid, pnJid: await this.findCachedAltForm(userJid, isUserJid) };
+        }
+        if (!isUserJid(userJid)) {
+            return { lidJid: null, pnJid: null };
+        }
+        const cachedLid = await this.findCachedAltForm(userJid, 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: 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: 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/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/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;

package/dist/transport/keepalive/WaKeepAlive.js

@@ -8,8 +8,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()`.
  */
 class WaKeepAlive {
     constructor(options) {
@@ -71,14 +76,25 @@ 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 {
@@ -111,6 +127,7 @@ class WaKeepAlive {
             this.logger.warn('keepalive ping failed, reconnecting socket', {
                 message: (0, primitives_1.toError)(error).message
             });
+            this.nodeOrchestrator.clearPending(new Error('socket resume requested by keepalive ping failure'));
             try {
                 await comms.closeSocketAndResume();
             }

package/dist/transport/node/builders/privacy.d.ts

@@ -4,4 +4,29 @@ export declare function buildGetPrivacySettingsIq(): BinaryNode;
 export declare function buildSetPrivacyCategoryIq(category: WaPrivacyCategory, value: WaPrivacyValue): BinaryNode;
 export declare function buildGetPrivacyDisallowedListIq(category: WaPrivacyCategory): BinaryNode;
 export declare function buildGetBlocklistIq(): BinaryNode;
-export declare function buildBlocklistChangeIq(jid: string, action: 'block' | 'unblock'): BinaryNode;
+/**
+ * Blocklist target in both addressing forms. At least one side is always
+ * present: LID-migrated accounts carry `lidJid` (plus `pnJid` when known),
+ * non-migrated accounts carry only `pnJid`.
+ */
+export type WaBlocklistTarget = {
+    readonly lidJid: string;
+    readonly pnJid: string | null;
+} | {
+    readonly lidJid: null;
+    readonly pnJid: string;
+};
+/**
+ * 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 declare function buildBlocklistBlockIq(target: WaBlocklistTarget): BinaryNode;
+/**
+ * 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 declare function buildBlocklistUnblockIq(jid: string): BinaryNode;

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

@@ -4,7 +4,8 @@ exports.buildGetPrivacySettingsIq = buildGetPrivacySettingsIq;
 exports.buildSetPrivacyCategoryIq = buildSetPrivacyCategoryIq;
 exports.buildGetPrivacyDisallowedListIq = buildGetPrivacyDisallowedListIq;
 exports.buildGetBlocklistIq = buildGetBlocklistIq;
-exports.buildBlocklistChangeIq = buildBlocklistChangeIq;
+exports.buildBlocklistBlockIq = buildBlocklistBlockIq;
+exports.buildBlocklistUnblockIq = buildBlocklistUnblockIq;
 const defaults_1 = require("../../../protocol/defaults");
 const nodes_1 = require("../../../protocol/nodes");
 const privacy_1 = require("../../../protocol/privacy");
@@ -45,11 +46,41 @@ function buildGetPrivacyDisallowedListIq(category) {
 function buildGetBlocklistIq() {
     return (0, query_1.buildIqNode)(nodes_1.WA_IQ_TYPES.GET, defaults_1.WA_DEFAULTS.HOST_DOMAIN, nodes_1.WA_XMLNS.BLOCKLIST);
 }
-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`).
+ */
+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 (0, query_1.buildIqNode)(nodes_1.WA_IQ_TYPES.SET, defaults_1.WA_DEFAULTS.HOST_DOMAIN, nodes_1.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.
+ */
+function buildBlocklistUnblockIq(jid) {
+    return (0, query_1.buildIqNode)(nodes_1.WA_IQ_TYPES.SET, defaults_1.WA_DEFAULTS.HOST_DOMAIN, nodes_1.WA_XMLNS.BLOCKLIST, [
+        {
+            tag: 'item',
+            attrs: { jid, action: 'unblock' }
         }
     ]);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "zapo-js",
-    "version": "1.6.0",
+    "version": "1.6.1",
     "description": "High-performance WhatsApp Web TypeScript library",
     "license": "MIT",
     "author": "vinikjkkj <contact@vinicius.email> (https://github.com/vinikjkkj)",