zapo-js 1.7.0 → 1.8.0

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,
@@ -398,17 +400,16 @@ class WaMessageDispatchCoordinator {
         ]);
         const messageWithIcdc = (0, icdc_1.injectDeviceListMetadata)(messageWithSecret, senderIcdc, recipientIcdc);
         const plaintext = await (0, padding_1.writeRandomPadMax16)(_proto_1.proto.Message.encode(messageWithIcdc).finish());
-        const buttonAddonKind = (0, content_1.resolveButtonAddonKind)(messageWithIcdc);
+        const outboundAttrs = (0, content_1.resolveOutboundMessageAttrs)(messageWithIcdc);
+        const buttonAddonKind = outboundAttrs.buttonAddonKind;
         const buttonAddonNode = buttonAddonKind ? (0, message_1.buildButtonAddonNode)(buttonAddonKind) : undefined;
         // when a <biz> companion is attached the stanza must advertise type=text and
         // omit enc.mediatype; sending type=media + mediatype=list/button alongside the
         // companion is rejected by the server as SMAX_INVALID (479).
-        const type = buttonAddonKind ? 'text' : (0, content_1.resolveMessageTypeAttr)(messageWithIcdc);
-        const edit = (0, content_1.resolveEditAttr)(messageWithIcdc) ?? undefined;
-        const mediatype = buttonAddonKind
-            ? undefined
-            : ((0, content_1.resolveEncMediaType)(messageWithIcdc) ?? undefined);
-        const metaAttrs = (0, content_1.resolveMetaAttrs)(messageWithIcdc);
+        const type = buttonAddonKind ? 'text' : outboundAttrs.typeAttr;
+        const edit = outboundAttrs.edit ?? undefined;
+        const mediatype = buttonAddonKind ? undefined : (outboundAttrs.mediatype ?? undefined);
+        const metaAttrs = outboundAttrs.metaAttrs;
         const metaNode = metaAttrs ? (0, message_1.buildMetaNode)(metaAttrs) : undefined;
         const customNodes = [];
         if (metaNode)
@@ -420,7 +421,7 @@ class WaMessageDispatchCoordinator {
                 customNodes.push(node);
             }
         }
