zapo-js 0.3.0 → 1.0.0

package/dist/types/client/coordinators/WaMessageCoordinator.d.ts

@@ -0,0 +1,232 @@
+import type { Readable } from 'node:stream';
+import type { WaMessageDispatchCoordinator } from '../coordinators/WaMessageDispatchCoordinator';
+import type { WaTrustedContactTokenCoordinator } from '../coordinators/WaTrustedContactTokenCoordinator';
+import type { WaDownloadMediaOptions, WaIncomingAddonEvent, WaIncomingMessageEvent, WaSendMessageOptions } from '../types';
+import type { Logger } from '../../infra/log/types';
+import type { WaMediaTransferClient } from '../../media/transfer/WaMediaTransferClient';
+import type { PeerDataOperationRequester } from '../../message/primitives/peer-data-operation';
+import type { WaMessagePublishResult, WaSendMessageContent, WaSendReceiptEventOptions, WaSendReceiptOptions } from '../../message/types';
+import { type Proto } from '../..';
+import type { WaMessageSecretStore } from '../../store/contracts/message-secret.store';
+import type { WaMessageStore } from '../../store/contracts/message.store';
+import { type WaMexQuerySocket } from '../../transport/node/mex/client';
+export interface WaMessageCoordinatorDeps {
+    readonly messageDispatch: WaMessageDispatchCoordinator;
+    readonly mediaTransfer: WaMediaTransferClient;
+    readonly logger: Logger;
+    readonly messageStore: WaMessageStore;
+    readonly messageSecretStore: WaMessageSecretStore;
+    readonly trustedContactToken: WaTrustedContactTokenCoordinator;
+    readonly emitAddon: (event: WaIncomingAddonEvent) => void;
+    readonly mexSocket: WaMexQuerySocket;
+    readonly peerDataOperation: PeerDataOperationRequester;
+}
+export interface WaRequestHistorySyncInput {
+    /** Chat the older messages should be fetched from. */
+    readonly chatJid: string;
+    /**
+     * Id of the oldest message currently in the local view. The server
+     * pages backwards from this anchor. Omit to let the server pick its
+     * own anchor (rarely useful).
+     */
+    readonly oldestMsgId?: string;
+    /** Whether {@link oldestMsgId} was sent by the current account. */
+    readonly oldestMsgFromMe?: boolean;
+    /** Epoch ms of the oldest local message; pairs with {@link oldestMsgId}. */
+    readonly oldestMsgTimestampMs?: number;
+    /**
+     * How many older messages to request. WhatsApp Web defaults to the
+     * server-side `history_sync_on_demand_message_count` AB-prop (~50);
+     * passing nothing here leaves the field unset so the server applies
+     * its own default.
+     */
+    readonly count?: number;
+}
+export interface WaReachoutTimelock {
+    readonly isActive: boolean;
+    readonly enforcementType: string | null;
+    readonly enforcementEndsAt: number | null;
+}
+export type WaMessageCappingType = 'INDIVIDUAL_NEW_CHAT_THREAD';
+export interface WaMessageCappingInfo {
+    readonly totalQuota: number | null;
+    readonly usedQuota: number | null;
+    readonly cycleStartAt: number | null;
+    readonly cycleEndAt: number | null;
+    readonly serverSentAt: number | null;
+    readonly oteStatus: string | null;
+    readonly mvStatus: string | null;
+    readonly cappingStatus: string | null;
+}
+/**
+ * Coordinates outbound message sending, receipts, addon decryption, media
+ * download, and the related MEX account queries. Accessed via
+ * {@link WaClient.message}.
+ */
+export declare class WaMessageCoordinator {
+    private readonly messageDispatch;
+    private readonly mediaTransfer;
+    private readonly logger;
+    private readonly messageStore;
+    private readonly messageSecretStore;
+    private readonly trustedContactToken;
+    private readonly emitAddon;
+    private readonly mexSocket;
+    private readonly peerDataOperation;
+    constructor(deps: WaMessageCoordinatorDeps);
+    /**
+     * Asks the server to backfill older messages for `chatJid` beyond what
+     * arrived in the initial history-sync. Implemented as a
+     * `PeerDataOperationRequestMessage` (type `HISTORY_SYNC_ON_DEMAND`)
+     * sent to this account's own user JID; the response arrives later as
+     * a `history_sync_chunk` event the same way the bootstrap chunks do -
+     * subscribe before calling if you need to react to the chunk.
+     *
+     * The method returns once the request is dispatched (with the protocol
+     * message id), **not** when the chunk arrives. Pair `oldestMsgId` +
+     * `oldestMsgTimestampMs` + `oldestMsgFromMe` from the topmost message
+     * currently visible to page backwards correctly.
+     */
+    requestHistorySync(input: WaRequestHistorySyncInput): Promise<{
+        readonly messageId: string;
+    }>;
+    /**
+     * Fetches the server-side "reachout" timelock that throttles cold outreach
+     * to non-contacts, returning the active window when enforcement is on.
+     */
+    getReachoutTimelock(): Promise<WaReachoutTimelock>;
+    /**
+     * Fetches the per-cycle message capping info applied to new-chat threads
+     * (quota, used, cycle boundaries, status flags).
+     */
+    getNewChatMessageCapping(type?: WaMessageCappingType): Promise<WaMessageCappingInfo>;
+    /**
+     * Force-refreshes the Signal session(s) for `jid`. Set `reasonIdentity` to
+     * `true` when the trigger was an identity change – this also queues a
+     * trusted-contact-token reissue.
+     */
+    syncSignalSession(jid: string, reasonIdentity?: boolean): Promise<void>;
+    /**
+     * Sends a message (any {@link WaSendMessageContent} kind – text, media,
+     * poll, reaction, edit, revoke, etc.) to `to` and returns the publish
+     * result containing the stanza id and ack metadata.
+     *
+     * `to` accepts any JID accepted by {@link normalizeRecipientJid}: bare
+     * digits (`'5511999999999'`), a phone JID (`'5511…@s.whatsapp.net'`),
+     * a group JID (`'…@g.us'`), or a LID. See the {@link WaSendMessageContent}
+     * union for the full kind list.
+     *
+     * **Gotchas:**
+     * - The stanza id is auto-generated unless you set `options.id`. Reusing
+     *   an id manually makes the send idempotent on the server but is also how
+     *   internal retries (`maxAttempts`) work – don't reuse ids across
+     *   logically distinct messages.
+     * - Sending to a `@newsletter` JID routes through a separate code path
+     *   that ignores most of `options` (no quote/forward/edit semantics).
+     * - Addon-crypto kinds (poll-vote, reaction, message-edit, ...) require an
+     *   authenticated session (`meJid` present) – throws otherwise.
+     * - Group sends fan out to every cached member device. If your
+     *   `groupMetadata` cache is empty/disabled, this triggers a metadata IQ
+     *   per send (rate-limited server-side, see {@link WaCreateStoreOptions}).
+     *
+     * @example
+     * ```ts
+     * // 1. Plain text (string shorthand)
+     * await client.message.send('5511999999999', 'hello!')
+     *
+     * // 2. Reply with mention
+     * await client.message.send(groupJid, {
+     *     type: 'text',
+     *     text: '@5511999999999 ping',
+     *     contextInfo: {
+     *         mentionedJid: ['5511999999999@s.whatsapp.net'],
+     *         quoted: { key: { remoteJid: groupJid, fromMe: false, id: incomingId } }
+     *     }
+     * })
+     *
+     * // 3. Image from a file path (the encoder opens + streams it for you)
+     * await client.message.send(jid, {
+     *     type: 'image',
+     *     media: '/tmp/photo.jpg',
+     *     mimetype: 'image/jpeg',
+     *     caption: 'check this out'
+     * })
+     *
+     * // 4. React to an incoming message (empty emoji = unreact)
+     * await client.message.send(event.key.remoteJid, {
+     *     type: 'reaction',
+     *     emoji: '👍',
+     *     target: event.key // or pass the whole event
+     * })
+     *
+     * // 5. Poll
+     * const result = await client.message.send(jid, {
+     *     type: 'poll',
+     *     name: 'lunch?',
+     *     options: ['pizza', 'sushi', 'burger'],
+     *     selectableCount: 1
+     * })
+     * console.log('sent as', result.id)
+     * ```
+     */
+    send(to: string, content: WaSendMessageContent, options?: WaSendMessageOptions): Promise<WaMessagePublishResult>;
+    /**
+     * Sends a receipt (delivery / read / played / inactive). Overloads:
+     * - Pass one or many `WaIncomingMessageEvent` to auto-derive chat/sender
+     *   metadata and batch ids by chat.
+     * - Pass an explicit `(jid, ids, options)` triple for manual control.
+     *
+     * **You usually don't need to call this for `'delivery'`** - the library
+     * already auto-ACKs delivery on every incoming `<message>` it decrypts
+     * successfully. Use this manually for `'read'`/`'played'` (read receipts
+     * the user explicitly toggled) or for `'inactive'`/retry receipts.
+     */
+    sendReceipt(target: WaIncomingMessageEvent | readonly WaIncomingMessageEvent[], options?: WaSendReceiptEventOptions): Promise<void>;
+    sendReceipt(jid: string, ids: string | readonly string[], options?: WaSendReceiptOptions): Promise<void>;
+    /**
+     * Resolves the media payload inside `source` and returns a `Readable`
+     * stream of the decrypted bytes. Throws when the message has no
+     * downloadable media.
+     *
+     * **Caller owns the stream** - pipe it somewhere or call `.destroy()` to
+     * release the underlying socket; an unconsumed stream leaks the connection.
+     * MAC + SHA-256 verification runs **as bytes are consumed**, so if you
+     * abort mid-read you've consumed unverified bytes. Pass `options.signal`
+     * to cancel cleanly, or use {@link downloadBytes} / {@link downloadToFile}
+     * for one-shot verified downloads.
+     */
+    download(source: WaIncomingMessageEvent | Proto.IMessage, options?: WaDownloadMediaOptions): Promise<Readable>;
+    /**
+     * Convenience wrapper around {@link download} that streams the decrypted
+     * media directly to `filePath`. On failure the **partial file is not
+     * cleaned up** - delete it yourself in the error handler if you don't
+     * want to leak corrupted artifacts.
+     */
+    downloadToFile(source: WaIncomingMessageEvent | Proto.IMessage, filePath: string, options?: WaDownloadMediaOptions): Promise<void>;
+    /**
+     * Convenience wrapper around {@link download} that buffers the decrypted
+     * media into a single `Uint8Array`. Use only for small media – caps via
+     * `options.maxBytes`.
+     */
+    downloadBytes(source: WaIncomingMessageEvent | Proto.IMessage, options?: WaDownloadMediaOptions): Promise<Uint8Array>;
+    /**
+     * Attempts to decrypt an addon payload (poll vote, reaction, edit, ...)
+     * attached to `event` and, on success, emits a typed
+     * `WaIncomingAddonEvent`. Silently returns when the parent message
+     * secret is missing or the payload is not an addon.
+     *
+     * Called automatically by the client unless `options.addons.autoDecrypt`
+     * is explicitly `false` - you rarely need to invoke it directly. The
+     * parent secret is looked up in the in-memory `messageSecret` cache
+     * first, then in the `messages` store. If both are `'none'`/missing,
+     * decryption fails and the event never fires; failures are logged at
+     * `warn` for `secretEncryptedMessage` addons (whose parent can be
+     * any message type, so the secret is only available when the
+     * `messages` mailbox is active) and at `debug` for the dedicated
+     * addon types (reactions, poll votes, event responses, comments)
+     * whose parent always carries a persisted secret or is itself
+     * short-lived.
+     */
+    tryDecryptAddon(event: WaIncomingMessageEvent): Promise<void>;
+    private dispatchReceipt;
+}

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

