zapo-js 0.3.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 http from 'node:http';
 import https from 'node:https';
-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';
+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,6 +15,11 @@ function normalizeHeaderRecord(headers) {
     }
     return 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;
@@ -26,6 +31,10 @@ export class WaMediaTransferClient {
         this.defaultDownloadAgent = options.defaultDownloadAgent;
         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 agent = request.agent ?? this.defaultDownloadAgent;
@@ -40,6 +49,7 @@ export class WaMediaTransferClient {
         });
         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);
@@ -50,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, {
@@ -78,6 +92,11 @@ export class WaMediaTransferClient {
         });
         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
@@ -116,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
@@ -138,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);
@@ -158,6 +186,7 @@ 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;
@@ -190,6 +219,7 @@ export class WaMediaTransferClient {
                     ok: status >= 200 && status < 300,
                     headers,
                     body: res,
+                    // eslint-disable-next-line @typescript-eslint/require-await
                     cancel: async () => {
                         res.destroy();
                     }
@@ -241,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,

package/dist/esm/message/addons/link-preview/builder.js

@@ -0,0 +1,36 @@
+export function buildExtendedTextWithPreview(text, resolved, thumbnailFields) {
+    const message = {
+        text,
+        matchedText: resolved.matchedText,
+        previewType: resolved.previewType
+    };
+    if (resolved.title !== undefined)
+        message.title = resolved.title;
+    if (resolved.description !== undefined)
+        message.description = resolved.description;
+    if (thumbnailFields.jpegThumbnail !== undefined) {
+        message.jpegThumbnail = thumbnailFields.jpegThumbnail;
+    }
+    if (thumbnailFields.thumbnailDirectPath !== undefined) {
+        message.thumbnailDirectPath = thumbnailFields.thumbnailDirectPath;
+    }
+    if (thumbnailFields.thumbnailSha256 !== undefined) {
+        message.thumbnailSha256 = thumbnailFields.thumbnailSha256;
+    }
+    if (thumbnailFields.thumbnailEncSha256 !== undefined) {
+        message.thumbnailEncSha256 = thumbnailFields.thumbnailEncSha256;
+    }
+    if (thumbnailFields.mediaKey !== undefined) {
+        message.mediaKey = thumbnailFields.mediaKey;
+    }
+    if (thumbnailFields.mediaKeyTimestamp !== undefined) {
+        message.mediaKeyTimestamp = thumbnailFields.mediaKeyTimestamp;
+    }
+    if (thumbnailFields.thumbnailWidth !== undefined) {
+        message.thumbnailWidth = thumbnailFields.thumbnailWidth;
+    }
+    if (thumbnailFields.thumbnailHeight !== undefined) {
+        message.thumbnailHeight = thumbnailFields.thumbnailHeight;
+    }
+    return { extendedTextMessage: message };
+}

package/dist/esm/message/addons/link-preview/detect.js

@@ -0,0 +1,55 @@
+const URL_REGEX = /\bhttps?:\/\/\S+/i;
+const TRAILING_PUNCT = '.,;:!?\'"»›>';
+const WRAPPER_PAIRS = Object.freeze({
+    ')': '(',
+    ']': '[',
+    '}': '{'
+});
+export function findFirstLink(text) {
+    const match = URL_REGEX.exec(text);
+    if (!match)
+        return null;
+    const raw = stripTrailing(match[0]);
+    if (raw.length === 0)
+        return null;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        return null;
+    return { matchedText: raw, url };
+}
+function stripTrailing(raw) {
+    let s = raw;
+    while (s.length > 0) {
+        const last = s[s.length - 1] ?? '';
+        if (TRAILING_PUNCT.includes(last)) {
+            s = s.slice(0, -1);
+            continue;
+        }
+        const opener = WRAPPER_PAIRS[last];
+        if (opener === undefined)
+            break;
+        // Only strip the closing wrapper if it's unbalanced (no matching opener
+        // inside the candidate URL). Keeps URLs like `/a_(b)` intact while
+        // still trimming `(see https://x.com)` → `https://x.com`.
+        if (countChar(s, last) > countChar(s, opener)) {
+            s = s.slice(0, -1);
+            continue;
+        }
+        break;
+    }
+    return s;
+}
+function countChar(s, ch) {
+    let n = 0;
+    for (let i = 0; i < s.length; i++) {
+        if (s[i] === ch)
+            n++;
+    }
+    return n;
+}