zapo-js 1.0.0 → 1.1.0

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) {
@@ -76,8 +80,8 @@ function parseWebpAnimation(data) {
     }
     return null;
 }
-const IMAGE_THUMB_MAX_EDGE = 320;
-const VIDEO_THUMB_MAX_EDGE = 48;
+const IMAGE_THUMB_MAX_EDGE = 100;
+const VIDEO_THUMB_MAX_EDGE = 100;
 const STICKER_THUMB_MAX_EDGE = 100;
 const EMPTY_PROCESSED = {};
 function isReadableStream(value) {
@@ -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/client/messaging/group-metadata.js

@@ -7,6 +7,7 @@ const primitives_1 = require("../../util/primitives");
 function createGroupMetadataCache(options) {
     const { groupMetadataStore, queryGroupMetadata, logger } = options;
     const dedup = new PromiseDedup_1.PromiseDedup();
+    const pendingMutations = new Map();
     const sanitizeParticipantUsers = (participants) => {
         const deduped = new Set();
         for (const participant of participants) {
@@ -109,14 +110,9 @@ function createGroupMetadataCache(options) {
     const extractParticipantUsersFromGroupEvent = (event) => {
         const candidates = [];
         for (const participant of event.participants ?? []) {
-            if (participant.jid) {
-                candidates.push(participant.jid);
-            }
-            if (participant.lidJid) {
-                candidates.push(participant.lidJid);
-            }
-            if (participant.phoneJid) {
-                candidates.push(participant.phoneJid);
+            const canonical = participant.jid ?? participant.lidJid ?? participant.phoneJid;
+            if (canonical) {
+                candidates.push(canonical);
             }
         }
         return sanitizeParticipantUsers(candidates);
@@ -133,6 +129,7 @@ function createGroupMetadataCache(options) {
         return participants;
     });
     const resolveParticipantUsers = (groupJid) => dedup.run(`resolve:${groupJid}`, async () => {
+        await pendingMutations.get(groupJid)?.catch(() => undefined);
         const cached = await groupMetadataStore.getGroupMetadata(groupJid);
         if (cached && cached.participants.length > 0) {
             return sanitizeParticipantUsers(cached.participants);
@@ -152,7 +149,7 @@ function createGroupMetadataCache(options) {
         const refreshed = await groupMetadataStore.getGroupMetadata(groupJid);
         return refreshed?.ephemeral ?? null;
     };
-    const mutateFromGroupEvent = async (event) => {
+    const applyGroupEvent = async (event) => {
         const groupJid = resolveGroupJidForGroupCacheEvent(event);
         if (!groupJid) {
             return;
@@ -221,6 +218,20 @@ function createGroupMetadataCache(options) {
             await replaceParticipantUsersInCache(groupJid, cachedWithSanitized, authorUsers, participantUsers);
         }
     };
+    const mutateFromGroupEvent = (event) => {
+        const groupJid = resolveGroupJidForGroupCacheEvent(event);
+        if (!groupJid) {
+            return applyGroupEvent(event);
+        }
+        const prev = pendingMutations.get(groupJid) ?? Promise.resolve();
+        const next = prev.then(() => applyGroupEvent(event), () => applyGroupEvent(event));
+        pendingMutations.set(groupJid, next);
+        return next.finally(() => {
+            if (pendingMutations.get(groupJid) === next) {
+                pendingMutations.delete(groupJid);
+            }
+        });
+    };
     return {
         resolveParticipantUsers,
         refreshParticipantUsers,

package/dist/{types/client → client}/messaging/key-protocol.d.ts

@@ -3,7 +3,7 @@ import type { WaAuthCredentials } from '../../auth/types';
 import type { DeviceFanoutResolver } from '../messaging/fanout';
 import type { Logger } from '../../infra/log/types';
 import type { WaMessagePublishResult } from '../../message/types';
-import { type Proto } from '../..';
+import { type Proto } from '../../proto';
 export type PublishProtocolMessageToDeviceFn = (deviceJid: string, protocolMessage: Proto.Message.IProtocolMessage, options?: {
     readonly id?: string;
     readonly pushPriority?: 'high' | 'high_force';

package/dist/client/messaging/key-protocol.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createAppStateSyncKeyProtocol = createAppStateSyncKeyProtocol;
-const _proto_1 = require("../../proto.js");
+const _proto_1 = require("../../proto");
 const jid_1 = require("../../protocol/jid");
 const bytes_1 = require("../../util/bytes");
 function createAppStateSyncKeyProtocol(options) {

package/dist/client/messaging/link-preview.js

@@ -6,7 +6,7 @@ const media_1 = require("../media");
 const constants_1 = require("../../media/constants");
 const WaMediaCrypto_1 = require("../../media/crypto/WaMediaCrypto");
 const detect_1 = require("../../message/addons/link-preview/detect");
-const _proto_1 = require("../../proto.js");
+const _proto_1 = require("../../proto");
 const primitives_1 = require("../../util/primitives");
 const INLINE_THUMBNAIL_MAX_BYTES = 64 * 1024;
 async function resolveLinkPreview(text, perMessage, deps) {

package/dist/client/messaging/messages.js

@@ -5,7 +5,7 @@ exports.getMediaConn = getMediaConn;
 const node_fs_1 = require("node:fs");
 const node_stream_1 = require("node:stream");
 const media_1 = require("../media");
-const _crypto_1 = require("../../crypto/index.js");
+const _crypto_1 = require("../../crypto");
 const constants_1 = require("../../media/constants");
 const WaMediaCrypto_1 = require("../../media/crypto/WaMediaCrypto");
 const sticker_pack_1 = require("../../media/sticker/sticker-pack");
@@ -15,7 +15,7 @@ const addon_crypto_1 = require("../../message/crypto/addon-crypto");
 const use_case_secret_1 = require("../../message/crypto/use-case-secret");
 const content_1 = require("../../message/encode/content");
 const sticker_pack_2 = require("../../message/kinds/sticker-pack");
-const _proto_1 = require("../../proto.js");
+const _proto_1 = require("../../proto");
 const constants_2 = require("../../protocol/constants");
 const jid_1 = require("../../protocol/jid");
 const media_2 = require("../../transport/node/builders/media");

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

@@ -1,6 +1,6 @@
 import { type WaNewsletterMexDeps } from '../newsletter/mex';
 import type { WaNewsletterAdminInfo, WaNewsletterAdminInviteInput, WaNewsletterAdminInviteResult, WaNewsletterCapability, WaNewsletterCapabilityExposure, WaNewsletterCreateInput, WaNewsletterFollowersOptions, WaNewsletterFollowersPage, WaNewsletterInsightMetricRequest, WaNewsletterMetadata, WaNewsletterPollVoter, WaNewsletterReactionSenders, WaNewsletterUpdateInput } from '../newsletter/types';
-import type { WaMexOperationResponses } from '../..';
+import type { WaMexOperationResponses } from '../../mex';
 import { type WaTosQueryResult } from '../../transport/node/builders/tos';
 /** Admin-side newsletter operations (create/update/delete + insights). */
 export interface WaNewsletterAdminOps {

package/dist/client/newsletter/content.js

@@ -8,7 +8,7 @@ const sticker_pack_1 = require("../../media/sticker/sticker-pack");
 const context_info_1 = require("../../message/context-info");
 const content_1 = require("../../message/encode/content");
 const sticker_pack_2 = require("../../message/kinds/sticker-pack");
-const _proto_1 = require("../../proto.js");
+const _proto_1 = require("../../proto");
 const message_1 = require("../../protocol/message");
 const bytes_1 = require("../../util/bytes");
 async function uploadNewsletterMedia(options, input) {

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

@@ -1,5 +1,5 @@
 import type { Logger } from '../../infra/log/types';
-import type { WaMexOperationResponses, WaMexOperationVariables } from '../..';
+import type { WaMexOperationResponses, WaMexOperationVariables } from '../../mex';
 import type { AbPropName } from '../../protocol/abprops';
 import { type WaMexOpKey, type WaMexQuerySocket } from '../../transport/node/mex/client';
 import type { BinaryNode } from '../../transport/types';

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

@@ -1,5 +1,5 @@
 import type { WaNewsletterAdminInfo, WaNewsletterAdminInviteResult, WaNewsletterCapability, WaNewsletterDehydratedMetadata, WaNewsletterDirectoryCategoryPreview, WaNewsletterDirectoryResults, WaNewsletterFollowersPage, WaNewsletterMetadata, WaNewsletterPollVoter, WaNewsletterReactionSenders } from '../newsletter/types';
-import type { WaMexOperationResponses } from '../..';
+import type { WaMexOperationResponses } from '../../mex';
 type WaNewsletterMetadataEnvelope = NonNullable<WaMexOperationResponses['FetchNewsletter']['xwa2_newsletter']>;
 export declare function parseNewsletterMetadata(envelope: WaNewsletterMetadataEnvelope | null | undefined): WaNewsletterMetadata;
 export declare function parseAdminInfo(data: WaMexOperationResponses['FetchNewsletterAdminInfo'] | null): WaNewsletterAdminInfo;

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

@@ -1,6 +1,6 @@
 import type { WaSendContextInfo } from '../../message/context-info';
 import type { WaMessagePublishResult } from '../../message/types';
-import type { WaMexOperationResponses } from '../..';
+import type { WaMexOperationResponses } from '../../mex';
 import type { WA_NEWSLETTER_VIEW_ROLES, WaNewsletterRole, WaNewsletterStateType } from '../../protocol/newsletter';
 export type WaNewsletterCapability = NonNullable<NonNullable<WaMexOperationResponses['FetchNewsletterAdminCapabilities']['xwa2_newsletter_admin']>['capabilities']>[number];
 export interface WaNewsletterPicture {

package/dist/{types/client → client}/persistence/history-sync.d.ts

@@ -2,7 +2,7 @@ import type { WriteBehindPersistence } from '../persistence/WriteBehindPersisten
 import type { WaClientEventMap } from '../types';
 import type { Logger } from '../../infra/log/types';
 import type { WaMediaTransferClient } from '../../media/transfer/WaMediaTransferClient';
-import { type Proto } from '../..';
+import { type Proto } from '../../proto';
 interface WaHistorySyncDeps {
     readonly logger: Logger;
     readonly mediaTransfer: WaMediaTransferClient;

package/dist/client/persistence/history-sync.js

@@ -4,7 +4,7 @@ exports.runHistorySyncNotification = runHistorySyncNotification;
 exports.processHistorySyncNotification = processHistorySyncNotification;
 const node_util_1 = require("node:util");
 const node_zlib_1 = require("node:zlib");
-const _proto_1 = require("../../proto.js");
+const _proto_1 = require("../../proto");
 const jid_1 = require("../../protocol/jid");
 const bytes_1 = require("../../util/bytes");
 const primitives_1 = require("../../util/primitives");

package/dist/client/persistence/mailbox.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.persistIncomingMailboxEntities = persistIncomingMailboxEntities;
 const content_1 = require("../../message/encode/content");
-const _proto_1 = require("../../proto.js");
+const _proto_1 = require("../../proto");
 const jid_1 = require("../../protocol/jid");
 const primitives_1 = require("../../util/primitives");
 function pairLidPn(a, b) {

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

@@ -1,5 +1,5 @@
 import type { AppStateCollectionName } from '../appstate/types';
-import type { DataForKey, WaAppstateActionKey, WaAppstateIndexArgs } from '..';
+import type { DataForKey, WaAppstateActionKey, WaAppstateIndexArgs } from '../appstate-spec';
 import type { WaAuthClientOptions, WaAuthCredentials, WaAuthDangerousOptions, WaAuthSocketOptions } from '../auth/types';
 import type { WaCallGroupParticipant, WaCallType } from './events/call';
 import type { IncomingPresenceType, PresenceLastSeen } from './events/presence';
@@ -8,7 +8,7 @@ import type { WaLinkPreviewOptions } from '../message/addons/link-preview/types'
 import type { WaQuoteRef, WaSendContextInfo } from '../message/context-info';
 import type { WaDecodedAddon } from '../message/crypto/addon-crypto';
 import type { WaMessageKey, WaMessagePublishOptions, WaMessageRef, WaSendEditKey } from '../message/types';
-import type { Proto } from '..';
+import type { Proto } from '../proto';
 import type { WaBotMsgEditType } from '../protocol/bot';
 import type { WaBusinessHoursDay, WaBusinessHoursMode } from '../protocol/business';
 import type { WaConnectionCode, WaConnectionOpenReason, WaDisconnectReason } from '../protocol/stream';
@@ -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/WaClient.js

@@ -32,7 +32,7 @@ const SYNC_RELATED_PROTOCOL_TYPES = new Set([
  *
  * @example
  * ```ts
- * import { createPinoLogger, createStore, WaClient } from '../index.js'
+ * import { createPinoLogger, createStore, WaClient } from '..'
  * import { createSqliteStore } from '@zapo-js/store-sqlite'
  *
  * const store = createStore({

package/dist/esm/client/WaClientFactory.js

@@ -149,7 +149,8 @@ function createIncomingNodeRuntime(input) {
         emitRegistrationCode: (event) => emitEvent('mobile_registration_code', event),
         emitAccountTakeoverNotice: (event) => emitEvent('mobile_account_takeover_notice', event),
         emitGroupEvent: (event) => {
-            emitEvent('group', event);
+            // Register the cache mutation before emitting so a handler that
+            // sends synchronously sees the fresh participants, not the stale ones.
             void messageDispatch.mutateGroupMetadataCacheFromGroupEvent(event).catch((error) => {
                 logger.warn('failed to mutate group metadata cache from group event', {
                     action: event.action,
@@ -158,6 +159,7 @@ function createIncomingNodeRuntime(input) {
                     message: toError(error).message
                 });
             });
+            emitEvent('group', event);
         },
         emitBusinessEvent: (event) => emitEvent('business', event),
         emitPictureEvent: (event) => emitEvent('picture', event),

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/coordinators/WaStreamControlCoordinator.js

@@ -50,11 +50,10 @@ export function createStreamControlHandler(options) {
         const reason = WA_DISCONNECT_REASONS.STREAM_ERROR_FORCE_LOGIN;
         stopCommsImmediately();
         await runStreamControlLifecycle(reason, async () => {
-            logger.warn('received forced login stream error; starting login lifecycle', {
+            logger.warn('received forced login stream error; reconnecting, keeping credentials', {
                 code
             });
-            await disconnect(reason, true, code);
-            await clearStoredCredentials();
+            await disconnect(reason, false, code);
             await restartBackendAfterStreamControl(reason);
         });
     };

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) {
@@ -60,8 +63,8 @@ export function parseWebpAnimation(data) {
     }
     return null;
 }
-const IMAGE_THUMB_MAX_EDGE = 320;
-const VIDEO_THUMB_MAX_EDGE = 48;
+const IMAGE_THUMB_MAX_EDGE = 100;
+const VIDEO_THUMB_MAX_EDGE = 100;
 const STICKER_THUMB_MAX_EDGE = 100;
 const EMPTY_PROCESSED = {};
 export function isReadableStream(value) {
@@ -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/client/messaging/group-metadata.js

@@ -4,6 +4,7 @@ import { toError } from '../../util/primitives.js';
 export function createGroupMetadataCache(options) {
     const { groupMetadataStore, queryGroupMetadata, logger } = options;
     const dedup = new PromiseDedup();
+    const pendingMutations = new Map();
     const sanitizeParticipantUsers = (participants) => {
         const deduped = new Set();
         for (const participant of participants) {
@@ -106,14 +107,9 @@ export function createGroupMetadataCache(options) {
     const extractParticipantUsersFromGroupEvent = (event) => {
         const candidates = [];
         for (const participant of event.participants ?? []) {
-            if (participant.jid) {
-                candidates.push(participant.jid);
-            }
-            if (participant.lidJid) {
-                candidates.push(participant.lidJid);
-            }
-            if (participant.phoneJid) {
-                candidates.push(participant.phoneJid);
+            const canonical = participant.jid ?? participant.lidJid ?? participant.phoneJid;
+            if (canonical) {
+                candidates.push(canonical);
             }
         }
         return sanitizeParticipantUsers(candidates);
@@ -130,6 +126,7 @@ export function createGroupMetadataCache(options) {
         return participants;
     });
     const resolveParticipantUsers = (groupJid) => dedup.run(`resolve:${groupJid}`, async () => {
+        await pendingMutations.get(groupJid)?.catch(() => undefined);
         const cached = await groupMetadataStore.getGroupMetadata(groupJid);
         if (cached && cached.participants.length > 0) {
             return sanitizeParticipantUsers(cached.participants);
@@ -149,7 +146,7 @@ export function createGroupMetadataCache(options) {
         const refreshed = await groupMetadataStore.getGroupMetadata(groupJid);
         return refreshed?.ephemeral ?? null;
     };
-    const mutateFromGroupEvent = async (event) => {
+    const applyGroupEvent = async (event) => {
         const groupJid = resolveGroupJidForGroupCacheEvent(event);
         if (!groupJid) {
             return;
@@ -218,6 +215,20 @@ export function createGroupMetadataCache(options) {
             await replaceParticipantUsersInCache(groupJid, cachedWithSanitized, authorUsers, participantUsers);
         }
     };
+    const mutateFromGroupEvent = (event) => {
+        const groupJid = resolveGroupJidForGroupCacheEvent(event);
+        if (!groupJid) {
+            return applyGroupEvent(event);
+        }
+        const prev = pendingMutations.get(groupJid) ?? Promise.resolve();
+        const next = prev.then(() => applyGroupEvent(event), () => applyGroupEvent(event));
+        pendingMutations.set(groupJid, next);
+        return next.finally(() => {
+            if (pendingMutations.get(groupJid) === next) {
+                pendingMutations.delete(groupJid);
+            }
+        });
+    };
     return {
         resolveParticipantUsers,
         refreshParticipantUsers,

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';