zapo-js 1.0.1 → 1.1.0

package/dist/client/coordinators/WaMessageCoordinator.js

@@ -4,9 +4,9 @@ exports.WaMessageCoordinator = void 0;
 const node_fs_1 = require("node:fs");
 const promises_1 = require("node:stream/promises");
 const receipt_1 = require("../events/receipt");
+const media_1 = require("../media");
 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 _proto_1 = require("../../proto");
 const jid_1 = require("../../protocol/jid");
 const client_1 = require("../../transport/node/mex/client");
@@ -235,23 +235,7 @@ class WaMessageCoordinator {
      * for one-shot verified downloads.
      */
     async download(source, options = {}) {
-        const message = 'rawNode' in source ? source.message : source;
-        const payload = (0, media_payload_1.resolveMediaPayload)(message);
-        if (!payload) {
-            throw new Error('message has no downloadable media');
-        }
-        const { plaintext, metadata } = await this.mediaTransfer.downloadAndDecryptStream({
-            directPath: payload.directPath,
-            mediaType: payload.mediaType,
-            mediaKey: payload.mediaKey,
-            fileSha256: payload.fileSha256,
-            fileEncSha256: payload.fileEncSha256,
-            timeoutMs: options.timeoutMs,
-            signal: options.signal,
-            maxBytes: options.maxBytes
-        });
-        metadata.catch(() => undefined);
-        return plaintext;
+        return (0, media_1.downloadMediaMessage)(source, { ...options, transfer: this.mediaTransfer });
     }
     /**
      * Convenience wrapper around {@link download} that streams the decrypted

package/dist/client/coordinators/WaMessageDispatchCoordinator.js

@@ -164,7 +164,8 @@ class WaMessageDispatchCoordinator {
             quote: options.quote,
             forward: options.forward,
             mentions: options.mentions,
-            meLid: this.deps.getCurrentCredentials()?.meLid
+            meLid: this.deps.getCurrentCredentials()?.meLid,
+            targetJid: recipientJid
         });
         const withCtx = ctx ? (0, context_info_1.applyContextInfo)(built.message, ctx) : built.message;
         const withViewOnce = options.viewOnce ? (0, content_1.wrapAsViewOnce)(withCtx) : withCtx;

package/dist/client/events/incoming.js

@@ -18,6 +18,7 @@ const call_1 = require("../events/call");
 const group_1 = require("../events/group");
 const mex_notification_1 = require("../events/mex-notification");
 const picture_1 = require("../events/picture");
+const receipt_1 = require("../events/receipt");
 const registration_1 = require("../events/registration");
 const constants_1 = require("../../protocol/constants");
 const jid_1 = require("../../protocol/jid");
@@ -188,7 +189,8 @@ function createIncomingReceiptHandler(options) {
                 status: mapped.status,
                 fromSelfDevice: mapped.fromSelfDevice,
                 participantJid: node.attrs.participant,
-                recipientJid: node.attrs.recipient
+                recipientJid: node.attrs.recipient,
+                messageIds: (0, receipt_1.extractReceiptIds)(node)
             });
         }
         else if (node.attrs.type && !INTERNAL_ONLY_RECEIPT_TYPES.has(node.attrs.type)) {

package/dist/client/events/receipt.d.ts

@@ -0,0 +1,30 @@
+import type { BinaryNode } from '../../transport/types';
+interface ReceiptTarget {
+    readonly chatJid: string;
+    readonly id: string;
+    readonly senderJid?: string;
+    readonly isGroupChat?: boolean;
+    readonly isBroadcastChat?: boolean;
+}
+interface AggregatedReceiptGroup {
+    readonly jid: string;
+    readonly ids: readonly string[];
+    readonly participant?: string;
+}
+export declare function aggregateReceiptTargets(targets: readonly ReceiptTarget[]): readonly AggregatedReceiptGroup[];
+/**
+ * Resolves every message id a `<receipt>` acknowledges, mirroring WhatsApp
+ * Web's `externalIds`. A batch receipt carries the extra ids in a
+ * `<list><item id=.../>` block; the top-level `attrs.id` is just one of them.
+ *
+ * - `<list><item>` ids come first. For `type="view"` receipts the item key is
+ *   `server_id` (not `id`), and the top-level id is NOT appended.
+ * - Otherwise the top-level `attrs.id` is appended last.
+ * - Aggregated receipts (carrying a `<participants>` child) are out of scope:
+ *   their ids live in `<user>` children, so this falls back to the single
+ *   top-level id for them.
+ *
+ * No dedup: matches wa-web, which pushes the top id without checking the list.
+ */
+export declare function extractReceiptIds(node: BinaryNode): readonly string[];
+export {};

package/dist/client/events/receipt.js

@@ -1,7 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.aggregateReceiptTargets = aggregateReceiptTargets;
+exports.extractReceiptIds = extractReceiptIds;
+const constants_1 = require("../../protocol/constants");
 const jid_1 = require("../../protocol/jid");
+const helpers_1 = require("../../transport/node/helpers");
 function needsParticipant(target) {
     if (target.isGroupChat !== undefined || target.isBroadcastChat !== undefined) {
         return target.isGroupChat === true || target.isBroadcastChat === true;
@@ -24,3 +27,32 @@ function aggregateReceiptTargets(targets) {
     }
     return [...groups.values()];
 }
+/**
+ * Resolves every message id a `<receipt>` acknowledges, mirroring WhatsApp
+ * Web's `externalIds`. A batch receipt carries the extra ids in a
+ * `<list><item id=.../>` block; the top-level `attrs.id` is just one of them.
+ *
+ * - `<list><item>` ids come first. For `type="view"` receipts the item key is
+ *   `server_id` (not `id`), and the top-level id is NOT appended.
+ * - Otherwise the top-level `attrs.id` is appended last.
+ * - Aggregated receipts (carrying a `<participants>` child) are out of scope:
+ *   their ids live in `<user>` children, so this falls back to the single
+ *   top-level id for them.
+ *
+ * No dedup: matches wa-web, which pushes the top id without checking the list.
+ */
+function extractReceiptIds(node) {
+    const topId = node.attrs.id;
+    if ((0, helpers_1.hasNodeChild)(node, 'participants')) {
+        return topId ? [topId] : [];
+    }
+    const isView = node.attrs.type === constants_1.WA_MESSAGE_TYPES.RECEIPT_TYPE_VIEW;
+    const list = (0, helpers_1.findNodeChild)(node, 'list');
+    const ids = list
+        ? [...(0, helpers_1.getNodeChildrenNonEmptyAttrValuesByTag)(list, 'item', isView ? 'server_id' : 'id')]
+        : [];
+    if (!isView && topId) {
+        ids.push(topId);
+    }
+    return ids;
+}

package/dist/{types/client → client}/media.d.ts

@@ -1,9 +1,11 @@
 import { type Readable } from 'node:stream';
-import type { WaMediaOptions } from './types';
+import type { WaDownloadMediaOptions, WaIncomingMessageEvent, WaMediaOptions } from './types';
 import type { Logger } from '../infra/log/types';
-import type { WaMediaTransferClient } from '../media/transfer/WaMediaTransferClient';
+import { WaMediaTransferClient } from '../media/transfer/WaMediaTransferClient';
 import type { WaMediaConn } from '../media/types';
 import type { WaSendMediaMessage } from '../message/types';
+import type { Proto } from '../proto';
+import type { WaProxyTransport } from '../transport/types';
 export interface ProcessedMediaFields {
     readonly jpegThumbnail?: Uint8Array;
     readonly pngThumbnail?: Uint8Array;
@@ -62,4 +64,59 @@ export declare function shouldNormalizeVoiceNote(media: WaMediaOptions | undefin
 export declare function hasMediaProcessingTasks(media: WaMediaOptions | undefined, content: WaSendMediaMessage): boolean;
 export declare function getScopedMediaLogger(parent: Logger): Logger;
 export declare function runMediaProcessor(media: WaMediaOptions | undefined, input: Uint8Array | string | undefined, content: WaSendMediaMessage, logger: Logger): Promise<ProcessedMediaFields>;
+export interface WaDownloadMediaMessageOptions extends WaDownloadMediaOptions {
+    /**
+     * Reuse an existing transfer client instead of creating a fresh one. Lets
+     * the download inherit proxy agents, timeouts, and the MAC-verification
+     * toggle, and avoids spinning up a new HTTP client per call in a loop. A
+     * stateless {@link WaMediaTransferClient} is created when omitted - fine
+     * for one-off downloads.
+     */
+    readonly transfer?: WaMediaTransferClient;
+    /**
+     * Proxy for the CDN download leg, mirroring `proxy.mediaDownload` on the
+     * client. The fetch runs over `node:http`/`node:https`, so only the Node
+     * `http.Agent` form is used; an undici dispatcher is ignored (same as the
+     * client treats `mediaDownload`). Takes precedence over the default agent
+     * of a `transfer` you pass.
+     */
+    readonly proxy?: WaProxyTransport;
+}
+/**
+ * Streams and decrypts the media attached to a message without a connected
+ * `WaClient`. Resolves the encrypted payload (directPath, mediaKey, file
+ * hashes) from `source`, fetches the ciphertext from the WhatsApp media CDN,
+ * and decrypts it on the fly.
+ *
+ * The media keys come from the (already decrypted) message itself, so this is
+ * for re-downloading media you have persisted - not for fetching media you
+ * never received. The CDN download needs no session or auth token; only the
+ * upload path does.
+ *
+ * **The caller owns the returned stream** - pipe it somewhere or call
+ * `.destroy()` to release the socket; an unconsumed stream leaks the
+ * connection. MAC + SHA-256 verification runs as bytes are consumed, so
+ * aborting mid-read leaves you with unverified bytes. Pass `options.signal`
+ * to cancel cleanly.
+ *
+ * @throws when `source` carries no downloadable media.
+ * @example
+ * ```ts
+ * import { downloadMediaMessage } from '..'
+ * import { createWriteStream } from 'node:fs'
+ *
+ * const stream = await downloadMediaMessage(event)
+ * stream.pipe(createWriteStream('photo.jpg'))
+ * ```
+ * @example
+ * ```ts
+ * // Route the CDN download through an http.Agent-style proxy
+ * import { HttpsProxyAgent } from 'https-proxy-agent'
+ *
+ * const stream = await downloadMediaMessage(event, {
+ *     proxy: new HttpsProxyAgent('http://127.0.0.1:8080')
+ * })
+ * ```
+ */
+export declare function downloadMediaMessage(source: Proto.IMessage | WaIncomingMessageEvent, options?: WaDownloadMediaMessageOptions): Promise<Readable>;
 export {};

package/dist/client/media.js

@@ -14,6 +14,7 @@ exports.shouldNormalizeVoiceNote = shouldNormalizeVoiceNote;
 exports.hasMediaProcessingTasks = hasMediaProcessingTasks;
 exports.getScopedMediaLogger = getScopedMediaLogger;
 exports.runMediaProcessor = runMediaProcessor;
+exports.downloadMediaMessage = downloadMediaMessage;
 const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const promises_1 = require("node:fs/promises");
@@ -22,6 +23,9 @@ const node_path_1 = require("node:path");
 const node_stream_1 = require("node:stream");
 const promises_2 = require("node:stream/promises");
 const core_1 = require("../crypto/core");
+const WaMediaTransferClient_1 = require("../media/transfer/WaMediaTransferClient");
+const media_payload_1 = require("../message/encode/media-payload");
+const proxy_1 = require("../transport/proxy");
 const bytes_1 = require("../util/bytes");
 const primitives_1 = require("../util/primitives");
 async function readFileHead(filePath, bytes) {
@@ -398,3 +402,59 @@ async function runMediaProcessor(media, input, content, logger) {
     }
     return result;
 }
+/**
+ * Streams and decrypts the media attached to a message without a connected
+ * `WaClient`. Resolves the encrypted payload (directPath, mediaKey, file
+ * hashes) from `source`, fetches the ciphertext from the WhatsApp media CDN,
+ * and decrypts it on the fly.
+ *
+ * The media keys come from the (already decrypted) message itself, so this is
+ * for re-downloading media you have persisted - not for fetching media you
+ * never received. The CDN download needs no session or auth token; only the
+ * upload path does.
+ *
+ * **The caller owns the returned stream** - pipe it somewhere or call
+ * `.destroy()` to release the socket; an unconsumed stream leaks the
+ * connection. MAC + SHA-256 verification runs as bytes are consumed, so
+ * aborting mid-read leaves you with unverified bytes. Pass `options.signal`
+ * to cancel cleanly.
+ *
+ * @throws when `source` carries no downloadable media.
+ * @example
+ * ```ts
+ * import { downloadMediaMessage } from '..'
+ * import { createWriteStream } from 'node:fs'
+ *
+ * const stream = await downloadMediaMessage(event)
+ * stream.pipe(createWriteStream('photo.jpg'))
+ * ```
+ * @example
+ * ```ts
+ * // Route the CDN download through an http.Agent-style proxy
+ * import { HttpsProxyAgent } from 'https-proxy-agent'
+ *
+ * const stream = await downloadMediaMessage(event, {
+ *     proxy: new HttpsProxyAgent('http://127.0.0.1:8080')
+ * })
+ * ```
+ */
+async function downloadMediaMessage(source, options = {}) {
+    const message = 'rawNode' in source ? source.message : source;
+    const payload = (0, media_payload_1.resolveMediaPayload)(message);
+    if (!payload) {
+        throw new Error('message has no downloadable media');
+    }
+    const transfer = options.transfer ?? new WaMediaTransferClient_1.WaMediaTransferClient();
+    const { plaintext } = await transfer.downloadAndDecryptStream({
+        directPath: payload.directPath,
+        mediaType: payload.mediaType,
+        mediaKey: payload.mediaKey,
+        fileSha256: payload.fileSha256,
+        fileEncSha256: payload.fileEncSha256,
+        agent: (0, proxy_1.toProxyAgent)(options.proxy),
+        timeoutMs: options.timeoutMs,
+        signal: options.signal,
+        maxBytes: options.maxBytes
+    });
+    return plaintext;
+}

package/dist/{types/client → client}/types.d.ts

@@ -512,6 +512,13 @@ export interface WaIncomingReceiptEvent extends WaIncomingBaseEvent {
     readonly fromSelfDevice: boolean;
     readonly participantJid?: string;
     readonly recipientJid?: string;
+    /**
+     * All message ids this receipt acknowledges. For batch read/delivery
+     * receipts this is the `<list><item>` ids plus the top-level `stanzaId`;
+     * for single receipts it is just `[stanzaId]`. Mirrors WhatsApp Web's
+     * `externalIds`.
+     */
+    readonly messageIds: readonly string[];
 }
 export interface WaIncomingPresenceEvent extends WaIncomingBaseEvent {
     readonly type: IncomingPresenceType;

package/dist/esm/appstate-spec.js

@@ -1,6 +1,6 @@
 import { proto } from './proto.js';
-import { WA_APPSTATE_SCHEMAS as RAW_WA_APPSTATE_SCHEMAS } from '../spec/appstate';
-export { WA_APPSTATE_COLLECTIONS, WA_APPSTATE_SCHEMAS } from '../spec/appstate';
+import { WA_APPSTATE_SCHEMAS as RAW_WA_APPSTATE_SCHEMAS } from '../../spec/appstate/index.js';
+export { WA_APPSTATE_COLLECTIONS, WA_APPSTATE_SCHEMAS } from '../../spec/appstate/index.js';
 const SCHEMA_BY_ACTION_NAME_BUILDER = {};
 for (const key of Object.keys(RAW_WA_APPSTATE_SCHEMAS)) {
     SCHEMA_BY_ACTION_NAME_BUILDER[RAW_WA_APPSTATE_SCHEMAS[key].name] = key;

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

@@ -1,9 +1,9 @@
 import { createWriteStream } from 'node:fs';
 import { pipeline } from 'node:stream/promises';
 import { aggregateReceiptTargets } from '../events/receipt.js';
+import { downloadMediaMessage } from '../media.js';
 import { buildAddonAdditionalData, decodeAddonPlaintext, decryptAddonPayload, identifyEncryptedAddon, resolveParentMessageSecret, resolvePollOptionNames, shouldUseAddonAdditionalData } from '../../message/crypto/addon-crypto.js';
 import { unwrapMessage } from '../../message/encode/content.js';
-import { resolveMediaPayload } from '../../message/encode/media-payload.js';
 import { proto } from '../../proto.js';
 import { applyDeviceToJid, normalizeRecipientJid } from '../../protocol/jid.js';
 import { runMexQuery } from '../../transport/node/mex/client.js';
@@ -232,23 +232,7 @@ export class WaMessageCoordinator {
      * for one-shot verified downloads.
      */
     async download(source, options = {}) {
-        const message = 'rawNode' in source ? source.message : source;
-        const payload = resolveMediaPayload(message);
-        if (!payload) {
-            throw new Error('message has no downloadable media');
-        }
-        const { plaintext, metadata } = await this.mediaTransfer.downloadAndDecryptStream({
-            directPath: payload.directPath,
-            mediaType: payload.mediaType,
-            mediaKey: payload.mediaKey,
-            fileSha256: payload.fileSha256,
-            fileEncSha256: payload.fileEncSha256,
-            timeoutMs: options.timeoutMs,
-            signal: options.signal,
-            maxBytes: options.maxBytes
-        });
-        metadata.catch(() => undefined);
-        return plaintext;
+        return downloadMediaMessage(source, { ...options, transfer: this.mediaTransfer });
     }
     /**
      * Convenience wrapper around {@link download} that streams the decrypted

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

@@ -161,7 +161,8 @@ export class WaMessageDispatchCoordinator {
             quote: options.quote,
             forward: options.forward,
             mentions: options.mentions,
-            meLid: this.deps.getCurrentCredentials()?.meLid
+            meLid: this.deps.getCurrentCredentials()?.meLid,
+            targetJid: recipientJid
         });
         const withCtx = ctx ? applyContextInfo(built.message, ctx) : built.message;
         const withViewOnce = options.viewOnce ? wrapAsViewOnce(withCtx) : withCtx;

package/dist/esm/client/events/incoming.js

@@ -3,6 +3,7 @@ import { parseCallNode } from '../events/call.js';
 import { parseGroupNotificationEvents } from '../events/group.js';
 import { parseMexNotification } from '../events/mex-notification.js';
 import { parsePictureNotificationEvents } from '../events/picture.js';
+import { extractReceiptIds } from '../events/receipt.js';
 import { parseRegistrationNotification } from '../events/registration.js';
 import { WA_CALL_NODE_ATTRS, WA_CALL_RECEIPT_PAYLOAD_TAGS, WA_DISCONNECT_REASONS, WA_MESSAGE_TAGS, WA_MESSAGE_TYPES, WA_NODE_TAGS, WA_NOTIFICATION_TYPES } from '../../protocol/constants.js';
 import { isLidJid, normalizeDeviceJid, toUserJid } from '../../protocol/jid.js';
@@ -173,7 +174,8 @@ export function createIncomingReceiptHandler(options) {
                 status: mapped.status,
                 fromSelfDevice: mapped.fromSelfDevice,
                 participantJid: node.attrs.participant,
-                recipientJid: node.attrs.recipient
+                recipientJid: node.attrs.recipient,
+                messageIds: extractReceiptIds(node)
             });
         }
         else if (node.attrs.type && !INTERNAL_ONLY_RECEIPT_TYPES.has(node.attrs.type)) {

package/dist/esm/client/events/receipt.js

@@ -1,4 +1,6 @@
+import { WA_MESSAGE_TYPES } from '../../protocol/constants.js';
 import { isGroupOrBroadcastJid } from '../../protocol/jid.js';
+import { findNodeChild, getNodeChildrenNonEmptyAttrValuesByTag, hasNodeChild } from '../../transport/node/helpers.js';
 function needsParticipant(target) {
     if (target.isGroupChat !== undefined || target.isBroadcastChat !== undefined) {
         return target.isGroupChat === true || target.isBroadcastChat === true;
@@ -21,3 +23,32 @@ export function aggregateReceiptTargets(targets) {
     }
     return [...groups.values()];
 }
+/**
+ * Resolves every message id a `<receipt>` acknowledges, mirroring WhatsApp
+ * Web's `externalIds`. A batch receipt carries the extra ids in a
+ * `<list><item id=.../>` block; the top-level `attrs.id` is just one of them.
+ *
+ * - `<list><item>` ids come first. For `type="view"` receipts the item key is
+ *   `server_id` (not `id`), and the top-level id is NOT appended.
+ * - Otherwise the top-level `attrs.id` is appended last.
+ * - Aggregated receipts (carrying a `<participants>` child) are out of scope:
+ *   their ids live in `<user>` children, so this falls back to the single
+ *   top-level id for them.
+ *
+ * No dedup: matches wa-web, which pushes the top id without checking the list.
+ */
+export function extractReceiptIds(node) {
+    const topId = node.attrs.id;
+    if (hasNodeChild(node, 'participants')) {
+        return topId ? [topId] : [];
+    }
+    const isView = node.attrs.type === WA_MESSAGE_TYPES.RECEIPT_TYPE_VIEW;
+    const list = findNodeChild(node, 'list');
+    const ids = list
+        ? [...getNodeChildrenNonEmptyAttrValuesByTag(list, 'item', isView ? 'server_id' : 'id')]
+        : [];
+    if (!isView && topId) {
+        ids.push(topId);
+    }
+    return ids;
+}

package/dist/esm/client/media.js

@@ -6,6 +6,9 @@ import { join } from 'node:path';
 import { Transform } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { randomIntAsync, sha256 } from '../crypto/core/index.js';
+import { WaMediaTransferClient } from '../media/transfer/WaMediaTransferClient.js';
+import { resolveMediaPayload } from '../message/encode/media-payload.js';
+import { toProxyAgent } from '../transport/proxy.js';
 import { bytesToBase64UrlSafe, TEXT_DECODER, toBytesView, toChunkBytes } from '../util/bytes.js';
 import { toError } from '../util/primitives.js';
 export async function readFileHead(filePath, bytes) {
@@ -382,3 +385,59 @@ export async function runMediaProcessor(media, input, content, logger) {
     }
     return result;
 }
+/**
+ * Streams and decrypts the media attached to a message without a connected
+ * `WaClient`. Resolves the encrypted payload (directPath, mediaKey, file
+ * hashes) from `source`, fetches the ciphertext from the WhatsApp media CDN,
+ * and decrypts it on the fly.
+ *
+ * The media keys come from the (already decrypted) message itself, so this is
+ * for re-downloading media you have persisted - not for fetching media you
+ * never received. The CDN download needs no session or auth token; only the
+ * upload path does.
+ *
+ * **The caller owns the returned stream** - pipe it somewhere or call
+ * `.destroy()` to release the socket; an unconsumed stream leaks the
+ * connection. MAC + SHA-256 verification runs as bytes are consumed, so
+ * aborting mid-read leaves you with unverified bytes. Pass `options.signal`
+ * to cancel cleanly.
+ *
+ * @throws when `source` carries no downloadable media.
+ * @example
+ * ```ts
+ * import { downloadMediaMessage } from '..'
+ * import { createWriteStream } from 'node:fs'
+ *
+ * const stream = await downloadMediaMessage(event)
+ * stream.pipe(createWriteStream('photo.jpg'))
+ * ```
+ * @example
+ * ```ts
+ * // Route the CDN download through an http.Agent-style proxy
+ * import { HttpsProxyAgent } from 'https-proxy-agent'
+ *
+ * const stream = await downloadMediaMessage(event, {
+ *     proxy: new HttpsProxyAgent('http://127.0.0.1:8080')
+ * })
+ * ```
+ */
+export async function downloadMediaMessage(source, options = {}) {
+    const message = 'rawNode' in source ? source.message : source;
+    const payload = resolveMediaPayload(message);
+    if (!payload) {
+        throw new Error('message has no downloadable media');
+    }
+    const transfer = options.transfer ?? new WaMediaTransferClient();
+    const { plaintext } = await transfer.downloadAndDecryptStream({
+        directPath: payload.directPath,
+        mediaType: payload.mediaType,
+        mediaKey: payload.mediaKey,
+        fileSha256: payload.fileSha256,
+        fileEncSha256: payload.fileEncSha256,
+        agent: toProxyAgent(options.proxy),
+        timeoutMs: options.timeoutMs,
+        signal: options.signal,
+        maxBytes: options.maxBytes
+    });
+    return plaintext;
+}

package/dist/esm/index.js

@@ -1,6 +1,8 @@
 export { WaClient } from './client/index.js';
+export { downloadMediaMessage } from './client/media.js';
 export { parseUsyncResultEnvelope } from './transport/node/builders/usync.js';
 export { getContentType, resolveMessageTarget } from './message/encode/content.js';
+export { resolveMediaPayload } from './message/encode/media-payload.js';
 export { fetchLatestWaWebVersion } from './transport/wa-web-version-fetcher.js';
 export { ConsoleLogger } from './infra/log/ConsoleLogger.js';
 export { PinoLogger, createPinoLogger } from './infra/log/PinoLogger.js';

package/dist/esm/message/context-info.js

@@ -1,4 +1,4 @@
-import { isGroupOrBroadcastJid } from '../protocol/jid.js';
+import { isGroupOrBroadcastJid, toUserJid } from '../protocol/jid.js';
 export function buildContextInfoProto(input) {
     const ctx = {};
     if (input.quotedMessageId !== undefined)
@@ -95,13 +95,23 @@ export function resolveSendContextInfo(input) {
         ctx.quotedMessageId = q.id ?? q.key?.id ?? ctx.quotedMessageId;
         const explicit = q.participant ?? q.key?.participant;
         const quotedRemote = q.remoteJid ?? q.key?.remoteJid;
+        const quotedFromMe = q.fromMe ?? q.key?.fromMe;
         const dmFallback = explicit === undefined && quotedRemote && !isGroupOrBroadcastJid(quotedRemote)
-            ? q.key?.fromMe
+            ? quotedFromMe
                 ? input.meLid
                 : quotedRemote
             : undefined;
         ctx.quotedParticipant = explicit ?? dmFallback ?? ctx.quotedParticipant;
-        ctx.quotedRemoteJid = quotedRemote ?? ctx.quotedRemoteJid;
+        const crossChat = quotedRemote !== undefined &&
+            (input.targetJid === undefined || !isSameChatJid(quotedRemote, input.targetJid));
+        if (quotedRemote !== undefined) {
+            if (crossChat) {
+                ctx.quotedRemoteJid = quotedRemote;
+            }
+            else {
+                delete ctx.quotedRemoteJid;
+            }
+        }
         ctx.quotedMessage = q.message ?? ctx.quotedMessage;
     }
     if (input.forward) {
@@ -121,3 +131,6 @@ function hasAnyKey(value) {
     }
     return false;
 }
+function isSameChatJid(a, b) {
+    return toUserJid(a) === toUserJid(b);
+}

package/dist/esm/message/encode/media-payload.js

@@ -20,6 +20,24 @@ function buildPayload(mediaType, fields) {
         fileLength: fields.fileLength ? longToNumber(fields.fileLength) : undefined
     };
 }
+/**
+ * Extracts the downloadable media metadata from a message, unwrapping
+ * ephemeral / view-once / document-with-caption envelopes first.
+ *
+ * Returns `null` when `message` is absent, carries no media, or the media node
+ * lacks the `directPath` / `mediaKey` needed to fetch and decrypt the blob (a
+ * non-`Uint8Array` `mediaKey` also yields `null`). Supported kinds: image,
+ * video (gif when `gifPlayback`), audio (ptt when `ptt`), document, sticker,
+ * ptv.
+ *
+ * @example
+ * ```ts
+ * const payload = resolveMediaPayload(event.message)
+ * if (payload) {
+ *     // payload.directPath, payload.mediaKey, payload.fileEncSha256, ...
+ * }
+ * ```
+ */
 export function resolveMediaPayload(message) {
     if (!message)
         return null;

package/dist/esm/mex.js

@@ -1 +1 @@
-export { WA_MEX_PERSIST_IDS, WA_MEX_OPERATION_SCHEMAS } from '../spec/mex';
+export { WA_MEX_PERSIST_IDS, WA_MEX_OPERATION_SCHEMAS } from '../../spec/mex/index.js';

package/dist/esm/protocol/message.js

@@ -23,7 +23,8 @@ export const WA_MESSAGE_TYPES = Object.freeze({
     RECEIPT_TYPE_PEER: 'peer_msg',
     RECEIPT_TYPE_SERVER_ERROR: 'server-error',
     RECEIPT_TYPE_RETRY: 'retry',
-    RECEIPT_TYPE_ENC_REKEY_RETRY: 'enc_rekey_retry'
+    RECEIPT_TYPE_ENC_REKEY_RETRY: 'enc_rekey_retry',
+    RECEIPT_TYPE_VIEW: 'view'
 });
 export const WA_RETRYABLE_ACK_CODES = Object.freeze(['408', '429', '500', '503']);
 export const WA_STANZA_MSG_TYPES = Object.freeze({

package/dist/esm/version-spec.js

@@ -1 +1 @@
-export { WA_VERSION } from '../spec/version';
+export { WA_VERSION } from '../../spec/version/index.js';

package/dist/{types/index.d.ts → index.d.ts}

@@ -6,7 +6,8 @@ export type { WaAppStateMutationCoordinator, WaBroadcastListParticipant, WaSetBr
 export type { WaBotCoordinator, WaBotInfo, WaBotPosingAsProfessional, WaBotProfileCommand, WaBotProfilePrompt, WaBotProfileResult, WaBotPromptOptions, WaGetBotProfileOptions } from './client/coordinators/WaBotCoordinator';
 export type { WaBroadcastListCoordinator, WaSendBroadcastListMessageInput } from './client/coordinators/WaBroadcastListCoordinator';
 export type { WaBusinessCoordinator, WaVerifiedNameBatchEntry } from './client/coordinators/WaBusinessCoordinator';
-export type { WaUploadMediaSource } from './client/media';
+export { downloadMediaMessage } from './client/media';
+export type { WaDownloadMediaMessageOptions, WaUploadMediaSource } from './client/media';
 export type { WaEditBusinessProfileInput } from './transport/node/builders/business';
 export type { WaEmailCoordinator, WaEmailStatus, WaEmailVerifyCodeResult } from './client/coordinators/WaEmailCoordinator';
 export type { WaCommunityCreateOptions, WaCommunitySubGroup, WaCommunitySubGroupResult, WaCommunitySubGroupsResult, WaGroupCoordinator, WaGroupCreateOptions, WaGroupMetadata, WaGroupParticipant, WaLinkSubGroupsResult, WaMembershipRequest, WaUnlinkSubGroupsResult } from './client/coordinators/WaGroupCoordinator';
@@ -19,6 +20,8 @@ export type { WaUsyncProtocolError, WaUsyncResultEnvelope } from './transport/no
 export type { WaSendStatusInput, WaStatusCoordinator } from './client/coordinators/WaStatusCoordinator';
 export type { WaEncryptedMessageInput, WaMessageAckMetadata, WaMessageKey, WaMessagePublishOptions, WaMessagePublishResult, WaMessageRef, WaMessageTargetInput, WaSendEditKey, WaSendEventLocation, WaSendEventMessage, WaSendEventParent, WaSendEventResponseMessage, WaSendEventResponseType, WaSendKeepMessage, WaSendMediaMessage, WaSendMessageContent, WaSendPinMessage, WaSendPollMessage, WaSendPollOptionInput, WaSendPollParent, WaSendPollVoteMessage, WaSendReactionMessage, WaSendReceiptEventOptions, WaSendReceiptInput, WaSendReceiptOptions, WaSendRevokeMessage, WaSendStickerPackMessage, WaSendStickerPackStickerInput, WaSendStickerPackTrayIcon, WaSendTextMessage } from './message/types';
 export { getContentType, resolveMessageTarget } from './message/encode/content';
+export { resolveMediaPayload } from './message/encode/media-payload';
+export type { WaResolvedMediaPayload } from './message/encode/media-payload';
 export type { WaSendContextInfo } from './message/context-info';
 export type { WaLinkPreviewFetcher, WaLinkPreviewOptions, WaLinkPreviewOverride, WaLinkPreviewResolved, WaLinkPreviewThumbnailBytes, WaLinkPreviewThumbnailInput, WaLinkPreviewThumbnailStream, WaLinkPreviewType } from './message/addons/link-preview/types';
 export type { SignalLidSyncResult } from './signal/api/SignalDeviceSyncApi';

package/dist/index.js

@@ -1,14 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WA_DIRTY_PROTOCOLS = exports.WA_DEFAULTS = exports.WA_COMPANION_PLATFORM_IDS = exports.WA_BUSINESS_HOURS_MODES = exports.WA_BUSINESS_HOURS_DAYS = exports.WA_BROWSERS = exports.WA_APP_STATE_SYNC_DATA_TYPE = exports.WA_APP_STATE_KEY_TYPES = exports.WA_APP_STATE_KDF_INFO = exports.WA_APP_STATE_ERROR_CODES = exports.WA_APP_STATE_COLLECTION_STATES = exports.WA_APP_STATE_COLLECTIONS = exports.WA_ACCOUNT_SYNC_PROTOCOLS = exports.toUserJid = exports.splitJid = exports.signalAddressKey = exports.parseSignalAddressFromJid = exports.parsePhoneJid = exports.parseJidFull = exports.normalizeRecipientJid = exports.normalizeDeviceJid = exports.isUserJid = exports.isStatusBroadcastJid = exports.isNewsletterJid = exports.isLidJid = exports.isHostedServer = exports.isHostedDeviceJid = exports.isHostedDeviceId = exports.isGroupOrBroadcastJid = exports.isGroupJid = exports.isBroadcastJid = exports.isBotJid = exports.getWaMediaHkdfInfo = exports.getWaCompanionPlatformId = exports.getLoginIdentity = exports.canonicalizeSignalServer = exports.canonicalizeSignalJid = exports.buildDeviceJid = exports.delay = exports.WaAuthMemoryStore = exports.createStore = exports.createNoopLogger = exports.createPinoLogger = exports.PinoLogger = exports.ConsoleLogger = exports.fetchLatestWaWebVersion = exports.resolveMessageTarget = exports.getContentType = exports.parseUsyncResultEnvelope = exports.WaClient = void 0;
-exports.proto = exports.WA_XMLNS = exports.WA_PRIVACY_VALUES = exports.WA_PRIVACY_TAGS = exports.WA_PRIVACY_SETTING_TO_CATEGORY = exports.WA_PRIVACY_DISALLOWED_LIST_CATEGORIES = exports.WA_PRIVACY_CATEGORY_TO_SETTING = exports.WA_PRIVACY_CATEGORIES = exports.WA_SUPPORTED_DIRTY_TYPES = exports.WA_STREAM_SIGNALING = exports.WA_SIGNALING = exports.WA_RETRYABLE_ACK_CODES = exports.WA_READY_STATES = exports.WA_PREVIEW_MEDIA_HKDF_INFO = exports.WA_PAIRING_KDF_INFO = exports.WA_NODE_TAGS = exports.WA_MEDIA_HKDF_INFO = exports.WA_MESSAGE_TYPES = exports.WA_MESSAGE_TAGS = exports.WA_LOGOUT_REASONS = exports.WA_IQ_TYPES = exports.WA_DISCONNECT_REASONS = exports.WA_DIRTY_TYPES = void 0;
+exports.WA_COMPANION_PLATFORM_IDS = exports.WA_BUSINESS_HOURS_MODES = exports.WA_BUSINESS_HOURS_DAYS = exports.WA_BROWSERS = exports.WA_APP_STATE_SYNC_DATA_TYPE = exports.WA_APP_STATE_KEY_TYPES = exports.WA_APP_STATE_KDF_INFO = exports.WA_APP_STATE_ERROR_CODES = exports.WA_APP_STATE_COLLECTION_STATES = exports.WA_APP_STATE_COLLECTIONS = exports.WA_ACCOUNT_SYNC_PROTOCOLS = exports.toUserJid = exports.splitJid = exports.signalAddressKey = exports.parseSignalAddressFromJid = exports.parsePhoneJid = exports.parseJidFull = exports.normalizeRecipientJid = exports.normalizeDeviceJid = exports.isUserJid = exports.isStatusBroadcastJid = exports.isNewsletterJid = exports.isLidJid = exports.isHostedServer = exports.isHostedDeviceJid = exports.isHostedDeviceId = exports.isGroupOrBroadcastJid = exports.isGroupJid = exports.isBroadcastJid = exports.isBotJid = exports.getWaMediaHkdfInfo = exports.getWaCompanionPlatformId = exports.getLoginIdentity = exports.canonicalizeSignalServer = exports.canonicalizeSignalJid = exports.buildDeviceJid = exports.delay = exports.WaAuthMemoryStore = exports.createStore = exports.createNoopLogger = exports.createPinoLogger = exports.PinoLogger = exports.ConsoleLogger = exports.fetchLatestWaWebVersion = exports.resolveMediaPayload = exports.resolveMessageTarget = exports.getContentType = exports.parseUsyncResultEnvelope = exports.downloadMediaMessage = exports.WaClient = void 0;
+exports.proto = exports.WA_XMLNS = exports.WA_PRIVACY_VALUES = exports.WA_PRIVACY_TAGS = exports.WA_PRIVACY_SETTING_TO_CATEGORY = exports.WA_PRIVACY_DISALLOWED_LIST_CATEGORIES = exports.WA_PRIVACY_CATEGORY_TO_SETTING = exports.WA_PRIVACY_CATEGORIES = exports.WA_SUPPORTED_DIRTY_TYPES = exports.WA_STREAM_SIGNALING = exports.WA_SIGNALING = exports.WA_RETRYABLE_ACK_CODES = exports.WA_READY_STATES = exports.WA_PREVIEW_MEDIA_HKDF_INFO = exports.WA_PAIRING_KDF_INFO = exports.WA_NODE_TAGS = exports.WA_MEDIA_HKDF_INFO = exports.WA_MESSAGE_TYPES = exports.WA_MESSAGE_TAGS = exports.WA_LOGOUT_REASONS = exports.WA_IQ_TYPES = exports.WA_DISCONNECT_REASONS = exports.WA_DIRTY_TYPES = exports.WA_DIRTY_PROTOCOLS = exports.WA_DEFAULTS = void 0;
 var _client_1 = require("./client");
 Object.defineProperty(exports, "WaClient", { enumerable: true, get: function () { return _client_1.WaClient; } });
+var media_1 = require("./client/media");
+Object.defineProperty(exports, "downloadMediaMessage", { enumerable: true, get: function () { return media_1.downloadMediaMessage; } });
 var usync_1 = require("./transport/node/builders/usync");
 Object.defineProperty(exports, "parseUsyncResultEnvelope", { enumerable: true, get: function () { return usync_1.parseUsyncResultEnvelope; } });
 var content_1 = require("./message/encode/content");
 Object.defineProperty(exports, "getContentType", { enumerable: true, get: function () { return content_1.getContentType; } });
 Object.defineProperty(exports, "resolveMessageTarget", { enumerable: true, get: function () { return content_1.resolveMessageTarget; } });
+var media_payload_1 = require("./message/encode/media-payload");
+Object.defineProperty(exports, "resolveMediaPayload", { enumerable: true, get: function () { return media_payload_1.resolveMediaPayload; } });
 var wa_web_version_fetcher_1 = require("./transport/wa-web-version-fetcher");
 Object.defineProperty(exports, "fetchLatestWaWebVersion", { enumerable: true, get: function () { return wa_web_version_fetcher_1.fetchLatestWaWebVersion; } });
 var ConsoleLogger_1 = require("./infra/log/ConsoleLogger");