@@ -1,69 +1,62 @@
 import type { WaAppStateSyncKey } from '../../appstate/types';
+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 { GroupParticipantsCache } from '../messaging/participants';
 import type { WaGroupEvent, WaSendMessageOptions, WaSignalMessagePublishInput } from '../types';
 import type { Logger } from '../../infra/log/types';
-import type { WaEncryptedMessageInput, WaMessagePublishOptions, WaMessagePublishResult, WaSendMessageContent, WaSendReceiptInput } from '../../message/types';
+import { type WaSendContextInfo } from '../../message/context-info';
+import { type IcdcMeta } from '../../message/crypto/icdc';
+import type { WaEncryptedMessageInput, WaMessageBuildResult, WaMessagePublishOptions, WaMessagePublishResult, WaSendMessageContent, WaSendReceiptInput } from '../../message/types';
 import type { WaMessageClient } from '../../message/WaMessageClient';
 import { type Proto } from '../..';
+import { type WaStatusDistributionSetting } from '../../protocol/constants';
 import type { OutboundRetryTracker } from '../../retry/tracker';
+import type { SignalDeviceSyncApi } from '../../signal/api/SignalDeviceSyncApi';
 import type { SenderKeyManager } from '../../signal/group/SenderKeyManager';
 import type { SignalSessionResolver } from '../../signal/session/resolver';
 import type { SignalProtocol } from '../../signal/session/SignalProtocol';
