zapo-js 0.1.0

package/dist/esm/client/coordinators/WaStreamControlCoordinator.js

@@ -0,0 +1,120 @@
+import { WA_DISCONNECT_REASONS, WA_STREAM_SIGNALING } from '../../protocol/constants.js';
+import { toError } from '../../util/primitives.js';
+export function createStreamControlHandler(options) {
+    const { logger, getComms, clearPendingQueries, clearMediaConnCache, disconnect, clearStoredCredentials, connect } = options;
+    let lifecyclePromise = null;
+    const runStreamControlLifecycle = (reason, action) => {
+        if (lifecyclePromise) {
+            logger.debug('stream-control lifecycle already running', { reason });
+            return lifecyclePromise;
+        }
+        lifecyclePromise = action().finally(() => {
+            lifecyclePromise = null;
+        });
+        return lifecyclePromise;
+    };
+    const restartBackendAfterStreamControl = async (reason) => {
+        logger.info('restarting backend after stream control', { reason });
+        try {
+            await connect();
+        }
+        catch (error) {
+            logger.warn('failed to restart backend after stream control', {
+                reason,
+                message: toError(error).message
+            });
+        }
+    };
+    const resumeSocketDueToStreamError = async (reason) => {
+        const comms = getComms();
+        if (!comms) {
+            return;
+        }
+        logger.info('resuming socket due to stream control node', { reason });
+        clearPendingQueries(new Error(`socket resume requested by ${reason}`));
+        clearMediaConnCache();
+        try {
+            await comms.closeSocketAndResume();
+        }
+        catch (error) {
+            logger.warn('failed to resume socket for stream control node', {
+                reason,
+                message: toError(error).message
+            });
+        }
+    };
+    const forceLoginDueToStreamError = async (code) => {
+        await runStreamControlLifecycle(`stream_error_code_${code}`, async () => {
+            logger.warn('received forced login stream error; starting login lifecycle', {
+                code
+            });
+            await disconnect();
+            await clearStoredCredentials();
+            await restartBackendAfterStreamControl(`stream_error_code_${code}`);
+        });
+    };
+    const disconnectDueToStreamError = async (reason) => {
+        await runStreamControlLifecycle(reason, async () => {
+            logger.warn('disconnecting due to stream control node', { reason });
+            await disconnect();
+        });
+    };
+    const logoutDueToStreamError = async (reason, shouldRestartBackend) => {
+        await runStreamControlLifecycle(reason, async () => {
+            logger.warn('logging out due to stream control node', {
+                reason,
+                shouldRestartBackend
+            });
+            await disconnect();
+            await clearStoredCredentials();
+            if (shouldRestartBackend) {
+                await restartBackendAfterStreamControl(reason);
+            }
+        });
+    };
+    return {
+        handleStreamControlResult: async (result) => {
+            switch (result.kind) {
+                case 'xmlstreamend':
+                    logger.info('received xmlstreamend stanza');
+                    return;
+                case 'stream_error_code':
+                    logger.warn('received stream:error with code', { code: result.code });
+                    if (result.code >= 500 && result.code < 600) {
+                        if (result.code === WA_STREAM_SIGNALING.FORCE_LOGIN_CODE) {
+                            await forceLoginDueToStreamError(result.code);
+                            return;
+                        }
+                        if (result.code === WA_STREAM_SIGNALING.FORCE_LOGOUT_CODE) {
+                            await logoutDueToStreamError(`stream_error_code_${WA_STREAM_SIGNALING.FORCE_LOGOUT_CODE}`, true);
+                            return;
+                        }
+                    }
+                    await resumeSocketDueToStreamError(`stream_error_code_${result.code}`);
+                    return;
+                case 'stream_error_replaced':
+                    logger.warn('received stream:error replaced, stopping client');
+                    await disconnectDueToStreamError(WA_DISCONNECT_REASONS.STREAM_ERROR_REPLACED);
+                    return;
+                case 'stream_error_device_removed':
+                    logger.warn('received stream:error device removed, logging out');
+                    await logoutDueToStreamError(WA_DISCONNECT_REASONS.STREAM_ERROR_DEVICE_REMOVED, false);
+                    return;
+                case 'stream_error_ack':
+                    logger.warn('received stream:error ack', { id: result.id });
+                    await resumeSocketDueToStreamError(WA_DISCONNECT_REASONS.STREAM_ERROR_ACK);
+                    return;
+                case 'stream_error_xml_not_well_formed':
+                    logger.warn('received stream:error xml-not-well-formed');
+                    await resumeSocketDueToStreamError(WA_DISCONNECT_REASONS.STREAM_ERROR_XML_NOT_WELL_FORMED);
+                    return;
+                case 'stream_error_other':
+                    logger.warn('received stream:error other');
+                    await resumeSocketDueToStreamError(WA_DISCONNECT_REASONS.STREAM_ERROR_OTHER);
+                    return;
+                default:
+                    return;
+            }
+        }
+    };
+}

