zapo-js 0.3.0 → 1.0.0

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

@@ -1,5 +1,9 @@
-import { WA_APP_STATE_CHAT_MUTATION_SPECS, WA_APP_STATE_COLLECTION_STATES } from '../../protocol/constants.js';
-import { isGroupJid, isGroupOrBroadcastJid, normalizeDeviceJid, normalizeRecipientJid, toUserJid } from '../../protocol/jid.js';
+import { downloadExternalBlobReference } from '../../appstate/utils.js';
+import { encodeEnumValue, WA_APPSTATE_SCHEMAS } from '../../appstate-spec.js';
+import { parseAppStateMutationEvent } from '../events/appstate-mutation.js';
+import { proto } from '../../proto.js';
+import { WA_APP_STATE_COLLECTION_STATES } from '../../protocol/constants.js';
+import { isGroupJid, isGroupOrBroadcastJid, isLidJid, isUserJid, normalizeDeviceJid, normalizeRecipientJid, toUserJid } from '../../protocol/jid.js';
 import { resolvePositive } from '../../util/coercion.js';
 import { toError } from '../../util/primitives.js';
 const WA_APP_STATE_MUTATION_FLUSH_SUCCESS_STATES = new Set([
@@ -7,18 +11,364 @@ const WA_APP_STATE_MUTATION_FLUSH_SUCCESS_STATES = new Set([
     WA_APP_STATE_COLLECTION_STATES.SUCCESS_HAS_MORE
 ]);
 const WA_APP_STATE_ARCHIVE_RANGE_DEFAULT_LIMIT = 256;
+function buildMutationIndexFromSchema(schema, indexArgs) {
+    const parts = new Array(schema.indexParts.length);
+    const args = indexArgs;
+    for (let i = 0; i < schema.indexParts.length; i += 1) {
+        const part = schema.indexParts[i];
+        if (part.type === 'literal') {
+            parts[i] = part.value;
+            continue;
+        }
+        const arg = args[part.name];
+        if (part.type === 'boolString') {
+            parts[i] = arg ? '1' : '0';
+            continue;
+        }
+        if (part.type === 'jidOrZero') {
+            if (arg === null || arg === undefined) {
+                const fromMeSlot = schema.indexParts.find((p) => p.type === 'boolString' && p.name === 'fromMe');
+                if (fromMeSlot && args['fromMe'] !== true) {
+                    throw new Error(`app-state index arg "${part.name}" for schema "${schema.name}" requires a JID when fromMe is not true`);
+                }
+                parts[i] = '0';
+                continue;
+            }
+            parts[i] = arg;
+            continue;
+        }
+        if (part.type === 'enum') {
+            if (typeof arg === 'number') {
+                parts[i] = String(arg);
+                continue;
+            }
+            if (typeof arg !== 'string') {
+                throw new Error(`app-state enum index arg "${part.name}" for schema "${schema.name}" must be a string`);
+            }
+            const numeric = encodeEnumValue(part.protoEnum, arg);
+            if (numeric === null) {
+                throw new Error(`app-state enum index arg "${part.name}"="${arg}" is not in enum ${part.protoEnum}`);
+            }
+            parts[i] = String(numeric);
+            continue;
+        }
+        if (typeof arg !== 'string') {
+            throw new Error(`app-state index arg "${part.name}" for schema "${schema.name}" must be a string`);
+        }
+        parts[i] = arg;
+    }
+    return JSON.stringify(parts);
+}
+function buildSetMutationFromSchema(input) {
+    return {
+        collection: input.schema.collection,
+        operation: 'set',
+        index: buildMutationIndexFromSchema(input.schema, input.indexArgs),
+        value: { ...input.value, timestamp: input.timestamp },
+        version: input.schema.version,
+        timestamp: input.timestamp
+    };
+}
+function splitFlatInput(schema, input) {
+    const indexNames = new Set();
+    for (const part of schema.indexParts) {
+        if (part.type !== 'literal') {
+            indexNames.add(part.name);
+        }
+    }
+    const indexArgs = {};
+    const data = {};
+    for (const key of Object.keys(input)) {
+        if (key === 'schema')
+            continue;
+        if (indexNames.has(key)) {
+            indexArgs[key] = input[key];
+        }
+        else {
+            data[key] = input[key];
+        }
+    }
+    return { indexArgs, data };
+}
+function wrapData(schema, data) {
+    const encoded = applyEnumEncodeToData(schema.valueEnumFields, data);
+    const field = schema.valueField;
+    if (field === null) {
+        return encoded;
+    }
+    return { [field]: encoded };
+}
+function applyEnumEncodeToData(enumFields, data) {
+    if (!enumFields)
+        return { ...data };
+    const out = { ...data };
+    for (const [fieldPath, enumPath] of Object.entries(enumFields)) {
+        applyEnumAtPath(out, fieldPath.split('.'), (raw) => {
+            if (typeof raw === 'number')
+                return raw;
+            if (typeof raw !== 'string')
+                return raw;
+            const numeric = encodeEnumValue(enumPath, raw);
+            if (numeric === null) {
+                throw new Error(`enum value "${raw}" not in ${enumPath}`);
+            }
+            return numeric;
+        });
+    }
+    return out;
+}
+function applyEnumAtPath(obj, segments, transform) {
+    if (segments.length === 0)
+        return;
+    const [head, ...rest] = segments;
+    if (rest.length === 0) {
+        if (head in obj) {
+            const value = obj[head];
+            if (Array.isArray(value)) {
+                obj[head] = value.map(transform);
+            }
+            else if (value !== null && value !== undefined) {
+                obj[head] = transform(value);
+            }
+        }
+        return;
+    }
+    const next = obj[head];
+    if (Array.isArray(next)) {
+        const cloned = next.map((item) => {
+            if (item && typeof item === 'object') {
+                const itemCopy = { ...item };
+                applyEnumAtPath(itemCopy, rest, transform);
+                return itemCopy;
+            }
+            return item;
+        });
+        obj[head] = cloned;
+        return;
+    }
+    if (next && typeof next === 'object') {
+        const nextCopy = { ...next };
+        applyEnumAtPath(nextCopy, rest, transform);
+        obj[head] = nextCopy;
+    }
+}
+function buildRemoveMutationFromSchema(input) {
+    return {
+        collection: input.schema.collection,
+        operation: 'remove',
+        index: buildMutationIndexFromSchema(input.schema, input.indexArgs),
+        previousValue: { timestamp: input.timestamp },
+        version: input.schema.version,
+        timestamp: input.timestamp
+    };
+}
+/**
+ * Coordinates app-state mutations (mute/star/read/pin/archive/clear/delete/
+ * lock chats, status privacy, broadcast lists) and emits parsed mutation
+ * events on sync. Accessed via {@link WaClient.chat}.
+ */
 export class WaAppStateMutationCoordinator {
     constructor(options) {
         this.logger = options.logger;
         this.messageStore = options.messageStore;
-        this.syncAppState = options.syncAppState;
+        this.appStateSync = options.appStateSync;
+        this.mediaTransfer = options.mediaTransfer;
+        this.isConnected = options.isConnected;
+        this.serverClock = options.serverClock;
         this.archiveRangeLimit = resolvePositive(options.archiveRangeLimit, WA_APP_STATE_ARCHIVE_RANGE_DEFAULT_LIMIT, 'WaAppStateMutationCoordinatorOptions.archiveRangeLimit');
+        this.emitMutation = options.emitMutation;
+        this.emitSnapshotMutations = options.emitSnapshotMutations === true;
+        this.nctSaltSink = options.nctSaltSink;
+        this.contactSink = options.contactSink;
         this.pendingMutations = new Map();
         this.flushPromise = null;
     }
+    /**
+     * Runs an app-state sync round, optionally applying pending mutations.
+     * Throws when the client is not connected. Returns the per-collection
+     * result; blocked collections are logged.
+     */
+    async sync(options = {}) {
+        if (!this.isConnected()) {
+            throw new Error('client is not connected');
+        }
+        const syncOptions = options.downloadExternalBlob
+            ? options
+            : {
+                ...options,
+                downloadExternalBlob: async (_collection, _kind, reference) => downloadExternalBlobReference(this.mediaTransfer, reference)
+            };
+        const syncResult = await this.appStateSync.sync(syncOptions);
+        const blockedCollections = this.getBlockedCollections(syncResult);
+        if (blockedCollections.length > 0) {
+            this.logger.warn('app-state sync has blocked collections', {
+                blockedCollections: blockedCollections.join(',')
+            });
+        }
+        this.emitEventsFromSyncResult(syncResult);
+        return syncResult;
+    }
+    /** Returns the names of collections reported as `BLOCKED` in `syncResult`. */
+    getBlockedCollections(syncResult) {
+        const blocked = [];
+        for (const entry of syncResult.collections) {
+            if (entry.state === WA_APP_STATE_COLLECTION_STATES.BLOCKED) {
+                blocked.push(entry.collection);
+            }
+        }
+        return blocked;
+    }
+    /**
+     * Walks a sync result and emits one `app_state_mutation` event per
+     * distinct (collection, index) – only the last mutation per key wins.
+     * Snapshot-source mutations are skipped unless `emitSnapshotMutations`
+     * was enabled at construction.
+     */
+    emitEventsFromSyncResult(syncResult) {
+        for (const collectionResult of syncResult.collections) {
+            const mutations = collectionResult.mutations ?? [];
+            // Persistence sinks (contact store, ...): run on the last-wins
+            // mutation per key INCLUDING snapshot sources, so pair-time
+            // bootstrap of the address book always lands in the store even
+            // when public events are suppressed for snapshot mutations.
+            if (this.contactSink) {
+                const sinkLastIndex = new Map();
+                for (let i = 0; i < mutations.length; i += 1) {
+                    const m = mutations[i];
+                    sinkLastIndex.set(`${m.collection}\u0001${m.index}`, i);
+                }
+                for (let i = 0; i < mutations.length; i += 1) {
+                    const m = mutations[i];
+                    if (sinkLastIndex.get(`${m.collection}\u0001${m.index}`) !== i) {
+                        continue;
+                    }
+                    try {
+                        this.handleContactMutation(m);
+                    }
+                    catch (error) {
+                        this.logger.debug('contact sink failed', {
+                            collection: m.collection,
+                            index: m.index,
+                            message: toError(error).message
+                        });
+                    }
+                }
+            }
+            const lastMutationIndexByKey = new Map();
+            for (let mutationIndex = 0; mutationIndex < mutations.length; mutationIndex += 1) {
+                const mutation = mutations[mutationIndex];
+                if (!this.emitSnapshotMutations && mutation.source === 'snapshot') {
+                    continue;
+                }
+                lastMutationIndexByKey.set(`${mutation.collection}\u0001${mutation.index}`, mutationIndex);
+            }
+            for (let mutationIndex = 0; mutationIndex < mutations.length; mutationIndex += 1) {
+                const mutation = mutations[mutationIndex];
+                if (!this.emitSnapshotMutations && mutation.source === 'snapshot') {
+                    continue;
+                }
+                const coalesceKey = `${mutation.collection}\u0001${mutation.index}`;
+                if (lastMutationIndexByKey.get(coalesceKey) !== mutationIndex) {
+                    continue;
+                }
+                try {
+                    this.handleNctSaltMutation(mutation);
+                    const event = parseAppStateMutationEvent(mutation);
+                    if (!event) {
+                        continue;
+                    }
+                    this.emitMutation?.(event);
+                }
+                catch (error) {
+                    this.logger.debug('failed to parse app-state mutation event', {
+                        collection: mutation.collection,
+                        source: mutation.source,
+                        index: mutation.index,
+                        message: toError(error).message
+                    });
+                }
+            }
+        }
+    }
+    handleNctSaltMutation(mutation) {
+        if (!this.nctSaltSink)
+            return;
+        const nctAction = mutation.value?.nctSaltSyncAction;
+        if (!nctAction) {
+            return;
+        }
+        if (mutation.operation === 'set' && nctAction.salt) {
+            this.nctSaltSink(nctAction.salt).catch((err) => this.logger.warn('nct salt sync set failed', {
+                message: toError(err).message
+            }));
+        }
+        else if (mutation.operation === 'remove') {
+            this.nctSaltSink(null).catch((err) => this.logger.warn('nct salt sync remove failed', {
+                message: toError(err).message
+            }));
+        }
+    }
+    handleContactMutation(mutation) {
+        if (!this.contactSink)
+            return;
+        // Cheap reject before JSON.parse: Contact mutations always carry
+        // the literal "contact" as their first index segment.
+        if (!mutation.index.includes('"contact"'))
+            return;
+        let parts;
+        try {
+            parts = JSON.parse(mutation.index);
+        }
+        catch {
+            return;
+        }
+        if (!Array.isArray(parts) || parts[0] !== 'contact' || typeof parts[1] !== 'string') {
+            return;
+        }
+        const indexJid = parts[1];
+        const lastUpdatedMs = mutation.timestamp > 0 ? mutation.timestamp : Date.now();
+        // Remove operations are a no-op for the contact store: `mergeContact`
+        // preserves prior displayName when incoming.displayName is undefined,
+        // and the row should stay around (the chat may still be open). The
+        // public mutation event still fires below so consumers can react.
+        if (mutation.operation === 'remove')
+            return;
+        const action = mutation.value?.contactAction;
+        if (!action)
+            return;
+        // Resolve canonical (LID-preferred) jid + cross-reference: the index
+        // typically carries the PN form, and `contactAction.lidJid` carries
+        // the LID counterpart. Store one row keyed by LID when both are known
+        // (mirrors what the contact store does for history-sync writes), with
+        // `phoneNumber` populated so PN-form lookups still resolve.
+        const lid = action.lidJid && isLidJid(action.lidJid) ? action.lidJid : undefined;
+        const indexIsPn = isUserJid(indexJid);
+        const indexIsLid = isLidJid(indexJid);
+        const jid = lid ?? indexJid;
+        const phoneNumber = indexIsPn ? indexJid : undefined;
+        const lidField = lid ?? (indexIsLid ? indexJid : undefined);
+        const displayName = action.fullName || action.firstName || undefined;
+        this.contactSink({
+            jid,
+            displayName,
+            lid: lidField,
+            phoneNumber,
+            lastUpdatedMs
+        });
+    }
+    /**
+     * Mutes or unmutes a chat. `muteEndTimestampMs` is required when
+     * `muted` is `true` and must be a non-negative safe-integer epoch.
+     *
+     * For a "mute forever" entry, pass a very large epoch value (the
+     * official client uses year-9999 epochs). The mute end is the absolute
+     * timestamp when WhatsApp will re-enable notifications - the client
+     * does **not** unmute automatically when the timer expires (you'll see
+     * the chat un-muted on the phone, but no `mutation` event re-fires).
+     */
     async setChatMute(chatJid, muted, muteEndTimestampMs) {
         const chatIndexJid = this.normalizeChatMutationJid(chatJid);
-        const timestamp = Date.now();
+        const timestamp = this.serverClock.nowMs();
         const normalizedMuteEnd = muteEndTimestampMs;
         if (normalizedMuteEnd !== undefined &&
             (!Number.isFinite(normalizedMuteEnd) ||
@@ -29,66 +379,63 @@ export class WaAppStateMutationCoordinator {
         if (muted && normalizedMuteEnd === undefined) {
             throw new Error('setChatMute requires muteEndTimestampMs when muted is true');
         }
-        const mutation = this.createSetMutation({
-            spec: WA_APP_STATE_CHAT_MUTATION_SPECS.MUTE,
-            chatIndexJid,
-            value: {
-                muteAction: {
-                    muted,
-                    ...(normalizedMuteEnd === undefined
-                        ? {}
-                        : { muteEndTimestamp: normalizedMuteEnd })
-                }
-            },
-            timestamp
-        });
-        await this.enqueueAndFlush([mutation]);
+        await this.enqueueAndFlush([
+            buildSetMutationFromSchema({
+                schema: WA_APPSTATE_SCHEMAS.Mute,
+                indexArgs: { chatJid: chatIndexJid },
+                value: {
+                    muteAction: {
+                        muted,
+                        ...(normalizedMuteEnd === undefined
+                            ? {}
+                            : { muteEndTimestamp: normalizedMuteEnd })
+                    }
+                },
+                timestamp
+            })
+        ]);
     }
+    /** Stars or un-stars a specific message. */
     async setMessageStar(message, starred) {
         const messageIndex = this.buildMessageMutationIndex(message);
-        const timestamp = Date.now();
-        const mutation = this.createSetMutation({
-            spec: WA_APP_STATE_CHAT_MUTATION_SPECS.STAR,
-            chatIndexJid: messageIndex.chatIndexJid,
-            value: {
-                starAction: {
-                    starred
-                }
-            },
-            timestamp,
-            indexPartsTail: messageIndex.indexPartsTail
-        });
-        await this.enqueueAndFlush([mutation]);
+        const timestamp = this.serverClock.nowMs();
+        await this.enqueueAndFlush([
+            buildSetMutationFromSchema({
+                schema: WA_APPSTATE_SCHEMAS.Star,
+                indexArgs: messageIndex,
+                value: { starAction: { starred } },
+                timestamp
+            })
+        ]);
     }
+    /** Marks the chat as read or unread. */
     async setChatRead(chatJid, read) {
         const chatIndexJid = this.normalizeChatMutationJid(chatJid);
-        const timestamp = Date.now();
+        const timestamp = this.serverClock.nowMs();
         const messageRange = await this.buildChatMessageRange(chatIndexJid);
-        const mutation = this.createSetMutation({
-            spec: WA_APP_STATE_CHAT_MUTATION_SPECS.MARK_CHAT_AS_READ,
-            chatIndexJid,
-            value: {
-                markChatAsReadAction: {
-                    read,
-                    messageRange
-                }
-            },
-            timestamp
-        });
-        await this.enqueueAndFlush([mutation]);
+        await this.enqueueAndFlush([
+            buildSetMutationFromSchema({
+                schema: WA_APPSTATE_SCHEMAS.MarkChatAsRead,
+                indexArgs: { chatJid: chatIndexJid },
+                value: { markChatAsReadAction: { read, messageRange } },
+                timestamp
+            })
+        ]);
     }
+    /**
+     * Pins or unpins the chat. Pinning also clears any active archive flag
+     * (the two states are mutually exclusive on the client). WhatsApp
+     * imposes a server-side cap on pinned chats - extra pins sync but the
+     * official UI will hide / reject them.
+     */
     async setChatPin(chatJid, pinned) {
         const chatIndexJid = this.normalizeChatMutationJid(chatJid);
-        const timestamp = Date.now();
+        const timestamp = this.serverClock.nowMs();
         const pending = [
-            this.createSetMutation({
-                spec: WA_APP_STATE_CHAT_MUTATION_SPECS.PIN,
-                chatIndexJid,
-                value: {
-                    pinAction: {
-                        pinned
-                    }
-                },
+            buildSetMutationFromSchema({
+                schema: WA_APPSTATE_SCHEMAS.Pin,
+                indexArgs: { chatJid: chatIndexJid },
+                value: { pinAction: { pinned } },
                 timestamp
             })
         ];
@@ -97,66 +444,82 @@ export class WaAppStateMutationCoordinator {
         }
         await this.enqueueAndFlush(pending);
     }
+    /** Archives or unarchives the chat. Archiving also clears any pin. */
     async setChatArchive(chatJid, archived) {
         const chatIndexJid = this.normalizeChatMutationJid(chatJid);
-        const timestamp = Date.now();
+        const timestamp = this.serverClock.nowMs();
         const pending = [
             await this.createArchiveMutation(chatIndexJid, archived, timestamp)
         ];
         if (archived) {
-            pending.push(this.createSetMutation({
-                spec: WA_APP_STATE_CHAT_MUTATION_SPECS.PIN,
-                chatIndexJid,
-                value: {
-                    pinAction: {
-                        pinned: false
-                    }
-                },
+            pending.push(buildSetMutationFromSchema({
+                schema: WA_APPSTATE_SCHEMAS.Pin,
+                indexArgs: { chatJid: chatIndexJid },
+                value: { pinAction: { pinned: false } },
                 timestamp
             }));
         }
         await this.enqueueAndFlush(pending);
     }
+    /**
+     * Clears the chat history (without deleting the chat itself - it stays
+     * in the chat list, just empty). Defaults to **preserving** starred
+     * messages and media; set `options.deleteStarred`/`deleteMedia` to wipe
+     * those too. The clear is local-only - other participants keep their
+     * copies.
+     */
     async clearChat(chatJid, options = {}) {
         const chatIndexJid = this.normalizeChatMutationJid(chatJid);
-        const timestamp = Date.now();
+        const timestamp = this.serverClock.nowMs();
         const deleteStarred = options.deleteStarred === true;
         const deleteMedia = options.deleteMedia === true;
         const messageRange = await this.buildChatMessageRange(chatIndexJid);
-        const mutation = this.createSetMutation({
-            spec: WA_APP_STATE_CHAT_MUTATION_SPECS.CLEAR_CHAT,
-            chatIndexJid,
-            value: {
-                clearChatAction: {
-                    messageRange
-                }
-            },
-            timestamp,
-            indexPartsTail: [deleteStarred ? '1' : '0', deleteMedia ? '1' : '0']
-        });
-        await this.enqueueAndFlush([mutation]);
+        await this.enqueueAndFlush([
+            buildSetMutationFromSchema({
+                schema: WA_APPSTATE_SCHEMAS.ClearChat,
+                indexArgs: {
+                    chatJid: chatIndexJid,
+                    deleteStarred: deleteStarred ? '1' : '0',
+                    deleteMedia: deleteMedia ? '1' : '0'
+                },
+                value: { clearChatAction: { messageRange } },
+                timestamp
+            })
+        ]);
     }
+    /**
+     * Deletes the chat entirely (removes from the chat list + drops every
+     * stored message). Local-only - the conversation continues to exist on
+     * the peer's device. For groups, this does **not** leave the group;
+     * use {@link WaGroupCoordinator.leaveGroup} for that.
+     */
     async deleteChat(chatJid, options = {}) {
         const chatIndexJid = this.normalizeChatMutationJid(chatJid);
-        const timestamp = Date.now();
+        const timestamp = this.serverClock.nowMs();
         const deleteMedia = options.deleteMedia === true;
         const messageRange = await this.buildChatMessageRange(chatIndexJid);
-        const mutation = this.createSetMutation({
-            spec: WA_APP_STATE_CHAT_MUTATION_SPECS.DELETE_CHAT,
-            chatIndexJid,
-            value: {
-                deleteChatAction: {
-                    messageRange
-                }
-            },
-            timestamp,
-            indexPartsTail: [deleteMedia ? '1' : '0']
-        });
-        await this.enqueueAndFlush([mutation]);
+        await this.enqueueAndFlush([
+            buildSetMutationFromSchema({
+                schema: WA_APPSTATE_SCHEMAS.DeleteChat,
+                indexArgs: {
+                    chatJid: chatIndexJid,
+                    deleteMedia: deleteMedia ? '1' : '0'
+                },
+                value: { deleteChatAction: { messageRange } },
+                timestamp
+            })
+        ]);
     }
+    /**
+     * Deletes a single message **locally** - removes it from your own
+     * device(s) only. The recipient(s) still see it. Use a `revoke`
+     * outgoing message ({@link WaMessageCoordinator.send} with
+     * `{ type: 'revoke', ... }`) to delete-for-everyone instead.
+     * `messageTimestampMs` must be a non-negative safe-integer epoch when set.
+     */
     async deleteMessageForMe(message, options = {}) {
         const messageIndex = this.buildMessageMutationIndex(message);
-        const timestamp = Date.now();
+        const timestamp = this.serverClock.nowMs();
         const deleteMedia = options.deleteMedia === true;
         const messageTimestampMs = options.messageTimestampMs;
         let messageTimestamp;
@@ -168,49 +531,47 @@ export class WaAppStateMutationCoordinator {
             }
             messageTimestamp = Math.floor(messageTimestampMs / 1000);
         }
-        const mutation = this.createSetMutation({
-            spec: WA_APP_STATE_CHAT_MUTATION_SPECS.DELETE_MESSAGE_FOR_ME,
-            chatIndexJid: messageIndex.chatIndexJid,
-            value: {
-                deleteMessageForMeAction: {
-                    deleteMedia,
-                    ...(messageTimestamp === undefined ? {} : { messageTimestamp })
-                }
-            },
-            timestamp,
-            indexPartsTail: messageIndex.indexPartsTail
-        });
-        await this.enqueueAndFlush([mutation]);
+        await this.enqueueAndFlush([
+            buildSetMutationFromSchema({
+                schema: WA_APPSTATE_SCHEMAS.DeleteMessageForMe,
+                indexArgs: messageIndex,
+                value: {
+                    deleteMessageForMeAction: {
+                        deleteMedia,
+                        ...(messageTimestamp === undefined ? {} : { messageTimestamp })
+                    }
+                },
+                timestamp
+            })
+        ]);
     }
+    /** Locks or unlocks the chat. Locking also clears archive and pin. */
     async setChatLock(chatJid, locked) {
         const chatIndexJid = this.normalizeChatMutationJid(chatJid);
-        const timestamp = Date.now();
+        const timestamp = this.serverClock.nowMs();
         const pending = [];
         if (locked) {
             pending.push(await this.createArchiveMutation(chatIndexJid, false, timestamp));
-            pending.push(this.createSetMutation({
-                spec: WA_APP_STATE_CHAT_MUTATION_SPECS.PIN,
-                chatIndexJid,
-                value: {
-                    pinAction: {
-                        pinned: false
-                    }
-                },
+            pending.push(buildSetMutationFromSchema({
+                schema: WA_APPSTATE_SCHEMAS.Pin,
+                indexArgs: { chatJid: chatIndexJid },
+                value: { pinAction: { pinned: false } },
                 timestamp
             }));
         }
-        pending.push(this.createSetMutation({
-            spec: WA_APP_STATE_CHAT_MUTATION_SPECS.LOCK_CHAT,
-            chatIndexJid,
-            value: {
-                lockChatAction: {
-                    locked
-                }
-            },
+        pending.push(buildSetMutationFromSchema({
+            schema: WA_APPSTATE_SCHEMAS.LockChat,
+            indexArgs: { chatJid: chatIndexJid },
+            value: { lockChatAction: { locked } },
             timestamp
         }));
         await this.enqueueAndFlush(pending);
     }
+    /**
+     * Drains any queued mutations through a sync round. Concurrent callers
+     * share the in-flight flush promise. Failed collections are re-queued
+     * before the error is rethrown.
+     */
     async flushMutations() {
         if (this.flushPromise) {
             return this.flushPromise;
@@ -268,7 +629,7 @@ export class WaAppStateMutationCoordinator {
                     seenCollections.add(mutation.collection);
                     collections.push(mutation.collection);
                 }
-                syncResult = await this.syncAppState({
+                syncResult = await this.sync({
                     collections,
                     pendingMutations: batch
                 });
@@ -320,30 +681,190 @@ export class WaAppStateMutationCoordinator {
             this.enqueueMutation(mutation);
         }
     }
-    createSetMutation(input) {
-        return {
-            collection: input.spec.collection,
-            operation: 'set',
-            index: this.buildMutationIndex(input.spec.action, input.chatIndexJid, input.indexPartsTail ?? []),
-            value: {
-                ...input.value,
-                timestamp: input.timestamp
-            },
-            version: input.spec.version,
-            timestamp: input.timestamp
+    /**
+     * Sets the account-wide status-broadcast distribution policy. `mode`
+     * accepts either the proto enum number or its string name; allow/deny
+     * lists are provided via `userJids`.
+     */
+    async setStatusPrivacy(input) {
+        const modeValue = typeof input.mode === 'number'
+            ? input.mode
+            : proto.SyncActionValue.StatusPrivacyAction.StatusDistributionMode[input.mode];
+        if (typeof modeValue !== 'number' || !Number.isInteger(modeValue)) {
+            throw new Error(`setStatusPrivacy: invalid mode ${String(input.mode)}`);
+        }
+        const userJid = input.userJids ? [...input.userJids] : [];
+        const value = {
+            statusPrivacy: {
+                mode: modeValue,
+                userJid,
+                ...(input.shareToFB === undefined ? {} : { shareToFB: input.shareToFB }),
+                ...(input.shareToIG === undefined ? {} : { shareToIG: input.shareToIG })
+            }
+        };
+        const timestamp = this.serverClock.nowMs();
+        await this.enqueueAndFlush([
+            buildSetMutationFromSchema({
+                schema: WA_APPSTATE_SCHEMAS.StatusPrivacy,
+                indexArgs: {},
+                value,
+                timestamp
+            })
+        ]);
+    }
+    /** Mutes/unmutes a single user's status broadcasts. Rejects group/broadcast JIDs. */
+    async setUserStatusMute(jid, muted) {
+        const indexJid = this.normalizeChatMutationJid(jid);
+        if (isGroupOrBroadcastJid(indexJid)) {
+            throw new Error(`setUserStatusMute requires a user jid, got ${jid}`);
+        }
+        const timestamp = this.serverClock.nowMs();
+        await this.enqueueAndFlush([
+            buildSetMutationFromSchema({
+                schema: WA_APPSTATE_SCHEMAS.UserStatusMute,
+                indexArgs: { id: indexJid },
+                value: { userStatusMuteAction: { muted } },
+                timestamp
+            })
+        ]);
+    }
+    /** Creates or updates the broadcast list identified by `input.id`. */
+    async setBroadcastList(input) {
+        const participants = input.participants.map((entry) => ({
+            lidJid: entry.lidJid,
+            ...(entry.pnJid === undefined ? {} : { pnJid: entry.pnJid })
+        }));
+        const value = {
+            businessBroadcastListAction: {
+                participants,
+                listName: input.listName,
+                labelIds: input.labelIds ? [...input.labelIds] : []
+            }
         };
+        const timestamp = this.serverClock.nowMs();
+        await this.enqueueAndFlush([
+            buildSetMutationFromSchema({
+                schema: WA_APPSTATE_SCHEMAS.BusinessBroadcastList,
+                indexArgs: { id: input.id },
+                value,
+                timestamp
+            })
+        ]);
+    }
+    /** Deletes the broadcast list identified by `id`. */
+    async removeBroadcastList(id) {
+        const timestamp = this.serverClock.nowMs();
+        await this.enqueueAndFlush([
+            buildRemoveMutationFromSchema({
+                schema: WA_APPSTATE_SCHEMAS.BusinessBroadcastList,
+                indexArgs: { id },
+                timestamp
+            })
+        ]);
+    }
+    /**
+     * Applies a `set` mutation against any registered app-state schema. This
+     * is the way to reach schemas that don't have a typed helper on this
+     * coordinator (Contact, LabelEdit, LabelJid, QuickReply, AiThreadPin,
+     * Favorites, Nux, ...). For the common chat actions there's a dedicated
+     * method ({@link setChatMute}, {@link setChatRead}, {@link setMessageStar},
+     * {@link setChatPin}, {@link setChatArchive}, etc.) – use those instead.
+     *
+     * `input` is flat – pick a `schema` name from {@link WA_APPSTATE_SCHEMAS},
+     * fill the index fields (`id`, `chatJid`, `labelId`, ...) and the value
+     * fields side-by-side, and the coordinator routes them to the right
+     * SyncActionValue subfield.
+     *
+     * @example
+     * ```ts
+     * // Add a contact to the address book
+     * await client.chat.set({
+     *     schema: 'Contact',
+     *     id: '5511999999999@s.whatsapp.net',
+     *     contactAction: { fullName: 'Maria Silva', firstName: 'Maria' }
+     * })
+     *
+     * // Create a chat label (color is a server-side palette index)
+     * await client.chat.set({
+     *     schema: 'LabelEdit',
+     *     id: 'label-1',
+     *     labelEditAction: { name: 'Pendente', color: 0, isActive: true }
+     * })
+     *
+     * // Apply that label to a chat
+     * await client.chat.set({
+     *     schema: 'LabelJid',
+     *     labelId: 'label-1',
+     *     chatJid: '5511999999999@s.whatsapp.net',
+     *     labelAssociationAction: { labeled: true }
+     * })
+     *
+     * // Save a business quick reply
+     * await client.chat.set({
+     *     schema: 'QuickReply',
+     *     id: 'qr-greeting',
+     *     quickReplyAction: { shortcut: '/oi', message: 'Olá! Tudo bem?' }
+     * })
+     * ```
+     */
+    async set(input) {
+        const resolved = WA_APPSTATE_SCHEMAS[input.schema];
+        const { indexArgs, data } = splitFlatInput(resolved, input);
+        const value = wrapData(resolved, data);
+        const timestamp = this.serverClock.nowMs();
+        const mutation = buildSetMutationFromSchema({
+            schema: resolved,
+            indexArgs: indexArgs,
+            value,
+            timestamp
+        });
+        await this.enqueueAndFlush([mutation]);
+    }
+    /**
+     * Applies a `remove` mutation against any registered app-state schema  -
+     * same shape as {@link set} but without the value fields (only the schema
+     * name + index args). Use this for schemas without a typed helper.
+     *
+     * @example
+     * ```ts
+     * // Drop a contact from the address book
+     * await client.chat.remove({
+     *     schema: 'Contact',
+     *     id: '5511999999999@s.whatsapp.net'
+     * })
+     *
+     * // Remove a label from a chat (the label itself stays – use LabelEdit
+     * // with `deleted: true` to delete the label definition entirely)
+     * await client.chat.remove({
+     *     schema: 'LabelJid',
+     *     labelId: 'label-1',
+     *     chatJid: '5511999999999@s.whatsapp.net'
+     * })
+     *
+     * // Delete a quick reply
+     * await client.chat.remove({
+     *     schema: 'QuickReply',
+     *     id: 'qr-greeting'
+     * })
+     * ```
+     */
+    async remove(input) {
+        const resolved = WA_APPSTATE_SCHEMAS[input.schema];
+        const { indexArgs } = splitFlatInput(resolved, input);
+        const timestamp = this.serverClock.nowMs();
+        const mutation = buildRemoveMutationFromSchema({
+            schema: resolved,
+            indexArgs: indexArgs,
+            timestamp
+        });
+        await this.enqueueAndFlush([mutation]);
     }
     async createArchiveMutation(chatIndexJid, archived, timestamp) {
         const messageRange = await this.buildChatMessageRange(chatIndexJid);
-        return this.createSetMutation({
-            spec: WA_APP_STATE_CHAT_MUTATION_SPECS.ARCHIVE,
-            chatIndexJid,
-            value: {
-                archiveChatAction: {
-                    archived,
-                    messageRange
-                }
-            },
+        return buildSetMutationFromSchema({
+            schema: WA_APPSTATE_SCHEMAS.Archive,
+            indexArgs: { chatJid: chatIndexJid },
+            value: { archiveChatAction: { archived, messageRange } },
             timestamp
         });
     }
@@ -428,8 +949,10 @@ export class WaAppStateMutationCoordinator {
         const fromMe = message.fromMe === true;
         const participant = this.resolveMessageMutationParticipant(chatIndexJid, fromMe, message.participantJid);
         return {
-            chatIndexJid,
-            indexPartsTail: [messageId, fromMe ? '1' : '0', participant]
+            remote: chatIndexJid,
+            id: messageId,
+            fromMe,
+            participant
         };
     }
     resolveMessageMutationParticipant(chatIndexJid, fromMe, participantJid) {
@@ -445,9 +968,6 @@ export class WaAppStateMutationCoordinator {
         }
         return normalizeDeviceJid(normalized);
     }
-    buildMutationIndex(action, chatIndexJid, indexPartsTail) {
-        return JSON.stringify([action, chatIndexJid, ...indexPartsTail]);
-    }
     describeMutationActions(mutations) {
         return mutations
             .map((mutation) => {