zapo-js 0.1.0

package/dist/esm/transport/index.js

@@ -0,0 +1,6 @@
+export { WaComms } from './WaComms.js';
+export { WaWebSocket } from './WaWebSocket.js';
+export { WaKeepAlive } from './keepalive/WaKeepAlive.js';
+export { WaNodeOrchestrator } from './node/WaNodeOrchestrator.js';
+export { WaNodeTransport } from './node/WaNodeTransport.js';
+export { assertIqResult, buildIqNode, parseIqError, queryWithContext } from './node/query.js';

package/dist/esm/transport/keepalive/WaKeepAlive.js

@@ -0,0 +1,141 @@
+import { WA_DEFAULTS, WA_IQ_TYPES, WA_NODE_TAGS, WA_XMLNS } from '../../protocol/constants.js';
+import { toError } from '../../util/primitives.js';
+const KEEPALIVE_DEFAULT_JITTER_RATIO = 0.1;
+const KEEPALIVE_DEFAULT_MIN_JITTER_MS = 250;
+const KEEPALIVE_MAX_JITTER_RATIO = 0.5;
+export class WaKeepAlive {
+    constructor(options) {
+        this.logger = options.logger;
+        this.nodeOrchestrator = options.nodeOrchestrator;
+        this.getCommsFn = options.getComms;
+        this.intervalMs = options.intervalMs ?? WA_DEFAULTS.HEALTH_CHECK_INTERVAL_MS;
+        this.timeoutMs = options.timeoutMs ?? WA_DEFAULTS.DEAD_SOCKET_TIMEOUT_MS;
+        this.hostDomain = options.hostDomain ?? WA_DEFAULTS.HOST_DOMAIN;
+        this.jitterRatio = this.normalizeJitterRatio(options.jitterRatio);
+        this.minJitterMs = this.normalizeMinJitterMs(options.minJitterMs);
+        this.timer = null;
+        this.generation = 0;
+        this.inFlight = false;
+    }
+    start() {
+        this.logger.info('keepalive start', {
+            intervalMs: this.intervalMs,
+            timeoutMs: this.timeoutMs,
+            jitterRatio: this.jitterRatio,
+            minJitterMs: this.minJitterMs
+        });
+        this.generation += 1;
+        this.inFlight = false;
+        this.clearTimer();
+        this.schedule(this.generation);
+    }
+    stop() {
+        this.logger.info('keepalive stop');
+        this.generation += 1;
+        this.inFlight = false;
+        this.clearTimer();
+    }
+    schedule(generation) {
+        if (generation !== this.generation) {
+            return;
+        }
+        this.clearTimer();
+        const nextDelayMs = this.computeNextDelayMs();
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            void this.run(generation);
+        }, nextDelayMs);
+        this.logger.trace('keepalive scheduled', {
+            generation,
+            inMs: nextDelayMs,
+            baseIntervalMs: this.intervalMs
+        });
+    }
+    async run(generation) {
+        if (generation !== this.generation) {
+            return;
+        }
+        const comms = this.getCommsFn();
+        if (!comms || !comms.getCommsState().connected) {
+            this.logger.trace('keepalive skipped: comms not connected');
+            this.schedule(generation);
+            return;
+        }
+        if (this.inFlight || this.nodeOrchestrator.hasPending()) {
+            this.logger.trace('keepalive skipped: in-flight or pending queries', {
+                inFlight: this.inFlight,
+                pendingQueries: this.nodeOrchestrator.hasPending()
+            });
+            this.schedule(generation);
+            return;
+        }
+        this.inFlight = true;
+        const startedAt = Date.now();
+        try {
+            const pingNode = {
+                tag: WA_NODE_TAGS.IQ,
+                attrs: {
+                    to: this.hostDomain,
+                    type: WA_IQ_TYPES.GET,
+                    xmlns: WA_XMLNS.WHATSAPP_PING
+                }
+            };
+            await this.nodeOrchestrator.query(pingNode, this.timeoutMs);
+            this.logger.debug('keepalive ping success', {
+                latencyMs: Date.now() - startedAt
+            });
+        }
+        catch (error) {
+            this.logger.warn('keepalive ping failed, reconnecting socket', {
+                message: toError(error).message
+            });
+            try {
+                await comms.closeSocketAndResume();
+            }
+            catch (resumeError) {
+                this.logger.warn('keepalive reconnect failed', {
+                    message: toError(resumeError).message
+                });
+            }
+        }
+        finally {
+            this.inFlight = false;
+        }
+        this.schedule(generation);
+    }
+    normalizeJitterRatio(value) {
+        if (!Number.isFinite(value)) {
+            return KEEPALIVE_DEFAULT_JITTER_RATIO;
+        }
+        const normalized = value;
+        return Math.min(Math.max(normalized, 0), KEEPALIVE_MAX_JITTER_RATIO);
+    }
+    normalizeMinJitterMs(value) {
+        if (!Number.isFinite(value)) {
+            return KEEPALIVE_DEFAULT_MIN_JITTER_MS;
+        }
+        return Math.max(0, Math.trunc(value));
+    }
+    computeNextDelayMs() {
+        if (this.intervalMs <= 0) {
+            return 0;
+        }
+        if (this.jitterRatio <= 0 && this.minJitterMs <= 0) {
+            return this.intervalMs;
+        }
+        const ratioJitterMs = Math.floor(this.intervalMs * this.jitterRatio);
+        const jitterWindowMs = Math.max(this.minJitterMs, ratioJitterMs);
+        if (jitterWindowMs <= 0) {
+            return this.intervalMs;
+        }
+        const offsetMs = Math.floor(Math.random() * (jitterWindowMs * 2 + 1) - jitterWindowMs);
+        return Math.max(1, this.intervalMs + offsetMs);
+    }
+    clearTimer() {
+        if (!this.timer) {
+            return;
+        }
+        clearTimeout(this.timer);
+        this.timer = null;
+    }
+}

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