-        const decryptFail = (0, content_1.resolveDecryptFailAttr)(messageWithIcdc);
+        const decryptFail = outboundAttrs.decryptFail;
         const envelope = {
             message: messageWithIcdc,
             plaintext,
@@ -540,7 +541,7 @@ class WaMessageDispatchCoordinator {
             replayStatusSetting: statusSetting,
             // Bare `<to jid=user>` ack hints route the skmsg through primary
             // devices that already hold the sender key.
-            customize: async ({ fanoutDeviceJids, distributionParticipants, messageWithSecret, sendOptions }) => {
+            customize: ({ fanoutDeviceJids, distributionParticipants, messageWithSecret, sendOptions }) => {
                 const distributedAddressKeys = new Set();
                 for (let i = 0; i < distributionParticipants.length; i += 1) {
                     distributedAddressKeys.add((0, jid_1.signalAddressKey)(distributionParticipants[i].address));
@@ -560,7 +561,7 @@ class WaMessageDispatchCoordinator {
                     seenAck.add(userJid);
                     ackHints.push({ jid: userJid });
                 }
-                const reportingArtifacts = await this.tryBuildReportingTokenArtifacts({
+                const reportingArtifacts = this.tryBuildReportingTokenArtifacts({
                     message: messageWithSecret,
                     stanzaId: sendOptions.id,
                     senderUserJid: (0, jid_1.toUserJid)(senderJid),
@@ -638,14 +639,15 @@ class WaMessageDispatchCoordinator {
                 participants.push(entry);
             }
         }
+        const outboundAttrs = (0, content_1.resolveOutboundMessageAttrs)(messageWithSecret);
         const messageNode = (0, message_1.buildGroupSenderKeyMessageNode)({
             to: input.groupJid,
-            type: (0, content_1.resolveMessageTypeAttr)(messageWithSecret),
+            type: outboundAttrs.typeAttr,
             id: sendOptions.id,
             phash: extras.phash,
-            edit: (0, content_1.resolveEditAttr)(messageWithSecret) ?? undefined,
-            mediatype: (0, content_1.resolveEncMediaType)(messageWithSecret) ?? undefined,
-            decryptFail: (0, content_1.resolveDecryptFailAttr)(messageWithSecret),
+            edit: outboundAttrs.edit ?? undefined,
+            mediatype: outboundAttrs.mediatype ?? undefined,
+            decryptFail: outboundAttrs.decryptFail,
             groupCiphertext: groupCiphertext.ciphertext,
             participants,
             deviceIdentity: shouldAttachDeviceIdentity
@@ -819,8 +821,9 @@ class WaMessageDispatchCoordinator {
                 break;
             }
         }
-        const reportingArtifacts = await this.tryBuildReportingTokenArtifacts({
+        const reportingArtifacts = this.tryBuildReportingTokenArtifacts({
             message,
+            messageBytes: (0, padding_1.unpadPkcs7)(plaintext),
             stanzaId: sendOptions.id,
             senderUserJid: (0, jid_1.toUserJid)(senderJid),
             remoteJid: groupJid,
@@ -975,8 +978,9 @@ class WaMessageDispatchCoordinator {
         phashTargets[phashTargetCount] = senderJid;
         phashTargets.length = phashTargetCount + 1;
         const localPhash = (0, phash_1.computePhashV2)(phashTargets);
-        const reportingArtifacts = await this.tryBuildReportingTokenArtifacts({
+        const reportingArtifacts = this.tryBuildReportingTokenArtifacts({
             message,
+            messageBytes: (0, padding_1.unpadPkcs7)(plaintext),
             stanzaId: sendOptions.id,
             senderUserJid: (0, jid_1.toUserJid)(senderJid),
             remoteJid: groupJid,
@@ -1070,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;
@@ -1088,9 +1127,6 @@ class WaMessageDispatchCoordinator {
         return (0, jid_1.normalizeDeviceJid)(meJid);
     }
     async encryptGroupDistributionParticipants(groupJid, senderKeyId, senderKeyDistributionMessage, participantUserJids) {
-        const distributionPayload = await (0, padding_1.writeRandomPadMax16)(_proto_1.proto.Message.encode({
-            senderKeyDistributionMessage
-        }).finish());
         const fanoutDeviceJids = await this.deps.fanoutResolver.resolveGroupParticipantDeviceJids(participantUserJids);
         if (fanoutDeviceJids.length === 0) {
             return {
@@ -1098,13 +1134,9 @@ class WaMessageDispatchCoordinator {
                 distributionParticipants: []
             };
         }
-        const fanoutTargetsByAddressKey = new Map();
         const fanoutAddresses = new Array(fanoutDeviceJids.length);
         for (let index = 0; index < fanoutDeviceJids.length; index += 1) {
-            const jid = fanoutDeviceJids[index];
-            const address = (0, jid_1.parseSignalAddressFromJid)(jid);
-            fanoutAddresses[index] = address;
-            fanoutTargetsByAddressKey.set((0, jid_1.signalAddressKey)(address), { jid, address });
+            fanoutAddresses[index] = (0, jid_1.parseSignalAddressFromJid)(fanoutDeviceJids[index]);
         }
         const pendingAddresses = await this.deps.senderKeyManager.filterParticipantsNeedingDistribution(groupJid, senderKeyId, fanoutAddresses);
         if (pendingAddresses.length === 0) {
@@ -1113,6 +1145,14 @@ class WaMessageDispatchCoordinator {
                 distributionParticipants: []
             };
         }
+        const fanoutTargetsByAddressKey = new Map();
+        for (let index = 0; index < fanoutAddresses.length; index += 1) {
+            const address = fanoutAddresses[index];
+            fanoutTargetsByAddressKey.set((0, jid_1.signalAddressKey)(address), {
+                jid: fanoutDeviceJids[index],
+                address
+            });
+        }
         const pendingAddressKeys = new Set();
         const pendingTargets = [];
         for (let index = 0; index < pendingAddresses.length; index += 1) {
@@ -1172,6 +1212,9 @@ class WaMessageDispatchCoordinator {
                 distributionParticipants: []
             };
         }
+        const distributionPayload = await (0, padding_1.writeRandomPadMax16)(_proto_1.proto.Message.encode({
+            senderKeyDistributionMessage
+        }).finish());
         const distributionEncryptRequests = new Array(availableTargets.length);
         for (let index = 0; index < availableTargets.length; index += 1) {
             const target = availableTargets[index];
@@ -1324,8 +1367,9 @@ class WaMessageDispatchCoordinator {
         const deviceIdentity = shouldAttachDeviceIdentity
             ? this.getEncodedSignedDeviceIdentity()
             : undefined;
-        const reportingArtifacts = await this.tryBuildReportingTokenArtifacts({
+        const reportingArtifacts = this.tryBuildReportingTokenArtifacts({
             message,
+            messageBytes: (0, padding_1.unpadPkcs7)(plaintext),
             stanzaId: sendOptions.id,
             senderUserJid: meUserJid,
             remoteJid: recipientUserJid,
@@ -1428,13 +1472,14 @@ class WaMessageDispatchCoordinator {
             return `3EB0${(0, bytes_1.bytesToHex)(await (0, _crypto_1.randomBytesAsync)(8)).toUpperCase()}`;
         }
     }
-    async tryBuildReportingTokenArtifacts(input) {
+    tryBuildReportingTokenArtifacts(input) {
         if (!input.stanzaId) {
             return null;
         }
         try {
-            return await (0, reporting_token_1.buildReportingTokenArtifacts)({
+            return (0, reporting_token_1.buildReportingTokenArtifacts)({
                 message: input.message,
+                messageBytes: input.messageBytes,
                 stanzaId: input.stanzaId,
                 senderUserJid: input.senderUserJid,
                 remoteJid: input.remoteJid

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[]>;