zapo-js 0.2.0 → 1.0.0

package/dist/client/coordinators/WaIncomingNodeCoordinator.js

@@ -1,12 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WaIncomingNodeCoordinator = void 0;
-const incoming_1 = require("../incoming");
+const chatstate_1 = require("../events/chatstate");
+const incoming_1 = require("../events/incoming");
+const presence_1 = require("../events/presence");
 const constants_1 = require("../../protocol/constants");
 const helpers_1 = require("../../transport/node/helpers");
 const parse_1 = require("../../transport/stream/parse");
 const primitives_1 = require("../../util/primitives");
-const INFO_BULLETIN_NOTIFICATION_TYPES = new Set([
+const INFO_BULLETIN_CHILD_TAGS = new Set([
     'offline',
     'offline_preview',
     'priority_offline_complete',
@@ -14,11 +16,14 @@ const INFO_BULLETIN_NOTIFICATION_TYPES = new Set([
     'thread_metadata',
     'client_expiration'
 ]);
+const FILTER_PROTECTED_TAGS = new Set([constants_1.WA_NODE_TAGS.SUCCESS, 'failure']);
 class WaIncomingNodeCoordinator {
     constructor(options) {
         this.logger = options.logger;
         this.runtime = options.runtime;
+        this.offlineResume = options.offlineResume;
         this.nodeHandlerRegistry = new Map();
+        this.stanzaFilters = [];
         this.registerDefaultIncomingHandlers();
         this.mediaConnWarmupPromise = null;
     }
@@ -28,11 +33,17 @@ class WaIncomingNodeCoordinator {
             id: node.attrs.id,
             type: node.attrs.type
         });
+        if (node.attrs.offline !== undefined) {
+            this.offlineResume.trackOfflineStanza();
+        }
         const streamControlResult = (0, parse_1.parseStreamControlNode)(node);
         if (streamControlResult) {
             await this.runtime.handleStreamControlResult(streamControlResult);
             return;
         }
+        if (await this.applyStanzaFilters(node)) {
+            return;
+        }
         if (await this.handleSuccessNode(node)) {
             return;
         }
@@ -45,6 +56,46 @@ class WaIncomingNodeCoordinator {
         }
         this.runtime.emitUnhandledIncomingNode((0, incoming_1.createUnhandledIncomingNodeEvent)(node));
     }
+    registerIncomingStanzaFilter(filter) {
+        this.stanzaFilters.push(filter);
+        return () => {
+            const index = this.stanzaFilters.indexOf(filter);
+            if (index !== -1) {
+                this.stanzaFilters.splice(index, 1);
+            }
+        };
+    }
+    async applyStanzaFilters(node) {
+        if (this.stanzaFilters.length === 0 || FILTER_PROTECTED_TAGS.has(node.tag)) {
+            return false;
+        }
+        const filterLogger = this.logger.child({ tag: node.tag, id: node.attrs.id });
+        for (let i = 0; i < this.stanzaFilters.length; i += 1) {
+            let verdict;
+            try {
+                verdict = await this.stanzaFilters[i](node);
+            }
+            catch (error) {
+                filterLogger.warn('incoming stanza filter threw', {
+                    message: (0, primitives_1.toError)(error).message
+                });
+                continue;
+            }
+            if (!verdict) {
+                continue;
+            }
+            filterLogger.trace('incoming stanza dropped by filter', {
+                type: node.attrs.type,
+                from: node.attrs.from
+            });
+            const ack = (0, incoming_1.buildInboundAck)(node);
+            if (ack) {
+                await (0, incoming_1.sendSafeAck)(this.logger, this.runtime.sendNode, ack);
+            }
+            return true;
+        }
+        return false;
+    }
     registerIncomingHandler(registration) {
         const handlersByTag = this.nodeHandlerRegistry.get(registration.tag);
         const entry = {
@@ -119,7 +170,8 @@ class WaIncomingNodeCoordinator {
         return false;
     }
     isRetryReceiptType(type) {
-        return type === 'retry' || type === 'enc_rekey_retry';
+        return (type === constants_1.WA_MESSAGE_TYPES.RECEIPT_TYPE_RETRY ||
+            type === constants_1.WA_MESSAGE_TYPES.RECEIPT_TYPE_ENC_REKEY_RETRY);
     }
     registerDefaultIncomingHandlers() {
         const runtime = this.runtime;
@@ -147,12 +199,43 @@ class WaIncomingNodeCoordinator {
                 emitUnhandledStanza: runtime.emitUnhandledIncomingNode
             })
         });
+        this.registerIncomingHandler({
+            tag: constants_1.WA_NODE_TAGS.NOTIFICATION,
+            subtype: constants_1.WA_NOTIFICATION_TYPES.BUSINESS,
+            handler: (0, incoming_1.createIncomingBusinessNotificationHandler)({
+                logger: this.logger,
+                sendNode: runtime.sendNode,
+                emitBusinessEvent: runtime.emitBusinessEvent,
+                emitUnhandledStanza: runtime.emitUnhandledIncomingNode
+            })
+        });
+        this.registerIncomingHandler({
+            tag: constants_1.WA_NODE_TAGS.NOTIFICATION,
+            subtype: constants_1.WA_NOTIFICATION_TYPES.PICTURE,
+            handler: (0, incoming_1.createIncomingPictureNotificationHandler)({
+                logger: this.logger,
+                sendNode: runtime.sendNode,
+                emitPictureEvent: runtime.emitPictureEvent,
+                emitUnhandledStanza: runtime.emitUnhandledIncomingNode
+            })
+        });
+        this.registerIncomingHandler({
+            tag: constants_1.WA_NODE_TAGS.NOTIFICATION,
+            subtype: constants_1.WA_NOTIFICATION_TYPES.REGISTRATION,
+            handler: (0, incoming_1.createIncomingRegistrationNotificationHandler)({
+                logger: this.logger,
+                sendNode: runtime.sendNode,
+                emitRegistrationCode: runtime.emitRegistrationCode,
+                emitAccountTakeoverNotice: runtime.emitAccountTakeoverNotice
+            })
+        });
         this.registerIncomingHandler({
             tag: constants_1.WA_NODE_TAGS.NOTIFICATION,
             handler: (0, incoming_1.createIncomingNotificationHandler)({
                 logger: this.logger,
                 sendNode: runtime.sendNode,
                 emitIncomingNotification: runtime.emitIncomingNotification,
+                emitMexNotification: runtime.emitMexNotification,
                 emitUnhandledStanza: runtime.emitUnhandledIncomingNode,
                 syncAppState: runtime.syncAppState
             })
@@ -172,28 +255,39 @@ class WaIncomingNodeCoordinator {
             })
         });
         this.registerIncomingHandler({
-            tag: 'presence',
+            tag: constants_1.WA_NODE_TAGS.PRESENCE,
+            // eslint-disable-next-line @typescript-eslint/require-await
             handler: async (node) => {
-                runtime.emitIncomingPresence((0, incoming_1.createIncomingBaseEvent)(node));
+                runtime.emitIncomingPresence({
+                    ...(0, incoming_1.createIncomingBaseEvent)(node),
+                    ...(0, presence_1.parsePresenceNode)(node)
+                });
                 return true;
             }
         });
         this.registerIncomingHandler({
-            tag: 'chatstate',
+            tag: constants_1.WA_NODE_TAGS.CHATSTATE,
+            // eslint-disable-next-line @typescript-eslint/require-await
             handler: async (node) => {
+                const parsed = (0, chatstate_1.parseChatstateNode)(node);
+                if (!parsed) {
+                    return false;
+                }
                 runtime.emitIncomingChatstate({
                     ...(0, incoming_1.createIncomingBaseEvent)(node),
-                    participantJid: node.attrs.participant
+                    ...parsed
                 });
                 return true;
             }
         });
         this.registerIncomingHandler({
-            tag: 'call',
-            handler: async (node) => {
-                runtime.emitIncomingCall((0, incoming_1.createIncomingBaseEvent)(node));
-                return true;
-            }
+            tag: constants_1.WA_NODE_TAGS.CALL,
+            handler: (0, incoming_1.createIncomingCallHandler)({
+                logger: this.logger,
+                sendNode: runtime.sendNode,
+                emitIncomingCall: runtime.emitIncomingCall,
+                getCurrentCredentials: runtime.getCurrentCredentials
+            })
         });
         this.registerIncomingHandler({
             tag: 'failure',
@@ -207,8 +301,13 @@ class WaIncomingNodeCoordinator {
         });
         this.registerIncomingHandler({
             tag: constants_1.WA_NODE_TAGS.ERROR,
+            // eslint-disable-next-line @typescript-eslint/require-await
             handler: async (node) => {
-                runtime.emitIncomingErrorStanza((0, incoming_1.createIncomingBaseEvent)(node));
+                runtime.emitIncomingErrorStanza({
+                    ...(0, incoming_1.createIncomingBaseEvent)(node),
+                    code: (0, primitives_1.parseOptionalInt)(node.attrs.code),
+                    text: node.attrs.text
+                });
                 return true;
             }
         });
@@ -266,13 +365,24 @@ class WaIncomingNodeCoordinator {
             return false;
         }
         let handled = false;
-        const ibType = node.attrs.type;
-        if (ibType && INFO_BULLETIN_NOTIFICATION_TYPES.has(ibType)) {
-            this.runtime.emitIncomingNotification((0, incoming_1.createInfoBulletinNotificationEvent)(node, ibType, {
-                count: (0, primitives_1.parseOptionalInt)(node.attrs.count),
-                t: (0, primitives_1.parseOptionalInt)(node.attrs.t)
-            }));
-            handled = true;
+        const children = (0, helpers_1.getNodeChildren)(node);
+        for (const child of children) {
+            if (INFO_BULLETIN_CHILD_TAGS.has(child.tag)) {
+                this.runtime.emitIncomingNotification((0, incoming_1.createInfoBulletinNotificationEvent)(node, child.tag, {
+                    count: (0, primitives_1.parseOptionalInt)(child.attrs.count),
+                    message: (0, primitives_1.parseOptionalInt)(child.attrs.message),
+                    receipt: (0, primitives_1.parseOptionalInt)(child.attrs.receipt),
+                    notification: (0, primitives_1.parseOptionalInt)(child.attrs.notification),
+                    t: (0, primitives_1.parseOptionalInt)(child.attrs.t)
+                }));
+                if (child.tag === 'offline_preview') {
+                    this.offlineResume.handleOfflinePreview((0, primitives_1.parseOptionalInt)(child.attrs.count) ?? 0);
+                }
+                if (child.tag === 'offline') {
+                    this.offlineResume.handleOfflineComplete((0, primitives_1.parseOptionalInt)(child.attrs.count) ?? 0);
+                }
+                handled = true;
+            }
         }
         const edgeRoutingNode = (0, helpers_1.findNodeChild)(node, constants_1.WA_NODE_TAGS.EDGE_ROUTING);
         if (edgeRoutingNode) {

package/dist/client/coordinators/WaLowLevelCoordinator.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLowLevelCoordinator = createLowLevelCoordinator;
+const constants_1 = require("../../protocol/constants");
+const primitives_1 = require("../../util/primitives");
+/** Builds a {@link WaLowLevelCoordinator} from its transport dependencies. */
+function createLowLevelCoordinator(options) {
+    const { logger, nodeOrchestrator, incomingNode, receiptQueue, isConnected } = options;
+    const defaultIqTimeoutMs = options.defaultIqTimeoutMs ?? constants_1.WA_DEFAULTS.IQ_TIMEOUT_MS;
+    return {
+        sendNode: async (node) => {
+            try {
+                await nodeOrchestrator.sendNode(node);
+            }
+            catch (error) {
+                const normalized = (0, primitives_1.toError)(error);
+                if (receiptQueue.shouldQueue(node, normalized)) {
+                    receiptQueue.enqueue(node);
+                    logger.warn('queued dangling receipt after send failure', {
+                        id: node.attrs.id,
+                        to: node.attrs.to,
+                        message: normalized.message,
+                        queueSize: receiptQueue.size()
+                    });
+                    return;
+                }
+                throw normalized;
+            }
+        },
+        query: async (node, timeoutMs = defaultIqTimeoutMs, queryOptions = {}) => {
+            if (!isConnected()) {
+                throw new Error('client is not connected');
+            }
+            logger.debug('wa client query', { tag: node.tag, id: node.attrs.id, timeoutMs });
+            return nodeOrchestrator.query(node, timeoutMs, queryOptions);
+        },
+        registerIncomingHandler: (registration) => incomingNode.registerIncomingHandler(registration),
+        unregisterIncomingHandler: (registration) => incomingNode.unregisterIncomingHandler(registration),
+        registerIncomingStanzaFilter: (filter) => incomingNode.registerIncomingStanzaFilter(filter)
+    };
+}

package/dist/client/coordinators/WaMessageCoordinator.js

@@ -0,0 +1,365 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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 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.js");
+const jid_1 = require("../../protocol/jid");
+const client_1 = require("../../transport/node/mex/client");
+const bytes_1 = require("../../util/bytes");
+const coercion_1 = require("../../util/coercion");
+const primitives_1 = require("../../util/primitives");
+function parseReachoutTimelockMexResponse(data) {
+    const root = data?.xwa2_fetch_account_reachout_timelock;
+    return {
+        isActive: root?.is_active === true,
+        enforcementType: (0, coercion_1.tryAsString)(root?.enforcement_type),
+        enforcementEndsAt: (0, coercion_1.tryAsNumber)(root?.time_enforcement_ends)
+    };
+}
+function parseMessageCappingMexResponse(data) {
+    const root = data?.xwa2_message_capping_info;
+    return {
+        totalQuota: (0, coercion_1.tryAsNumber)(root?.total_quota),
+        usedQuota: (0, coercion_1.tryAsNumber)(root?.used_quota),
+        cycleStartAt: (0, coercion_1.tryAsNumber)(root?.cycle_start_timestamp),
+        cycleEndAt: (0, coercion_1.tryAsNumber)(root?.cycle_end_timestamp),
+        serverSentAt: (0, coercion_1.tryAsNumber)(root?.server_sent_timestamp),
+        oteStatus: (0, coercion_1.tryAsString)(root?.ote_status),
+        mvStatus: (0, coercion_1.tryAsString)(root?.mv_status),
+        cappingStatus: (0, coercion_1.tryAsString)(root?.capping_status)
+    };
+}
+/**
+ * Coordinates outbound message sending, receipts, addon decryption, media
+ * download, and the related MEX account queries. Accessed via
+ * {@link WaClient.message}.
+ */
+class WaMessageCoordinator {
+    constructor(deps) {
+        this.messageDispatch = deps.messageDispatch;
+        this.mediaTransfer = deps.mediaTransfer;
+        this.logger = deps.logger;
+        this.messageStore = deps.messageStore;
+        this.messageSecretStore = deps.messageSecretStore;
+        this.trustedContactToken = deps.trustedContactToken;
+        this.emitAddon = deps.emitAddon;
+        this.mexSocket = deps.mexSocket;
+        this.peerDataOperation = deps.peerDataOperation;
+    }
+    /**
+     * Asks the server to backfill older messages for `chatJid` beyond what
+     * arrived in the initial history-sync. Implemented as a
+     * `PeerDataOperationRequestMessage` (type `HISTORY_SYNC_ON_DEMAND`)
+     * sent to this account's own user JID; the response arrives later as
+     * a `history_sync_chunk` event the same way the bootstrap chunks do -
+     * subscribe before calling if you need to react to the chunk.
+     *
+     * The method returns once the request is dispatched (with the protocol
+     * message id), **not** when the chunk arrives. Pair `oldestMsgId` +
+     * `oldestMsgTimestampMs` + `oldestMsgFromMe` from the topmost message
+     * currently visible to page backwards correctly.
+     */
+    async requestHistorySync(input) {
+        const chatJid = (0, jid_1.normalizeRecipientJid)(input.chatJid);
+        if (input.count !== undefined) {
+            if (!Number.isFinite(input.count) ||
+                !Number.isSafeInteger(input.count) ||
+                input.count <= 0) {
+                throw new Error(`invalid count: ${input.count}`);
+            }
+        }
+        if (input.oldestMsgTimestampMs !== undefined) {
+            if (!Number.isFinite(input.oldestMsgTimestampMs) ||
+                !Number.isSafeInteger(input.oldestMsgTimestampMs) ||
+                input.oldestMsgTimestampMs < 0) {
+                throw new Error(`invalid oldestMsgTimestampMs: ${input.oldestMsgTimestampMs}`);
+            }
+        }
+        const historySyncOnDemandRequest = {
+            chatJid,
+            supportInlineResponse: true,
+            ...(input.oldestMsgId === undefined ? {} : { oldestMsgId: input.oldestMsgId }),
+            ...(input.oldestMsgFromMe === undefined
+                ? {}
+                : { oldestMsgFromMe: input.oldestMsgFromMe }),
+            ...(input.oldestMsgTimestampMs === undefined
+                ? {}
+                : { oldestMsgTimestampMs: input.oldestMsgTimestampMs }),
+            ...(input.count === undefined ? {} : { onDemandMsgCount: input.count })
+        };
+        return this.peerDataOperation.send(_proto_1.proto.Message.PeerDataOperationRequestType.HISTORY_SYNC_ON_DEMAND, { historySyncOnDemandRequest });
+    }
+    /**
+     * Fetches the server-side "reachout" timelock that throttles cold outreach
+     * to non-contacts, returning the active window when enforcement is on.
+     */
+    async getReachoutTimelock() {
+        const data = await (0, client_1.runMexQuery)(this.mexSocket, 'FetchReachoutTimelock', {});
+        return parseReachoutTimelockMexResponse(data);
+    }
+    /**
+     * Fetches the per-cycle message capping info applied to new-chat threads
+     * (quota, used, cycle boundaries, status flags).
+     */
+    async getNewChatMessageCapping(type = 'INDIVIDUAL_NEW_CHAT_THREAD') {
+        const data = await (0, client_1.runMexQuery)(this.mexSocket, 'FetchNewChatMessageCappingInfo', {
+            input: { type }
+        });
+        return parseMessageCappingMexResponse(data);
+    }
+    /**
+     * Force-refreshes the Signal session(s) for `jid`. Set `reasonIdentity` to
+     * `true` when the trigger was an identity change – this also queues a
+     * trusted-contact-token reissue.
+     */
+    async syncSignalSession(jid, reasonIdentity = false) {
+        await this.messageDispatch.syncSignalSession(jid, reasonIdentity);
+        if (reasonIdentity) {
+            this.trustedContactToken.reissueOnIdentityChange(jid).catch((err) => this.logger.warn('tc token reissue on identity change failed', {
+                jid,
+                message: (0, primitives_1.toError)(err).message
+            }));
+        }
+    }
+    /**
+     * Sends a message (any {@link WaSendMessageContent} kind – text, media,
+     * poll, reaction, edit, revoke, etc.) to `to` and returns the publish
+     * result containing the stanza id and ack metadata.
+     *
+     * `to` accepts any JID accepted by {@link normalizeRecipientJid}: bare
+     * digits (`'5511999999999'`), a phone JID (`'5511…@s.whatsapp.net'`),
+     * a group JID (`'…@g.us'`), or a LID. See the {@link WaSendMessageContent}
+     * union for the full kind list.
+     *
+     * **Gotchas:**
+     * - The stanza id is auto-generated unless you set `options.id`. Reusing
+     *   an id manually makes the send idempotent on the server but is also how
+     *   internal retries (`maxAttempts`) work – don't reuse ids across
+     *   logically distinct messages.
+     * - Sending to a `@newsletter` JID routes through a separate code path
+     *   that ignores most of `options` (no quote/forward/edit semantics).
+     * - Addon-crypto kinds (poll-vote, reaction, message-edit, ...) require an
+     *   authenticated session (`meJid` present) – throws otherwise.
+     * - Group sends fan out to every cached member device. If your
+     *   `groupMetadata` cache is empty/disabled, this triggers a metadata IQ
+     *   per send (rate-limited server-side, see {@link WaCreateStoreOptions}).
+     *
+     * @example
+     * ```ts
+     * // 1. Plain text (string shorthand)
+     * await client.message.send('5511999999999', 'hello!')
+     *
+     * // 2. Reply with mention
+     * await client.message.send(groupJid, {
+     *     type: 'text',
+     *     text: '@5511999999999 ping',
+     *     contextInfo: {
+     *         mentionedJid: ['5511999999999@s.whatsapp.net'],
+     *         quoted: { key: { remoteJid: groupJid, fromMe: false, id: incomingId } }
+     *     }
+     * })
+     *
+     * // 3. Image from a file path (the encoder opens + streams it for you)
+     * await client.message.send(jid, {
+     *     type: 'image',
+     *     media: '/tmp/photo.jpg',
+     *     mimetype: 'image/jpeg',
+     *     caption: 'check this out'
+     * })
+     *
+     * // 4. React to an incoming message (empty emoji = unreact)
+     * await client.message.send(event.key.remoteJid, {
+     *     type: 'reaction',
+     *     emoji: '👍',
+     *     target: event.key // or pass the whole event
+     * })
+     *
+     * // 5. Poll
+     * const result = await client.message.send(jid, {
+     *     type: 'poll',
+     *     name: 'lunch?',
+     *     options: ['pizza', 'sushi', 'burger'],
+     *     selectableCount: 1
+     * })
+     * console.log('sent as', result.id)
+     * ```
+     */
+    send(to, content, options = {}) {
+        return this.messageDispatch.sendMessage(to, content, options);
+    }
+    async sendReceipt(first, second, third) {
+        if (typeof first === 'string') {
+            const ids = second;
+            await this.dispatchReceipt(first, ids, third ?? {});
+            return;
+        }
+        const events = Array.isArray(first) ? first : [first];
+        const options = second ?? {};
+        const targets = events.map((event) => {
+            if (!event.key.remoteJid || !event.key.id) {
+                throw new Error('sendReceipt event is missing key.remoteJid or key.id');
+            }
+            const senderJid = event.key.participant ?? event.key.remoteJid;
+            return {
+                chatJid: event.key.remoteJid,
+                id: event.key.id,
+                senderJid: senderJid
+                    ? (0, jid_1.applyDeviceToJid)(senderJid, event.key.senderDevice)
+                    : undefined,
+                isGroupChat: event.key.isGroup,
+                isBroadcastChat: event.key.isBroadcast
+            };
+        });
+        for (const group of (0, receipt_1.aggregateReceiptTargets)(targets)) {
+            await this.dispatchReceipt(group.jid, group.ids, {
+                ...options,
+                participant: group.participant
+            });
+        }
+    }
+    /**
+     * Resolves the media payload inside `source` and returns a `Readable`
+     * stream of the decrypted bytes. Throws when the message has no
+     * downloadable media.
+     *
+     * **Caller owns the stream** - pipe it somewhere or call `.destroy()` to
+     * release the underlying socket; an unconsumed stream leaks the connection.
+     * MAC + SHA-256 verification runs **as bytes are consumed**, so if you
+     * abort mid-read you've consumed unverified bytes. Pass `options.signal`
+     * to cancel cleanly, or use {@link downloadBytes} / {@link downloadToFile}
+     * 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;
+    }
+    /**
+     * Convenience wrapper around {@link download} that streams the decrypted
+     * media directly to `filePath`. On failure the **partial file is not
+     * cleaned up** - delete it yourself in the error handler if you don't
+     * want to leak corrupted artifacts.
+     */
+    async downloadToFile(source, filePath, options = {}) {
+        const stream = await this.download(source, options);
+        await (0, promises_1.pipeline)(stream, (0, node_fs_1.createWriteStream)(filePath));
+    }
+    /**
+     * Convenience wrapper around {@link download} that buffers the decrypted
+     * media into a single `Uint8Array`. Use only for small media – caps via
+     * `options.maxBytes`.
+     */
+    async downloadBytes(source, options = {}) {
+        const stream = await this.download(source, options);
+        return (0, bytes_1.readAllBytes)(stream, { maxBytes: options.maxBytes });
+    }
+    /**
+     * Attempts to decrypt an addon payload (poll vote, reaction, edit, ...)
+     * attached to `event` and, on success, emits a typed
+     * `WaIncomingAddonEvent`. Silently returns when the parent message
+     * secret is missing or the payload is not an addon.
+     *
+     * Called automatically by the client unless `options.addons.autoDecrypt`
+     * is explicitly `false` - you rarely need to invoke it directly. The
+     * parent secret is looked up in the in-memory `messageSecret` cache
+     * first, then in the `messages` store. If both are `'none'`/missing,
+     * decryption fails and the event never fires; failures are logged at
+     * `warn` for `secretEncryptedMessage` addons (whose parent can be
+     * any message type, so the secret is only available when the
+     * `messages` mailbox is active) and at `debug` for the dedicated
+     * addon types (reactions, poll votes, event responses, comments)
+     * whose parent always carries a persisted secret or is itself
+     * short-lived.
+     */
+    async tryDecryptAddon(event) {
+        const message = event.message;
+        if (!message)
+            return;
+        const addon = (0, addon_crypto_1.identifyEncryptedAddon)(message);
+        if (!addon)
+            return;
+        const targetMessageId = addon.targetMessageKey.id;
+        if (!targetMessageId)
+            return;
+        const parentEntry = await (0, addon_crypto_1.resolveParentMessageSecret)(targetMessageId, this.messageSecretStore, this.messageStore);
+        if (!parentEntry) {
+            const logCtx = {
+                id: event.key.id,
+                targetId: targetMessageId,
+                kind: addon.kind
+            };
+            if ((0, content_1.unwrapMessage)(message).secretEncryptedMessage) {
+                this.logger.warn('addon parent message secret not found - enable the `messages` mailbox to support decryption of secretEncryptedMessage addons on arbitrary parents', logCtx);
+            }
+            else {
+                this.logger.debug('addon parent message secret not found', logCtx);
+            }
+            return;
+        }
+        const parentMsgOriginalSender = parentEntry.senderJid;
+        const modificationSender = event.key.participant ?? event.key.remoteJid;
+        const plaintext = await (0, addon_crypto_1.decryptAddonPayload)({
+            messageSecret: parentEntry.secret,
+            stanzaId: targetMessageId,
+            parentMsgOriginalSender,
+            modificationSender,
+            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
+        });
+        let decrypted = (0, addon_crypto_1.decodeAddonPlaintext)(addon.kind, plaintext);
+        if (decrypted.kind === 'poll_vote' && decrypted.pollVote.selectedOptions) {
+            const names = await (0, addon_crypto_1.resolvePollOptionNames)(decrypted.pollVote.selectedOptions, targetMessageId, this.messageStore);
+            if (names) {
+                decrypted = { ...decrypted, selectedOptionNames: names };
+            }
+        }
+        this.emitAddon({
+            rawNode: event.rawNode,
+            key: event.key,
+            stanzaType: event.stanzaType,
+            offline: event.offline,
+            kind: addon.kind,
+            targetMessageId,
+            decrypted,
+            raw: message
+        });
+    }
+    dispatchReceipt(jid, ids, options) {
+        const idArray = typeof ids === 'string' ? [ids] : ids;
+        if (idArray.length === 0) {
+            throw new Error('sendReceipt requires at least one message id');
+        }
+        const [id, ...rest] = idArray;
+        const input = {
+            ...options,
+            to: jid,
+            id,
+            listIds: rest.length > 0 ? rest : undefined
+        };
+        return this.messageDispatch.sendReceipt(input);
+    }
+}
+exports.WaMessageCoordinator = WaMessageCoordinator;