+import type { SignalAddress } from '../../signal/types';
 import type { WaDeviceListStore } from '../../store/contracts/device-list.store';
 import type { WaIdentityStore } from '../../store/contracts/identity.store';
 import type { WaMessageSecretStore } from '../../store/contracts/message-secret.store';
 import type { WaSessionStore } from '../../store/contracts/session.store';
 import type { WaSignalStore } from '../../store/contracts/signal.store';
 import type { BinaryNode } from '../../transport/types';
+import type { ServerClock } from '../../util/clock';
 interface WaMessageDispatchCoordinatorOptions {
     readonly logger: Logger;
     readonly messageClient: WaMessageClient;
     readonly retryTracker: OutboundRetryTracker;
     readonly sessionResolver: SignalSessionResolver;
     readonly fanoutResolver: DeviceFanoutResolver;
-    readonly participantsCache: GroupParticipantsCache;
+    readonly groupMetadataCache: GroupMetadataCache;
     readonly appStateSyncKeyProtocol: AppStateSyncKeyProtocol;
-    readonly buildMessageContent: (content: WaSendMessageContent) => Promise<Proto.IMessage>;
+    readonly buildMessageContent: (content: WaSendMessageContent, ctx?: {
+        readonly to: string;
+        readonly outgoingStanzaId?: string;
+        readonly meJid?: string;
+    }) => Promise<WaMessageBuildResult>;
     readonly senderKeyManager: SenderKeyManager;
     readonly signalProtocol: SignalProtocol;
     readonly signalStore: WaSignalStore;
     readonly sessionStore: WaSessionStore;
     readonly identityStore: WaIdentityStore;
     readonly deviceListStore: WaDeviceListStore;
+    readonly signalDeviceSync: SignalDeviceSyncApi;
     readonly messageSecretStore: WaMessageSecretStore;
-    readonly getCurrentMeJid: () => string | null | undefined;
-    readonly getCurrentMeLid: () => string | null | undefined;
-    readonly getCurrentSignedIdentity: () => Proto.IADVSignedDeviceIdentity | null | undefined;
+    readonly getCurrentCredentials: () => WaAuthCredentials | null;
     readonly resolvePrivacyTokenNode: (recipientJid: string) => Promise<BinaryNode | null>;
     readonly onDirectMessageSent: (recipientJid: string) => void;
+    readonly sendNewsletterMessage?: (newsletterJid: string, content: WaSendMessageContent, options: WaSendMessageOptions, contextInfo: WaSendContextInfo | null) => Promise<WaMessagePublishResult>;
     readonly getIcdcHashLength?: () => number;
     readonly mobileMessageIdFormat?: boolean;
+    readonly serverClock: ServerClock;
 }
 export declare class WaMessageDispatchCoordinator {
-    private readonly logger;
-    private readonly messageClient;
-    private readonly retryTracker;
-    private readonly sessionResolver;
-    private readonly fanoutResolver;
-    private readonly participantsCache;
-    private readonly appStateSyncKeyProtocol;
-    private readonly buildMessageContent;
-    private readonly senderKeyManager;
-    private readonly signalProtocol;
-    private readonly signalStore;
-    private readonly sessionStore;
-    private readonly identityStore;
-    private readonly deviceListStore;
-    private readonly messageSecretStore;
-    private readonly getCurrentMeJid;
-    private readonly getCurrentMeLid;
-    private readonly getCurrentSignedIdentity;
-    private readonly resolvePrivacyTokenNode;
-    private readonly onDirectMessageSent;
-    private readonly getIcdcHashLength;
+    private readonly deps;
     private readonly mobileMessageIdFormat;
+    private readonly serverClock;
     private readonly icdcDedup;
     private readonly privacyTokenDedup;
     private readonly distributionDedup;
@@ -72,23 +65,53 @@ export declare class WaMessageDispatchCoordinator {
     publishEncryptedMessage(input: WaEncryptedMessageInput, options?: WaMessagePublishOptions): Promise<WaMessagePublishResult>;
     publishSignalMessage(input: WaSignalMessagePublishInput, options?: WaMessagePublishOptions): Promise<WaMessagePublishResult>;
     sendMessage(to: string, content: WaSendMessageContent, options?: WaSendMessageOptions): Promise<WaMessagePublishResult>;
+    /**
+     * For a 1:1 recipient passed in PN form, returns the LID-addressed user JID
+     * (cache-first; falls back to a one-shot `queryLidsByPhoneJids`). Switching
+     * to LID before fanout ensures the envelope, eligible-requester list, and
+     * retry-receipt addressing all agree, which keeps the retry tracker from
+     * rejecting receipts that arrive in LID form. Returns the original PN if
+     * no LID is known/resolvable. Inputs already in LID form pass through.
+     */
+    private resolveDirectRecipientLid;
     syncSignalSession(jid: string, reasonIdentity?: boolean): Promise<void>;
     sendReceipt(input: WaSendReceiptInput): Promise<void>;
+    publishProtocolMessageToDevice(deviceJid: string, protocolMessage: Proto.Message.IProtocolMessage, options?: {
+        readonly id?: string;
+        readonly pushPriority?: 'high' | 'high_force';
+    }): Promise<WaMessagePublishResult>;
+    publishStatusMessage(input: {
+        readonly message: Proto.IMessage;
+        readonly recipients: readonly string[];
+        readonly statusSetting?: WaStatusDistributionSetting;
+        readonly options?: WaSendMessageOptions;
+    }): Promise<WaMessagePublishResult>;
+    publishBroadcastListMessage(input: {
+        readonly listJid: string;
+        readonly message: Proto.IMessage;
+        readonly recipients: readonly string[];
+        readonly options?: WaSendMessageOptions;
+    }): Promise<WaMessagePublishResult>;
+    private publishSenderKeyFanout;
     requestAppStateSyncKeys(keyIds: readonly Uint8Array[]): Promise<readonly string[]>;
     sendAppStateSyncKeyShare(toDeviceJid: string, keys: readonly WaAppStateSyncKey[], missingKeyIds?: readonly Uint8Array[]): Promise<void>;
-    mutateParticipantsCacheFromGroupEvent(event: WaGroupEvent): Promise<void>;
+    mutateGroupMetadataCacheFromGroupEvent(event: WaGroupEvent): Promise<void>;
     private shouldUseGroupDirectPath;
     private publishGroupDirectMessage;
+    private buildBotSidecarParticipant;
     private publishGroupSenderKeyMessage;
     private resolveGroupAddressingMode;
     private resolveSenderForAddressingMode;
     private encryptGroupDistributionParticipants;
     private publishDirectSignalMessageWithFanout;
     private withResolvedMessageId;
-    private generateOutgoingMessageId;
+    generateOutgoingMessageId(): Promise<string>;
     private tryBuildReportingTokenArtifacts;
     private getEncodedSignedDeviceIdentity;
-    private resolveUserIcdc;
+    resolveUserIcdc(userJid: string, localIdentity?: {
+        readonly address: SignalAddress;
+        readonly pubKey: Uint8Array;
+    }): Promise<IcdcMeta | null>;
     private requireCurrentMeJid;
 }
 export {};

package/dist/types/client/coordinators/WaNewsletterCoordinator.d.ts

@@ -0,0 +1,13 @@
+import { type WaNewsletterAdminOps } from '../newsletter/admin';
+import { type WaNewsletterDiscoveryOps } from '../newsletter/discovery';
+import { type WaNewsletterMessagingDeps, type WaNewsletterMessagingOps } from '../newsletter/messaging';
+export { parseNewsletterMetadata } from '../newsletter/parse';
+export type { WaNewsletterAdminInfo, WaNewsletterAdminInviteInput, WaNewsletterAdminInviteResult, WaNewsletterAdminProfile, WaNewsletterCapabilityExposure, WaNewsletterCreateInput, WaNewsletterDehydratedMetadata, WaNewsletterDirectoryCategoriesPreviewOptions, WaNewsletterDirectoryCategoryPreview, WaNewsletterDirectoryListOptions, WaNewsletterDirectoryResults, WaNewsletterDirectorySearchOptions, WaNewsletterDirectoryView, WaNewsletterFetchOptions, WaNewsletterFollower, WaNewsletterFollowersOptions, WaNewsletterFollowersPage, WaNewsletterInsightMetricRequest, WaNewsletterMetadata, WaNewsletterMuteInput, WaNewsletterPicture, WaNewsletterPollVoter, WaNewsletterReactInput, WaNewsletterReactionSenders, WaNewsletterRecommendedOptions, WaNewsletterRevokeInput, WaNewsletterSendOptions, WaNewsletterSendResult, WaNewsletterSimilarOptions, WaNewsletterUpdateInput, WaNewsletterViewReceiptInput, WaNewsletterVotePollInput, WaPageInfo } from '../newsletter/types';
+/**
+ * Newsletter coordinator surface – combines the discovery, admin, and
+ * messaging operation sets. Accessed via {@link WaClient.newsletter}.
+ */
+export type WaNewsletterCoordinator = WaNewsletterDiscoveryOps & WaNewsletterAdminOps & WaNewsletterMessagingOps;
+export type WaNewsletterCoordinatorOptions = WaNewsletterMessagingDeps;
+/** Builds a {@link WaNewsletterCoordinator} from its MEX/messaging dependencies. */
+export declare function createNewsletterCoordinator(options: WaNewsletterCoordinatorOptions): WaNewsletterCoordinator;

package/dist/types/client/coordinators/WaPassiveTasksCoordinator.d.ts

@@ -1,4 +1,4 @@
-import type { WaAppStateSyncClient } from '../../appstate/WaAppStateSyncClient';
+import type { WaAppStateSyncClient } from '../../appstate/sync/WaAppStateSyncClient';
 import type { WaAuthCredentials } from '../../auth/types';
 import type { Logger } from '../../infra/log/types';
 import type { SignalDigestSyncApi } from '../../signal/api/SignalDigestSyncApi';
@@ -13,11 +13,11 @@ type WaPassiveTasksRuntime = {
     readonly getCurrentCredentials: () => WaAuthCredentials | null;
     readonly persistServerHasPreKeys: (serverHasPreKeys: boolean) => Promise<void>;
     readonly sendNodeDirect: (node: BinaryNode) => Promise<void>;
-    readonly takeDanglingReceipts: () => BinaryNode[];
+    readonly takeDanglingReceipts: () => readonly BinaryNode[];
     readonly requeueDanglingReceipt: (node: BinaryNode) => void;
     readonly shouldQueueDanglingReceipt: (node: BinaryNode, error: Error) => boolean;
     readonly syncAbProps: () => void;
-    readonly sendPresenceAvailable: () => Promise<void>;
+    readonly sendInitialPresence: () => Promise<void>;
 };
 export declare class WaPassiveTasksCoordinator {
     private readonly logger;
@@ -48,6 +48,7 @@ export declare class WaPassiveTasksCoordinator {
     handleDigestNotification(): Promise<void>;
     resetInFlightState(): void;
     private runPassiveTasksAfterConnect;
+    private sendActiveModeIq;
     private validateDigestAndRecoverPreKeys;
     private uploadPreKeysIfMissing;
     private rotateSignedPreKeyIfDue;

package/dist/types/client/coordinators/WaPresenceCoordinator.d.ts

@@ -0,0 +1,27 @@
+import type { WaAuthCredentials } from '../../auth/types';
+import { type BuildChatstateNodeInput } from '../../transport/node/builders/chatstate';
+import { type BuildPresenceSubscribeNodeInput } from '../../transport/node/builders/presence';
+import type { BinaryNode } from '../../transport/types';
+/**
+ * Coordinates own presence broadcasts and peer presence subscriptions.
+ * Accessed via {@link WaClient.presence}.
+ */
+export interface WaPresenceCoordinator {
+    /** Broadcasts the current account's `available`/`unavailable` presence. */
+    readonly send: (type?: 'available' | 'unavailable') => Promise<void>;
+    /** Sends a chatstate hint (typing/recording/paused/...) into a specific chat. */
+    readonly sendChatstate: (jid: string, options: Omit<BuildChatstateNodeInput, 'jid'>) => Promise<void>;
+    /**
+     * Subscribes to presence updates (online/offline + chatstate) for a chat.
+     * The subscription is per-jid and lives only for the current connection;
+     * after a reconnect the caller must re-subscribe to keep receiving events.
+     */
+    readonly subscribe: (jid: string, options?: Omit<BuildPresenceSubscribeNodeInput, 'jid'>) => Promise<void>;
+}
+interface WaPresenceCoordinatorOptions {
+    readonly sendNode: (node: BinaryNode) => Promise<void>;
+    readonly getCurrentCredentials: () => WaAuthCredentials | null;
+}
+/** Builds a {@link WaPresenceCoordinator} from its node-send dependency. */
+export declare function createPresenceCoordinator(options: WaPresenceCoordinatorOptions): WaPresenceCoordinator;
+export {};

package/dist/types/client/coordinators/WaPrivacyCoordinator.d.ts

@@ -11,16 +11,43 @@ export interface WaBlocklistResult {
     readonly jids: readonly string[];
     readonly dhash?: string;
 }
+/**
+ * Coordinates privacy queries/mutations: per-category settings, blocklist,
+ * and the per-category disallowed lists. Accessed via {@link WaClient.privacy}.
+ */
 export interface WaPrivacyCoordinator {
+    /** Fetches the current value of every privacy category. */
     readonly getPrivacySettings: () => Promise<WaPrivacySettings>;
+    /**
+     * Updates a single privacy category to a new {@link WaPrivacyValue}.
+     *
+     * The `'contact_blacklist'` value (a deny-list of specific contacts on
+     * top of `'contacts'`/`'all'`) only flips the **mode** here - you must
+     * separately populate the per-category disallowed list with
+     * {@link getDisallowedList} + the corresponding app-state mutation, or
+     * the deny-list stays empty.
+     */
     readonly setPrivacySetting: <S extends WaPrivacySettingName>(setting: S, value: WaPrivacySettingValueMap[S]) => Promise<void>;
+    /**
+     * Fetches the per-category disallowed list (the JIDs explicitly excluded
+     * from `contact_blacklist`/`contact_whitelist` style settings).
+     */
     readonly getDisallowedList: (category: WaPrivacyDisallowedListSettingName) => Promise<WaPrivacyDisallowedListResult>;
+    /** Returns the current account-wide blocklist. */
     readonly getBlocklist: () => Promise<WaBlocklistResult>;
+    /**
+     * Blocks `jid` (account-wide blocklist). After this, the peer can no
+     * longer message/call you and cannot see your last seen/online/photo/
+     * status. The block is symmetric only from the peer's read perspective -
+     * they don't get an explicit "you were blocked" notification.
+     */
     readonly blockUser: (jid: string) => Promise<void>;
+    /** Removes `jid` from the blocklist. */
     readonly unblockUser: (jid: string) => Promise<void>;
 }
 interface WaPrivacyCoordinatorOptions {
     readonly queryWithContext: (context: string, node: BinaryNode, timeoutMs?: number, contextData?: Readonly<Record<string, unknown>>) => Promise<BinaryNode>;
 }
+/** Builds a {@link WaPrivacyCoordinator} backed by the given IQ query function. */
 export declare function createPrivacyCoordinator(options: WaPrivacyCoordinatorOptions): WaPrivacyCoordinator;
 export {};

package/dist/types/client/coordinators/WaProfileCoordinator.d.ts

@@ -1,4 +1,8 @@
+import type { WaAppStateMutationCoordinator } from '../coordinators/WaAppStateMutationCoordinator';
+import type { Logger } from '../../infra/log/types';
+import type { SignalLidSyncResult } from '../../signal/api/SignalDeviceSyncApi';
 import { type WaProfilePictureType } from '../../transport/node/builders/profile';
+import { type WaMexQuerySocket } from '../../transport/node/mex/client';
 import type { BinaryNode } from '../../transport/types';
 export interface WaProfilePictureResult {
     readonly url?: string;
@@ -19,20 +23,129 @@ export interface WaDisappearingModeResult {
     readonly timestamp: number;
     readonly ephemeralityDisabled?: boolean;
 }
+export interface WaTextStatusResult {
+    readonly jid: string;
+    readonly text: string | null;
+    readonly emoji: string | null;
+    readonly ephemeralDurationSec: number | null;
+    readonly lastUpdateTime: number | null;
+}
+export interface WaSetTextStatusInput {
+    readonly text?: string | null;
+    readonly emoji?: string | null;
+    readonly ephemeralDurationSec?: number | null;
+}
+export interface WaUsernameResult {
+    readonly jid: string;
+    readonly username: string | null;
+}
+export interface WaOwnUsernameResult {
+    readonly username: string | null;
+    readonly state: string | null;
+    readonly pin: string | null;
+}
+export interface WaSetUsernameInput {
+    readonly username: string;
+    readonly reserved?: boolean;
+    readonly sessionId?: string;
+    readonly source?: 'USER_INPUT';
+}
+export interface WaUsernameAvailabilityResult {
+    readonly available: boolean;
+    readonly suggestions: readonly string[];
+}
+/**
+ * Coordinates own/peer profile queries and mutations: picture, status, text
+ * status, username, disappearing mode, and LID lookup. Accessed via
+ * {@link WaClient.profile}.
+ */
 export interface WaProfileCoordinator {
+    /** Fetches a profile picture envelope (URL + direct path + id). */
     readonly getProfilePicture: (jid: string, type?: WaProfilePictureType, existingId?: string) => Promise<WaProfilePictureResult>;
+    /**
+     * Sets the profile picture for the current account or `targetJid`
+     * (group/community admin operation when set). `imageBytes` is uploaded
+     * **as-is** - the library does not transcode, resize, or crop, so pass
+     * pre-encoded JPEG bytes shaped to WhatsApp's expected picture format
+     * (square, JPEG, reasonable resolution). Returns the server-side
+     * picture id on success.
+     */
     readonly setProfilePicture: (imageBytes: Uint8Array, targetJid?: string) => Promise<string | null>;
+    /** Deletes the profile picture for the current account or `targetJid` (admin op for groups/communities). */
     readonly deleteProfilePicture: (targetJid?: string) => Promise<void>;
+    /** Fetches the legacy "About" status for a single JID. */
     readonly getStatus: (jid: string) => Promise<WaProfileStatusResult>;
+    /** Sets the current account's legacy "About" status. */
     readonly setStatus: (text: string) => Promise<void>;
+    /**
+     * Sets the account's pushName - the display name broadcast to other
+     * users in chats and group participant lists. WhatsApp Web applies the
+     * change via a `SettingPushName` app-state mutation (collection
+     * `critical_block`); the new value reaches peers as their next
+     * incoming-message envelope from this account carries the updated
+     * `notify` attr. Empty strings are accepted but reset the display name
+     * to the device fingerprint default.
+     */
+    readonly setPushName: (name: string) => Promise<void>;
+    /** Batched usync fetch of picture id + status for many JIDs. */
     readonly getProfiles: (jids: readonly string[]) => Promise<readonly WaProfileInfo[]>;
+    /** Batched fetch of the disappearing-mode setting per JID. */
     readonly getDisappearingMode: (jids: readonly string[]) => Promise<readonly WaDisappearingModeResult[]>;
+    /**
+     * Sets the account-wide default disappearing-mode duration applied to
+     * **new** 1:1 chats started by this account. `durationSeconds` is the
+     * ephemeral message lifetime (`0` disables, `86400` = 24h, `604800` =
+     * 7d, `7776000` = 90d). Existing chats keep their per-chat setting -
+     * change that with a system `disappearing_mode` message instead.
+     */
+    readonly setDisappearingMode: (durationSeconds: number) => Promise<void>;
+    /** Batched fetch of the modern text-status (emoji + text) per JID. */
+    readonly getTextStatuses: (jids: readonly string[]) => Promise<readonly WaTextStatusResult[]>;
+    /**
+     * Updates the current account's text status (the modern "About" emoji +
+     * text shown in chat). Passing `text: null` (or `''`) **clears** the
+     * status; passing `ephemeralDurationSec` without `text` and `emoji` is
+     * silently coerced back to `0` (server rejects expiring empty statuses).
+     */
+    readonly setTextStatus: (input: WaSetTextStatusInput) => Promise<void>;
+    /** Batched fetch of username per JID. */
+    readonly getUsernames: (jids: readonly string[]) => Promise<readonly WaUsernameResult[]>;
+    /** Fetches the current account's username record (value, state, recovery pin). */
+    readonly getOwnUsername: () => Promise<WaOwnUsernameResult>;
+    /**
+     * Reserves/sets a username on the current account. Returns `true` only
+     * when the server reports `'SUCCESS'`; on any other outcome (taken,
+     * invalid, rate-limited) it returns `false` without throwing - check the
+     * value and consult {@link checkUsernameAvailability} for suggestions.
+     */
+    readonly setUsername: (input: WaSetUsernameInput) => Promise<boolean>;
+    /** Deletes the current account's username. Returns `true` on success. */
+    readonly deleteUsername: () => Promise<boolean>;
+    /** Fetches the "About" text for a single JID via MEX. */
+    readonly getAboutStatus: (jid: string) => Promise<string | null>;
+    /** Checks whether a username is available and returns server suggestions. */
+    readonly checkUsernameAvailability: (username: string) => Promise<WaUsernameAvailabilityResult>;
+    /** Sets the username recovery PIN. Returns `true` on success. */
+    readonly setUsernameKey: (pin: string) => Promise<boolean>;
+    /** Resolves LIDs for a list of phone numbers (handles normalization). */
+    readonly getLidsByPhoneNumbers: (phoneNumbers: readonly string[]) => Promise<readonly SignalLidSyncResult[]>;
 }
 interface WaProfileCoordinatorOptions {
     readonly queryWithContext: (context: string, node: BinaryNode, timeoutMs?: number, contextData?: Readonly<Record<string, unknown>>, options?: {
         readonly useSystemId?: boolean;
     }) => Promise<BinaryNode>;
     readonly generateSid: () => Promise<string>;
+    readonly mexSocket: WaMexQuerySocket;
+    readonly queryLidsByPhoneJids: (phoneJids: readonly string[]) => Promise<readonly SignalLidSyncResult[]>;
+    /**
+     * App-state mutation coordinator. {@link WaProfileCoordinator.setPushName}
+     * routes through `mutations.set({ schema: 'SettingPushName', ... })` so
+     * the pushName change shares the same flush pipeline as other queued
+     * mutations.
+     */
+    readonly mutations: WaAppStateMutationCoordinator;
+    readonly logger: Logger;
 }
+/** Builds a {@link WaProfileCoordinator} from its IQ/MEX/SID dependencies. */
 export declare function createProfileCoordinator(options: WaProfileCoordinatorOptions): WaProfileCoordinator;
 export {};