zapo-js 0.2.0 → 1.0.0

package/dist/esm/media/sticker/sticker-pack.js

@@ -0,0 +1,133 @@
+import { readFile } from 'node:fs/promises';
+import { Readable } from 'node:stream';
+import { TEXT_ENCODER } from '../../util/bytes.js';
+const SIGNATURE_LOCAL_FILE = 0x04034b50;
+const SIGNATURE_CENTRAL_DIR = 0x02014b50;
+const SIGNATURE_END_OF_CENTRAL_DIR = 0x06054b50;
+const COMPRESSION_STORED = 0;
+const VERSION_NEEDED = 20;
+const LOCAL_HEADER_SIZE = 30;
+const CENTRAL_HEADER_SIZE = 46;
+const EOCD_SIZE = 22;
+const CRC32_TABLE = (() => {
+    const table = new Array(256);
+    for (let i = 0; i < 256; i += 1) {
+        let c = i;
+        for (let k = 0; k < 8; k += 1) {
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        }
+        table[i] = c >>> 0;
+    }
+    return table;
+})();
+function crc32(bytes) {
+    let crc = 0xffffffff;
+    for (let i = 0; i < bytes.byteLength; i += 1) {
+        crc = CRC32_TABLE[(crc ^ bytes[i]) & 0xff] ^ (crc >>> 8);
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+function validateEntries(entries) {
+    if (entries.length === 0) {
+        throw new Error('sticker pack zip requires at least one entry');
+    }
+    const seen = new Set();
+    for (const entry of entries) {
+        if (!entry.fileName) {
+            throw new Error('sticker pack zip entry requires a non-empty fileName');
+        }
+        if (seen.has(entry.fileName)) {
+            throw new Error(`sticker pack zip has duplicate fileName: ${entry.fileName}`);
+        }
+        seen.add(entry.fileName);
+    }
+}
+async function loadEntryBytes(source) {
+    if (typeof source === 'string') {
+        const buf = await readFile(source);
+        return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+    }
+    return source;
+}
+function buildLocalHeader(name, crc, dataLength) {
+    const out = new Uint8Array(LOCAL_HEADER_SIZE + name.byteLength);
+    const view = new DataView(out.buffer, out.byteOffset, out.byteLength);
+    view.setUint32(0, SIGNATURE_LOCAL_FILE, true);
+    view.setUint16(4, VERSION_NEEDED, true);
+    view.setUint16(6, 0, true);
+    view.setUint16(8, COMPRESSION_STORED, true);
+    view.setUint16(10, 0, true);
+    view.setUint16(12, 0, true);
+    view.setUint32(14, crc, true);
+    view.setUint32(18, dataLength, true);
+    view.setUint32(22, dataLength, true);
+    view.setUint16(26, name.byteLength, true);
+    view.setUint16(28, 0, true);
+    out.set(name, LOCAL_HEADER_SIZE);
+    return out;
+}
+function buildCentralDirectory(entries) {
+    let totalSize = 0;
+    for (const entry of entries)
+        totalSize += CENTRAL_HEADER_SIZE + entry.name.byteLength;
+    const out = new Uint8Array(totalSize);
+    const view = new DataView(out.buffer, out.byteOffset, out.byteLength);
+    let offset = 0;
+    for (const entry of entries) {
+        view.setUint32(offset, SIGNATURE_CENTRAL_DIR, true);
+        view.setUint16(offset + 4, VERSION_NEEDED, true);
+        view.setUint16(offset + 6, VERSION_NEEDED, true);
+        view.setUint16(offset + 8, 0, true);
+        view.setUint16(offset + 10, COMPRESSION_STORED, true);
+        view.setUint16(offset + 12, 0, true);
+        view.setUint16(offset + 14, 0, true);
+        view.setUint32(offset + 16, entry.crc, true);
+        view.setUint32(offset + 20, entry.dataLength, true);
+        view.setUint32(offset + 24, entry.dataLength, true);
+        view.setUint16(offset + 28, entry.name.byteLength, true);
+        view.setUint16(offset + 30, 0, true);
+        view.setUint16(offset + 32, 0, true);
+        view.setUint16(offset + 34, 0, true);
+        view.setUint16(offset + 36, 0, true);
+        view.setUint32(offset + 38, 0, true);
+        view.setUint32(offset + 42, entry.localOffset, true);
+        offset += CENTRAL_HEADER_SIZE;
+        out.set(entry.name, offset);
+        offset += entry.name.byteLength;
+    }
+    return out;
+}
+function buildEocd(entryCount, centralDirSize, centralDirOffset) {
+    const out = new Uint8Array(EOCD_SIZE);
+    const view = new DataView(out.buffer, out.byteOffset, out.byteLength);
+    view.setUint32(0, SIGNATURE_END_OF_CENTRAL_DIR, true);
+    view.setUint16(4, 0, true);
+    view.setUint16(6, 0, true);
+    view.setUint16(8, entryCount, true);
+    view.setUint16(10, entryCount, true);
+    view.setUint32(12, centralDirSize, true);
+    view.setUint32(16, centralDirOffset, true);
+    view.setUint16(20, 0, true);
+    return out;
+}
+export function createStickerPackZipStream(entries) {
+    validateEntries(entries);
+    return Readable.from(zipChunks(entries));
+}
+async function* zipChunks(entries) {
+    const central = [];
+    let offset = 0;
+    for (const entry of entries) {
+        const data = await loadEntryBytes(entry.source);
+        const name = TEXT_ENCODER.encode(entry.fileName);
+        const crc = crc32(data);
+        const header = buildLocalHeader(name, crc, data.byteLength);
+        yield header;
+        yield data;
+        central.push({ name, crc, dataLength: data.byteLength, localOffset: offset });
+        offset += header.byteLength + data.byteLength;
+    }
+    const centralDir = buildCentralDirectory(central);
+    yield centralDir;
+    yield buildEocd(central.length, centralDir.byteLength, offset);
+}

package/dist/esm/media/{WaMediaTransferClient.js → transfer/WaMediaTransferClient.js}

@@ -1,10 +1,10 @@
-import { Readable } from 'node:stream';
-import { DEFAULT_MEDIA_HOSTS } from './constants.js';
-import { WaMediaCrypto } from './WaMediaCrypto.js';
-import { WA_DEFAULTS } from '../protocol/constants.js';
-import { EMPTY_BYTES, readAllBytes } from '../util/bytes.js';
-import { toError } from '../util/primitives.js';
-const GOT_OPTIONAL_MODULE = 'got';
+import http from 'node:http';
+import https from 'node:https';
+import { DEFAULT_MEDIA_HOSTS } from '../constants.js';
+import { WaMediaCrypto } from '../crypto/WaMediaCrypto.js';
+import { WA_DEFAULTS } from '../../protocol/constants.js';
+import { EMPTY_BYTES, readAllBytes } from '../../util/bytes.js';
+import { toError } from '../../util/primitives.js';
 function normalizeHeaderRecord(headers) {
     if (!headers) {
         return {};
@@ -15,56 +15,11 @@ function normalizeHeaderRecord(headers) {
     }
     return normalized;
 }
-function asOptionalGotModule(loaded) {
-    if (loaded && typeof loaded === 'object') {
-        const direct = loaded.stream;
-        if (typeof direct === 'function') {
-            return loaded;
-        }
-        const fallback = loaded.default;
-        if (fallback &&
-            typeof fallback === 'object' &&
-            'stream' in fallback &&
-            typeof fallback.stream === 'function') {
-            return fallback;
-        }
-        if (typeof fallback === 'function' && 'stream' in fallback) {
-            const maybeStream = fallback.stream;
-            if (typeof maybeStream === 'function') {
-                return fallback;
-            }
-        }
-    }
-    if (typeof loaded === 'function' && 'stream' in loaded) {
-        const maybeStream = loaded.stream;
-        if (typeof maybeStream === 'function') {
-            return loaded;
-        }
-    }
-    return null;
-}
-async function loadOptionalGotModule() {
-    try {
-        const loaded = await import(GOT_OPTIONAL_MODULE);
-        const module = asOptionalGotModule(loaded);
-        if (module) {
-            return module;
-        }
-        throw new Error('invalid got module export');
-    }
-    catch (error) {
-        const normalized = toError(error);
-        const code = normalized.code;
-        const message = normalized.message ?? '';
-        const isModuleNotFound = (code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND') &&
-            (message.includes(`'${GOT_OPTIONAL_MODULE}'`) ||
-                message.includes(`"${GOT_OPTIONAL_MODULE}"`));
-        if (isModuleNotFound) {
-            throw new Error('optional dependency "got" is not installed. Install with: npm i got');
-        }
-        throw normalized;
-    }
-}
+/**
+ * Streaming media uploader/downloader. Handles host failover, encryption
+ * (`WaMediaCrypto`), and MAC verification. Used internally by the message
+ * coordinator and exposed for direct media transfer use cases.
+ */
 export class WaMediaTransferClient {
     constructor(options = {}) {
         this.logger = options.logger;
@@ -72,31 +27,29 @@ export class WaMediaTransferClient {
         this.defaultTimeoutMs = options.defaultTimeoutMs ?? WA_DEFAULTS.MEDIA_TIMEOUT_MS;
         this.defaultMaxReadBytes = options.defaultMaxReadBytes;
         this.defaultHeaders = normalizeHeaderRecord(options.defaultHeaders);
-        this.defaultUploadDispatcher = options.defaultUploadDispatcher;
-        this.defaultDownloadDispatcher = options.defaultDownloadDispatcher;
         this.defaultUploadAgent = options.defaultUploadAgent;
         this.defaultDownloadAgent = options.defaultDownloadAgent;
-        this.gotModulePromise = null;
+        this.skipMacVerification = options.skipMacVerification === true;
     }
+    /**
+     * Streams an encrypted media payload from the first responsive media host.
+     * Returns the raw transfer response – caller is responsible for piping the body.
+     */
     async downloadStream(request) {
         const { urls, headers, timeoutMs } = this.resolveTransferRequest(request);
-        const dispatcher = request.dispatcher ?? this.defaultDownloadDispatcher;
         const agent = request.agent ?? this.defaultDownloadAgent;
         this.logger?.debug('media download stream start', {
             urls: urls.length,
             timeoutMs
         });
-        const result = await this.fetchWithFallback(urls, timeoutMs, request.signal, (url, signal) => this.transferRequest(url, {
-            method: 'GET',
-            headers,
-            signal
-        }, dispatcher, agent));
+        const result = await this.fetchWithFallback(urls, timeoutMs, request.signal, (url, signal) => this.httpRequest(url, { method: 'GET', headers, signal }, agent));
         this.logger?.trace('media download stream response', {
             url: result.url,
             status: result.status
         });
         return result;
     }
+    /** Convenience wrapper: downloads the encrypted body and returns it as a Uint8Array. */
     async downloadBytes(request) {
         const response = await this.downloadStream(request);
         await this.assertSuccessfulResponse(response);
@@ -107,6 +60,10 @@ export class WaMediaTransferClient {
             maxBytes: request.maxBytes ?? this.defaultMaxReadBytes
         });
     }
+    /**
+     * Uploads a raw (already-encrypted or plaintext) body to the requested
+     * media URL. Returns the server's transfer response unchanged.
+     */
     async uploadStream(request) {
         const bodyIsBytes = request.body instanceof Uint8Array;
         const { urls, headers, timeoutMs } = this.resolveTransferRequest(request, {
@@ -115,7 +72,6 @@ export class WaMediaTransferClient {
                 ? String(request.contentLength)
                 : undefined
         });
-        const dispatcher = request.dispatcher ?? this.defaultUploadDispatcher;
         const agent = request.agent ?? this.defaultUploadAgent;
         const uploadUrls = bodyIsBytes ? urls : urls.slice(0, 1);
         if (!bodyIsBytes && urls.length > 1) {
@@ -129,29 +85,18 @@ export class WaMediaTransferClient {
             timeoutMs,
             method
         });
-        const result = await this.fetchWithFallback(uploadUrls, timeoutMs, request.signal, async (url, signal) => {
-            if (bodyIsBytes) {
-                return this.transferRequest(url, {
-                    method,
-                    headers,
-                    signal,
-                    body: request.body
-                }, dispatcher, agent);
-            }
-            return this.transferRequest(url, {
-                method,
-                headers,
-                signal,
-                body: request.body,
-                duplex: 'half'
-            }, dispatcher, agent);
-        });
+        const result = await this.fetchWithFallback(uploadUrls, timeoutMs, request.signal, (url, signal) => this.httpRequest(url, { method, headers, signal, body: request.body }, agent));
         this.logger?.trace('media upload stream response', {
             url: result.url,
             status: result.status
         });
         return result;
     }
+    /**
+     * Encrypts the plaintext body with the per-`mediaType` HKDF keys (a new
+     * media key is generated when none is supplied) and uploads it. Returns
+     * the upload response plus the derived key/hashes for the message stanza.
+     */
     async uploadEncrypted(request) {
         this.logger?.info('media encrypted upload start', {
             mediaType: request.mediaType
@@ -165,7 +110,6 @@ export class WaMediaTransferClient {
                 directPath: request.directPath,
                 hosts: request.hosts,
                 headers: request.headers,
-                dispatcher: request.dispatcher,
                 agent: request.agent,
                 timeoutMs: request.timeoutMs,
                 signal: request.signal,
@@ -191,6 +135,10 @@ export class WaMediaTransferClient {
             plaintextLength: metadata.plaintextLength
         };
     }
+    /**
+     * Downloads an encrypted media payload, decrypts it, and verifies the MAC
+     * + file SHA-256s. Returns the decrypted bytes.
+     */
     async downloadAndDecrypt(request) {
         this.logger?.info('media encrypted download start', {
             mediaType: request.mediaType
@@ -213,6 +161,11 @@ export class WaMediaTransferClient {
             throw error;
         }
     }
+    /**
+     * Streaming variant of {@link downloadAndDecrypt}: returns a `plaintext`
+     * Readable plus a `metadata` promise that resolves after the stream ends
+     * with the verified hashes (or rejects on MAC/size failure).
+     */
     async downloadAndDecryptStream(request) {
         const response = await this.downloadStream(request);
         await this.assertSuccessfulResponse(response);
@@ -221,7 +174,8 @@ export class WaMediaTransferClient {
             mediaType: request.mediaType,
             mediaKey: request.mediaKey,
             expectedFileSha256: request.fileSha256,
-            expectedFileEncSha256: request.fileEncSha256
+            expectedFileEncSha256: request.fileEncSha256,
+            skipMacVerification: this.skipMacVerification
         });
         decrypted.metadata.catch(() => undefined);
         this.logger?.debug('media encrypted download stream ready', {
@@ -232,125 +186,58 @@ export class WaMediaTransferClient {
             metadata: decrypted.metadata
         };
     }
+    /** Drains a streaming response body to a Uint8Array (respects `maxBytes`). */
     async readResponseBytes(response, maxBytes) {
         if (!response.body) {
             return EMPTY_BYTES;
         }
         return readAllBytes(response.body, { maxBytes: maxBytes ?? this.defaultMaxReadBytes });
     }
-    async transferRequest(url, init, dispatcher, agent) {
-        if (agent) {
-            return this.gotWithAgent(url, init, agent);
-        }
-        return this.fetchWithDispatcher(url, init, dispatcher);
-    }
-    async fetchWithDispatcher(url, init, dispatcher) {
-        const response = !dispatcher
-            ? await fetch(url, init)
-            : await fetch(url, {
-                ...init,
-                dispatcher
-            });
-        return this.toFetchTransferResponse(response);
-    }
-    toFetchTransferResponse(response) {
-        return {
-            status: response.status,
-            ok: response.ok,
-            headers: Object.fromEntries(response.headers.entries()),
-            body: response.body
-                ? Readable.fromWeb(response.body)
-                : null,
-            cancel: async () => {
-                if (!response.body) {
-                    return;
-                }
-                try {
-                    await response.body.cancel();
-                }
-                catch {
-                    // ignore cancel errors from remote resets
-                }
-            }
-        };
-    }
-    async gotWithAgent(url, init, agent) {
-        const got = await this.loadGotModule();
-        const urlObj = new URL(url);
-        const gotAgent = urlObj.protocol === 'http:'
-            ? { http: agent }
-            : urlObj.protocol === 'https:'
-                ? { https: agent }
-                : { http: agent, https: agent };
+    async httpRequest(url, init, agent) {
+        const parsed = new URL(url);
+        const transport = parsed.protocol === 'https:' ? https : http;
         return new Promise((resolve, reject) => {
-            const request = got.stream(url, {
-                method: init.method,
-                headers: (init.headers ?? {}),
-                body: init.body,
-                signal: init.signal,
-                throwHttpErrors: false,
-                retry: { limit: 0 },
-                agent: gotAgent
-            });
-            const onError = (error) => {
-                request.off('response', onResponse);
-                reject(toError(error));
-            };
-            const onResponse = (incoming) => {
-                request.off('error', onError);
-                resolve(this.toGotTransferResponse(incoming));
-            };
-            request.once('error', onError);
-            request.once('response', onResponse);
-        });
-    }
-    async loadGotModule() {
-        if (!this.gotModulePromise) {
-            this.gotModulePromise = loadOptionalGotModule().catch((error) => {
-                this.gotModulePromise = null;
-                throw error;
-            });
-        }
-        return this.gotModulePromise;
-    }
-    toGotTransferResponse(incoming) {
-        if (!incoming || typeof incoming !== 'object') {
-            throw new Error('invalid got response object');
-        }
-        const stream = incoming;
-        const status = typeof stream.statusCode === 'number' &&
-            Number.isFinite(stream.statusCode) &&
-            stream.statusCode >= 100 &&
-            stream.statusCode <= 599
-            ? stream.statusCode
-            : 500;
-        const headers = {};
-        if (stream.headers && typeof stream.headers === 'object') {
-            const input = stream.headers;
-            for (const key in input) {
-                const value = input[key];
-                if (typeof value === 'string') {
-                    headers[key] = value;
-                    continue;
-                }
-                if (Array.isArray(value)) {
-                    headers[key] = value.join(', ');
-                    continue;
-                }
-                if (value !== undefined && value !== null) {
-                    headers[key] = String(value);
+            const req = transport.request(url, {
+                method: init.method ?? 'GET',
+                headers: init.headers,
+                signal: init.signal ?? undefined,
+                agent: agent ?? undefined
+            }, (res) => {
+                const status = res.statusCode ?? 500;
+                const headers = {};
+                for (const key in res.headers) {
+                    const value = res.headers[key];
+                    if (typeof value === 'string') {
+                        headers[key] = value;
+                    }
+                    else if (Array.isArray(value)) {
+                        headers[key] = value.join(', ');
+                    }
                 }
+                resolve({
+                    status,
+                    ok: status >= 200 && status < 300,
+                    headers,
+                    body: res,
+                    // eslint-disable-next-line @typescript-eslint/require-await
+                    cancel: async () => {
+                        res.destroy();
+                    }
+                });
+            });
+            req.on('error', (error) => reject(toError(error)));
+            const body = init.body;
+            if (body instanceof Uint8Array) {
+                req.end(body);
             }
-        }
-        return {
-            status,
-            ok: status >= 200 && status < 300,
-            headers,
-            body: stream,
-            cancel: async () => {
-                stream.destroy();
+            else if (body) {
+                body.on('error', (err) => req.destroy(toError(err)));
+                body.pipe(req);
             }
-        };
+            else {
+                req.end();
+            }
+        });
     }
     resolveTransferRequest(request, extraHeaders) {
         const headers = { ...this.defaultHeaders };
@@ -384,10 +271,11 @@ export class WaMediaTransferClient {
                     fileEncSha256: encrypted.fileEncSha256,
                     plaintextLength: request.plaintext.byteLength
                 }),
+                // eslint-disable-next-line @typescript-eslint/require-await
                 cleanup: async () => undefined
             };
         }
-        const prepared = await WaMediaCrypto.encryptReadable(request.mediaType, mediaKey, request.plaintext);
+        const prepared = await WaMediaCrypto.encryptReadable(request.mediaType, mediaKey, request.plaintext, { expectedFileSize: request.contentLength ?? undefined });
         return {
             body: prepared.encrypted,
             contentLength: request.contentLength !== null && request.contentLength !== undefined

package/dist/esm/media/{conn.js → transfer/conn.js}

@@ -1,6 +1,11 @@
-import { WA_NODE_TAGS } from '../protocol/constants.js';
-import { findNodeChild, getNodeChildrenByTag } from '../transport/node/helpers.js';
-import { assertIqResult } from '../transport/node/query.js';
+import { WA_NODE_TAGS } from '../../protocol/constants.js';
+import { findNodeChild, getNodeChildrenByTag } from '../../transport/node/helpers.js';
+import { assertIqResult } from '../../transport/node/query.js';
+import { parseOptionalInt } from '../../util/primitives.js';
+/**
+ * Parses a `media_conn` IQ response into a {@link WaMediaConn} (auth token,
+ * absolute expiry, and host list). Throws on missing auth/ttl/hosts.
+ */
 export function parseMediaConnResponse(node, nowMs) {
     assertIqResult(node, 'media_conn');
     const mediaConnNode = findNodeChild(node, WA_NODE_TAGS.MEDIA_CONN);
@@ -11,8 +16,8 @@ export function parseMediaConnResponse(node, nowMs) {
     if (!auth) {
         throw new Error('media_conn response is missing auth');
     }
-    const ttlRaw = Number.parseInt(mediaConnNode.attrs.ttl ?? '0', 10);
-    if (!Number.isFinite(ttlRaw) || ttlRaw <= 0) {
+    const ttlRaw = parseOptionalInt(mediaConnNode.attrs.ttl) ?? 0;
+    if (ttlRaw <= 0) {
         throw new Error('media_conn response has invalid ttl');
     }
     const expiresAtMs = ttlRaw >= 1000000000 ? ttlRaw * 1000 : nowMs + ttlRaw * 1000;

package/dist/esm/message/WaMessageClient.js

@@ -1,4 +1,4 @@
-import { describeAckNode, isAckOrReceiptNode, isNegativeAckNode, isRetryableNegativeAck } from './ack.js';
+import { describeAckNode, isAckOrReceiptNode, isNegativeAckNode, isRetryableNegativeAck } from './primitives/ack.js';
 import { WA_DEFAULTS, WA_MESSAGE_TAGS, WA_MESSAGE_TYPES, WA_NODE_TAGS } from '../protocol/constants.js';
 import { buildReceiptNode } from '../transport/node/builders/global.js';
 import { delay } from '../util/async.js';
@@ -11,6 +11,11 @@ class MessagePublishNackError extends Error {
         this.retryable = retryable;
     }
 }
+/**
+ * Low-level message-publishing client. Sends pre-built message/receipt nodes,
+ * handles ack timeouts and retry on negative-ack failures, and is the
+ * transport hook used by {@link WaMessageCoordinator}.
+ */
 export class WaMessageClient {
     constructor(options) {
         this.logger = options.logger;
@@ -20,6 +25,11 @@ export class WaMessageClient {
         this.defaultMaxAttempts = options.defaultMaxAttempts ?? WA_DEFAULTS.MESSAGE_MAX_ATTEMPTS;
         this.defaultRetryDelayMs = options.defaultRetryDelayMs ?? WA_DEFAULTS.MESSAGE_RETRY_DELAY_MS;
     }
+    /**
+     * Publishes a `<message>` stanza and awaits its ack/receipt, retrying on
+     * retryable negative-ack errors up to `maxAttempts`. Returns the ack
+     * metadata extracted from the server response.
+     */
     async publishNode(node, options = {}) {
         if (node.tag !== WA_MESSAGE_TAGS.MESSAGE) {
             throw new Error(`invalid node tag for message publish: ${node.tag}`);
@@ -51,14 +61,25 @@ export class WaMessageClient {
                 if (isNegativeAckNode(ackNode)) {
                     throw new MessagePublishNackError(`negative publish ack: ${describeAckNode(ackNode)}`, isRetryableNegativeAck(ackNode));
                 }
-                this.logger.info('message publish acknowledged', {
-                    id,
-                    tag: ackNode.tag,
-                    type: ackNode.attrs.type,
-                    phash: ackNode.attrs.phash,
-                    addressingMode: ackNode.attrs.addressing_mode,
-                    attempts: attempt
-                });
+                if (attempt > 1) {
+                    this.logger.info('message publish acknowledged after retry', {
+                        id,
+                        tag: ackNode.tag,
+                        type: ackNode.attrs.type,
+                        phash: ackNode.attrs.phash,
+                        addressingMode: ackNode.attrs.addressing_mode,
+                        attempts: attempt
+                    });
+                }
+                else {
+                    this.logger.trace('message publish acknowledged', {
+                        id,
+                        tag: ackNode.tag,
+                        type: ackNode.attrs.type,
+                        phash: ackNode.attrs.phash,
+                        addressingMode: ackNode.attrs.addressing_mode
+                    });
+                }
                 return {
                     id,
                     attempts: attempt,
@@ -71,25 +92,33 @@ export class WaMessageClient {
                 const nackRetryable = error instanceof MessagePublishNackError ? error.retryable : false;
                 const canRetry = attempt < maxAttempts &&
                     (this.isRetryablePublishError(lastError) || nackRetryable);
+                if (canRetry) {
+                    this.logger.debug('message publish attempt failed, will retry', {
+                        attempt,
+                        maxAttempts,
+                        nackRetryable,
+                        message: lastError.message
+                    });
+                    await delay(retryDelayMs * attempt);
+                    continue;
+                }
                 this.logger.warn('message publish attempt failed', {
                     attempt,
                     maxAttempts,
-                    canRetry,
                     nackRetryable,
                     message: lastError.message
                 });
-                if (!canRetry) {
-                    throw lastError;
-                }
-                await delay(retryDelayMs * attempt);
+                throw lastError;
             }
         }
         throw lastError ?? new Error('message publish failed');
     }
+    /** Builds the encrypted message envelope from `input` and publishes it via {@link publishNode}. */
     async publishEncrypted(input, options = {}) {
         const node = this.buildEncryptedMessageNode(input);
         return this.publishNode(node, options);
     }
+    /** Fire-and-forget variant: sends a `<message>` stanza without awaiting an ack. */
     async sendMessageNode(node) {
         if (node.tag !== WA_MESSAGE_TAGS.MESSAGE) {
             throw new Error(`invalid node tag for message send: ${node.tag}`);
@@ -101,6 +130,7 @@ export class WaMessageClient {
         });
         await this.sendNode(node);
     }
+    /** Builds and sends an encrypted message envelope without awaiting an ack. */
     async sendEncrypted(input) {
         const node = this.buildEncryptedMessageNode(input);
         await this.sendMessageNode(node);
@@ -165,12 +195,13 @@ export class WaMessageClient {
         };
         return node;
     }
+    /** Builds and sends a `<receipt>` stanza (delivery/read/played/etc.). */
     async sendReceipt(input) {
         const node = buildReceiptNode({
             kind: 'outbound',
             to: input.to,
             id: input.id,
-            type: input.type ?? 'read',
+            type: input.type ?? WA_MESSAGE_TYPES.RECEIPT_TYPE_READ,
             participant: input.participant,
             recipient: input.recipient,
             category: input.category,