zapo-js 1.4.0 → 1.5.0

package/dist/client/WaClientFactory.d.ts

@@ -14,6 +14,7 @@ import { WaIncomingNodeCoordinator } from './coordinators/WaIncomingNodeCoordina
 import { type WaLowLevelCoordinator } from './coordinators/WaLowLevelCoordinator';
 import { WaMessageCoordinator } from './coordinators/WaMessageCoordinator';
 import { WaMessageDispatchCoordinator } from './coordinators/WaMessageDispatchCoordinator';
+import { WaMobileCoordinator } from './coordinators/WaMobileCoordinator';
 import { type WaNewsletterCoordinator } from './coordinators/WaNewsletterCoordinator';
 import { WaPassiveTasksCoordinator } from './coordinators/WaPassiveTasksCoordinator';
 import { type WaPresenceCoordinator } from './coordinators/WaPresenceCoordinator';
@@ -119,6 +120,8 @@ export interface WaClientDependencies {
     readonly trustedContactToken: WaTrustedContactTokenCoordinator;
     readonly abPropsCoordinator: WaAbPropsCoordinator;
     readonly peerDataOperation: PeerDataOperationRequester;
+    readonly mobileCoordinator: WaMobileCoordinator;
+    readonly isMobilePrimary: () => boolean;
 }
 export declare function resolveWaClientBase(options: WaClientOptions, logger: Logger): WaClientBase;
 export declare function buildWaClientDependencies(input: {

package/dist/client/WaClientFactory.js

@@ -17,6 +17,7 @@ const WaIncomingNodeCoordinator_1 = require("./coordinators/WaIncomingNodeCoordi
 const WaLowLevelCoordinator_1 = require("./coordinators/WaLowLevelCoordinator");
 const WaMessageCoordinator_1 = require("./coordinators/WaMessageCoordinator");
 const WaMessageDispatchCoordinator_1 = require("./coordinators/WaMessageDispatchCoordinator");
+const WaMobileCoordinator_1 = require("./coordinators/WaMobileCoordinator");
 const WaNewsletterCoordinator_1 = require("./coordinators/WaNewsletterCoordinator");
 const WaOfflineResumeCoordinator_1 = require("./coordinators/WaOfflineResumeCoordinator");
 const WaPassiveTasksCoordinator_1 = require("./coordinators/WaPassiveTasksCoordinator");
@@ -65,7 +66,6 @@ const WaNodeTransport_1 = require("../transport/node/WaNodeTransport");
 const proxy_1 = require("../transport/proxy");
 const clock_1 = require("../util/clock");
 const primitives_1 = require("../util/primitives");
-const runtime_1 = require("../util/runtime");
 function assertProxyTransport(value, path) {
     if (value === undefined) {
         return;
@@ -89,7 +89,7 @@ function validateProxyOptions(options) {
 }
 function resolveWaClientBase(options, logger) {
     validateProxyOptions(options);
-    const deviceBrowser = options.deviceBrowser ?? constants_1.WA_DEFAULTS.DEVICE_BROWSER;
+    const device = (0, constants_1.resolveWaDeviceIdentity)(options);
     const sessionId = options.sessionId.trim();
     if (sessionId.length === 0) {
         throw new Error('sessionId must be a non-empty string');
@@ -98,9 +98,9 @@ function resolveWaClientBase(options, logger) {
     const normalizedOptions = Object.freeze({
         ...options,
         sessionId,
-        deviceBrowser,
-        deviceOsDisplayName: options.deviceOsDisplayName ?? (0, runtime_1.getRuntimeOsDisplayName)(),
-        devicePlatform: options.devicePlatform ?? (0, constants_1.getWaCompanionPlatformId)(deviceBrowser),
+        deviceBrowser: device.browser,
+        deviceOsDisplayName: device.osDisplayName,
+        devicePlatform: device.platform,
         urls: options.urls ?? options.chatSocketUrls ?? constants_1.WA_DEFAULTS.CHAT_SOCKET_URLS,
         iqTimeoutMs: options.iqTimeoutMs ?? constants_1.WA_DEFAULTS.IQ_TIMEOUT_MS,
         nodeQueryTimeoutMs: options.nodeQueryTimeoutMs ?? constants_1.WA_DEFAULTS.NODE_QUERY_TIMEOUT_MS,
@@ -455,6 +455,7 @@ function buildWaClientDependencies(input) {
     });
     messageDispatch = new WaMessageDispatchCoordinator_1.WaMessageDispatchCoordinator({
         logger,
+        emitMessageSend: (event) => runtime.emitEvent('message_send', event),
         messageClient,
         retryTracker,
         sessionResolver,
@@ -591,6 +592,7 @@ function buildWaClientDependencies(input) {
         serverClock,
         emitSnapshotMutations: options.chatEvents?.emitSnapshotMutations === true,
         emitMutation: (event) => runtime.emitEvent('mutation', event),
+        emitMutationSend: (event) => runtime.emitEvent('mutation_send', event),
         nctSaltSink: (salt) => trustedContactToken.handleNctSaltSync(salt),
         contactSink: runtime.persistContact,
         pushNameSink: (name) => {
@@ -1017,6 +1019,20 @@ function buildWaClientDependencies(input) {
         isConnected: () => connectionManager?.isConnected() ?? false,
         defaultIqTimeoutMs: options.iqTimeoutMs
     });
+    const mobileCoordinator = new WaMobileCoordinator_1.WaMobileCoordinator({
+        logger,
+        authClient,
+        messageDispatch,
+        chatCoordinator: appStateMutations,
+        deviceSync: signalDeviceSync,
+        appStateStore: sessionStore.appState,
+        queryWithContext: runtime.queryWithContext,
+        emitEvent: runtime.emitEvent,
+        registerIncomingHandler: (registration) => incomingNode.registerIncomingHandler(registration),
+        isMobilePrimary,
+        persistence: options.companionHost?.persistence,
+        includePem: options.companionHost?.includePem
+    });
     return {
         nodeTransport,
         nodeOrchestrator,
@@ -1057,6 +1073,8 @@ function buildWaClientDependencies(input) {
         connectionManager,
         trustedContactToken,
         abPropsCoordinator,
-        peerDataOperation
+        peerDataOperation,
+        mobileCoordinator,
+        isMobilePrimary
     };
 }

package/dist/client/coordinators/WaAppStateMutationCoordinator.d.ts

@@ -33,6 +33,7 @@ interface WaAppStateMutationCoordinatorOptions {
     readonly serverClock: ServerClock;
     readonly archiveRangeLimit?: number;
     readonly emitMutation?: (event: WaAppStateMutationEvent) => void;
+    readonly emitMutationSend?: (event: WaAppStateMutationEvent) => void;
     readonly emitSnapshotMutations?: boolean;
     readonly nctSaltSink?: (salt: Uint8Array | null) => Promise<void>;
     /**
@@ -79,6 +80,7 @@ export declare class WaAppStateMutationCoordinator {
     private readonly serverClock;
     private readonly archiveRangeLimit;
     private readonly emitMutation?;
+    private readonly emitMutationSend?;
     private readonly emitSnapshotMutations;
     private readonly nctSaltSink?;
     private readonly contactSink?;
@@ -160,6 +162,12 @@ export declare class WaAppStateMutationCoordinator {
      */
     flushMutations(): Promise<void>;
     private enqueueAndFlush;
+    /**
+     * Surfaces an action this client is sending via the outbound `mutation_send`
+     * event, so consumers can observe their own change at action time. Parse
+     * failures are swallowed (best-effort).
+     */
+    private emitLocalMutation;
     private enqueueMutation;
     private takePendingMutationsBatch;
     private flushPendingMutationsLoop;

package/dist/client/coordinators/WaAppStateMutationCoordinator.js

@@ -14,6 +14,8 @@ const WA_APP_STATE_MUTATION_FLUSH_SUCCESS_STATES = new Set([
     constants_1.WA_APP_STATE_COLLECTION_STATES.SUCCESS_HAS_MORE
 ]);
 const WA_APP_STATE_ARCHIVE_RANGE_DEFAULT_LIMIT = 256;
+/** Placeholder MACs for locally-emitted mutation events (the parser ignores them). */
+const WA_EMPTY_MUTATION_MAC = new Uint8Array(0);
 function buildMutationIndexFromSchema(schema, indexArgs) {
     const parts = new Array(schema.indexParts.length);
     const args = indexArgs;
@@ -160,7 +162,6 @@ function buildRemoveMutationFromSchema(input) {
         collection: input.schema.collection,
         operation: 'remove',
         index: buildMutationIndexFromSchema(input.schema, input.indexArgs),
-        previousValue: { timestamp: input.timestamp },
         version: input.schema.version,
         timestamp: input.timestamp
     };
@@ -180,6 +181,7 @@ class WaAppStateMutationCoordinator {
         this.serverClock = options.serverClock;
         this.archiveRangeLimit = (0, coercion_1.resolvePositive)(options.archiveRangeLimit, WA_APP_STATE_ARCHIVE_RANGE_DEFAULT_LIMIT, 'WaAppStateMutationCoordinatorOptions.archiveRangeLimit');
         this.emitMutation = options.emitMutation;
+        this.emitMutationSend = options.emitMutationSend;
         this.emitSnapshotMutations = options.emitSnapshotMutations === true;
         this.nctSaltSink = options.nctSaltSink;
         this.contactSink = options.contactSink;
@@ -617,9 +619,43 @@ class WaAppStateMutationCoordinator {
     async enqueueAndFlush(mutations) {
         for (const mutation of mutations) {
             this.enqueueMutation(mutation);
+            this.emitLocalMutation(mutation);
         }
         await this.flushMutations();
     }
+    /**
+     * Surfaces an action this client is sending via the outbound `mutation_send`
+     * event, so consumers can observe their own change at action time. Parse
+     * failures are swallowed (best-effort).
+     */
+    emitLocalMutation(input) {
+        if (!this.emitMutationSend)
+            return;
+        const value = input.operation === 'set' ? input.value : null;
+        try {
+            const event = (0, appstate_mutation_1.parseAppStateMutationEvent)({
+                collection: input.collection,
+                operation: input.operation,
+                source: 'local',
+                index: input.index,
+                value,
+                version: input.version,
+                indexMac: WA_EMPTY_MUTATION_MAC,
+                valueMac: WA_EMPTY_MUTATION_MAC,
+                keyId: WA_EMPTY_MUTATION_MAC,
+                timestamp: input.timestamp
+            });
+            if (event)
+                this.emitMutationSend(event);
+        }
+        catch (error) {
+            this.logger.debug('failed to emit local app-state mutation event', {
+                collection: input.collection,
+                index: input.index,
+                message: (0, primitives_1.toError)(error).message
+            });
+        }
+    }
     enqueueMutation(mutation) {
         const key = `${mutation.collection}\u0001${mutation.index}`;
         if (this.pendingMutations.has(key)) {

package/dist/client/coordinators/WaGroupCoordinator.js

@@ -5,6 +5,7 @@ const group_1 = require("../events/group");
 const defaults_1 = require("../../protocol/defaults");
 const group_2 = require("../../protocol/group");
 const jid_1 = require("../../protocol/jid");
+const message_1 = require("../../protocol/message");
 const nodes_1 = require("../../protocol/nodes");
 const notification_1 = require("../../protocol/notification");
 const account_sync_1 = require("../../transport/node/builders/account-sync");
@@ -90,7 +91,11 @@ function parseGroupCommons(target) {
         ? (0, helpers_1.findNodeChild)(membershipApprovalNode, nodes_1.WA_NODE_TAGS.GROUP_JOIN)
         : undefined;
     const addressingModeRaw = attrs.addressing_mode;
-    const addressingMode = addressingModeRaw === 'lid' ? 'lid' : addressingModeRaw === 'pn' ? 'pn' : undefined;
+    const addressingMode = addressingModeRaw === message_1.WA_ADDRESSING_MODES.LID
+        ? message_1.WA_ADDRESSING_MODES.LID
+        : addressingModeRaw === message_1.WA_ADDRESSING_MODES.PN
+            ? message_1.WA_ADDRESSING_MODES.PN
+            : undefined;
     const rawJid = attrs.id ?? attrs.jid ?? '';
     const jid = rawJid && !rawJid.includes('@') ? `${rawJid}@${defaults_1.WA_DEFAULTS.GROUP_SERVER}` : rawJid;
     return {

package/dist/client/coordinators/WaMessageDispatchCoordinator.d.ts

@@ -3,7 +3,7 @@ import type { WaAuthCredentials } from '../../auth/types';
 import type { DeviceFanoutResolver } from '../messaging/fanout';
 import type { GroupMetadataCache } from '../messaging/group-metadata';
 import type { AppStateSyncKeyProtocol } from '../messaging/key-protocol';
-import type { WaGroupEvent, WaSendMessageOptions, WaSignalMessagePublishInput } from '../types';
+import type { WaGroupEvent, WaOutgoingMessageEvent, WaSendMessageOptions, WaSignalMessagePublishInput } from '../types';
 import type { Logger } from '../../infra/log/types';
 import { type WaSendContextInfo } from '../../message/context-info';
 import { type IcdcMeta } from '../../message/crypto/icdc';
@@ -26,6 +26,8 @@ import type { BinaryNode } from '../../transport/types';
 import type { ServerClock } from '../../util/clock';
 interface WaMessageDispatchCoordinatorOptions {
     readonly logger: Logger;
+    /** Emits the outbound decrypted message (`message_send` event); best-effort. */
+    readonly emitMessageSend?: (event: WaOutgoingMessageEvent) => void;
     readonly messageClient: WaMessageClient;
     readonly retryTracker: OutboundRetryTracker;
     readonly sessionResolver: SignalSessionResolver;

package/dist/client/coordinators/WaMessageDispatchCoordinator.js

@@ -203,6 +203,16 @@ class WaMessageDispatchCoordinator {
             }
             : withViewOnce;
         const upload = built.upload;
+        if (this.deps.emitMessageSend) {
+            try {
+                this.deps.emitMessageSend({ to: recipientJid, id: sendOptions.id, message });
+            }
+            catch (error) {
+                this.deps.logger.debug('message_send emit failed', {
+                    message: (0, primitives_2.toError)(error).message
+                });
+            }
+        }
         const messageWithOverride = options.messageSecret
             ? {
                 ...message,
@@ -894,17 +904,17 @@ class WaMessageDispatchCoordinator {
     resolveGroupAddressingMode(participantUserJids, groupJid) {
         for (let index = 0; index < participantUserJids.length; index += 1) {
             if ((0, jid_1.isLidJid)(participantUserJids[index])) {
-                return 'lid';
+                return constants_1.WA_ADDRESSING_MODES.LID;
             }
         }
         this.deps.logger.trace('group addressing mode resolved to pn (default)', {
             groupJid,
             participants: participantUserJids.length
         });
-        return 'pn';
+        return constants_1.WA_ADDRESSING_MODES.PN;
     }
     resolveSenderForAddressingMode(addressingMode, meJid) {
-        if (addressingMode === 'lid') {
+        if (addressingMode === constants_1.WA_ADDRESSING_MODES.LID) {
             const meLid = this.deps.getCurrentCredentials()?.meLid;
             if (meLid && meLid.includes('@')) {
                 try {

package/dist/client/coordinators/WaMobileCoordinator.d.ts

@@ -0,0 +1,192 @@
+import { type PhoneNumberToLidMapping } from '../messaging/companion-host';
+import type { CompanionHostPersistence, CompanionRecord } from '../persistence/companion-host';
+import type { WaClientPluginContext } from '../plugins/types';
+import type { WaClientEventMap } from '../types';
+import type { WaClientDependencies } from '../WaClientFactory';
+import type { Logger } from '../../infra/log/types';
+type WaMobileEmit = <K extends keyof WaClientEventMap>(event: K, ...args: Parameters<WaClientEventMap[K]>) => void;
+/** Result of a successful {@link WaMobileCoordinator.linkCompanion}. */
+export interface LinkCompanionResult {
+    readonly deviceJid: string;
+    readonly keyIndex: number;
+}
+/** Dependencies for {@link WaMobileCoordinator}, injected by the client factory. */
+export interface WaMobileCoordinatorDeps {
+    readonly logger: Logger;
+    readonly authClient: WaClientDependencies['authClient'];
+    readonly messageDispatch: WaClientDependencies['messageDispatch'];
+    readonly chatCoordinator: WaClientDependencies['chatCoordinator'];
+    readonly deviceSync: WaClientDependencies['signalDeviceSync'];
+    readonly appStateStore: WaClientPluginContext['stores']['appState'];
+    readonly queryWithContext: WaClientPluginContext['queryWithContext'];
+    readonly emitEvent: WaMobileEmit;
+    readonly registerIncomingHandler: WaClientPluginContext['registerIncomingHandler'];
+    readonly isMobilePrimary: () => boolean;
+    readonly persistence?: CompanionHostPersistence;
+    readonly includePem?: boolean;
+}
+/**
+ * Hosts companion devices from a mobile-primary session: signs a companion's
+ * device identity, uploads `pair-device`, tracks the linked set, and can revoke
+ * a device. Exposed at `client.mobile`; requires a registered primary session.
+ * Supports the QR ({@link linkCompanion}) and pairing-code
+ * ({@link linkCompanionByCode}) flows.
+ */
+export declare class WaMobileCoordinator {
+    private readonly authClient;
+    private readonly messageDispatch;
+    private readonly chatCoordinator;
+    private readonly deviceSync;
+    private readonly appStateStore;
+    private readonly queryWithContext;
+    private readonly emitEvent;
+    private readonly isMobilePrimary;
+    private readonly logger;
+    private readonly persistence?;
+    private readonly includePem;
+    private epoch;
+    private pendingCompanionHello;
+    private pendingFinish;
+    private accountKeyIndexes;
+    private pushNameSeeded;
+    constructor(deps: WaMobileCoordinatorDeps);
+    /**
+     * Links the companion from its pairing QR: signs the device identity, uploads
+     * `pair-device`, and returns the server-assigned device jid.
+     *
+     * @throws when there is no primary session or the server rejects the upload
+     * (e.g. the linked-device cap is reached).
+     */
+    linkCompanion(qr: string): Promise<LinkCompanionResult>;
+    /**
+     * Links a companion via its 8-character pairing code (the "link with phone
+     * number" flow). The companion must have requested a code for this account
+     * first (its `companion_hello` is recorded); this drives `primary_hello`,
+     * awaits `companion_finish`, and completes the same `pair-device` upload as
+     * the QR path.
+     *
+     * @throws when there is no primary session, no companion is pending, the code
+     * is wrong, or the handshake times out.
+     */
+    linkCompanionByCode(pairingCode: string): Promise<LinkCompanionResult>;
+    /** Re-signs and republishes the key-index list for the current device set. */
+    publishKeyIndexList(): Promise<void>;
+    /**
+     * Unlinks a companion this primary linked: sends the `remove-companion-device`
+     * IQ, drops it from the tracked set, and republishes the key-index list for
+     * the reduced device set.
+     *
+     * @throws when there is no registered primary session, the companion is not
+     * tracked, or the server rejects the removal.
+     */
+    revokeCompanion(companionDeviceJid: string, reason?: string): Promise<void>;
+    /**
+     * Unlinks EVERY companion from the account in a single `remove-companion-device`
+     * `all="true"` stanza (the phone's "log out all companion devices"), clears the
+     * tracked set, and republishes the key-index list for the primary alone.
+     * `excludeHostedCompanion` spares companions this account itself hosts.
+     *
+     * @throws when there is no registered primary session or the server rejects
+     * the removal.
+     */
+    revokeAllCompanions(reason?: string, options?: {
+        readonly excludeHostedCompanion?: boolean;
+    }): Promise<void>;
+    /** Returns the companions this primary has linked in the current epoch. */
+    listCompanions(): Promise<readonly CompanionRecord[]>;
+    /**
+     * Reconciles the tracked companion set against the account's live device list
+     * on the server (`usync`). Drops companions the server no longer lists - one
+     * the user unlinked, or one that self-removed while the primary was offline -
+     * then persists and emits `companion_host_revoked` for each. Runs on connect
+     * and on `account_sync`; safe to call manually. A no-op (no server query, no
+     * epoch created) when no companions are tracked. Returns the removed jids.
+     */
+    reconcileCompanions(): Promise<readonly string[]>;
+    /**
+     * Prunes tracked companions to those whose device slot is still in
+     * `serverDeviceIndexes`, persisting + emitting `companion_host_revoked` for
+     * each drop. Shared by the connect-time (`usync`) and `account_sync` paths.
+     */
+    private pruneCompanionsToDevices;
+    /**
+     * Reconciles from an `account_sync` notification's `<devices>` payload - the
+     * fresh, authoritative device set - so a companion the user just unlinked is
+     * pruned immediately (no `usync` round-trip, which would read a stale cache).
+     */
+    private reconcileFromAccountSync;
+    /**
+     * Shares the primary's active app-state sync key with a linked companion via
+     * an `APP_STATE_SYNC_KEY_SHARE` peer message so it can decrypt app-state.
+     * Establishes the outbound Signal session on demand, so call it once the
+     * companion is online (prekeys uploaded), not at link time.
+     *
+     * @throws when there is no primary session or no active sync key.
+     */
+    shareAppStateSyncKeys(companionDeviceJid: string): Promise<void>;
+    /**
+     * Pushes the `INITIAL_BOOTSTRAP` history sync to a linked companion as a
+     * `HISTORY_SYNC_NOTIFICATION` peer message. Flips the companion's
+     * `initialChatHistory` bootstrap flag; without it the companion self-removes
+     * with `HistorySyncTimeout`. Requires the companion online with prekeys.
+     *
+     * @throws when there is no registered primary session.
+     */
+    sendHistorySyncBootstrap(companionDeviceJid: string, options?: {
+        readonly phoneNumberToLidMappings?: readonly PhoneNumberToLidMapping[];
+    }): Promise<void>;
+    /**
+     * `ClientPairingProps` for the `<client-props>` pair-device element. A
+     * LID-native primary declares the chat DB LID-migrated + pure-LID session so
+     * the companion runs `setIsLidMigrated` at pair time and does not self-remove
+     * on its LID-addressed blocklist.
+     */
+    private buildClientPairingProps;
+    /**
+     * Seeds the primary's own `setting_pushName` into the `critical_block`
+     * app-state collection, once per session. The companion's critical bootstrap
+     * completes only when it finds an applied `SettingPushName` action; without
+     * one it self-removes with `syncd_timeout`. Falls back to the account phone
+     * number when no push name is set. Idempotent and best-effort.
+     */
+    private ensureAccountPushNameAppState;
+    private completeLink;
+    /**
+     * Best-effort background provisioning after a companion links: pushes the
+     * history-sync bootstrap and shares the app-state sync key. Fire-and-forget
+     * and retried, because the companion needs a moment to upload prekeys before
+     * the outbound Signal session these peer messages ride on can be established.
+     */
+    private provisionLinkedCompanion;
+    private provisionLinkedCompanionWithRetry;
+    private handleNotification;
+    /**
+     * Tracks the account's live device key-indexes from an `account_sync`
+     * notification so a new companion gets a non-colliding key index and the
+     * published key-index list keeps every existing device valid.
+     */
+    private updateAccountKeyIndexes;
+    private forgetAccountKeyIndex;
+    /**
+     * The key indexes currently valid for this account - index 0 (the primary),
+     * the account's own live devices, and every tracked companion. Sorted
+     * ascending. Deliberately excludes `epoch.currentKeyIndex`, which is an
+     * allocation high-water mark, not proof a device still exists: after revoking
+     * the last-linked companion its index must drop out of the published list.
+     */
+    private validKeyIndexes;
+    /**
+     * Allocates the next companion key index, advancing strictly past both the
+     * epoch's monotonic high-water mark and every currently-valid index so a
+     * revoked index is never reused (reuse breaks previously linked devices).
+     */
+    private nextKeyIndex;
+    private storeCompanionHello;
+    private resolveCompanionFinish;
+    private nodeBytes;
+    private requirePrimaryIdentityKeyPair;
+    private ensureEpoch;
+    private generateRawId;
+    private persist;
+}
+export {};