package/dist/esm/client/dirty.js

@@ -0,0 +1,250 @@
+import { randomBytesAsync } from '../crypto/index.js';
+import { WA_ACCOUNT_SYNC_PROTOCOLS, WA_DEFAULTS, WA_DIRTY_PROTOCOLS, WA_DIRTY_TYPES, WA_IQ_TYPES, WA_SUPPORTED_DIRTY_TYPES } from '../protocol/constants.js';
+import { toUserJid } from '../protocol/jid.js';
+import { buildAccountBlocklistSyncIq, buildAccountDevicesSyncIq, buildAccountPictureSyncIq, buildAccountPrivacySyncIq, buildClearDirtyBitsIq, buildGroupsDirtySyncIq, buildNewsletterMetadataSyncIq } from '../transport/node/builders/accountSync.js';
+import { getNodeChildren } from '../transport/node/helpers.js';
+import { assertIqResult, parseIqError } from '../transport/node/query.js';
+import { bytesToHex } from '../util/bytes.js';
+import { toError } from '../util/primitives.js';
+const SUPPORTED_DIRTY_TYPES = new Set(WA_SUPPORTED_DIRTY_TYPES);
+const ACCOUNT_SYNC_PROTOCOL_SET = new Set(WA_ACCOUNT_SYNC_PROTOCOLS);
+function parseDirtyBitNode(node, logger) {
+    const type = node.attrs.type;
+    const timestamp = Number.parseInt(node.attrs.timestamp ?? '', 10);
+    if (!type || !Number.isFinite(timestamp)) {
+        logger.warn('received invalid dirty bit node', {
+            type,
+            timestamp: node.attrs.timestamp
+        });
+        return null;
+    }
+    const protocols = getNodeChildren(node).map((child) => child.tag);
+    return {
+        type,
+        timestamp,
+        protocols
+    };
+}
+function splitDirtyBitsBySupport(dirtyBits) {
+    return {
+        supported: dirtyBits.filter((dirtyBit) => SUPPORTED_DIRTY_TYPES.has(dirtyBit.type)),
+        unsupported: dirtyBits.filter((dirtyBit) => !SUPPORTED_DIRTY_TYPES.has(dirtyBit.type))
+    };
+}
+function resolveAccountSyncProtocols(protocols) {
+    const selected = protocols.filter((protocol) => ACCOUNT_SYNC_PROTOCOL_SET.has(protocol));
+    if (selected.length > 0) {
+        return selected;
+    }
+    return WA_ACCOUNT_SYNC_PROTOCOLS;
+}
+export function parseDirtyBits(nodes, logger) {
+    return nodes
+        .map((node) => parseDirtyBitNode(node, logger))
+        .filter((dirtyBit) => dirtyBit !== null);
+}
+export async function handleDirtyBits(runtime, dirtyBits) {
+    const meJid = runtime.getCurrentCredentials()?.meJid ?? null;
+    if (!meJid) {
+        runtime.logger.trace('dirty bits skipped: session is not registered');
+        return;
+    }
+    const { supported, unsupported } = splitDirtyBitsBySupport(dirtyBits);
+    runtime.logger.info('handling dirty bits from info bulletin', {
+        supported: supported.map((entry) => entry.type).join(','),
+        unsupported: unsupported.map((entry) => entry.type).join(',')
+    });
+    const handledSupported = (await Promise.allSettled(supported.map(async (dirtyBit) => handleDirtyBit(runtime, dirtyBit)))).flatMap((result, index) => {
+        if (result.status === 'fulfilled') {
+            return [supported[index]];
+        }
+        runtime.logger.warn('failed handling dirty bit', {
+            type: supported[index].type,
+            message: toError(result.reason).message
+        });
+        return [];
+    });
+    await clearDirtyBits(runtime, unsupported.concat(handledSupported));
+}
+async function handleDirtyBit(runtime, dirtyBit) {
+    switch (dirtyBit.type) {
+        case WA_DIRTY_TYPES.ACCOUNT_SYNC:
+            await handleAccountSyncDirtyBit(runtime, dirtyBit.protocols);
+            return;
+        case WA_DIRTY_TYPES.SYNCD_APP_STATE:
+            await handleSyncdAppStateDirtyBit(runtime);
+            return;
+        case WA_DIRTY_TYPES.GROUPS:
+            await syncGroupsDirtyBit(runtime);
+            return;
+        case WA_DIRTY_TYPES.NEWSLETTER_METADATA:
+            await syncNewsletterMetadataDirtyBit(runtime);
+            return;
+        default:
+            runtime.logger.debug('received unsupported dirty bit', {
+                type: dirtyBit.type
+            });
+    }
+}
+async function handleAccountSyncDirtyBit(runtime, protocols) {
+    const selectedProtocols = resolveAccountSyncProtocols(protocols);
+    runtime.logger.info('received account_sync dirty bit', {
+        protocols: selectedProtocols.join(',')
+    });
+    const failures = [];
+    await Promise.all(selectedProtocols.map(async (protocol) => {
+        try {
+            await runAccountSyncProtocol(runtime, protocol);
+        }
+        catch (error) {
+            failures.push(protocol);
+            runtime.logger.warn('account_sync protocol failed', {
+                protocol,
+                message: toError(error).message
+            });
+        }
+    }));
+    if (failures.length > 0) {
+        throw new Error(`account_sync protocols failed: ${failures.join(',')}`);
+    }
+}
+async function runAccountSyncProtocol(runtime, protocol) {
+    switch (protocol) {
+        case WA_DIRTY_PROTOCOLS.DEVICES:
+            await syncAccountDevicesDirtyBit(runtime);
+            return;
+        case WA_DIRTY_PROTOCOLS.PICTURE:
+            await syncAccountPictureDirtyBit(runtime);
+            return;
+        case WA_DIRTY_PROTOCOLS.PRIVACY:
+            await syncAccountPrivacyDirtyBit(runtime);
+            return;
+        case WA_DIRTY_PROTOCOLS.BLOCKLIST:
+            await syncAccountBlocklistDirtyBit(runtime);
+            return;
+        case WA_DIRTY_PROTOCOLS.NOTICE:
+            await syncAccountNoticeDirtyBit(runtime);
+            return;
+        default:
+            runtime.logger.debug('unsupported account_sync protocol', {
+                protocol
+            });
+    }
+}
+async function handleSyncdAppStateDirtyBit(runtime) {
+    runtime.logger.info('received syncd_app_state dirty bit, starting sync');
+    await runtime.syncAppState();
+}
+async function syncAccountDevicesDirtyBit(runtime) {
+    const credentials = runtime.getCurrentCredentials();
+    const meJid = credentials?.meJid ?? null;
+    if (!meJid) {
+        runtime.logger.warn('account_sync devices skipped: meJid is missing');
+        return;
+    }
+    const userJids = resolveAccountSyncDeviceTargets(credentials);
+    if (userJids.length === 0) {
+        runtime.logger.warn('account_sync devices skipped: no valid account_sync targets');
+        return;
+    }
+    await runSyncQuery(runtime, {
+        queryContext: 'account_sync.devices',
+        node: buildAccountDevicesSyncIq(userJids, await generateUsyncSid()),
+        logMessage: 'account_sync devices synchronized',
+        contextData: { meJid, targets: userJids.join(',') }
+    });
+}
+async function syncAccountPictureDirtyBit(runtime) {
+    const meJid = runtime.getCurrentCredentials()?.meJid ?? null;
+    if (!meJid) {
+        runtime.logger.warn('account_sync picture skipped: meJid is missing');
+        return;
+    }
+    const targetJid = toUserJid(meJid);
+    const response = await runtime.queryWithContext('account_sync.picture', buildAccountPictureSyncIq(targetJid), WA_DEFAULTS.IQ_TIMEOUT_MS, { meJid, target: targetJid });
+    if (response.tag !== 'iq') {
+        throw new Error(`account_sync.picture returned non-iq node (${response.tag})`);
+    }
+    if (response.attrs.type === WA_IQ_TYPES.RESULT) {
+        runtime.logger.debug('account_sync picture synchronized', {
+            meJid,
+            target: targetJid
+        });
+        return;
+    }
+    const iqError = parseIqError(response);
+    const isPictureMissing = (iqError.numericCode === 404 || iqError.code === '404') &&
+        iqError.text.toLowerCase() === 'item-not-found';
+    if (isPictureMissing) {
+        runtime.logger.debug('account_sync picture skipped: no profile picture found', {
+            meJid,
+            target: targetJid
+        });
+        return;
+    }
+    throw new Error(`account_sync.picture iq failed (${iqError.code}: ${iqError.text})`);
+}
+async function syncAccountPrivacyDirtyBit(runtime) {
+    await runSyncQuery(runtime, {
+        queryContext: 'account_sync.privacy',
+        node: buildAccountPrivacySyncIq(),
+        logMessage: 'account_sync privacy synchronized'
+    });
+}
+async function syncAccountBlocklistDirtyBit(runtime) {
+    await runSyncQuery(runtime, {
+        queryContext: 'account_sync.blocklist',
+        node: buildAccountBlocklistSyncIq(),
+        logMessage: 'account_sync blocklist synchronized'
+    });
+}
+async function syncAccountNoticeDirtyBit(runtime) {
+    runtime.logger.info('account_sync notice protocol received (no GraphQL/MEX job configured)');
+}
+async function syncGroupsDirtyBit(runtime) {
+    await runSyncQuery(runtime, {
+        queryContext: 'dirty.groups',
+        assertContext: 'groups',
+        node: buildGroupsDirtySyncIq(),
+        logMessage: 'groups dirty sync completed'
+    });
+}
+async function syncNewsletterMetadataDirtyBit(runtime) {
+    runtime.logger.info('newsletter_metadata dirty bit received (GraphQL/MEX sync intentionally disabled)');
+    await runtime.queryWithContext('dirty.newsletter_metadata', buildNewsletterMetadataSyncIq(), WA_DEFAULTS.IQ_TIMEOUT_MS);
+}
+async function generateUsyncSid() {
+    return bytesToHex(await randomBytesAsync(8));
+}
+function resolveAccountSyncDeviceTargets(credentials) {
+    if (!credentials?.meJid) {
+        return [];
+    }
+    const dedup = new Set();
+    dedup.add(toUserJid(credentials.meJid));
+    if (credentials.meLid && credentials.meLid.includes('@')) {
+        dedup.add(toUserJid(credentials.meLid));
+    }
+    return [...dedup];
+}
+async function runSyncQuery(runtime, args) {
+    const response = await runtime.queryWithContext(args.queryContext, args.node, WA_DEFAULTS.IQ_TIMEOUT_MS, args.contextData);
+    assertIqResult(response, args.assertContext ?? args.queryContext);
+    runtime.logger.debug(args.logMessage, args.contextData);
+}
+async function clearDirtyBits(runtime, dirtyBits) {
+    try {
+        await runtime.queryWithContext('dirty.clear', buildClearDirtyBitsIq(dirtyBits), WA_DEFAULTS.IQ_TIMEOUT_MS, {
+            count: dirtyBits.length
+        });
+        runtime.logger.info('dirty bits cleared', {
+            count: dirtyBits.length
+        });
+    }
+    catch (error) {
+        runtime.logger.warn('failed to clear dirty bits', {
+            count: dirtyBits.length,
+            message: toError(error).message
+        });
+    }
+}

