zapo-js 0.3.0 → 1.0.0

package/dist/types/client/WaClient.d.ts

@@ -1,122 +1,229 @@
 import { EventEmitter } from 'node:events';
-import type { WaAppStateStoreData, WaAppStateSyncOptions, WaAppStateSyncResult } from '../appstate/types';
-import type { WaAppStateSyncClient } from '../appstate/WaAppStateSyncClient';
+import type { WaAuthClient } from '../auth/WaAuthClient';
 import type { WaAppStateMutationCoordinator } from './coordinators/WaAppStateMutationCoordinator';
+import type { WaBotCoordinator } from './coordinators/WaBotCoordinator';
+import type { WaBroadcastListCoordinator } from './coordinators/WaBroadcastListCoordinator';
 import type { WaBusinessCoordinator } from './coordinators/WaBusinessCoordinator';
 import type { WaEmailCoordinator } from './coordinators/WaEmailCoordinator';
 import type { WaGroupCoordinator } from './coordinators/WaGroupCoordinator';
-import type { WaMessageDispatchCoordinator } from './coordinators/WaMessageDispatchCoordinator';
+import type { WaLowLevelCoordinator } from './coordinators/WaLowLevelCoordinator';
+import type { WaMessageCoordinator } from './coordinators/WaMessageCoordinator';
+import type { WaNewsletterCoordinator } from './coordinators/WaNewsletterCoordinator';
+import type { WaPresenceCoordinator } from './coordinators/WaPresenceCoordinator';
 import type { WaPrivacyCoordinator } from './coordinators/WaPrivacyCoordinator';
 import type { WaProfileCoordinator } from './coordinators/WaProfileCoordinator';
-import { type WriteBehindDrainResult } from './persistence/WriteBehindPersistence';
-import type { WaClientEventMap, WaClientOptions, WaIncomingNodeHandlerRegistration, WaSendMessageOptions } from './types';
+import type { WaStatusCoordinator } from './coordinators/WaStatusCoordinator';
+import type { WaClientEventMap, WaClientOptions, WaIgnoreKey, WaIgnoreKeyPredicate } from './types';
 import type { Logger } from '../infra/log/types';
-import type { WaMediaTransferClient } from '../media/WaMediaTransferClient';
-import type { WaMessagePublishResult, WaSendMessageContent, WaSendReceiptInput } from '../message/types';
-import type { WaMessageClient } from '../message/WaMessageClient';
 import { type WaLogoutReason } from '../protocol/stream';
