zapo-js 1.7.1 → 1.8.0

package/dist/client/WaClient.js

@@ -61,6 +61,7 @@ class WaClientImpl extends node_events_1.EventEmitter {
                 syncAppState: () => this.deps.chatCoordinator.sync().then(() => { }),
                 syncAppStateWithOptions: (syncOptions) => this.deps.chatCoordinator.sync(syncOptions),
                 emitEvent: this.emit.bind(this),
+                hasEventListener: (event) => this.listenerCount(event) > 0,
                 handleIncomingMessageEvent: this.handleIncomingMessageEvent.bind(this),
                 handleError: this.handleError.bind(this),
                 handleIncomingFrame: this.handleIncomingFrame.bind(this),

package/dist/client/WaClientFactory.d.ts

@@ -60,6 +60,8 @@ interface WaClientBuildRuntime {
     readonly syncAppState: () => Promise<void>;
     readonly syncAppStateWithOptions: (options?: WaAppStateSyncOptions) => Promise<WaAppStateSyncResult>;
     readonly emitEvent: <K extends keyof WaClientEventMap>(event: K, ...args: Parameters<WaClientEventMap[K]>) => void;
+    /** Whether anything is subscribed, for events whose payload costs something to build. */
+    readonly hasEventListener: (event: keyof WaClientEventMap) => boolean;
     readonly handleIncomingMessageEvent: (event: WaIncomingMessageEvent) => Promise<void>;
     readonly handleError: (error: Error) => void;
     readonly handleIncomingFrame: (frame: Uint8Array) => Promise<void>;

package/dist/client/WaClientFactory.js

@@ -32,6 +32,7 @@ const devices_1 = require("./events/devices");
 const dirty_1 = require("./events/dirty");
 const identity_1 = require("./events/identity");
 const privacy_token_1 = require("./events/privacy-token");
+const username_1 = require("./events/username");
 const fanout_1 = require("./messaging/fanout");
 const group_metadata_1 = require("./messaging/group-metadata");
 const key_protocol_1 = require("./messaging/key-protocol");
@@ -41,6 +42,7 @@ const WaMediaTransferClient_1 = require("../media/transfer/WaMediaTransferClient
 const fetcher_1 = require("../message/addons/link-preview/fetcher");
 const newsletter_1 = require("../message/kinds/newsletter");
 const incoming_1 = require("../message/primitives/incoming");
+const media_retry_1 = require("../message/primitives/media-retry");
 const peer_data_operation_1 = require("../message/primitives/peer-data-operation");
 const WaMessageClient_1 = require("../message/WaMessageClient");
 const constants_1 = require("../protocol/constants");
@@ -122,7 +124,7 @@ function resolveWaClientBase(options, logger) {
     };
 }
 function createIncomingNodeRuntime(input) {
-    const { logger, emitEvent, authClient, connectionManager, nodeOrchestrator, streamControl, mediaMessageBuildOptions, retryCoordinator, messageDispatch, sendNode, syncAppState, disconnect, clearStoredCredentials, getCurrentCredentials, handleClientDirtyBits, incomingMessageAckOptions } = input;
+    const { logger, emitEvent, authClient, connectionManager, nodeOrchestrator, streamControl, mediaMessageBuildOptions, retryCoordinator, mediaRetryRequester, messageDispatch, sendNode, syncAppState, disconnect, clearStoredCredentials, getCurrentCredentials, handleClientDirtyBits, incomingMessageAckOptions } = input;
     return {
         handleStreamControlResult: streamControl.handleStreamControlResult,
         persistSuccessAttributes: (attributes) => authClient.persistSuccessAttributes(attributes, { countsAsLogin: true }),
@@ -141,6 +143,7 @@ function createIncomingNodeRuntime(input) {
         handleIncomingMessageNode: (node) => (0, incoming_1.handleIncomingMessageAck)(node, incomingMessageAckOptions),
         sendNode,
         handleIncomingRetryReceipt: (node) => retryCoordinator.handleIncomingRetryReceipt(node),
+        handleMediaRetryNotification: (node) => mediaRetryRequester.handleNotification(node),
         trackOutboundReceipt: (node) => retryCoordinator.trackOutboundReceipt(node),
         emitIncomingReceipt: (event) => emitEvent('receipt', event),
         emitIncomingPresence: (event) => emitEvent('presence', event),
@@ -382,6 +385,8 @@ function buildWaClientDependencies(input) {
     });
     const privacyCoordinator = (0, WaPrivacyCoordinator_1.createPrivacyCoordinator)({
         logger,
+        contactStore: sessionStore.contacts,
+        isUsernamePrivacyListIdentifierEnabled: () => abPropsCoordinator.getConfigValue('username_contact_privacy_setting_allow_uncontact_set_enable'),
         queryWithContext: runtime.queryWithContext,
         resolveUserJidPair: (userJid) => signalDeviceSync.resolveUserJidPair(userJid),
         getSelfLid: () => getCurrentCredentials()?.meLid ?? null,
@@ -514,9 +519,15 @@ function buildWaClientDependencies(input) {
         generateOutgoingMessageId: () => messageDispatch.generateOutgoingMessageId(),
         subscribeToProtocolMessage: runtime.subscribeProtocolMessage
     });
+    const mediaRetryRequester = (0, media_retry_1.createMediaRetryRequester)({
+        logger,
+        sendNode: (node) => nodeOrchestrator.sendNode(node, false),
+        getCurrentCredentials
+    });
     const messageCoordinator = new WaMessageCoordinator_1.WaMessageCoordinator({
         messageDispatch,
         mediaTransfer,
+        mediaRetry: mediaRetryRequester,
         mediaUploadOptions: mediaMessageBuildOptions,
         logger,
         messageStore: sessionStore.messages,
@@ -719,7 +730,15 @@ function buildWaClientDependencies(input) {
         },
         emitNewsletterMessageUpdate: (event) => runtime.emitEvent('newsletter_message_update', event),
         emitUnavailableMessage: (event) => runtime.emitEvent('message_unavailable', event),
-        emitUnhandledStanza: (event) => runtime.emitEvent('debug_unhandled_stanza', event)
+        emitUnhandledStanza: (event) => runtime.emitEvent('debug_unhandled_stanza', event),
+        emitDecryptedPayload: (build) => {
+            // Built only if someone is subscribed: the payload carries a copy of
+            // the plaintext and a redacted node, and this runs per `<enc>`.
+            if (!runtime.hasEventListener('debug_decrypted_payload')) {
+                return;
+            }
+            runtime.emitEvent('debug_decrypted_payload', build());
+        }
     };
     const handleClientDirtyBits = (dirtyBits) => (0, dirty_1.handleDirtyBits)({
         logger,
@@ -752,6 +771,7 @@ function buildWaClientDependencies(input) {
             streamControl,
             mediaMessageBuildOptions,
             retryCoordinator,
+            mediaRetryRequester,
             messageDispatch,
             sendNode: runtime.sendNode,
             syncAppState: runtime.syncAppState,
@@ -928,6 +948,10 @@ function buildWaClientDependencies(input) {
             if ((0, helpers_1.findNodeChild)(node, constants_1.WA_NODE_TAGS.PRIVACY)) {
                 privacyCoordinator.scheduleAccountSyncRefresh();
             }
+            const usernameEvent = (0, username_1.parseOwnUsernameNotification)(node);
+            if (usernameEvent) {
+                runtime.emitEvent('own_username', usernameEvent);
+            }
             return false;
         }
     });

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

@@ -22,6 +22,7 @@ interface WaIncomingNodeRuntime {
     readonly handleIncomingMessageNode: (node: BinaryNode) => Promise<boolean>;
     readonly sendNode: (node: BinaryNode) => Promise<void>;
     readonly handleIncomingRetryReceipt: (node: BinaryNode) => Promise<void>;
+    readonly handleMediaRetryNotification: (node: BinaryNode) => void;
     readonly trackOutboundReceipt: (node: BinaryNode) => Promise<void>;
     readonly emitIncomingReceipt: (event: WaIncomingReceiptEvent) => void;
     readonly emitIncomingPresence: (event: WaIncomingPresenceEvent) => void;

package/dist/client/coordinators/WaIncomingNodeCoordinator.js

@@ -238,7 +238,8 @@ class WaIncomingNodeCoordinator {
                 emitIncomingNotification: runtime.emitIncomingNotification,
                 emitMexNotification: runtime.emitMexNotification,
                 emitUnhandledStanza: runtime.emitUnhandledIncomingNode,
-                syncAppState: runtime.syncAppState
+                syncAppState: runtime.syncAppState,
+                handleMediaRetryNotification: runtime.handleMediaRetryNotification
             })
         });
         this.registerIncomingHandler({

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

@@ -8,6 +8,7 @@ import type { WaDownloadMediaOptions, WaIncomingAddonEvent, WaIncomingMessageEve
 import type { Logger } from '../../infra/log/types';
 import type { WaMediaTransferClient } from '../../media/transfer/WaMediaTransferClient';
 import type { MediaKind } from '../../media/types';
+import type { WaMediaRetryRequest, WaMediaRetryRequester, WaMediaRetryResult } from '../../message/primitives/media-retry';
 import type { PeerDataOperationRequester } from '../../message/primitives/peer-data-operation';
 import type { WaMessagePublishResult, WaSendMessageContent, WaSendReceiptEventOptions, WaSendReceiptOptions } from '../../message/types';
 import { type Proto } from '../../proto';
@@ -17,6 +18,8 @@ import { type WaMexQuerySocket } from '../../transport/node/mex/client';
 export interface WaMessageCoordinatorDeps {
     readonly messageDispatch: WaMessageDispatchCoordinator;
     readonly mediaTransfer: WaMediaTransferClient;
+    /** Backs {@link WaMessageCoordinator.requestMediaReupload}. */
+    readonly mediaRetry: WaMediaRetryRequester;
     /** Media upload wiring shared with the send path; backs {@link WaMessageCoordinator.upload}. */
     readonly mediaUploadOptions: WaMediaMessageOptions;
     readonly logger: Logger;
@@ -163,6 +166,7 @@ export interface WaMediaUploadResult extends UploadResult {
 export declare class WaMessageCoordinator {
     private readonly messageDispatch;
     private readonly mediaTransfer;
+    private readonly mediaRetry;
     private readonly mediaUploadOptions;
     private readonly logger;
     private readonly messageStore;
@@ -373,6 +377,52 @@ export declare class WaMessageCoordinator {
      * `options.maxBytes`.
      */
     downloadBytes(source: WaIncomingMessageEvent | Proto.IMessage, options?: WaDownloadMediaOptions): Promise<Uint8Array>;
+    /**
+     * Asks the sender's primary device to re-upload a message's media, for when
+     * the CDN answers `404`/`410` because the blob expired - typically old
+     * media surfaced by a history sync. Sends a `server-error` receipt carrying
+     * the sealed request and resolves once the server answers with a
+     * `mediaretry` notification, usually within a couple of seconds.
+     *
+     * On `result: 'success'` only the `directPath` changes - the media key,
+     * hashes, and length of the original message stay valid, so patch the path
+     * into the message and download again. A second call for a message already
+     * in flight joins the first request instead of sending another receipt.
+     *
+     * The other three `result` values are answers too, not thrown errors:
+     * `not_found` means the sender no longer holds the file and nothing can
+     * recover it, `decryption_error` that it could not open its own copy, and
+     * `general_error` anything else including a result code this version does
+     * not recognize.
+     *
+     * Requires the message's media key, so it only works for media you received
+     * or sent, never for a bare message id. Newsletter messages are rejected -
+     * channel media has no per-message key to seal the request with. Pass an
+     * explicit `WaMediaRetryRequest` instead of an event when you hold the
+     * message id, chat jid, and media key but not the decoded message.
+     *
+     * @throws when the message carries no downloadable media, is a newsletter
+     * message, the session is not paired, the stanza cannot be sent, or no
+     * notification arrives before `options.timeoutMs`. It does **not** throw on
+     * a `not_found` / `general_error` answer - check `result`.
+     * @example
+     * ```ts
+     * const image = event.message?.imageMessage
+     * try {
+     *     return await client.message.downloadBytes(event)
+     * } catch {
+     *     const retry = await client.message.requestMediaReupload(event)
+     *     if (retry.result !== 'success') throw new Error(`reupload ${retry.result}`)
+     *     return await client.message.downloadBytes({
+     *         imageMessage: { ...image, directPath: retry.directPath }
+     *     })
+     * }
+     * ```
+     */
+    requestMediaReupload(event: WaIncomingMessageEvent, options?: {
+        readonly timeoutMs?: number;
+    }): Promise<WaMediaRetryResult>;
+    requestMediaReupload(request: WaMediaRetryRequest): Promise<WaMediaRetryResult>;
     /**
      * Attempts to decrypt an addon payload (poll vote, reaction, edit, ...)
      * attached to `event` and, on success, emits a typed

package/dist/client/coordinators/WaMessageCoordinator.js

@@ -9,6 +9,7 @@ const messages_1 = require("../messaging/messages");
 const constants_1 = require("../../media/constants");
 const addon_crypto_1 = require("../../message/crypto/addon-crypto");
 const content_1 = require("../../message/encode/content");
+const media_payload_1 = require("../../message/encode/media-payload");
 const group_history_1 = require("../../message/kinds/group-history");
 const _proto_1 = require("../../proto");
 const jid_1 = require("../../protocol/jid");
@@ -79,6 +80,7 @@ class WaMessageCoordinator {
     constructor(deps) {
         this.messageDispatch = deps.messageDispatch;
         this.mediaTransfer = deps.mediaTransfer;
+        this.mediaRetry = deps.mediaRetry;
         this.mediaUploadOptions = deps.mediaUploadOptions;
         this.logger = deps.logger;
         this.messageStore = deps.messageStore;
@@ -486,6 +488,30 @@ class WaMessageCoordinator {
         const stream = await this.download(source, options);
         return (0, bytes_1.readAllBytes)(stream, { maxBytes: options.maxBytes });
     }
+    requestMediaReupload(source, options) {
+        if (!('key' in source)) {
+            return this.mediaRetry.request(source);
+        }
+        const key = source.key;
+        if (!key.id || !key.remoteJid) {
+            throw new Error('requestMediaReupload event is missing key.remoteJid or key.id');
+        }
+        if (key.isNewsletter) {
+            throw new Error('requestMediaReupload is not supported on newsletter messages');
+        }
+        const payload = (0, media_payload_1.resolveMediaPayload)(source.message);
+        if (!payload) {
+            throw new Error('message has no downloadable media');
+        }
+        return this.mediaRetry.request({
+            messageId: key.id,
+            chatJid: key.remoteJid,
+            mediaKey: payload.mediaKey,
+            fromMe: key.fromMe,
+            participant: key.participant,
+            timeoutMs: options?.timeoutMs
+        });
+    }
     /**
      * Attempts to decrypt an addon payload (poll vote, reaction, edit, ...)
      * attached to `event` and, on success, emits a typed
@@ -529,19 +555,23 @@ class WaMessageCoordinator {
             }
             return;
         }
-        const parentMsgOriginalSender = parentEntry.senderJid;
-        const modificationSender = event.key.participant ?? event.key.remoteJid;
-        const plaintext = await (0, addon_crypto_1.decryptAddonPayload)({
+        const modificationSenderRaw = event.key.participant ?? event.key.remoteJid;
+        if (!modificationSenderRaw)
+            return;
+        const modificationSenderCandidates = (0, addon_crypto_1.collectUniqueUserJids)(event.key.fromMe ? event.rawNode.attrs.from : undefined, modificationSenderRaw, event.key.participantAlt, event.key.remoteJidAlt, event.rawNode.attrs.participant_pn, event.rawNode.attrs.sender_pn, event.rawNode.attrs.participant, event.key.isGroup ? undefined : event.rawNode.attrs.from);
+        const keyParentSender = (0, addon_crypto_1.resolveAddonParentSenderFromKey)(addon.targetMessageKey, event.key.isGroup);
+        const parentMsgOriginalSenderCandidates = (0, addon_crypto_1.collectUniqueUserJids)(keyParentSender, parentEntry.senderJid);
+        const senderPairs = (0, addon_crypto_1.buildAddonSenderPairs)({
+            parentCandidates: parentMsgOriginalSenderCandidates,
+            modificationCandidates: modificationSenderCandidates
+        });
+        const plaintext = await (0, addon_crypto_1.decryptAddonPayloadWithSenderFallback)({
             messageSecret: parentEntry.secret,
             stanzaId: targetMessageId,
-            parentMsgOriginalSender,
-            modificationSender,
+            senderPairs,
             modificationType: addon.modificationType,
             ciphertext: addon.encPayload,
-            iv: addon.encIv,
-            additionalData: (0, addon_crypto_1.shouldUseAddonAdditionalData)(addon.modificationType)
-                ? (0, addon_crypto_1.buildAddonAdditionalData)(targetMessageId, modificationSender)
-                : undefined
+            iv: addon.encIv
         });
         let decrypted = (0, addon_crypto_1.decodeAddonPlaintext)(addon.kind, plaintext);
         if (decrypted.kind === 'poll_vote' && decrypted.pollVote.selectedOptions) {

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

@@ -188,6 +188,14 @@ export declare class WaMessageDispatchCoordinator {
     private buildBotSidecarParticipant;
     private publishGroupSenderKeyMessage;
     private resolveGroupAddressingMode;
+    /**
+     * Parent-author JID stored with the outgoing message secret. Peers address
+     * us by LID in `pollCreationMessageKey` during the PN→LID migration, so a
+     * valid `meLid` wins. A malformed LID must not abort the send: fall back to
+     * a normalized `meJid`, then to the empty sender (same recoverable path as
+     * {@link resolveSenderForAddressingMode}).
+     */
+    private resolveOutgoingSecretSenderJid;
     private resolveSenderForAddressingMode;
     private encryptGroupDistributionParticipants;
     private publishDirectSignalMessageWithFanout;

package/dist/client/coordinators/WaMessageDispatchCoordinator.js

@@ -374,9 +374,11 @@ class WaMessageDispatchCoordinator {
             rawSecret.length > 0 &&
             sendOptions.id &&
             (this.deps.persistAllMessageSecrets || (0, content_1.needsSecretPersistence)(messageWithSecret))) {
-            const meJid = this.deps.getCurrentCredentials()?.meJid ?? '';
             void this.deps.messageSecretStore
-                .set(sendOptions.id, { secret: rawSecret, senderJid: meJid })
+                .set(sendOptions.id, {
+                secret: rawSecret,
+                senderJid: this.resolveOutgoingSecretSenderJid()
+            })
                 .catch((error) => {
                 this.deps.logger.warn('failed to persist outgoing message secret', {
                     id: sendOptions.id,
@@ -1072,6 +1074,41 @@ class WaMessageDispatchCoordinator {
         });
         return constants_1.WA_ADDRESSING_MODES.PN;
     }
+    /**
+     * Parent-author JID stored with the outgoing message secret. Peers address
+     * us by LID in `pollCreationMessageKey` during the PN→LID migration, so a
+     * valid `meLid` wins. A malformed LID must not abort the send: fall back to
+     * a normalized `meJid`, then to the empty sender (same recoverable path as
+     * {@link resolveSenderForAddressingMode}).
+     */
+    resolveOutgoingSecretSenderJid() {
+        const credentials = this.deps.getCurrentCredentials();
+        const meLid = credentials?.meLid;
+        if (meLid && meLid.includes('@')) {
+            try {
+                return (0, jid_1.toUserJid)(meLid);
+            }
+            catch (error) {
+                this.deps.logger.trace('ignoring malformed me lid jid', {
+                    meLid,
+                    message: (0, primitives_2.toError)(error).message
+                });
+            }
+        }
+        const meJid = credentials?.meJid;
+        if (meJid && meJid.includes('@')) {
+            try {
+                return (0, jid_1.toUserJid)(meJid);
+            }
+            catch (error) {
+                this.deps.logger.trace('ignoring malformed me jid', {
+                    meJid,
+                    message: (0, primitives_2.toError)(error).message
+                });
+            }
+        }
+        return '';
+    }
     resolveSenderForAddressingMode(addressingMode, meJid) {
         if (addressingMode === constants_1.WA_ADDRESSING_MODES.LID) {
             const meLid = this.deps.getCurrentCredentials()?.meLid;

package/dist/client/coordinators/WaMobileCoordinator.js

@@ -607,8 +607,7 @@ class WaMobileCoordinator {
         }
     }
     nodeBytes(parent, tag) {
-        const content = (0, _transport_1.findNodeChild)(parent, tag)?.content;
-        return content instanceof Uint8Array ? content : null;
+        return (0, _transport_1.getNodeBytesContent)((0, _transport_1.findNodeChild)(parent, tag)) ?? null;
     }
     requirePrimaryIdentityKeyPair() {
         if (!this.isMobilePrimary()) {

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

@@ -2,6 +2,7 @@ import { type WaBlocklistResult, type WaPrivacyDisallowedListResult, type WaPriv
 import type { Logger } from '../../infra/log/types';
 import { type WaPrivacyDisallowedListSettingName, type WaPrivacySettingName, type WaPrivacySettingValueMap } from '../../protocol/privacy';
 import type { SignalUserJidPair } from '../../signal/api/SignalDeviceSyncApi';
+import type { WaContactStore } from '../../store/contracts/contact.store';
 import type { BinaryNode } from '../../transport/types';
 /** JIDs to add to / remove from a category's disallowed list. */
 export interface WaPrivacyDisallowedListInput {
@@ -47,7 +48,9 @@ export interface WaPrivacyCoordinator {
     /**
      * Fetches the per-category disallowed list (the JIDs explicitly excluded
      * while the category sits on `'contact_blacklist'`). Returns an empty
-     * list when the category is on any other value.
+     * list when the category is on any other value. `entries` carries the same
+     * membership as `jids` plus each entry's handle, when the server
+     * identified it that way.
      */
     readonly getDisallowedList: (category: WaPrivacyDisallowedListSettingName) => Promise<WaPrivacyDisallowedListResult>;
     /**
@@ -83,7 +86,9 @@ export interface WaPrivacyCoordinator {
     /**
      * Returns the current account-wide blocklist. Blocks/unblocks performed
      * on another device are refetched through the same dirty-bit path as
-     * {@link getPrivacySettings} and re-emitted as `blocklist`.
+     * {@link getPrivacySettings} and re-emitted as `blocklist`. `entries`
+     * carries the same membership as `jids` plus each entry's handle, when the
+     * server identified it that way.
      */
     readonly getBlocklist: () => Promise<WaBlocklistResult>;
     /**
@@ -98,6 +103,10 @@ export interface WaPrivacyCoordinator {
      * 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.
+     *
+     * A migrated entry also carries one identifier attribute, read from the
+     * stored contact: the phone jid, the username handle, or the display name.
+     * Entries with none of them are sent as `unknown_identifier`.
      */
     readonly blockUser: (jid: string) => Promise<void>;
     /**
@@ -138,6 +147,13 @@ interface WaPrivacyCoordinatorOptions {
      */
     readonly getSelfLid: () => string | null;
     readonly emitPrivacy: (event: WaPrivacyAccountSyncResult) => void;
+    /** Source of the username / display-name identifiers a migrated write carries. */
+    readonly contactStore: WaContactStore;
+    /**
+     * Server-synced `username_contact_privacy_setting_allow_uncontact_set_enable`
+     * AB-prop, off by default - entries then fall back to `pn_jid`.
+     */
+    readonly isUsernamePrivacyListIdentifierEnabled: () => boolean;
 }
 /** Builds a {@link WaPrivacyCoordinator} backed by the given IQ query function. */
 export declare function createPrivacyCoordinator(options: WaPrivacyCoordinatorOptions): WaPrivacyCoordinatorRuntime;

package/dist/client/coordinators/WaPrivacyCoordinator.js

@@ -10,6 +10,30 @@ const privacy_2 = require("../../protocol/privacy");
 const privacy_3 = require("../../transport/node/builders/privacy");
 const query_1 = require("../../transport/node/query");
 const primitives_1 = require("../../util/primitives");
+/**
+ * Adds the identifier fields a migrated write may carry. Only the writes that
+ * consume them call it - an unblock addresses by jid alone, and a
+ * disallowed-list write with the AB gate closed falls back to `pn_jid`.
+ */
+async function withContactIdentifiers(options, target) {
+    if (target.lidJid === null)
+        return target;
+    try {
+        const contact = await options.contactStore.getByJid(target.lidJid);
+        return {
+            ...target,
+            username: contact?.username ?? null,
+            displayName: contact?.displayName ?? null
+        };
+    }
+    catch (error) {
+        options.logger.debug('contact identifier lookup failed', {
+            jid: target.lidJid,
+            message: (0, primitives_1.toError)(error).message
+        });
+        return target;
+    }
+}
 /**
  * Resolves a blocklist input into both addressing forms via
  * `resolveUserJidPair` (device-list cache first, usync fallback for phone
@@ -50,10 +74,19 @@ async function resolveDisallowedListEntries(options, input) {
         { action: privacy_2.WA_PRIVACY_LIST_ACTIONS.ADD, jids: input.add ?? [] },
         { action: privacy_2.WA_PRIVACY_LIST_ACTIONS.REMOVE, jids: input.remove ?? [] }
     ];
+    const usernameIdentifierAllowed = options.isUsernamePrivacyListIdentifierEnabled();
     for (const { action, jids } of actions) {
         for (const jid of jids) {
-            const target = await resolveBlocklistTarget(options, jid);
-            entries.push({ action, lidJid: target.lidJid, pnJid: target.pnJid });
+            const resolved = await resolveBlocklistTarget(options, jid);
+            const target = usernameIdentifierAllowed
+                ? await withContactIdentifiers(options, resolved)
+                : resolved;
+            entries.push({
+                action,
+                lidJid: target.lidJid,
+                pnJid: target.pnJid,
+                username: target.username ?? null
+            });
         }
     }
     if (entries.length === 0) {
@@ -192,7 +225,7 @@ function createPrivacyCoordinator(options) {
             return (0, privacy_1.parseBlocklist)(result);
         },
         blockUser: async (jid) => {
-            const target = await resolveBlocklistTarget(options, jid);
+            const target = await withContactIdentifiers(options, await resolveBlocklistTarget(options, jid));
             const node = (0, privacy_3.buildBlocklistBlockIq)(target);
             const result = await queryWithContext('privacy.blockUser', node, undefined, {
                 jid: target.lidJid ?? target.pnJid

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

@@ -54,6 +54,24 @@ export interface WaUsernameAvailabilityResult {
     readonly available: boolean;
     readonly suggestions: readonly string[];
 }
+export type WaUsernameLookupResult = {
+    readonly status: 'found';
+    readonly jid: string;
+    readonly username: string | null;
+    readonly isBusiness: boolean;
+    readonly pnJid: string | null;
+} | {
+    readonly status: 'key-required';
+    readonly username: string | null;
+} | {
+    readonly status: 'not-found';
+};
+export interface WaResolveUsernameInput {
+    /** A leading `@` and a `:1234` key suffix are accepted. */
+    readonly username: string;
+    /** Overrides a key parsed out of {@link username}. */
+    readonly usernameKey?: string;
+}
 /**
  * Coordinates own/peer profile queries and mutations: picture, status, text
  * status, username, disappearing mode, and LID lookup. Accessed via
@@ -109,13 +127,23 @@ export interface WaProfileCoordinator {
     readonly setTextStatus: (input: WaSetTextStatusInput) => Promise<void>;
     /** Batched fetch of username per JID. */
     readonly getUsernames: (jids: readonly string[]) => Promise<readonly WaUsernameResult[]>;
+    /**
+     * Resolves a username handle to the account's LID, so a message can be
+     * addressed to `@handle`. `'key-required'` means the server withheld the
+     * JID - repeat the call with `usernameKey`.
+     *
+     * @throws when the handle fails local validation, before any round-trip.
+     */
+    readonly resolveUsername: (input: WaResolveUsernameInput) => Promise<WaUsernameLookupResult>;
     /** Fetches the current account's username record (value, state, recovery pin). */
     readonly getOwnUsername: () => Promise<WaOwnUsernameResult>;
     /**
      * Reserves/sets a username on the current account. Returns `true` only
-     * when the server reports `'SUCCESS'`; on any other outcome (taken,
-     * invalid, rate-limited) it returns `false` without throwing - check the
-     * value and consult {@link checkUsernameAvailability} for suggestions.
+     * when the server reports `'SUCCESS'`; on any other server outcome (taken,
+     * rate-limited) it returns `false` without throwing - check the value and
+     * consult {@link checkUsernameAvailability} for suggestions.
+     *
+     * @throws when the handle fails local validation, before any round-trip.
      */
     readonly setUsername: (input: WaSetUsernameInput) => Promise<boolean>;
     /** Deletes the current account's username. Returns `true` on success. */
@@ -124,7 +152,11 @@ export interface WaProfileCoordinator {
     readonly getAboutStatus: (jid: string) => Promise<string | null>;
     /** Checks whether a username is available and returns server suggestions. */
     readonly checkUsernameAvailability: (username: string) => Promise<WaUsernameAvailabilityResult>;
-    /** Sets the username recovery PIN. Returns `true` on success. */
+    /**
+     * Sets the username recovery PIN. Returns `true` on success.
+     *
+     * @throws when `pin` is not exactly 4 digits, before any round-trip.
+     */
     readonly setUsernameKey: (pin: string) => Promise<boolean>;
     /** Resolves LIDs for a list of phone numbers (handles normalization). */
     readonly getLidsByPhoneNumbers: (phoneNumbers: readonly string[]) => Promise<readonly SignalLidSyncResult[]>;