package/dist/esm/client/events/chat.js

@@ -0,0 +1,223 @@
+export function parseChatEventFromAppStateMutation(mutation) {
+    const value = mutation.value;
+    const parsedIndex = parseMutationIndex(mutation.index);
+    if (!parsedIndex?.chatJid) {
+        return null;
+    }
+    const syncActionValueKey = value ? findPresentSyncActionValueKey(value) : null;
+    const baseEvent = {
+        source: mutation.source,
+        collection: mutation.collection,
+        operation: mutation.operation,
+        mutationIndex: mutation.index,
+        indexAction: parsedIndex?.action,
+        indexParts: parsedIndex?.parts,
+        syncActionValueKey: syncActionValueKey ?? undefined,
+        chatJid: parsedIndex?.chatJid,
+        timestamp: mutation.timestamp,
+        version: mutation.version
+    };
+    if (value?.archiveChatAction) {
+        return {
+            ...baseEvent,
+            action: 'archive',
+            ...pickOptionalPrimitive('archived', value.archiveChatAction.archived, 'boolean')
+        };
+    }
+    if (value?.muteAction) {
+        return {
+            ...baseEvent,
+            action: 'mute',
+            ...pickOptionalPrimitive('muted', value.muteAction.muted, 'boolean'),
+            ...pickOptionalPrimitive('muteEndTimestampMs', parseOptionalLong(value.muteAction.muteEndTimestamp), 'number')
+        };
+    }
+    if (value?.pinAction) {
+        return {
+            ...baseEvent,
+            action: 'pin',
+            ...pickOptionalPrimitive('pinned', value.pinAction.pinned, 'boolean')
+        };
+    }
+    if (value?.markChatAsReadAction) {
+        return {
+            ...baseEvent,
+            action: 'mark_read',
+            ...pickOptionalPrimitive('read', value.markChatAsReadAction.read, 'boolean')
+        };
+    }
+    if (value?.clearChatAction) {
+        return {
+            ...baseEvent,
+            action: 'clear',
+            ...pickOptionalPrimitive('deleteStarred', parseIndexFlag(parsedIndex?.parts[2]), 'boolean'),
+            ...pickOptionalPrimitive('deleteMedia', parseIndexFlag(parsedIndex?.parts[3]), 'boolean')
+        };
+    }
+    if (value?.deleteChatAction) {
+        return {
+            ...baseEvent,
+            action: 'delete',
+            ...pickOptionalPrimitive('deleteMedia', parseIndexFlag(parsedIndex?.parts[2]), 'boolean')
+        };
+    }
+    if (value?.lockChatAction) {
+        return {
+            ...baseEvent,
+            action: 'lock',
+            ...pickOptionalPrimitive('locked', value.lockChatAction.locked, 'boolean')
+        };
+    }
+    if (value?.chatAssignment) {
+        return {
+            ...baseEvent,
+            action: 'chat_assignment',
+            ...pickOptionalPrimitive('deviceAgentId', value.chatAssignment.deviceAgentID, 'string')
+        };
+    }
+    const fallbackAction = normalizeIndexAction(parsedIndex?.action) ??
+        normalizeValueActionKey(syncActionValueKey);
+    if (!fallbackAction) {
+        return null;
+    }
+    return {
+        ...baseEvent,
+        action: fallbackAction
+    };
+}
+function parseMutationIndex(index) {
+    let parsed;
+    try {
+        parsed = JSON.parse(index);
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(parsed) || parsed.length === 0) {
+        return null;
+    }
+    const parts = [];
+    for (const item of parsed) {
+        if (typeof item === 'string') {
+            parts.push(item);
+            continue;
+        }
+        if (typeof item === 'number' || typeof item === 'boolean') {
+            parts.push(String(item));
+            continue;
+        }
+        return null;
+    }
+    return {
+        action: parts[0],
+        parts,
+        chatJid: extractChatJid(parts)
+    };
+}
+function normalizeIndexAction(indexAction) {
+    if (!indexAction) {
+        return null;
+    }
+    switch (indexAction) {
+        case 'archive':
+            return 'archive';
+        case 'mute':
+            return 'mute';
+        case 'pin':
+        case 'pin_v1':
+            return 'pin';
+        case 'markChatAsRead':
+            return 'mark_read';
+        case 'clearChat':
+            return 'clear';
+        case 'deleteChat':
+            return 'delete';
+        case 'lock':
+            return 'lock';
+        case 'agentChatAssignment':
+            return 'chat_assignment';
+        default:
+            return toSnakeCase(indexAction);
+    }
+}
+function normalizeValueActionKey(syncActionValueKey) {
+    if (!syncActionValueKey) {
+        return null;
+    }
+    switch (syncActionValueKey) {
+        case 'archiveChatAction':
+            return 'archive';
+        case 'muteAction':
+            return 'mute';
+        case 'pinAction':
+            return 'pin';
+        case 'markChatAsReadAction':
+            return 'mark_read';
+        case 'clearChatAction':
+            return 'clear';
+        case 'deleteChatAction':
+            return 'delete';
+        case 'lockChatAction':
+            return 'lock';
+        case 'chatAssignment':
+            return 'chat_assignment';
+        default:
+            return toSnakeCase(syncActionValueKey.endsWith('Action')
+                ? syncActionValueKey.slice(0, -'Action'.length)
+                : syncActionValueKey);
+    }
+}
+function parseOptionalLong(value) {
+    if (value === null || value === undefined) {
+        return undefined;
+    }
+    try {
+        const parsed = typeof value === 'number' ? value : value.toNumber();
+        if (!Number.isFinite(parsed) || !Number.isSafeInteger(parsed)) {
+            return undefined;
+        }
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseIndexFlag(value) {
+    if (value === '1') {
+        return true;
+    }
+    if (value === '0') {
+        return false;
+    }
+    return undefined;
+}
+function extractChatJid(parts) {
+    for (let index = 1; index < parts.length; index += 1) {
+        const value = parts[index];
+        if (value.includes('@')) {
+            return value;
+        }
+    }
+    return undefined;
+}
+function findPresentSyncActionValueKey(value) {
+    for (const [key, keyValue] of Object.entries(value)) {
+        if (key === 'timestamp') {
+            continue;
+        }
+        if (keyValue === null || keyValue === undefined) {
+            continue;
+        }
+        return key;
+    }
+    return null;
+}
+function toSnakeCase(value) {
+    return value
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .replace(/-/g, '_')
+        .toLowerCase();
+}
+function pickOptionalPrimitive(key, value, type) {
+    return typeof value === type ? { [key]: value } : {};
+}