@@ -0,0 +1,143 @@
+import { WA_DEFAULTS, WA_IQ_TYPES, WA_NODE_TAGS, WA_XMLNS } from '../../protocol/constants.js';
+import { toError } from '../../util/primitives.js';
+export class WaNodeOrchestrator {
+    constructor(options) {
+        this.logger = options.logger;
+        this.sendNodeFn = options.sendNode;
+        this.defaultTimeoutMs = options.defaultTimeoutMs ?? WA_DEFAULTS.NODE_QUERY_TIMEOUT_MS;
+        this.hostDomain = options.hostDomain ?? WA_DEFAULTS.HOST_DOMAIN;
+        this.stanzaPrefix = null;
+        this.stanzaCounter = 0;
+        this.pendingQueries = new Map();
+    }
+    hasPending() {
+        return this.pendingQueries.size > 0;
+    }
+    clearPending(reason) {
+        this.logger.warn('clearing pending node queries', {
+            count: this.pendingQueries.size,
+            reason: reason.message
+        });
+        for (const pending of this.pendingQueries.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(reason);
+        }
+        this.pendingQueries.clear();
+    }
+    tryResolvePending(node) {
+        const id = node.attrs.id;
+        if (!id) {
+            return false;
+        }
+        const pending = this.pendingQueries.get(id);
+        if (!pending) {
+            return false;
+        }
+        clearTimeout(pending.timer);
+        this.pendingQueries.delete(id);
+        this.logger.trace('resolved pending query node', {
+            id,
+            tag: node.tag,
+            type: node.attrs.type
+        });
+        pending.resolve(node);
+        return true;
+    }
+    async handleIncomingNode(node) {
+        if (this.tryResolvePending(node)) {
+            return true;
+        }
+        if (node.tag !== WA_NODE_TAGS.IQ || node.attrs.type !== WA_IQ_TYPES.GET) {
+            return false;
+        }
+        const xmlns = node.attrs.xmlns;
+        if (xmlns !== WA_XMLNS.XMPP_PING && xmlns !== WA_XMLNS.WHATSAPP_PING) {
+            return false;
+        }
+        const attrs = {
+            to: node.attrs.from ?? this.hostDomain,
+            type: WA_IQ_TYPES.RESULT
+        };
+        if (node.attrs.id) {
+            attrs.id = node.attrs.id;
+        }
+        await this.sendNodeFn({
+            tag: WA_NODE_TAGS.IQ,
+            attrs
+        });
+        this.logger.debug('auto-responded to ping iq', { id: node.attrs.id, xmlns });
+        return true;
+    }
+    async sendNode(node) {
+        const outbound = this.withAutoId(node);
+        await this.sendNodeFn(outbound);
+    }
+    async query(node, timeoutMs = this.defaultTimeoutMs) {
+        const outbound = this.withAutoId(node);
+        const id = outbound.attrs.id;
+        if (!id) {
+            throw new Error('query node id is required');
+        }
+        if (this.pendingQueries.has(id)) {
+            throw new Error(`pending node id collision: ${id}`);
+        }
+        this.logger.debug('sending query node', {
+            id,
+            tag: outbound.tag,
+            type: outbound.attrs.type,
+            timeoutMs
+        });
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingQueries.delete(id);
+                this.logger.warn('query node timeout', { id, timeoutMs });
+                reject(new Error(`query timeout (${id}) after ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.pendingQueries.set(id, {
+                resolve,
+                reject,
+                timer
+            });
+            this.sendNodeFn(outbound).catch((error) => {
+                clearTimeout(timer);
+                this.pendingQueries.delete(id);
+                this.logger.warn('failed to send query node', {
+                    id,
+                    message: toError(error).message
+                });
+                reject(toError(error));
+            });
+        });
+    }
+    withAutoId(node) {
+        if (node.attrs.id) {
+            return node;
+        }
+        const prefix = this.getStanzaPrefix();
+        this.stanzaCounter += 1;
+        const generatedId = `${prefix}${this.stanzaCounter}`;
+        this.logger.trace('generated stanza id', { id: generatedId });
+        return {
+            ...node,
+            attrs: {
+                ...node.attrs,
+                id: generatedId
+            }
+        };
+    }
+    getStanzaPrefix() {
+        if (this.stanzaPrefix) {
+            return this.stanzaPrefix;
+        }
+        this.stanzaPrefix = this.generateStanzaPrefix();
+        return this.stanzaPrefix;
+    }
+    generateStanzaPrefix() {
+        const seed = crypto.getRandomValues(new Uint8Array(4));
+        const left = seed[0] * 256 + seed[1];
+        const right = seed[2] * 256 + seed[3];
+        const prefix = `${left}.${right}-`;
+        this.logger.debug('generated stanza prefix', { prefix });
+        return prefix;
+    }
+}

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

@@ -0,0 +1,64 @@
+import { EventEmitter } from 'node:events';
+import { ConsoleLogger } from '../../infra/log/ConsoleLogger.js';
+import { decodeBinaryNodeStanza, encodeBinaryNodeStanza } from '../binary/index.js';
+import { formatBinaryNodeAsXml } from '../node/xml.js';
+import { toError } from '../../util/primitives.js';
+export class WaNodeTransport extends EventEmitter {
+    constructor(logger = new ConsoleLogger('info')) {
+        super();
+        this.logger = logger;
+        this.comms = null;
+    }
+    on(event, listener) {
+        return super.on(event, listener);
+    }
+    bindComms(comms) {
+        this.comms = comms;
+        this.logger.debug('node transport bindComms', { connected: comms !== null });
+    }
+    async sendNode(node) {
+        const comms = this.comms;
+        if (!comms) {
+            throw new Error('comms is not connected');
+        }
+        this.logger.trace('node transport send node', {
+            tag: node.tag,
+            id: node.attrs.id,
+            type: node.attrs.type,
+            xml: this.shouldIncludeTraceXml() ? formatBinaryNodeAsXml(node) : undefined
+        });
+        const frame = encodeBinaryNodeStanza(node);
+        this.emit('node_out', node, frame);
+        this.emit('frame_out', frame);
+        await comms.sendFrame(frame);
+    }
+    async dispatchIncomingFrame(frame, onNode) {
+        this.emit('frame_in', frame);
+        let node;
+        try {
+            node = await decodeBinaryNodeStanza(frame);
+        }
+        catch (error) {
+            const normalized = toError(error);
+            if (normalized.message === 'stream end stanza is not a binary node') {
+                return;
+            }
+            this.logger.warn('failed to decode binary node frame', {
+                message: normalized.message
+            });
+            this.emit('decode_error', normalized, frame);
+            return;
+        }
+        this.emit('node_in', node, frame);
+        this.logger.trace('node transport node in', {
+            tag: node.tag,
+            id: node.attrs.id,
+            type: node.attrs.type,
+            xml: this.shouldIncludeTraceXml() ? formatBinaryNodeAsXml(node) : undefined
+        });
+        await onNode(node);
+    }
+    shouldIncludeTraceXml() {
+        return this.logger.level === 'trace';
+    }
+}

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

@@ -0,0 +1,101 @@
+import { WA_DEFAULTS, WA_NODE_TAGS, WA_XMLNS } from '../../../protocol/constants.js';
+import { buildIqNode } from '../../node/query.js';
+export function buildAccountDevicesSyncIq(userJids, sid) {
+    return buildIqNode('get', WA_DEFAULTS.HOST_DOMAIN, WA_XMLNS.USYNC, [
+        {
+            tag: WA_NODE_TAGS.USYNC,
+            attrs: {
+                sid,
+                index: '0',
+                last: 'true',
+                mode: WA_NODE_TAGS.QUERY,
+                context: WA_NODE_TAGS.NOTIFICATION
+            },
+            content: [
+                {
+                    tag: WA_NODE_TAGS.QUERY,
+                    attrs: {},
+                    content: [
+                        {
+                            tag: WA_NODE_TAGS.DEVICES,
+                            attrs: {
+                                version: '2'
+                            }
+                        }
+                    ]
+                },
+                {
+                    tag: WA_NODE_TAGS.LIST,
+                    attrs: {},
+                    content: userJids.map((jid) => ({
+                        tag: WA_NODE_TAGS.USER,
+                        attrs: {
+                            jid
+                        }
+                    }))
+                }
+            ]
+        }
+    ]);
+}
+export function buildAccountPictureSyncIq(meJid) {
+    return buildIqNode('get', WA_DEFAULTS.HOST_DOMAIN, WA_XMLNS.PROFILE_PICTURE, [
+        {
+            tag: WA_NODE_TAGS.PICTURE,
+            attrs: {
+                type: 'image',
+                query: 'url'
+            }
+        }
+    ], {
+        target: meJid
+    });
+}
+export function buildAccountPrivacySyncIq() {
+    return buildIqNode('get', WA_DEFAULTS.HOST_DOMAIN, WA_XMLNS.PRIVACY, [
+        {
+            tag: WA_NODE_TAGS.PRIVACY,
+            attrs: {}
+        }
+    ]);
+}
+export function buildAccountBlocklistSyncIq() {
+    return buildIqNode('get', WA_DEFAULTS.HOST_DOMAIN, WA_XMLNS.BLOCKLIST);
+}
+export function buildGroupsDirtySyncIq() {
+    return buildIqNode('get', WA_DEFAULTS.GROUP_SERVER, WA_XMLNS.GROUPS, [
+        {
+            tag: WA_NODE_TAGS.PARTICIPATING,
+            attrs: {},
+            content: [
+                {
+                    tag: WA_NODE_TAGS.PARTICIPANTS,
+                    attrs: {}
+                },
+                {
+                    tag: WA_NODE_TAGS.DESCRIPTION,
+                    attrs: {}
+                }
+            ]
+        }
+    ]);
+}
+export function buildNewsletterMetadataSyncIq() {
+    return buildIqNode('get', WA_DEFAULTS.HOST_DOMAIN, WA_XMLNS.NEWSLETTER, [
+        {
+            tag: WA_NODE_TAGS.MY_ADDONS,
+            attrs: {
+                limit: '1'
+            }
+        }
+    ]);
+}
+export function buildClearDirtyBitsIq(dirtyBits) {
+    return buildIqNode('set', WA_DEFAULTS.HOST_DOMAIN, WA_XMLNS.DIRTY_BITS, dirtyBits.map((dirtyBit) => ({
+        tag: 'clean',
+        attrs: {
+            type: dirtyBit.type,
+            timestamp: `${dirtyBit.timestamp}`
+        }
+    })));
+}

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

@@ -0,0 +1,47 @@
+import { WA_DEFAULTS } from '../../../protocol/defaults.js';
+import { WA_XMLNS } from '../../../protocol/nodes.js';
+import { buildIqNode } from '../../node/query.js';
+export function buildCreateGroupIq(input) {
+    const children = input.participants.map((jid) => ({
+        tag: 'participant',
+        attrs: { jid }
+    }));
+    if (input.description) {
+        children.push({
+            tag: 'description',
+            attrs: { id: `${Date.now()}` },
+            content: [{ tag: 'body', attrs: {}, content: input.description }]
+        });
+    }
+    return buildIqNode('set', WA_DEFAULTS.GROUP_SERVER, WA_XMLNS.GROUPS, [
+        {
+            tag: 'create',
+            attrs: { subject: input.subject },
+            content: children
+        }
+    ]);
+}
+export function buildGroupParticipantChangeIq(input) {
+    return buildIqNode('set', input.groupJid, WA_XMLNS.GROUPS, [
+        {
+            tag: input.action,
+            attrs: {},
+            content: input.participants.map((jid) => ({
+                tag: 'participant',
+                attrs: { jid }
+            }))
+        }
+    ]);
+}
+export function buildLeaveGroupIq(groupJids) {
+    return buildIqNode('set', WA_DEFAULTS.GROUP_SERVER, WA_XMLNS.GROUPS, [
+        {
+            tag: 'leave',
+            attrs: {},
+            content: groupJids.map((jid) => ({
+                tag: 'group',
+                attrs: { id: jid }
+            }))
+        }
+    ]);
+}

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

@@ -0,0 +1,7 @@
+export { buildAccountBlocklistSyncIq, buildAccountDevicesSyncIq, buildAccountPictureSyncIq, buildAccountPrivacySyncIq, buildClearDirtyBitsIq, buildGroupsDirtySyncIq, buildNewsletterMetadataSyncIq } from '../../node/builders/accountSync.js';
+export { buildCompanionFinishRequestNode, buildCompanionHelloRequestNode, buildGetCountryCodeRequestNode, buildIqResultNode, buildNotificationAckNode } from '../../node/builders/pairing.js';
+export { buildMediaConnIq } from '../../node/builders/media.js';
+export { buildDirectMessageFanoutNode, buildGroupDirectMessageNode, buildGroupRetryMessageNode, buildGroupSenderKeyMessageNode, buildInboundDeliveryReceiptNode, buildInboundMessageAckNode, buildInboundReceiptAckNode, buildInboundRetryReceiptNode, buildInboundRetryReceiptAckNode } from '../../node/builders/message.js';
+export { buildRetryReceiptNode } from '../../node/builders/retry.js';
+export { buildMissingPreKeysFetchIq, buildPreKeyUploadIq, buildSignedPreKeyRotateIq } from '../../node/builders/prekeys.js';
+export { buildCreateGroupIq, buildGroupParticipantChangeIq, buildLeaveGroupIq } from '../../node/builders/group.js';

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

@@ -0,0 +1,10 @@
+import { WA_DEFAULTS, WA_NODE_TAGS, WA_XMLNS } from '../../../protocol/constants.js';
+import { buildIqNode } from '../../node/query.js';
+export function buildMediaConnIq() {
+    return buildIqNode('set', WA_DEFAULTS.HOST_DOMAIN, WA_XMLNS.MEDIA, [
+        {
+            tag: WA_NODE_TAGS.MEDIA_CONN,
+            attrs: {}
+        }
+    ]);
+}