zapo-js 0.2.0 → 1.0.0

package/dist/esm/appstate/{WaAppStateSyncClient.js → sync/WaAppStateSyncClient.js}

@@ -1,14 +1,14 @@
-import { APP_STATE_DEFAULT_COLLECTIONS, APP_STATE_DEFAULT_COLLECTION_VERSION, APP_STATE_EMPTY_LT_HASH } from './constants.js';
-import { WaAppStateCrypto } from './WaAppStateCrypto.js';
-import { parseSyncResponse } from './WaAppStateSyncResponseParser.js';
-import { proto } from '../proto.js';
-import { WA_APP_STATE_COLLECTION_STATES, WA_DEFAULTS, WA_IQ_TYPES, WA_NODE_TAGS, WA_XMLNS } from '../protocol/constants.js';
-import { parseSignalAddressFromJid } from '../protocol/jid.js';
-import { assertIqResult } from '../transport/node/query.js';
-import { decodeProtoBytes } from '../util/bytes.js';
-import { bytesToHex, uint8Equal } from '../util/bytes.js';
-import { longToNumber } from '../util/primitives.js';
-export class WaAppStateMissingKeyError extends Error {
+import { APP_STATE_DEFAULT_COLLECTION_VERSION, APP_STATE_DEFAULT_COLLECTIONS, APP_STATE_EMPTY_LT_HASH } from '../constants.js';
+import { WaAppStateCrypto } from '../crypto/WaAppStateCrypto.js';
+import { parseSyncResponse } from '../parsers/response-parser.js';
+import { randomBytesAsync, randomIntAsync } from '../../crypto/index.js';
+import { proto } from '../../proto.js';
+import { WA_APP_STATE_COLLECTION_STATES, WA_DEFAULTS, WA_IQ_TYPES, WA_NODE_TAGS, WA_XMLNS } from '../../protocol/constants.js';
+import { applyDeviceToJid, normalizeDeviceJid, parseSignalAddressFromJid } from '../../protocol/jid.js';
+import { assertIqResult } from '../../transport/node/query.js';
+import { bytesToHex, decodeProtoBytes, uint8TimingSafeEqual } from '../../util/bytes.js';
+import { longToNumber, toError } from '../../util/primitives.js';
+class WaAppStateMissingKeyError extends Error {
     constructor(message, keyId, collection) {
         super(message);
         this.keyId = keyId;
@@ -16,23 +16,56 @@ export class WaAppStateMissingKeyError extends Error {
         this.name = 'WaAppStateMissingKeyError';
     }
 }
+/**
+ * App-state synchronization client. Owns the sync key inventory, processes
+ * snapshots/patches, encrypts pending mutations, and persists the resulting
+ * collection state in the {@link WaAppStateStore}.
+ */
 export class WaAppStateSyncClient {
     constructor(options) {
         this.logger = options.logger;
         this.query = options.query;
         this.store = options.store;
+        this.serverClock = options.serverClock;
         this.getCurrentMeJid = options.getCurrentMeJid;
         this.hostDomain = options.hostDomain ?? WA_DEFAULTS.HOST_DOMAIN;
         this.defaultTimeoutMs = options.defaultTimeoutMs ?? WA_DEFAULTS.APP_STATE_SYNC_TIMEOUT_MS;
         this.onMissingKeys = options.onMissingKeys;
-        this.crypto = new WaAppStateCrypto();
+        this.isOwnAccountDevice = options.isOwnAccountDevice;
+        this.sendKeyShare = options.sendKeyShare;
+        this.triggerSync = options.triggerSync;
+        this.crypto = new WaAppStateCrypto(undefined, options.skipMacVerification === true);
+        this.mobilePrimary = options.mobilePrimary ?? false;
         this.syncContext = null;
         this.syncPromise = null;
     }
-    async exportState() {
-        this.logger.trace('app-state export requested');
-        return this.store.exportData();
+    /**
+     * Returns the active app-state sync key, generating and persisting a new
+     * one when the store is empty (used during initial setup).
+     */
+    async ensureInitialSyncKey() {
+        const existing = await this.store.getActiveSyncKey();
+        if (existing) {
+            return existing;
+        }
+        const keyIdBytes = await randomBytesAsync(2);
+        const keyData = await randomBytesAsync(32);
+        const rawId = await randomIntAsync(0, 4294967295);
+        const key = {
+            keyId: keyIdBytes,
+            keyData,
+            timestamp: this.serverClock.nowMs(),
+            fingerprint: { rawId, currentIndex: 0, deviceIndexes: [0] }
+        };
+        await this.store.upsertSyncKeys([key]);
+        this.crypto.clearCache();
+        this.logger.info('app-state initial sync key generated (mobile primary)', {
+            keyId: bytesToHex(keyIdBytes),
+            rawId
+        });
+        return key;
     }
+    /** Imports peer-shared sync keys into the store; returns the count actually added. */
     async importSyncKeys(keys) {
         this.logger.debug('app-state importing sync keys', { count: keys.length });
         const inserted = await this.store.upsertSyncKeys(keys);
@@ -42,6 +75,119 @@ export class WaAppStateSyncClient {
         }
         return inserted;
     }
+    /** Handler for `AppStateSyncKeyShare` protocol messages – stores received keys and triggers a sync. */
+    async handleIncomingKeyShare(context, protocolMessage) {
+        const log = this.logger.child({ id: context.id, from: context.remoteJid });
+        const share = protocolMessage.appStateSyncKeyShare;
+        if (!share) {
+            log.warn('incoming app-state key share protocol message without payload');
+            return;
+        }
+        try {
+            const imported = await this.importSyncKeyShare(share);
+            log.info('imported app-state sync key share from protocol message', { imported });
+            if (imported > 0 && this.triggerSync) {
+                void this.triggerSync().catch((error) => {
+                    log.warn('failed to sync app-state after key share import', {
+                        message: toError(error).message
+                    });
+                });
+            }
+        }
+        catch (error) {
+            log.warn('failed to import app-state sync key share from protocol message', {
+                message: toError(error).message
+            });
+        }
+    }
+    /** Handler for `AppStateSyncKeyRequest` protocol messages – replies with the requested keys via `sendKeyShare`. */
+    async handleIncomingKeyRequest(context, protocolMessage) {
+        const log = this.logger.child({ id: context.id, from: context.remoteJid });
+        const request = protocolMessage.appStateSyncKeyRequest;
+        if (!request) {
+            log.warn('incoming app-state key request protocol message without payload');
+            return;
+        }
+        const senderJid = context.participant ?? context.remoteJid;
+        if (!senderJid) {
+            log.warn('incoming app-state key request missing sender jid');
+            return;
+        }
+        let requesterDeviceJid;
+        try {
+            const requesterRaw = applyDeviceToJid(senderJid, context.senderDevice);
+            requesterDeviceJid = normalizeDeviceJid(requesterRaw);
+        }
+        catch (error) {
+            log.warn('incoming app-state key request has malformed sender jid', {
+                senderJid,
+                message: toError(error).message
+            });
+            return;
+        }
+        const deviceLog = log.child({ to: requesterDeviceJid });
+        if (this.isOwnAccountDevice && !this.isOwnAccountDevice(requesterDeviceJid)) {
+            deviceLog.warn('incoming app-state key request ignored: sender is not own account');
+            return;
+        }
+        const requestedKeyIds = this.extractKeyRequestIds(request);
+        if (requestedKeyIds.length === 0) {
+            deviceLog.warn('incoming app-state key request has no valid key ids');
+            return;
+        }
+        if (!this.sendKeyShare) {
+            deviceLog.warn('incoming app-state key request received but no sendKeyShare wired');
+            return;
+        }
+        const requestedKeys = await this.store.getSyncKeysBatch(requestedKeyIds);
+        const availableKeys = [];
+        const missingKeyIds = [];
+        for (let i = 0; i < requestedKeys.length; i += 1) {
+            const key = requestedKeys[i];
+            if (key !== null) {
+                availableKeys.push(key);
+            }
+            else {
+                missingKeyIds.push(requestedKeyIds[i]);
+            }
+        }
+        try {
+            await this.sendKeyShare(requesterDeviceJid, availableKeys, missingKeyIds);
+            deviceLog.info('responded to app-state key request', {
+                requested: requestedKeyIds.length,
+                shared: availableKeys.length,
+                missing: missingKeyIds.length
+            });
+        }
+        catch (error) {
+            deviceLog.warn('failed to respond to app-state key request', {
+                requested: requestedKeyIds.length,
+                shared: availableKeys.length,
+                missing: missingKeyIds.length,
+                message: toError(error).message
+            });
+        }
+    }
+    extractKeyRequestIds(request) {
+        const deduped = new Map();
+        for (const key of request.keyIds ?? []) {
+            try {
+                const keyId = decodeProtoBytes(key.keyId, 'appStateSyncKeyRequest.keyIds[].keyId');
+                const keyHex = bytesToHex(keyId);
+                if (deduped.has(keyHex)) {
+                    continue;
+                }
+                deduped.set(keyHex, keyId);
+            }
+            catch (error) {
+                this.logger.trace('ignoring malformed app-state key id request entry', {
+                    message: toError(error).message
+                });
+            }
+        }
+        return [...deduped.values()];
+    }
+    /** Imports the keys from a decoded `AppStateSyncKeyShare` proto message. */
     async importSyncKeyShare(share) {
         const keys = [];
         for (const item of share.keys ?? []) {
@@ -57,13 +203,19 @@ export class WaAppStateSyncClient {
                 keyId,
                 keyData,
                 timestamp: item.keyData?.timestamp === null || item.keyData?.timestamp === undefined
-                    ? Date.now()
+                    ? this.serverClock.nowMs()
                     : this.normalizeProtoLong(item.keyData?.timestamp, 'appStateSyncKeyShare.keys[].keyData.timestamp'),
                 fingerprint: item.keyData?.fingerprint ?? undefined
             });
         }
         return this.importSyncKeys(keys);
     }
+    /**
+     * Runs one app-state sync round across the requested collections,
+     * applying any `pendingMutations` and downloading external snapshots
+     * via `options.downloadExternalBlob` when present. Concurrent calls
+     * share the in-flight promise.
+     */
     async sync(options = {}) {
         if (this.syncPromise) {
             this.logger.debug('app-state sync already in flight, joining existing run');
@@ -95,7 +247,7 @@ export class WaAppStateSyncClient {
             for (let index = 0; index < collections.length; index += 1) {
                 context.collections.set(collections[index], initialCollectionStates[index]);
             }
-            this.logger.info('app-state sync start', {
+            this.logger.debug('app-state sync start', {
                 collections: collections.length,
                 pendingMutations: options.pendingMutations?.length ?? 0
             });
@@ -145,13 +297,13 @@ export class WaAppStateSyncClient {
             }
             if (stateChanged && context.dirtyCollections.size > 0) {
                 await this.persistCollectionUpdates();
-                this.logger.info('app-state sync persisted updated state');
+                this.logger.debug('app-state sync persisted updated state');
             }
             const orderedResults = collections.map((collection) => resultMap.get(collection) ?? {
                 collection,
                 state: WA_APP_STATE_COLLECTION_STATES.ERROR_RETRY
             });
-            this.logger.info('app-state sync finished', {
+            this.logger.debug('app-state sync finished', {
                 collections: orderedResults.length,
                 stateChanged
             });
@@ -283,7 +435,7 @@ export class WaAppStateSyncClient {
             content: [
                 {
                     tag: WA_NODE_TAGS.SYNC,
-                    attrs: {},
+                    attrs: this.mobilePrimary ? { data_namespace: '3' } : {},
                     content: collectionNodes
                 }
             ]
@@ -305,11 +457,12 @@ export class WaAppStateSyncClient {
         return payloadByCollection;
     }
     async processCollectionRound({ collection, payloadByCollection, pendingByCollection, options, outgoingContexts, skippedUploadCollections }) {
+        const collectionLogger = this.logger.child({ collection });
         const payload = payloadByCollection.get(collection);
         let shouldRefetch = false;
         let collectionStateChanged = false;
         if (!payload) {
-            this.logger.warn('app-state sync response missing collection payload', { collection });
+            collectionLogger.warn('app-state sync response missing collection payload');
             return this.createCollectionOutcome(collection, WA_APP_STATE_COLLECTION_STATES.ERROR_RETRY);
         }
         if (payload.state === WA_APP_STATE_COLLECTION_STATES.ERROR_FATAL ||
@@ -369,8 +522,7 @@ export class WaAppStateSyncClient {
                     payload.state === WA_APP_STATE_COLLECTION_STATES.SUCCESS_HAS_MORE ||
                     (payload.state === WA_APP_STATE_COLLECTION_STATES.SUCCESS &&
                         skippedUploadCollections.has(collection));
-            this.logger.debug('app-state collection processed', {
-                collection: payload.collection,
+            collectionLogger.debug('app-state collection processed', {
                 state: payload.state,
                 version: payload.version,
                 appliedMutations: appliedMutations.length
@@ -379,16 +531,13 @@ export class WaAppStateSyncClient {
         }
         catch (error) {
             if (error instanceof WaAppStateMissingKeyError) {
-                this.logger.warn('app-state blocked by missing key', {
-                    collection: payload.collection,
+                collectionLogger.debug('app-state blocked by missing key', {
                     message: error.message
                 });
                 return this.createCollectionOutcome(collection, WA_APP_STATE_COLLECTION_STATES.BLOCKED, payload.version, shouldRefetch, collectionStateChanged, undefined, error.keyId);
             }
-            const message = error instanceof Error ? error.message : String(error);
-            this.logger.warn('app-state collection processing failed', {
-                collection: payload.collection,
-                message
+            collectionLogger.debug('app-state collection processing failed', {
+                message: toError(error).message
             });
             return this.createCollectionOutcome(collection, WA_APP_STATE_COLLECTION_STATES.ERROR_RETRY, payload.version, true, collectionStateChanged);
         }
@@ -414,11 +563,13 @@ export class WaAppStateSyncClient {
             return;
         }
         const keyIdsHex = keyIds.map((keyId) => bytesToHex(keyId));
-        this.logger.info('app-state requesting missing sync keys', {
+        const requestLogger = this.logger.child({
             keys: keyIdsHex.length,
-            keyIds: keyIdsHex.join(','),
             collections: collections.join(',')
         });
+        requestLogger.debug('app-state requesting missing sync keys', {
+            keyIds: keyIdsHex.join(',')
+        });
         try {
             await input.onMissingKeys({
                 keyIds,
@@ -426,10 +577,8 @@ export class WaAppStateSyncClient {
             });
         }
         catch (error) {
-            this.logger.warn('app-state missing key callback failed', {
-                keys: keyIdsHex.length,
-                collections: collections.join(','),
-                message: error instanceof Error ? error.message : String(error)
+            requestLogger.warn('app-state missing key callback failed', {
+                message: toError(error).message
             });
         }
     }
@@ -452,7 +601,8 @@ export class WaAppStateSyncClient {
                 const decodedMutations = proto.SyncdMutations.decode(patchBytes);
                 readyPatch = {
                     ...readyPatch,
-                    mutations: decodedMutations.mutations ?? []
+                    mutations: decodedMutations.mutations ?? [],
+                    externalMutations: undefined
                 };
             }
             return this.validatePatch(payload.collection, readyPatch);
@@ -462,11 +612,13 @@ export class WaAppStateSyncClient {
         if (!snapshot.version?.version) {
             throw new Error(`snapshot for ${collection} is missing version`);
         }
-        if (!snapshot.mac) {
-            throw new Error(`snapshot for ${collection} is missing mac`);
-        }
-        if (!snapshot.keyId?.id) {
-            throw new Error(`snapshot for ${collection} is missing keyId`);
+        if (!this.crypto.isMacVerificationSkipped) {
+            if (!snapshot.mac) {
+                throw new Error(`snapshot for ${collection} is missing mac`);
+            }
+            if (!snapshot.keyId?.id) {
+                throw new Error(`snapshot for ${collection} is missing keyId`);
+            }
         }
         return snapshot;
     }
@@ -481,14 +633,16 @@ export class WaAppStateSyncClient {
         if (!patch.version?.version) {
             throw new Error(`patch for ${collection} is missing version`);
         }
-        if (!patch.snapshotMac) {
-            throw new Error(`patch for ${collection} is missing snapshotMac`);
-        }
-        if (!patch.patchMac) {
-            throw new Error(`patch for ${collection} is missing patchMac`);
-        }
-        if (!patch.keyId?.id) {
-            throw new Error(`patch for ${collection} is missing keyId`);
+        if (!this.crypto.isMacVerificationSkipped) {
+            if (!patch.snapshotMac) {
+                throw new Error(`patch for ${collection} is missing snapshotMac`);
+            }
+            if (!patch.patchMac) {
+                throw new Error(`patch for ${collection} is missing patchMac`);
+            }
+            if (!patch.keyId?.id) {
+                throw new Error(`patch for ${collection} is missing keyId`);
+            }
         }
         if (patch.mutations && patch.mutations.length > 0 && patch.externalMutations) {
             throw new Error(`patch for ${collection} has inline and external mutations together`);
@@ -502,10 +656,13 @@ export class WaAppStateSyncClient {
     }
     async applySnapshot(collection, snapshot) {
         const version = this.normalizeProtoLong(snapshot.version?.version, `snapshot.version.version (${collection})`);
-        const keyId = decodeProtoBytes(snapshot.keyId?.id, `snapshot.keyId.id (${collection})`);
-        const keyData = await this.getKeyData(keyId);
-        if (!keyData) {
-            throw new WaAppStateMissingKeyError(`missing snapshot key ${bytesToHex(keyId)} for ${collection}`, keyId, collection);
+        let keyData = null;
+        if (!this.crypto.isMacVerificationSkipped) {
+            const keyId = decodeProtoBytes(snapshot.keyId?.id, `snapshot.keyId.id (${collection})`);
+            keyData = await this.getKeyData(keyId);
+            if (!keyData) {
+                throw new WaAppStateMissingKeyError(`missing snapshot key ${bytesToHex(keyId)} for ${collection}`, keyId, collection);
+            }
         }
         const indexValueMap = new Map();
         const mutations = [];
@@ -533,9 +690,11 @@ export class WaAppStateSyncClient {
             ltHashInputIndex += 1;
         }
         const ltHash = await this.crypto.ltHashAdd(APP_STATE_EMPTY_LT_HASH, ltHashInput);
-        const expectedSnapshotMac = await this.crypto.generateSnapshotMac(keyData, ltHash, version, collection);
-        if (!uint8Equal(expectedSnapshotMac, snapshot.mac)) {
-            throw new Error(`snapshot MAC mismatch for ${collection}`);
+        if (keyData !== null) {
+            const expectedSnapshotMac = await this.crypto.generateSnapshotMac(keyData, ltHash, version, collection);
+            if (!uint8TimingSafeEqual(expectedSnapshotMac, snapshot.mac)) {
+                throw new Error(`snapshot MAC mismatch for ${collection}`);
+            }
         }
         this.setCollectionState(collection, version, ltHash, indexValueMap);
         return mutations;
@@ -546,10 +705,13 @@ export class WaAppStateSyncClient {
         if (current.version !== patchVersion - 1) {
             throw new Error(`patch version mismatch for ${collection}: local=${current.version}, incoming=${patchVersion}`);
         }
-        const patchKeyId = decodeProtoBytes(patch.keyId?.id, `patch.keyId.id (${collection})`);
-        const patchKeyData = await this.getKeyData(patchKeyId);
-        if (!patchKeyData) {
-            throw new WaAppStateMissingKeyError(`missing patch key ${bytesToHex(patchKeyId)} for ${collection}`, patchKeyId, collection);
+        let patchKeyData = null;
+        if (!this.crypto.isMacVerificationSkipped) {
+            const patchKeyId = decodeProtoBytes(patch.keyId?.id, `patch.keyId.id (${collection})`);
+            patchKeyData = await this.getKeyData(patchKeyId);
+            if (!patchKeyData) {
+                throw new WaAppStateMissingKeyError(`missing patch key ${bytesToHex(patchKeyId)} for ${collection}`, patchKeyId, collection);
+            }
         }
         const decryptedMutations = await this.decryptPatchMutations(collection, patch);
         const macMutations = new Array(decryptedMutations.length);
@@ -564,7 +726,9 @@ export class WaAppStateSyncClient {
             };
         }
         const nextState = await this.computeNextCollectionState(current.hash, current.indexValueMap, macMutations, collection);
-        await this.assertPatchMacsMatch(patch, collection, patchKeyData, patchVersion, nextState.hash, valueMacs);
+        if (patchKeyData !== null) {
+            await this.assertPatchMacsMatch(patch, collection, patchKeyData, patchVersion, nextState.hash, valueMacs);
+        }
         this.setCollectionState(collection, patchVersion, nextState.hash, nextState.indexValueMap);
         return decryptedMutations;
     }
@@ -667,12 +831,16 @@ export class WaAppStateSyncClient {
     async assertPatchMacsMatch(patch, collection, patchKeyData, patchVersion, nextHash, valueMacs) {
         const snapshotMac = decodeProtoBytes(patch.snapshotMac, `patch.snapshotMac (${collection})`);
         const expectedSnapshotMac = await this.crypto.generateSnapshotMac(patchKeyData, nextHash, patchVersion, collection);
-        if (!uint8Equal(expectedSnapshotMac, snapshotMac)) {
-            throw new Error(`patch snapshot MAC mismatch for ${collection}`);
+        // non-fatal: wa-mob/wa-web tolerate this – patchMac below covers payload integrity.
+        if (!uint8TimingSafeEqual(expectedSnapshotMac, snapshotMac)) {
+            this.logger.debug('patch snapshot MAC mismatch (tolerated)', {
+                collection,
+                patchVersion
+            });
         }
         const patchMac = decodeProtoBytes(patch.patchMac, `patch.patchMac (${collection})`);
         const expectedPatchMac = await this.crypto.generatePatchMac(patchKeyData, snapshotMac, valueMacs, patchVersion, collection);
-        if (!uint8Equal(expectedPatchMac, patchMac)) {
+        if (!uint8TimingSafeEqual(expectedPatchMac, patchMac)) {
             throw new Error(`patch MAC mismatch for ${collection}`);
         }
     }
@@ -681,7 +849,7 @@ export class WaAppStateSyncClient {
             throw new WaAppStateMissingKeyError(`no sync key available to upload ${collection}`, null, collection);
         }
         const encryptedResults = await Promise.all(pendingMutations.map(async (mutation) => {
-            const value = mutation.operation === 'set' ? mutation.value : mutation.previousValue;
+            const value = mutation.operation === 'set' ? mutation.value : null;
             const operationCode = mutation.operation === 'remove'
                 ? proto.SyncdMutation.SyncdOperation.REMOVE
                 : proto.SyncdMutation.SyncdOperation.SET;
@@ -720,14 +888,12 @@ export class WaAppStateSyncClient {
         const snapshotMac = await this.crypto.generateSnapshotMac(activeKey.keyData, nextState.hash, patchVersion, collection);
         const patchMac = await this.crypto.generatePatchMac(activeKey.keyData, snapshotMac, valueMacs, patchVersion, collection);
         const deviceIndex = this.resolveDeviceIndex();
-        const clientDebugData = this.buildPatchClientDebugData();
         const encodedPatch = proto.SyncdPatch.encode({
             mutations: encryptedMutations,
             snapshotMac,
             patchMac,
             keyId: { id: activeKey.keyId },
-            ...(deviceIndex === undefined ? {} : { deviceIndex }),
-            clientDebugData
+            ...(deviceIndex === undefined ? {} : { deviceIndex })
         }).finish();
         return {
             encodedPatch,
@@ -755,12 +921,6 @@ export class WaAppStateSyncClient {
             return undefined;
         }
     }
-    buildPatchClientDebugData() {
-        return proto.PatchDebugData.encode({
-            isSenderPrimary: false,
-            senderPlatform: proto.PatchDebugData.Platform.WEB
-        }).finish();
-    }
     async computeNextCollectionState(baseHash, baseMap, mutations, collection) {
         const indexValueMap = new Map(baseMap);
         const addValues = [];
@@ -801,8 +961,7 @@ export class WaAppStateSyncClient {
             return longToNumber(value);
         }
         catch (error) {
-            const reason = error instanceof Error ? error.message : String(error);
-            throw new Error(`invalid ${field}: ${reason}`);
+            throw new Error(`invalid ${field}: ${toError(error).message}`);
         }
     }
     groupPendingMutations(pendingMutations) {

package/dist/esm/appstate/utils.js

@@ -1,17 +1,29 @@
 import { WA_APP_STATE_COLLECTIONS, WA_APP_STATE_KEY_TYPES } from '../protocol/constants.js';
 import { decodeProtoBytes } from '../util/bytes.js';
 const APP_STATE_COLLECTION_NAMES = new Set(Object.values(WA_APP_STATE_COLLECTIONS));
+/**
+ * Returns `value` typed as a known {@link AppStateCollectionName}, or `null`
+ * when the string is unrecognized.
+ */
 export function parseCollectionName(value) {
     return value && APP_STATE_COLLECTION_NAMES.has(value) ? value : null;
 }
 function keyDeviceId(keyId) {
     return keyId.byteLength < 6 ? null : (keyId[0] << 8) | keyId[1];
 }
+/**
+ * Reads the 32-bit big-endian epoch encoded in bytes 2..5 of an app-state key id.
+ * Returns `-1` when the key id is too short.
+ */
 export function keyEpoch(keyId) {
     return keyId.byteLength < 6
         ? -1
         : keyId[2] * 16777216 + keyId[3] * 65536 + keyId[4] * 256 + keyId[5];
 }
+/**
+ * Picks the highest-epoch app-state sync key from `keys`. Ties are broken by
+ * the lower device id. Returns `null` when the iterable is empty.
+ */
 export function pickActiveSyncKey(keys) {
     let active = null;
     for (const key of keys) {
@@ -36,6 +48,10 @@ export function pickActiveSyncKey(keys) {
     }
     return active;
 }
+/**
+ * Downloads and decrypts an external app-state blob via the media transfer
+ * client. Throws when the reference is missing required fields.
+ */
 export async function downloadExternalBlobReference(mediaTransfer, reference) {
     if (!reference.directPath) {
         throw new Error('external blob reference is missing directPath');

package/dist/esm/appstate-spec.js

@@ -0,0 +1,79 @@
+import { proto } from './proto.js';
+import { WA_APPSTATE_SCHEMAS as RAW_WA_APPSTATE_SCHEMAS } from '../spec/appstate';
+export { WA_APPSTATE_COLLECTIONS, WA_APPSTATE_SCHEMAS } from '../spec/appstate';
+const SCHEMA_BY_ACTION_NAME_BUILDER = {};
+for (const key of Object.keys(RAW_WA_APPSTATE_SCHEMAS)) {
+    SCHEMA_BY_ACTION_NAME_BUILDER[RAW_WA_APPSTATE_SCHEMAS[key].name] = key;
+}
+export const WA_APPSTATE_SCHEMA_BY_ACTION_NAME = Object.freeze(SCHEMA_BY_ACTION_NAME_BUILDER);
+export function getAppstateSchemaByActionName(actionName) {
+    const key = WA_APPSTATE_SCHEMA_BY_ACTION_NAME[actionName];
+    if (!key) {
+        return null;
+    }
+    return { key, schema: RAW_WA_APPSTATE_SCHEMAS[key] };
+}
+export function resolveEnumObject(protoEnumPath) {
+    const segments = protoEnumPath.split('.');
+    let cursor = proto.SyncActionValue;
+    for (const seg of segments) {
+        if (cursor === null || cursor === undefined)
+            return null;
+        if (typeof cursor !== 'object' && typeof cursor !== 'function')
+            return null;
+        cursor = cursor[seg];
+    }
+    if (cursor === null || cursor === undefined)
+        return null;
+    if (typeof cursor !== 'object' && typeof cursor !== 'function')
+        return null;
+    return cursor;
+}
+export function encodeEnumValue(protoEnumPath, name) {
+    const enumObj = resolveEnumObject(protoEnumPath);
+    if (!enumObj)
+        return null;
+    const value = enumObj[name];
+    return typeof value === 'number' ? value : null;
+}
+export function decodeEnumValue(protoEnumPath, value) {
+    const enumObj = resolveEnumObject(protoEnumPath);
+    if (!enumObj)
+        return null;
+    for (const key of Object.keys(enumObj)) {
+        if (enumObj[key] === value)
+            return key;
+    }
+    return null;
+}
+export function decodeIndexArgsFromSchema(schema, parts) {
+    if (parts.length !== schema.indexParts.length) {
+        return null;
+    }
+    const args = {};
+    for (let i = 0; i < schema.indexParts.length; i += 1) {
+        const part = schema.indexParts[i];
+        const raw = parts[i];
+        if (part.type === 'literal') {
+            continue;
+        }
+        if (part.type === 'boolString') {
+            if (raw !== '0' && raw !== '1')
+                return null;
+            args[part.name] = raw === '1';
+            continue;
+        }
+        if (part.type === 'jidOrZero') {
+            args[part.name] = raw === '0' ? null : raw;
+            continue;
+        }
+        if (part.type === 'enum') {
+            const numeric = Number(raw);
+            const name = Number.isFinite(numeric) ? decodeEnumValue(part.protoEnum, numeric) : null;
+            args[part.name] = name ?? raw;
+            continue;
+        }
+        args[part.name] = raw;
+    }
+    return args;
+}