-import type { SignalLidSyncResult } from '../signal/api/SignalDeviceSyncApi';
-import type { BinaryNode } from '../transport/types';
+/**
+ * Top-level WhatsApp client. Owns the transport, auth, signal, and per-feature
+ * coordinators (accessible via getters such as {@link message}, {@link group},
+ * {@link newsletter}, etc.) and re-emits every {@link WaClientEventMap} event.
+ *
+ * Lifecycle: construct with {@link WaClientOptions}, call {@link connect} to
+ * open the socket, react to `connection`/`auth_qr`/`auth_pairing_code` events,
+ * then use the coordinator getters to drive the session. Call {@link disconnect}
+ * to shut down cleanly or {@link logout} to remove the companion device.
+ *
+ * @example
+ * ```ts
+ * import { createPinoLogger, createStore, WaClient } from '..'
+ * import { createSqliteStore } from '@zapo-js/store-sqlite'
+ *
+ * const store = createStore({
+ *     backends: { sqlite: createSqliteStore({ path: '.auth/state.sqlite' }) },
+ *     providers: {
+ *         auth: 'sqlite',
+ *         signal: 'sqlite',
+ *         preKey: 'sqlite',
+ *         session: 'sqlite',
+ *         identity: 'sqlite',
+ *         senderKey: 'sqlite',
+ *         appState: 'sqlite',
+ *         privacyToken: 'sqlite',
+ *         messages: 'sqlite',
+ *         threads: 'sqlite',
+ *         contacts: 'sqlite'
+ *     }
+ * })
+ *
+ * const client = new WaClient(
+ *     { store, sessionId: 'default' },
+ *     await createPinoLogger({ level: 'info', pretty: true })
+ * )
+ *
+ * client.on('auth_qr', ({ qr, ttlMs }) => console.log('scan:', qr, ttlMs))
+ * client.on('connection', (event) => console.log('connection', event))
+ * client.on('message', async (event) => {
+ *     if (event.message?.conversation === 'ping') {
+ *         await client.message.send(event.chatJid!, 'pong')
+ *     }
+ * })
+ *
+ * await client.connect()
+ * ```
+ */
 export declare class WaClient extends EventEmitter {
     private readonly options;
     private readonly logger;
-    private readonly appStateStore;
-    private readonly contactStore;
-    private readonly messageStore;
-    private readonly messageSecretStore;
-    private readonly participantsStore;
-    private readonly privacyTokenStore;
-    private readonly deviceListStore;
-    private readonly retryStore;
-    private readonly signalStore;
-    private readonly preKeyStore;
-    private readonly sessionStore;
-    private readonly identityStore;
-    private readonly senderKeyStore;
-    private readonly threadStore;
-    private readonly authClient;
-    private readonly nodeOrchestrator;
-    private readonly nodeTransport;
-    private readonly signalDeviceSync;
-    readonly appStateSync: WaAppStateSyncClient;
-    readonly chatCoordinator: WaAppStateMutationCoordinator;
-    private readonly incomingNode;
-    readonly mediaTransfer: WaMediaTransferClient;
-    readonly messageDispatch: WaMessageDispatchCoordinator;
-    readonly messageClient: WaMessageClient;
-    readonly groupCoordinator: WaGroupCoordinator;
-    readonly privacyCoordinator: WaPrivacyCoordinator;
-    readonly profileCoordinator: WaProfileCoordinator;
-    readonly businessCoordinator: WaBusinessCoordinator;
-    readonly emailCoordinator: WaEmailCoordinator;
-    private readonly passiveTasks;
-    private readonly keepAlive;
-    private readonly receiptQueue;
-    private readonly connectionManager;
-    private readonly trustedContactToken;
+    private readonly stores;
+    private readonly deps;
+    private readonly appStateSync;
+    private readonly mediaTransfer;
     private readonly writeBehind;
     private connectPromise;
     private acceptingIncomingEvents;
     private activeIncomingHandlers;
     private readonly incomingHandlersDrainedWaiters;
+    /**
+     * @param options Client configuration (store, transport, addons, history...).
+     * @param logger  Optional structured logger. Defaults to a `ConsoleLogger('info')`.
+     */
     constructor(options: WaClientOptions, logger?: Logger);
+    private runClientTooOldRecover;
+    /** Strongly-typed `EventEmitter#on` over {@link WaClientEventMap}. */
     on<K extends keyof WaClientEventMap>(event: K, listener: WaClientEventMap[K]): this;
     on(event: string | symbol, listener: (...args: unknown[]) => void): this;
+    /** Strongly-typed `EventEmitter#once` over {@link WaClientEventMap}. */
     once<K extends keyof WaClientEventMap>(event: K, listener: WaClientEventMap[K]): this;
     once(event: string | symbol, listener: (...args: unknown[]) => void): this;
+    /** Strongly-typed `EventEmitter#off` over {@link WaClientEventMap}. */
     off<K extends keyof WaClientEventMap>(event: K, listener: WaClientEventMap[K]): this;
     off(event: string | symbol, listener: (...args: unknown[]) => void): this;
+    /** Strongly-typed `EventEmitter#emit` over {@link WaClientEventMap}. */
     emit<K extends keyof WaClientEventMap>(event: K, payload: Parameters<WaClientEventMap[K]>[0]): boolean;
     emit(event: string | symbol, ...args: unknown[]): boolean;
+    /**
+     * Returns the current auth state snapshot (credentials, registration,
+     * connection flag) – useful for resuming or inspecting the client.
+     */
     getState(): {
         connected: boolean;
         registered: boolean;
         hasQr: boolean;
         hasPairingCode: boolean;
     };
+    /**
+     * Returns the credentials persisted for the current session, or `null` if
+     * the client has not been paired yet.
+     */
     getCredentials(): import("..").WaAuthCredentials | null;
+    /**
+     * Returns the measured skew between the local clock and the server, in
+     * milliseconds, or `null` if no handshake has completed yet.
+     */
     getClockSkewMs(): number | null;
-    sendNode(node: BinaryNode): Promise<void>;
-    sendPresence(type?: 'available' | 'unavailable'): Promise<void>;
-    query(node: BinaryNode, timeoutMs?: number, options?: {
-        readonly useSystemId?: boolean;
-    }): Promise<BinaryNode>;
-    registerIncomingHandler(registration: WaIncomingNodeHandlerRegistration): () => void;
-    unregisterIncomingHandler(registration: WaIncomingNodeHandlerRegistration): boolean;
     private bindNodeTransportEvents;
     private handleIncomingMessageEvent;
-    private handleIncomingAppStateSyncKeyShare;
-    private handleIncomingAppStateSyncKeyRequest;
-    private extractAppStateSyncKeyRequestIds;
-    private isOwnAccountDeviceJid;
-    private handleHistorySyncNotification;
     private queryWithContext;
     private handleIncomingFrame;
+    /**
+     * Opens the transport and runs the noise/auth handshake. If a connection
+     * is already in flight, the in-flight promise is reused. Resolves once the
+     * client is fully ready; pairing prompts are surfaced via the `auth_qr`
+     * and `auth_pairing_code` events while this awaits.
+     *
+     * **First-time pairing:** the promise stays pending until the user scans a
+     * QR or types the pairing code. Subscribe to `auth_qr` / `auth_pairing_code`
+     * *before* awaiting – they fire while `connect()` is still running.
+     *
+     * @example
+     * ```ts
+     * // QR pairing (default – works headless)
+     * client.on('auth_qr', ({ qr }) => console.log('scan:', qr))
+     * client.on('auth_paired', ({ credentials }) => console.log('paired:', credentials.meJid))
+     * await client.connect()
+     *
+     * // Link-code pairing – call requestPairingCode while connect() is running
+     * void client.connect()
+     * await new Promise((r) => client.once('auth_pairing_required', r))
+     * const code = await client.auth.requestPairingCode('5511999999999')
+     * console.log('enter code on phone:', code)
+     * ```
+     */
     connect(): Promise<void>;
+    /**
+     * Closes the transport gracefully: pauses incoming events, flushes the
+     * write-behind persistence queue, and emits a `connection` close event
+     * with reason `client_disconnected`. Does not clear stored credentials -
+     * call {@link connect} again to resume the same session. There is no
+     * built-in auto-reconnect; subscribe to `connection: { status: 'close' }`
+     * and decide your own backoff.
+     */
     disconnect(): Promise<void>;
-    requestPairingCode(phoneNumber: string, shouldShowPushNotification?: boolean, customCode?: string): Promise<string>;
-    fetchPairingCountryCodeIso(): Promise<string>;
-    getLidsByPhoneNumbers(phoneNumbers: readonly string[]): Promise<readonly SignalLidSyncResult[]>;
-    sendMessage(to: string, content: WaSendMessageContent, options?: WaSendMessageOptions): Promise<WaMessagePublishResult>;
-    syncSignalSession(jid: string, reasonIdentity?: boolean): Promise<void>;
+    /**
+     * Drops matching inbound stanzas before any handler runs. Server still
+     * gets the ack so it stops re-delivering. Returns an `unregister` function.
+     *
+     * Accepts either a declarative descriptor or a predicate. The descriptor
+     * matches by `remoteJid`/`fromMe`/`id`/`participant` (PN ↔ LID alt-attrs
+     * resolved automatically) and throws when no match field is given or
+     * arrays are empty. The predicate receives a parsed
+     * {@link WaIgnoreKeyContext} and returns `true` to drop the stanza.
+     *
+     * @example
+     * ```ts
+     * client.ignoreKey({ remoteJid: spammerJid })
+     * client.ignoreKey({ fromMe: true, only: ['message'] })
+     * client.ignoreKey((m) => m.kind === 'message' && isGroupJid(m.remoteJid ?? ''))
+     * ```
+     */
+    ignoreKey(input: WaIgnoreKey | WaIgnoreKeyPredicate): () => void;
+    /** Auth client: pairing, credentials, registration state. */
+    get auth(): WaAuthClient;
+    /** Message coordinator: send/receive, receipts, addons, media download. */
+    get message(): WaMessageCoordinator;
+    /** Presence coordinator: own/peer presence subscriptions. */
+    get presence(): WaPresenceCoordinator;
+    /** Low-level coordinator: raw node send/query escape hatch. */
+    get lowlevel(): WaLowLevelCoordinator;
+    /** App-state mutation coordinator: chat-side settings (mute, pin, etc.). */
     get chat(): WaAppStateMutationCoordinator;
+    /** Group coordinator: create/query/manage WhatsApp groups and communities. */
     get group(): WaGroupCoordinator;
+    /** Status coordinator: status broadcast send and reactions. */
+    get status(): WaStatusCoordinator;
+    /**
+     * Broadcast-list coordinator: list management and broadcast sends.
+     * **Business-only** - the underlying app-state schema rejects regular
+     * accounts. See {@link WaBroadcastListCoordinator}.
+     */
+    get broadcastList(): WaBroadcastListCoordinator;
+    /** Newsletter coordinator: create/query/follow/admin/send for channels. */
+    get newsletter(): WaNewsletterCoordinator;
+    /** Privacy coordinator: privacy categories, blocklist, disallowed list. */
     get privacy(): WaPrivacyCoordinator;
+    /** Profile coordinator: own/peer profile fields (picture, status, username). */
     get profile(): WaProfileCoordinator;
+    /**
+     * Business coordinator: business profile, verified-name lookups. Reads
+     * work from any account; **writes (`editBusinessProfile`,
+     * `updateCoverPhoto`, `deleteCoverPhoto`) are business-only** and throw
+     * on regular accounts. See {@link WaBusinessCoordinator}.
+     */
     get business(): WaBusinessCoordinator;
+    /** Bot coordinator: Meta-AI bot profiles, prompt/chunk decryption. */
+    get bot(): WaBotCoordinator;
+    /**
+     * Email coordinator: bind/unbind/verify email on the account.
+     * **Mobile-only** - every method throws unless the client is connected
+     * via `options.mobileTransport`. See {@link WaEmailCoordinator}.
+     */
     get email(): WaEmailCoordinator;
+    /**
+     * Unpairs this companion device by removing it server-side. Requires an
+     * authenticated session; throws when no `meJid` is present.
+     *
+     * **Does not** disconnect the socket or clear local stores by itself -
+     * the server initiates the close after accepting the IQ, which surfaces
+     * via a `connection` event with `isLogout: true`. That close handler is
+     * what wipes the persisted state, honoring `options.logoutStoreClear`.
+     * The {@link WaClient} instance is single-shot after logout: create a
+     * fresh one (with a fresh `sessionId` or pre-cleared store) to re-pair.
+     */
     logout(reason?: WaLogoutReason): Promise<void>;
-    sendReceipt(input: WaSendReceiptInput): Promise<void>;
-    flushAppStateMutations(): Promise<void>;
-    flushWriteBehind(timeoutMs?: number): Promise<WriteBehindDrainResult>;
-    exportAppState(): Promise<WaAppStateStoreData>;
-    syncAppState(options?: WaAppStateSyncOptions): Promise<WaAppStateSyncResult>;
-    private executeAppStateSync;
-    private getBlockedAppStateCollections;
-    private emitChatEventsFromAppStateSyncResult;
-    private handleNctSaltMutation;
     private clearStoredState;
-    private tryDecryptAddon;
     private tryEnterIncomingHandler;
     private leaveIncomingHandler;
     private pauseIncomingEventsAndWaitDrain;

package/dist/types/client/WaClientFactory.d.ts

@@ -1,25 +1,33 @@
+import { WaAppStateSyncClient } from '../appstate/sync/WaAppStateSyncClient';
 import type { WaAppStateSyncOptions, WaAppStateSyncResult } from '../appstate/types';
-import { WaAppStateSyncClient } from '../appstate/WaAppStateSyncClient';
 import { WaAuthClient } from '../auth/WaAuthClient';
 import { WaConnectionManager } from './connection/WaConnectionManager';
 import { WaReceiptQueue } from './connection/WaReceiptQueue';
 import { WaAbPropsCoordinator } from './coordinators/WaAbPropsCoordinator';
 import { WaAppStateMutationCoordinator } from './coordinators/WaAppStateMutationCoordinator';
+import { type WaBotCoordinator } from './coordinators/WaBotCoordinator';
+import { type WaBroadcastListCoordinator } from './coordinators/WaBroadcastListCoordinator';
 import { type WaBusinessCoordinator } from './coordinators/WaBusinessCoordinator';
 import { type WaEmailCoordinator } from './coordinators/WaEmailCoordinator';
 import { type WaGroupCoordinator } from './coordinators/WaGroupCoordinator';
 import { WaIncomingNodeCoordinator } from './coordinators/WaIncomingNodeCoordinator';
+import { type WaLowLevelCoordinator } from './coordinators/WaLowLevelCoordinator';
+import { WaMessageCoordinator } from './coordinators/WaMessageCoordinator';
 import { WaMessageDispatchCoordinator } from './coordinators/WaMessageDispatchCoordinator';
+import { type WaNewsletterCoordinator } from './coordinators/WaNewsletterCoordinator';
 import { WaPassiveTasksCoordinator } from './coordinators/WaPassiveTasksCoordinator';
+import { type WaPresenceCoordinator } from './coordinators/WaPresenceCoordinator';
 import { type WaPrivacyCoordinator } from './coordinators/WaPrivacyCoordinator';
 import { type WaProfileCoordinator } from './coordinators/WaProfileCoordinator';
 import { WaRetryCoordinator } from './coordinators/WaRetryCoordinator';
+import { type WaStatusCoordinator } from './coordinators/WaStatusCoordinator';
 import { type WaStreamControlHandler } from './coordinators/WaStreamControlCoordinator';
 import { WaTrustedContactTokenCoordinator } from './coordinators/WaTrustedContactTokenCoordinator';
-import { type WaMediaMessageOptions } from './messages';
-import type { WaClientEventMap, WaClientOptions, WaIncomingMessageEvent } from './types';
+import { type WaMediaMessageOptions } from './messaging/messages';
+import type { WaClientEventMap, WaClientOptions, WaIncomingMessageEvent, WaIncomingProtocolMessageEvent } from './types';
 import type { Logger } from '../infra/log/types';
-import { WaMediaTransferClient } from '../media/WaMediaTransferClient';
+import { WaMediaTransferClient } from '../media/transfer/WaMediaTransferClient';
+import { type PeerDataOperationRequester } from '../message/primitives/peer-data-operation';
 import { WaMessageClient } from '../message/WaMessageClient';
 import { SignalDeviceSyncApi } from '../signal/api/SignalDeviceSyncApi';
 import { SignalDigestSyncApi } from '../signal/api/SignalDigestSyncApi';
@@ -29,6 +37,7 @@ import { SignalRotateKeyApi } from '../signal/api/SignalRotateKeyApi';
 import { SignalSessionSyncApi } from '../signal/api/SignalSessionSyncApi';
 import { SenderKeyManager } from '../signal/group/SenderKeyManager';
 import { SignalProtocol } from '../signal/session/SignalProtocol';
+import type { WaStoredContactRecord } from '../store/contracts/contact.store';
 import { WaKeepAlive } from '../transport/keepalive/WaKeepAlive';
 import { WaNodeOrchestrator } from '../transport/node/WaNodeOrchestrator';
 import { WaNodeTransport } from '../transport/node/WaNodeTransport';
@@ -54,8 +63,16 @@ interface WaClientBuildRuntime {
     readonly handleIncomingFrame: (frame: Uint8Array) => Promise<void>;
     readonly clearStoredState: () => Promise<void>;
     readonly resumeIncomingEvents: () => void;
+    readonly subscribeProtocolMessage: (handler: (event: WaIncomingProtocolMessageEvent) => void) => () => void;
+    /**
+     * Sink for address-book contact rows synced over app-state. Wired by
+     * `WaClient` to {@link WriteBehindPersistence.persistContact} so Contact
+     * mutations land in the contact store at pair-time (snapshot) and on
+     * every incremental sync.
+     */
+    readonly persistContact: (record: WaStoredContactRecord) => void;
 }
-interface WaClientDependencies {
+export interface WaClientDependencies {
     readonly nodeTransport: WaNodeTransport;
     readonly nodeOrchestrator: WaNodeOrchestrator;
     readonly keepAlive: WaKeepAlive;
@@ -72,21 +89,29 @@ interface WaClientDependencies {
     readonly signalSessionSync: SignalSessionSyncApi;
     readonly authClient: WaAuthClient;
     readonly messageDispatch: WaMessageDispatchCoordinator;
+    readonly messageCoordinator: WaMessageCoordinator;
+    readonly presenceCoordinator: WaPresenceCoordinator;
     readonly retryCoordinator: WaRetryCoordinator;
     readonly appStateSync: WaAppStateSyncClient;
     readonly chatCoordinator: WaAppStateMutationCoordinator;
     readonly streamControl: WaStreamControlHandler;
     readonly incomingNode: WaIncomingNodeCoordinator;
+    readonly lowLevelCoordinator: WaLowLevelCoordinator;
     readonly passiveTasks: WaPassiveTasksCoordinator;
     readonly groupCoordinator: WaGroupCoordinator;
+    readonly statusCoordinator: WaStatusCoordinator;
+    readonly broadcastListCoordinator: WaBroadcastListCoordinator;
+    readonly newsletterCoordinator: WaNewsletterCoordinator;
     readonly privacyCoordinator: WaPrivacyCoordinator;
     readonly profileCoordinator: WaProfileCoordinator;
     readonly businessCoordinator: WaBusinessCoordinator;
+    readonly botCoordinator: WaBotCoordinator;
     readonly emailCoordinator: WaEmailCoordinator;
     readonly receiptQueue: WaReceiptQueue;
     readonly connectionManager: WaConnectionManager;
     readonly trustedContactToken: WaTrustedContactTokenCoordinator;
     readonly abPropsCoordinator: WaAbPropsCoordinator;
+    readonly peerDataOperation: PeerDataOperationRequester;
 }
 export declare function resolveWaClientBase(options: WaClientOptions, logger: Logger): WaClientBase;
 export declare function buildWaClientDependencies(input: {

package/dist/types/client/connection/WaConnectionManager.d.ts

@@ -16,6 +16,7 @@ interface WaConnectionManagerOptions {
     readonly nodeTransport: WaNodeTransport;
     readonly getPassiveTasks: () => WaPassiveTasksCoordinator | null;
     readonly clearStoredCredentials: () => Promise<void>;
+    readonly onPostPairReconnected: () => void;
 }
 export declare class WaConnectionManager {
     private readonly logger;
@@ -26,28 +27,29 @@ export declare class WaConnectionManager {
     private readonly nodeTransport;
     private readonly getPassiveTasks;
     private readonly clearStoredCredentialsCallback;
+    private readonly onPostPairReconnected;
     private comms;
     private clockSkewMs;
     private mediaConnCache;
     private connectPromise;
     private pairingReconnectPromise;
+    private pairingReconnectTimeout;
     private frameHandler;
     private pendingComms;
     private lifecycleGeneration;
     private lifecycleQueue;
-    private lastConnectWasNewLogin;
     constructor(options: WaConnectionManagerOptions);
     connect(frameHandler: (frame: Uint8Array) => Promise<void>): Promise<void>;
     scheduleReconnectAfterPairing(): void;
     disconnect(): Promise<void>;
     clearStoredCredentials(): Promise<void>;
     isConnected(): boolean;
-    wasNewLogin(): boolean;
     getComms(): WaComms | null;
     getClockSkewMs(): number | null;
     getMediaConnCache(): WaMediaConn | null;
     setMediaConnCache(value: WaMediaConn | null): void;
     updateClockSkewFromSuccess(serverUnixSeconds: number): void;
+    setClockSkewMs(clockSkewMs: number, source: string): void;
     private connectInternal;
     private reconnectAsRegisteredAfterPairing;
     private reconnectAsRegisteredAfterPairingInternal;

package/dist/types/client/connection/WaReceiptQueue.d.ts

@@ -8,6 +8,6 @@ export declare class WaReceiptQueue {
     });
     shouldQueue(node: BinaryNode, error: Error): boolean;
     enqueue(node: BinaryNode): void;
-    take(): BinaryNode[];
+    take(): readonly BinaryNode[];
     size(): number;
 }