zapo-js 0.3.0 → 1.0.0

package/dist/esm/transport/node/builders/profile.js

@@ -1,4 +1,4 @@
-import { WA_DEFAULTS, WA_NODE_TAGS, WA_XMLNS } from '../../../protocol/constants.js';
+import { WA_DEFAULTS, WA_IQ_TYPES, WA_NODE_TAGS, WA_XMLNS } from '../../../protocol/constants.js';
 import { buildIqNode } from '../../node/query.js';
 export function buildGetProfilePictureIq(targetJid, type = 'preview', existingId) {
     const pictureAttrs = {
@@ -8,7 +8,7 @@ export function buildGetProfilePictureIq(targetJid, type = 'preview', existingId
     if (existingId) {
         pictureAttrs.id = existingId;
     }
-    return buildIqNode('get', WA_DEFAULTS.HOST_DOMAIN, WA_XMLNS.PROFILE_PICTURE, [
+    return buildIqNode(WA_IQ_TYPES.GET, WA_DEFAULTS.HOST_DOMAIN, WA_XMLNS.PROFILE_PICTURE, [
         {
             tag: WA_NODE_TAGS.PICTURE,
             attrs: pictureAttrs
@@ -22,7 +22,7 @@ export function buildSetProfilePictureIq(imageBytes, targetJid) {
     if (targetJid) {
         attrs.target = targetJid;
     }
-    return buildIqNode('set', WA_DEFAULTS.HOST_DOMAIN, WA_XMLNS.PROFILE_PICTURE, [
+    return buildIqNode(WA_IQ_TYPES.SET, WA_DEFAULTS.HOST_DOMAIN, WA_XMLNS.PROFILE_PICTURE, [
         {
             tag: WA_NODE_TAGS.PICTURE,
             attrs: { type: 'image' },
@@ -35,12 +35,12 @@ export function buildDeleteProfilePictureIq(targetJid) {
     if (targetJid) {
         attrs.target = targetJid;
     }
-    return buildIqNode('set', WA_DEFAULTS.HOST_DOMAIN, WA_XMLNS.PROFILE_PICTURE, undefined, attrs);
+    return buildIqNode(WA_IQ_TYPES.SET, WA_DEFAULTS.HOST_DOMAIN, WA_XMLNS.PROFILE_PICTURE, undefined, attrs);
 }
 export function buildSetStatusIq(text) {
-    return buildIqNode('set', WA_DEFAULTS.HOST_DOMAIN, WA_XMLNS.STATUS, [
+    return buildIqNode(WA_IQ_TYPES.SET, WA_DEFAULTS.HOST_DOMAIN, WA_XMLNS.STATUS, [
         {
-            tag: 'status',
+            tag: WA_NODE_TAGS.STATUS,
             attrs: {},
             content: text
         }
@@ -48,7 +48,27 @@ export function buildSetStatusIq(text) {
 }
 export function buildGetDisappearingModeUsyncQueryNode() {
     return {
-        tag: 'disappearing_mode',
+        tag: WA_NODE_TAGS.DISAPPEARING_MODE,
+        attrs: {}
+    };
+}
+export function buildSetDisappearingModeIq(durationSeconds) {
+    return buildIqNode(WA_IQ_TYPES.SET, WA_DEFAULTS.HOST_DOMAIN, WA_XMLNS.DISAPPEARING_MODE, [
+        {
+            tag: WA_NODE_TAGS.DISAPPEARING_MODE,
+            attrs: { duration: String(durationSeconds) }
+        }
+    ]);
+}
+export function buildGetTextStatusUsyncQueryNode() {
+    return {
+        tag: WA_NODE_TAGS.TEXT_STATUS,
+        attrs: {}
+    };
+}
+export function buildGetUsernameUsyncQueryNode() {
+    return {
+        tag: WA_NODE_TAGS.USERNAME,
         attrs: {}
     };
 }
@@ -59,7 +79,7 @@ export function buildGetStatusUsyncQueryNodes() {
             attrs: {}
         },
         {
-            tag: 'status',
+            tag: WA_NODE_TAGS.STATUS,
             attrs: {}
         },
         {

package/dist/esm/transport/node/builders/tos.js

@@ -0,0 +1,58 @@
+import { WA_DEFAULTS } from '../../../protocol/defaults.js';
+import { WA_IQ_TYPES, WA_XMLNS } from '../../../protocol/nodes.js';
+import { buildIqNode } from '../../node/query.js';
+import { parseOptionalInt } from '../../../util/primitives.js';
+function noticeNodes(noticeIds) {
+    return noticeIds.map((id) => ({
+        tag: 'notice',
+        attrs: { id }
+    }));
+}
+export function buildTosQueryIq(noticeIds) {
+    if (noticeIds.length === 0) {
+        throw new Error('tos query requires at least one notice id');
+    }
+    return buildIqNode(WA_IQ_TYPES.GET, WA_DEFAULTS.HOST_DOMAIN, WA_XMLNS.TOS, [
+        {
+            tag: 'request',
+            attrs: {},
+            content: noticeNodes(noticeIds)
+        }
+    ]);
+}
+export function buildTosUpdateIq(noticeIds) {
+    if (noticeIds.length === 0) {
+        throw new Error('tos update requires at least one notice id');
+    }
+    return buildIqNode(WA_IQ_TYPES.SET, WA_DEFAULTS.HOST_DOMAIN, WA_XMLNS.TOS, [
+        {
+            tag: 'request',
+            attrs: { type: 'session_update' },
+            content: noticeNodes(noticeIds)
+        }
+    ]);
+}
+export function parseTosQueryResponse(node) {
+    const tosNode = Array.isArray(node.content)
+        ? node.content.find((child) => child.tag === 'tos')
+        : undefined;
+    if (!tosNode) {
+        throw new Error('tos response missing <tos> node');
+    }
+    const refreshSeconds = parseOptionalInt(tosNode.attrs.refresh) ?? 0;
+    const notices = [];
+    if (Array.isArray(tosNode.content)) {
+        for (const child of tosNode.content) {
+            if (child.tag !== 'notice')
+                continue;
+            const id = child.attrs.id;
+            if (!id)
+                continue;
+            notices.push({
+                id,
+                accepted: child.attrs.state !== 'false'
+            });
+        }
+    }
+    return { refreshSeconds, notices };
+}

package/dist/esm/transport/node/builders/usync.js

@@ -1,5 +1,7 @@
-import { WA_DEFAULTS, WA_NODE_TAGS, WA_USYNC_CONTEXTS, WA_USYNC_DEFAULTS, WA_USYNC_MODES, WA_XMLNS } from '../../../protocol/constants.js';
+import { WA_DEFAULTS, WA_IQ_TYPES, WA_NODE_TAGS, WA_USYNC_CONTEXTS, WA_USYNC_DEFAULTS, WA_USYNC_MODES, WA_XMLNS } from '../../../protocol/constants.js';
+import { findNodeChild, getNodeChildrenByTag } from '../../node/helpers.js';
 import { buildIqNode } from '../../node/query.js';
+import { parseOptionalInt } from '../../../util/primitives.js';
 export function buildUsyncUserNode(input) {
     return {
         tag: WA_NODE_TAGS.USER,
@@ -10,6 +12,53 @@ export function buildUsyncUserNode(input) {
         ...(input.content !== undefined ? { content: input.content } : {})
     };
 }
+export function iterateUsyncUsers(result) {
+    const usyncNode = findNodeChild(result, WA_NODE_TAGS.USYNC);
+    if (!usyncNode)
+        return null;
+    const listNode = findNodeChild(usyncNode, WA_NODE_TAGS.LIST);
+    if (!listNode)
+        return null;
+    return getNodeChildrenByTag(listNode, WA_NODE_TAGS.USER);
+}
+const EMPTY_USYNC_RESULT_ENVELOPE = Object.freeze({
+    errors: Object.freeze({}),
+    refresh: Object.freeze({})
+});
+/**
+ * Walks a `usync` IQ result and extracts per-protocol error envelopes plus
+ * `refresh` hints. Returns an empty envelope when the result has no `usync`
+ * payload.
+ */
+export function parseUsyncResultEnvelope(result) {
+    const usyncNode = findNodeChild(result, WA_NODE_TAGS.USYNC);
+    if (!usyncNode)
+        return EMPTY_USYNC_RESULT_ENVELOPE;
+    const resultNode = findNodeChild(usyncNode, 'result');
+    if (!resultNode)
+        return EMPTY_USYNC_RESULT_ENVELOPE;
+    if (!Array.isArray(resultNode.content))
+        return EMPTY_USYNC_RESULT_ENVELOPE;
+    const errors = {};
+    const refresh = {};
+    for (let i = 0; i < resultNode.content.length; i += 1) {
+        const protoNode = resultNode.content[i];
+        const errorNode = findNodeChild(protoNode, WA_NODE_TAGS.ERROR);
+        if (errorNode) {
+            errors[protoNode.tag] = {
+                code: parseOptionalInt(errorNode.attrs.code) ?? null,
+                text: errorNode.attrs.text ?? null,
+                backoffSeconds: parseOptionalInt(errorNode.attrs.backoff) ?? null
+            };
+            continue;
+        }
+        const refreshSeconds = parseOptionalInt(protoNode.attrs.refresh);
+        if (refreshSeconds !== undefined) {
+            refresh[protoNode.tag] = refreshSeconds;
+        }
+    }
+    return { errors, refresh };
+}
 export function buildUsyncIq(input) {
     if (input.queryProtocolNodes.length === 0) {
         throw new Error('usync query must include at least one protocol node');
@@ -18,7 +67,7 @@ export function buildUsyncIq(input) {
     for (let index = 0; index < input.users.length; index += 1) {
         users[index] = buildUsyncUserNode(input.users[index]);
     }
-    return buildIqNode('get', input.hostDomain ?? WA_DEFAULTS.HOST_DOMAIN, WA_XMLNS.USYNC, [
+    return buildIqNode(WA_IQ_TYPES.GET, input.hostDomain ?? WA_DEFAULTS.HOST_DOMAIN, WA_XMLNS.USYNC, [
         {
             tag: WA_NODE_TAGS.USYNC,
             attrs: {

package/dist/esm/transport/node/helpers.js

@@ -127,6 +127,8 @@ export function decodeNodeContentUtf8OrBytes(value, field) {
     throw new Error(`node ${field} has no binary content`);
 }
 export function getNodeTextContent(node) {
+    if (!node)
+        return undefined;
     const content = node.content;
     if (content instanceof Uint8Array)
         return TEXT_DECODER.decode(content);
@@ -146,7 +148,7 @@ export function decodeNodeContentBase64OrBytes(value, field) {
     }
     throw new Error(`missing binary node content for ${field}`);
 }
-export function formatNodeIdPrefixFromSeed(seed) {
+function formatNodeIdPrefixFromSeed(seed) {
     const left = ((seed[0] << 8) | seed[1]) >>> 0;
     const right = ((seed[2] << 8) | seed[3]) >>> 0;
     return `${left}.${right}-`;

package/dist/esm/transport/node/mex/argo-decoder.js

@@ -4,7 +4,7 @@ async function loadArgo() {
     if (cachedArgo !== undefined)
         return cachedArgo;
     try {
-        cachedArgo = (await import('argo-codec'));
+        cachedArgo = await import('argo-codec');
     }
     catch {
         cachedArgo = null;
@@ -124,7 +124,7 @@ function readDesc(ctx) {
 }
 function readError(ctx) {
     const message = readStringFromBlock(ctx);
-    skipOptional(ctx); // location — never observed in MEX errors so far
+    skipOptional(ctx); // location – never observed in MEX errors so far
     const path = readPath(ctx);
     const extensions = readOptionalDesc(ctx);
     return { message, path, extensions };

package/dist/esm/transport/node/mex/client.js

@@ -1,3 +1,4 @@
+import { WA_MEX_PERSIST_IDS } from '../../../mex.js';
 import { WA_DEFAULTS, WA_IQ_TYPES, WA_NODE_TAGS, WA_XMLNS } from '../../../protocol/constants.js';
 import { decodeNodeContentUtf8OrBytes, findNodeChild } from '../../node/helpers.js';
 import { decodeMexArgoResponse, isMexArgoDecoderAvailable } from '../../node/mex/argo-decoder.js';
@@ -5,6 +6,27 @@ import { assertIqResult } from '../../node/query.js';
 import { TEXT_DECODER } from '../../../util/bytes.js';
 import { toError } from '../../../util/primitives.js';
 const MEX_DEFAULT_TIMEOUT_MS = 32000;
+/**
+ * Typed wrapper around `dispatchMexQuery` that resolves persist IDs from the
+ * generated `WA_MEX_PERSIST_IDS` table. The op key constrains the `variables`
+ * shape via `WaMexOperationVariables` and defaults the response to
+ * `WaMexOperationResponses[K] | null` (the response tree the extractor walked
+ * from the Relay `operation.selections`; leaves are `unknown` since Relay
+ * strips scalar types at codegen).
+ */
+export async function runMexQuery(socket, opKey, variables) {
+    const persist = WA_MEX_PERSIST_IDS[opKey];
+    if (!persist) {
+        throw new Error(`mex/${String(opKey)} persist IDs not found`);
+    }
+    const { data } = await dispatchMexQuery(socket, {
+        docId: persist.docId,
+        clientDocId: persist.clientDocId,
+        opName: opKey,
+        variables: variables
+    });
+    return data;
+}
 export async function dispatchMexQuery(socket, args) {
     const body = JSON.stringify({
         queryId: args.clientDocId,

package/dist/esm/transport/node/query.js

@@ -1,6 +1,11 @@
 import { WA_IQ_TYPES, WA_NODE_TAGS } from '../../protocol/constants.js';
 import { findNodeChild } from '../node/helpers.js';
 import { toError } from '../../util/primitives.js';
+/**
+ * Builds an IQ stanza (`<iq type="get|set" to="..." xmlns="..."/>`) with the
+ * given children/attrs. The caller is responsible for the `id` attribute
+ * (the transport assigns one automatically when omitted).
+ */
 export function buildIqNode(type, to, xmlns, content, attrs = {}) {
     return {
         tag: WA_NODE_TAGS.IQ,
@@ -13,6 +18,10 @@ export function buildIqNode(type, to, xmlns, content, attrs = {}) {
         ...(content !== undefined ? { content } : {})
     };
 }
+/**
+ * Reads the standard error envelope from an IQ stanza, returning the string
+ * `code`/`text` and (when parseable) the numeric `code`.
+ */
 export function parseIqError(node) {
     const errorNode = findNodeChild(node, WA_NODE_TAGS.ERROR);
     const code = errorNode?.attrs.code ?? node.attrs.type ?? 'unknown';
@@ -24,6 +33,10 @@ export function parseIqError(node) {
         ...(Number.isSafeInteger(parsedCode) ? { numericCode: parsedCode } : {})
     };
 }
+/**
+ * Throws when `node` is not a successful IQ result, embedding the parsed
+ * error envelope and the `context` label in the message.
+ */
 export function assertIqResult(node, context) {
     if (node.tag !== WA_NODE_TAGS.IQ) {
         throw new Error(`${context} returned non-iq node (${node.tag})`);
@@ -34,6 +47,10 @@ export function assertIqResult(node, context) {
     const error = parseIqError(node);
     throw new Error(`${context} iq failed (${error.code}: ${error.text})`);
 }
+/**
+ * Wraps `query(...)` so failures are logged with a `context` label and the
+ * stanza's tag/id/type, then rethrown. Used by every coordinator's IQ call.
+ */
 export async function queryWithContext(query, logger, context, node, timeoutMs, contextData = {}) {
     try {
         return await query(node, timeoutMs);

package/dist/esm/transport/node/usync.js

@@ -3,3 +3,15 @@ export function createUsyncSidGenerator() {
     const generatorPromise = createNodeIdGenerator();
     return async () => (await generatorPromise).next();
 }
+export function logUsyncProtocolErrors(envelope, logger, context) {
+    for (const protocol of Object.keys(envelope.errors)) {
+        const err = envelope.errors[protocol];
+        logger.warn('usync protocol error', {
+            context,
+            protocol,
+            code: err.code,
+            text: err.text,
+            backoffSeconds: err.backoffSeconds
+        });
+    }
+}

package/dist/esm/transport/noise/WaClientPayload.js

@@ -1,8 +1,8 @@
 import { randomUUID } from 'node:crypto';
 import { md5Bytes } from '../../crypto/core/primitives.js';
 import { proto } from '../../proto.js';
-import { DEFAULT_VERSION_BASE } from '../noise/constants.js';
 import { intToBytes } from '../../util/bytes.js';
+import { WA_VERSION } from '../../version-spec.js';
 function parseVersion(versionBase) {
     const [p = '2', s = '3000', t = '0'] = versionBase.split('.');
     const primary = Number.parseInt(p, 10);
@@ -107,12 +107,13 @@ function defaultDeviceProps(versionBase, config, version) {
             supportHostedGroupMsg: true,
             supportBizHostedMsg: true,
             supportFbidBotChatHistory: true,
-            supportMessageAssociation: true
+            supportMessageAssociation: true,
+            supportInlineContacts: true
         }
     }).finish();
 }
 function buildCommonPayload(config, version) {
-    const versionBase = config.versionBase ?? DEFAULT_VERSION_BASE;
+    const versionBase = config.versionBase ?? WA_VERSION;
     const pull = config.pull ?? true;
     return {
         passive: config.passive === true,
@@ -120,10 +121,9 @@ function buildCommonPayload(config, version) {
         connectType: proto.ClientPayload.ConnectType.WIFI_UNKNOWN,
         connectReason: proto.ClientPayload.ConnectReason.USER_ACTIVATED,
         userAgent: config.userAgent ?? defaultUserAgent(versionBase, config.deviceOsDisplayName, version),
-        webInfo: config.webInfo ??
-            {
-                webSubPlatform: defaultWebSubPlatform()
-            }
+        webInfo: config.webInfo ?? {
+            webSubPlatform: defaultWebSubPlatform()
+        }
     };
 }
 export function buildLoginPayload(config) {
@@ -147,7 +147,7 @@ export function buildRegistrationPayload(config) {
     if (!Number.isSafeInteger(signedPreKeyId) || signedPreKeyId <= 0) {
         throw new Error('registration payload requires a valid signedPreKeyId');
     }
-    const versionBase = config.versionBase ?? DEFAULT_VERSION_BASE;
+    const versionBase = config.versionBase ?? WA_VERSION;
     const version = parseVersion(versionBase);
     const common = buildCommonPayload(config, version);
     const devicePairingData = {

package/dist/esm/transport/noise/WaMobileClientPayload.js

@@ -13,6 +13,11 @@ function parseAppVersion(version) {
         quaternary: at(3)
     };
 }
+/**
+ * Builds the encoded {@link Proto.ClientPayload} bytes the WhatsApp Mobile
+ * transport sends after the noise login handshake. Throws when
+ * `username`/`appVersion` are missing/invalid.
+ */
 export function buildMobileLoginPayload(config) {
     if (!Number.isSafeInteger(config.username) || config.username <= 0) {
         throw new Error('mobile login payload requires a valid numeric username');

package/dist/esm/transport/noise/WaNoiseCert.js

@@ -26,6 +26,11 @@ function parseNoiseCertificate(certificate) {
         signature: signatureBytes
     };
 }
+/**
+ * Validates a WhatsApp noise certificate chain against `rootCa` (defaults to
+ * the production root) and confirms the leaf binds `serverStatic`. Throws on
+ * any structural mismatch, bad signature, or unexpected issuer serial.
+ */
 export async function verifyNoiseCertificateChain(certificateChain, serverStatic, rootCa = PRODUCTION_ROOT_CA) {
     const chain = proto.CertChain.decode(certificateChain);
     if (!chain.leaf || !chain.intermediate) {

package/dist/esm/transport/noise/WaNoiseHandshake.js

@@ -1,53 +1,55 @@
-import { aesGcmDecrypt, aesGcmEncrypt, buildNonce, hkdfSplit, importAesGcmKey, sha256 } from '../../crypto/index.js';
+import { aesGcmDecrypt, aesGcmEncrypt, hkdfSplit, sha256, writeNonceCounter } from '../../crypto/index.js';
 import { WaNoiseSocket } from '../noise/WaNoiseSocket.js';
-import { concatBytes, EMPTY_BYTES } from '../../util/bytes.js';
+import { EMPTY_BYTES } from '../../util/bytes.js';
+/**
+ * Implements the Noise XX-style handshake state used by WaComms: tracks the
+ * handshake hash, chaining key, derived cipher key, and nonce counter. Calls
+ * {@link finish} to produce the post-handshake {@link WaNoiseSocket}.
+ */
 export class WaNoiseHandshake {
     constructor() {
+        this.nonceScratch = new Uint8Array(12);
         this.handshakeHash = EMPTY_BYTES;
         this.chainingKey = EMPTY_BYTES;
         this.cipherKey = null;
         this.nonce = 0;
     }
-    async start(protocolName, prologue) {
-        const hashInput = protocolName.length === 32 ? protocolName : await sha256(protocolName);
+    start(protocolName, prologue) {
+        const hashInput = protocolName.length === 32 ? protocolName : sha256(protocolName);
         this.handshakeHash = hashInput;
         this.chainingKey = hashInput;
-        this.cipherKey = await importAesGcmKey(this.handshakeHash, ['encrypt', 'decrypt']);
-        await this.authenticate(prologue);
+        this.cipherKey = this.handshakeHash;
+        this.authenticate(prologue);
     }
-    async authenticate(data) {
-        this.handshakeHash = await sha256(concatBytes([this.handshakeHash, data]));
+    authenticate(data) {
+        this.handshakeHash = sha256([this.handshakeHash, data]);
     }
-    async mixIntoKey(keyMaterial) {
+    mixIntoKey(keyMaterial) {
         this.nonce = 0;
-        const [newChainingKey, nextCipherKey] = await hkdfSplit(keyMaterial, this.chainingKey, '');
+        const [newChainingKey, nextCipherKey] = hkdfSplit(keyMaterial, this.chainingKey, EMPTY_BYTES);
         this.chainingKey = newChainingKey;
-        this.cipherKey = await importAesGcmKey(nextCipherKey, ['encrypt', 'decrypt']);
+        this.cipherKey = nextCipherKey;
     }
-    async encrypt(plaintext) {
+    encrypt(plaintext) {
         if (!this.cipherKey) {
             throw new Error('noise handshake cipher key is not initialized');
         }
-        const nonce = buildNonce(this.nonce++);
-        const ciphertext = await aesGcmEncrypt(this.cipherKey, nonce, plaintext, this.handshakeHash);
-        await this.authenticate(ciphertext);
+        writeNonceCounter(this.nonceScratch, this.nonce++);
+        const ciphertext = aesGcmEncrypt(this.cipherKey, this.nonceScratch, plaintext, this.handshakeHash);
+        this.authenticate(ciphertext);
         return ciphertext;
     }
-    async decrypt(ciphertext) {
+    decrypt(ciphertext) {
         if (!this.cipherKey) {
             throw new Error('noise handshake cipher key is not initialized');
         }
-        const nonce = buildNonce(this.nonce++);
-        const plaintext = await aesGcmDecrypt(this.cipherKey, nonce, ciphertext, this.handshakeHash);
-        await this.authenticate(ciphertext);
+        writeNonceCounter(this.nonceScratch, this.nonce++);
+        const plaintext = aesGcmDecrypt(this.cipherKey, this.nonceScratch, ciphertext, this.handshakeHash);
+        this.authenticate(ciphertext);
         return plaintext;
     }
-    async finish() {
-        const [writeKeyRaw, readKeyRaw] = await hkdfSplit(EMPTY_BYTES, this.chainingKey, '');
-        const [writeKey, readKey] = await Promise.all([
-            importAesGcmKey(writeKeyRaw, ['encrypt']),
-            importAesGcmKey(readKeyRaw, ['decrypt'])
-        ]);
+    finish() {
+        const [writeKey, readKey] = hkdfSplit(EMPTY_BYTES, this.chainingKey, EMPTY_BYTES);
         this.handshakeHash = EMPTY_BYTES;
         this.chainingKey = EMPTY_BYTES;
         this.cipherKey = null;