zapo-js 0.3.0 → 1.0.1

package/dist/esm/client/events/presence.js

@@ -0,0 +1,41 @@
+import { isGroupJid } from '../../protocol/jid.js';
+import { WA_PRESENCE_LAST_SENTINELS, WA_PRESENCE_TYPES } from '../../protocol/presence.js';
+import { parseOptionalInt } from '../../util/primitives.js';
+function parseLastSeen(value) {
+    if (value === WA_PRESENCE_LAST_SENTINELS.DENY) {
+        return { kind: 'privacy_denied' };
+    }
+    if (value === WA_PRESENCE_LAST_SENTINELS.NONE) {
+        return { kind: 'never_online' };
+    }
+    if (value === WA_PRESENCE_LAST_SENTINELS.ERROR) {
+        return { kind: 'unknown' };
+    }
+    const unixSeconds = parseOptionalInt(value);
+    if (unixSeconds === undefined) {
+        return { kind: 'unknown' };
+    }
+    return { kind: 'timestamp', unixSeconds };
+}
+export function parsePresenceNode(node) {
+    const from = node.attrs.from;
+    const isGroup = from !== undefined && isGroupJid(from);
+    const type = node.attrs.type === WA_PRESENCE_TYPES.UNAVAILABLE
+        ? WA_PRESENCE_TYPES.UNAVAILABLE
+        : WA_PRESENCE_TYPES.AVAILABLE;
+    const result = { type };
+    if (isGroup) {
+        const count = parseOptionalInt(node.attrs.count);
+        if (count !== undefined) {
+            result.groupOnlineCount = count;
+        }
+        else if (type === WA_PRESENCE_TYPES.UNAVAILABLE) {
+            result.groupOnlineCount = 0;
+        }
+        return result;
+    }
+    if (type === WA_PRESENCE_TYPES.UNAVAILABLE && node.attrs.last !== undefined) {
+        result.lastSeen = parseLastSeen(node.attrs.last);
+    }
+    return result;
+}

package/dist/esm/client/events/receipt.js

@@ -0,0 +1,23 @@
+import { isGroupOrBroadcastJid } from '../../protocol/jid.js';
+function needsParticipant(target) {
+    if (target.isGroupChat !== undefined || target.isBroadcastChat !== undefined) {
+        return target.isGroupChat === true || target.isBroadcastChat === true;
+    }
+    return isGroupOrBroadcastJid(target.chatJid);
+}
+export function aggregateReceiptTargets(targets) {
+    const groups = new Map();
+    for (const target of targets) {
+        const participant = needsParticipant(target) && target.senderJid && target.senderJid !== target.chatJid
+            ? target.senderJid
+            : undefined;
+        const key = `${target.chatJid}|${participant ?? ''}`;
+        let group = groups.get(key);
+        if (!group) {
+            group = { jid: target.chatJid, participant, ids: [] };
+            groups.set(key, group);
+        }
+        group.ids.push(target.id);
+    }
+    return [...groups.values()];
+}

package/dist/esm/client/media.js

@@ -1,9 +1,12 @@
+import { createHash } from 'node:crypto';
 import { createReadStream, createWriteStream } from 'node:fs';
-import { open, unlink } from 'node:fs/promises';
+import { open, stat, unlink } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { Transform } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
-import { toBytesView } from '../util/bytes.js';
+import { randomIntAsync, sha256 } from '../crypto/core/index.js';
+import { bytesToBase64UrlSafe, TEXT_DECODER, toBytesView, toChunkBytes } from '../util/bytes.js';
 import { toError } from '../util/primitives.js';
 export async function readFileHead(filePath, bytes) {
     const fh = await open(filePath, 'r');
@@ -57,8 +60,8 @@ export function parseWebpAnimation(data) {
     }
     return null;
 }
-const IMAGE_THUMB_MAX_EDGE = 320;
-const VIDEO_THUMB_MAX_EDGE = 48;
+const IMAGE_THUMB_MAX_EDGE = 100;
+const VIDEO_THUMB_MAX_EDGE = 100;
 const STICKER_THUMB_MAX_EDGE = 100;
 const EMPTY_PROCESSED = {};
 export function isReadableStream(value) {
@@ -81,8 +84,135 @@ async function streamToTempFile(source) {
 export async function cleanupTempFile(filePath) {
     await unlink(filePath).catch(() => undefined);
 }
+function createSha256SizeMeter() {
+    const hash = createHash('sha256');
+    let byteLength = 0;
+    const transform = new Transform({
+        transform(chunk, _enc, cb) {
+            const bytes = chunk instanceof Uint8Array ? chunk : toChunkBytes(chunk);
+            hash.update(bytes);
+            byteLength += bytes.byteLength;
+            cb(null, bytes);
+        }
+    });
+    return {
+        transform,
+        finalize: () => ({ fileSha256: toBytesView(hash.digest()), byteLength })
+    };
+}
+async function streamToTempFileWithSha256(source) {
+    const filePath = join(tmpdir(), `zapo-media-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    const meter = createSha256SizeMeter();
+    try {
+        await pipeline(source, meter.transform, createWriteStream(filePath));
+    }
+    catch (error) {
+        await unlink(filePath).catch(() => undefined);
+        throw error;
+    }
+    return { filePath, ...meter.finalize() };
+}
+async function preparePlaintextUploadSource(media) {
+    if (media instanceof Uint8Array) {
+        return { fileSha256: sha256(media), byteLength: media.byteLength, body: media };
+    }
+    if (typeof media === 'string') {
+        await assertReadableFile(media);
+        const result = await streamToTempFileWithSha256(createReadStream(media));
+        return {
+            fileSha256: result.fileSha256,
+            byteLength: result.byteLength,
+            body: createReadStream(result.filePath),
+            cleanup: () => cleanupTempFile(result.filePath)
+        };
+    }
+    if (isReadableStream(media)) {
+        const result = await streamToTempFileWithSha256(media);
+        return {
+            fileSha256: result.fileSha256,
+            byteLength: result.byteLength,
+            body: createReadStream(result.filePath),
+            cleanup: () => cleanupTempFile(result.filePath)
+        };
+    }
+    throw new Error('media upload received unsupported source type');
+}
+// node:crypto randomInt caps max at 2**48 - 1; well within JS safe integer range.
+const MEDIA_UPLOAD_ID_MAX = 281474976710655;
+async function generateMediaUploadId() {
+    const value = await randomIntAsync(0, MEDIA_UPLOAD_ID_MAX);
+    return value.toString(10);
+}
+export function selectMediaUploadHost(mediaConn) {
+    return mediaConn.hosts.find((host) => !host.isFallback)?.hostname ?? mediaConn.hosts[0].hostname;
+}
+export function buildMediaUploadUrl(host, path, auth, fileSha256, mediaId) {
+    const hashToken = bytesToBase64UrlSafe(fileSha256);
+    const base = `https://${host}${path}/${hashToken}?auth=${encodeURIComponent(auth)}&token=${encodeURIComponent(hashToken)}`;
+    return mediaId !== undefined ? `${base}&media_id=${mediaId}` : base;
+}
+export function assertMediaUploadStatus(status, label) {
+    if (status < 200 || status >= 300) {
+        throw new Error(`${label} failed with status ${status}`);
+    }
+}
+export function parseMediaUploadJsonBody(body, label) {
+    try {
+        return JSON.parse(TEXT_DECODER.decode(body));
+    }
+    catch (error) {
+        throw new Error(`${label} returned invalid json: ${toError(error).message}`);
+    }
+}
+export async function performPlaintextMediaUpload(deps, input) {
+    const prepared = await preparePlaintextUploadSource(input.source);
+    try {
+        const host = selectMediaUploadHost(deps.mediaConn);
+        const mediaId = await generateMediaUploadId();
+        const url = buildMediaUploadUrl(host, input.path, deps.mediaConn.auth, prepared.fileSha256, mediaId);
+        deps.logger.debug(input.logLabel ?? 'sending media upload', {
+            host,
+            path: input.path,
+            size: prepared.byteLength
+        });
+        const response = await deps.mediaTransfer.uploadStream({
+            url,
+            method: 'POST',
+            body: prepared.body,
+            contentLength: prepared.byteLength,
+            contentType: input.mimetype
+        });
+        const responseBytes = await deps.mediaTransfer.readResponseBytes(response);
+        return {
+            responseBytes,
+            status: response.status,
+            fileSha256: prepared.fileSha256,
+            byteLength: prepared.byteLength,
+            mediaId
+        };
+    }
+    finally {
+        await prepared.cleanup?.();
+    }
+}
+async function assertReadableFile(filePath) {
+    try {
+        const stats = await stat(filePath);
+        if (!stats.isFile()) {
+            throw new Error(`media path is not a regular file: ${filePath}`);
+        }
+    }
+    catch (error) {
+        const err = toError(error);
+        if (err.code === 'ENOENT') {
+            throw new Error(`media file not found: ${filePath}`);
+        }
+        throw err;
+    }
+}
 export async function resolveMediaInputs(shouldProcess, raw) {
     if (typeof raw === 'string') {
+        await assertReadableFile(raw);
         return {
             processorInput: raw,
             uploadMedia: createReadStream(raw)
@@ -140,6 +270,12 @@ function shouldGenerateWaveform(media, content) {
         content.type === 'audio' &&
         content.waveform === undefined);
 }
+export function shouldNormalizeVoiceNote(media, content) {
+    return (!!media?.processor?.normalizeVoiceNote &&
+        media.normalizeVoiceNote === true &&
+        content.type === 'audio' &&
+        content.ptt === true);
+}
 function shouldGenerateStickerThumbnail(media, content) {
     return (!!media?.processor?.generateStickerThumbnail &&
         media.generateStickerThumbnail !== false &&
@@ -165,19 +301,33 @@ async function runProcessorStep(step, content, logger, fn) {
         return null;
     }
 }
+// Reuse one scoped child logger per parent. The processor is allowed to be
+// shared across WaClient sessions; without this cache, each call would mint
+// a fresh child logger and any package-side dedup keyed by Logger identity
+// (e.g. ffmpeg's missing-binary warn) would reset on every send.
+const SCOPED_MEDIA_LOGGER_CACHE = new WeakMap();
+export function getScopedMediaLogger(parent) {
+    let scoped = SCOPED_MEDIA_LOGGER_CACHE.get(parent);
+    if (!scoped) {
+        scoped = parent.child({ scope: 'media-utils' });
+        SCOPED_MEDIA_LOGGER_CACHE.set(parent, scoped);
+    }
+    return scoped;
+}
 export async function runMediaProcessor(media, input, content, logger) {
     const processor = media?.processor;
     if (!processor || !hasMediaProcessingTasks(media, content) || !input)
         return EMPTY_PROCESSED;
     const result = {};
+    const ctx = { logger: getScopedMediaLogger(logger) };
     const isVideo = content.type === 'video' || content.type === 'ptv';
     const thumbFn = isVideo ? processor.generateVideoThumbnail : processor.generateImageThumbnail;
     const thumbMaxEdge = isVideo ? VIDEO_THUMB_MAX_EDGE : IMAGE_THUMB_MAX_EDGE;
     const thumbTask = shouldGenerateThumbnail(media, content)
-        ? runProcessorStep('thumbnail', content, logger, () => thumbFn(input, thumbMaxEdge))
+        ? runProcessorStep('thumbnail', content, logger, () => thumbFn(input, thumbMaxEdge, ctx))
         : null;
     const probeTask = shouldProbeMedia(media, content)
-        ? runProcessorStep('probe', content, logger, () => processor.probeMedia(input))
+        ? runProcessorStep('probe', content, logger, () => processor.probeMedia(input, ctx))
         : null;
     const [thumb, probe] = await Promise.all([thumbTask, probeTask]);
     if (thumb) {
@@ -200,7 +350,7 @@ export async function runMediaProcessor(media, input, content, logger) {
         }
     }
     if (shouldGenerateWaveform(media, content)) {
-        const waveformResult = await runProcessorStep('waveform', content, logger, () => processor.computeWaveform(input));
+        const waveformResult = await runProcessorStep('waveform', content, logger, () => processor.computeWaveform(input, ctx));
         if (waveformResult) {
             result.waveform = waveformResult.waveform;
             if (result.seconds === undefined &&
@@ -211,7 +361,7 @@ export async function runMediaProcessor(media, input, content, logger) {
     }
     if (content.type === 'sticker') {
         if (shouldGenerateStickerThumbnail(media, content)) {
-            const stickerThumb = await runProcessorStep('stickerThumbnail', content, logger, () => processor.generateStickerThumbnail(input, STICKER_THUMB_MAX_EDGE));
+            const stickerThumb = await runProcessorStep('stickerThumbnail', content, logger, () => processor.generateStickerThumbnail(input, STICKER_THUMB_MAX_EDGE, ctx));
             if (stickerThumb) {
                 result.pngThumbnail = stickerThumb.pngThumbnail;
                 result.width = stickerThumb.width;

package/dist/esm/client/messaging/fanout.js

@@ -1,8 +1,8 @@
 import { PromiseDedup } from '../../infra/perf/PromiseDedup.js';
-import { isHostedDeviceJid, normalizeDeviceJid, splitJid, toUserJid } from '../../protocol/jid.js';
+import { normalizeDeviceJid, splitJid, toUserJid } from '../../protocol/jid.js';
 import { toError } from '../../util/primitives.js';
 export function createDeviceFanoutResolver(options) {
-    const { signalDeviceSync, getCurrentMeJid, getCurrentMeLid, logger } = options;
+    const { signalDeviceSync, getCurrentCredentials, logger } = options;
     const dedup = new PromiseDedup();
     const resolveDirectFanoutDeviceJids = async (recipientJid, selfDeviceJidForRecipient) => {
         const recipientUserJid = toUserJid(recipientJid);
@@ -37,7 +37,7 @@ export function createDeviceFanoutResolver(options) {
             return [...fanout];
         }
         catch (error) {
-            logger.warn('signal device fanout sync failed, falling back to direct recipient', {
+            logger.debug('signal device fanout sync failed, falling back to direct recipient', {
                 to: recipientJid,
                 message: toError(error).message
             });
@@ -46,7 +46,8 @@ export function createDeviceFanoutResolver(options) {
     };
     const resolveGroupParticipantDeviceJidsInternal = async (participantUserJids) => {
         const meDeviceJids = new Set();
-        const meJid = getCurrentMeJid();
+        const credentials = getCurrentCredentials();
+        const meJid = credentials?.meJid;
         if (meJid) {
             try {
                 meDeviceJids.add(normalizeDeviceJid(meJid));
@@ -58,7 +59,7 @@ export function createDeviceFanoutResolver(options) {
                 });
             }
         }
-        const meLid = getCurrentMeLid();
+        const meLid = credentials?.meLid;
         if (meLid && meLid.includes('@')) {
             try {
                 meDeviceJids.add(normalizeDeviceJid(meLid));
@@ -92,9 +93,6 @@ export function createDeviceFanoutResolver(options) {
                 }
                 for (const deviceJid of entry.deviceJids) {
                     const normalizedDeviceJid = normalizeDeviceJid(deviceJid);
-                    if (isHostedDeviceJid(normalizedDeviceJid)) {
-                        continue;
-                    }
                     if (meDeviceJids.has(normalizedDeviceJid)) {
                         continue;
                     }
@@ -104,7 +102,7 @@ export function createDeviceFanoutResolver(options) {
             return [...fanout];
         }
         catch (error) {
-            logger.warn('group participant device sync failed, falling back to participant user jids', {
+            logger.debug('group participant device sync failed, falling back to participant user jids', {
                 participants: candidateUsers.length,
                 message: toError(error).message
             });
@@ -128,14 +126,15 @@ export function createDeviceFanoutResolver(options) {
         }
     };
     const resolveOwnPeerDeviceJids = async () => {
-        const meJid = getCurrentMeJid();
+        const credentials = getCurrentCredentials();
+        const meJid = credentials?.meJid;
         if (!meJid) {
             throw new Error('resolveOwnPeerDeviceJids requires registered meJid');
         }
         const meUserJid = toUserJid(meJid);
         const meDevices = new Set();
         meDevices.add(normalizeDeviceJid(meJid));
-        const meLid = getCurrentMeLid();
+        const meLid = credentials?.meLid;
         if (meLid && meLid.includes('@')) {
             try {
                 meDevices.add(normalizeDeviceJid(meLid));

package/dist/esm/client/messaging/{participants.js → group-metadata.js}

@@ -1,9 +1,10 @@
 import { PromiseDedup } from '../../infra/perf/PromiseDedup.js';
 import { toUserJid } from '../../protocol/jid.js';
 import { toError } from '../../util/primitives.js';
-export function createGroupParticipantsCache(options) {
-    const { participantsStore, queryGroupParticipantJids, logger } = options;
+export function createGroupMetadataCache(options) {
+    const { groupMetadataStore, queryGroupMetadata, logger } = options;
     const dedup = new PromiseDedup();
+    const pendingMutations = new Map();
     const sanitizeParticipantUsers = (participants) => {
         const deduped = new Set();
         for (const participant of participants) {
@@ -33,10 +34,19 @@ export function createGroupParticipantsCache(options) {
         }
         return true;
     };
-    const mergeParticipantUsersIntoCache = async (groupJid, cachedParticipants, participantsToAdd) => {
+    const upsertParticipants = async (cached, groupJid, participants) => {
+        await groupMetadataStore.upsertGroupMetadata({
+            groupJid,
+            participants,
+            ephemeral: cached?.ephemeral,
+            updatedAtMs: Date.now()
+        });
+    };
+    const mergeParticipantUsersIntoCache = async (groupJid, cached, participantsToAdd) => {
         if (participantsToAdd.length === 0) {
             return;
         }
+        const cachedParticipants = cached.participants;
         const nextParticipants = [...cachedParticipants];
         const existing = new Set(cachedParticipants);
         for (const participant of participantsToAdd) {
@@ -49,33 +59,27 @@ export function createGroupParticipantsCache(options) {
         if (nextParticipants.length === cachedParticipants.length) {
             return;
         }
-        await participantsStore.upsertGroupParticipants({
-            groupJid,
-            participants: nextParticipants,
-            updatedAtMs: Date.now()
-        });
+        await upsertParticipants(cached, groupJid, nextParticipants);
     };
-    const removeParticipantUsersFromCache = async (groupJid, cachedParticipants, participantsToRemove) => {
+    const removeParticipantUsersFromCache = async (groupJid, cached, participantsToRemove) => {
         if (participantsToRemove.length === 0) {
             return;
         }
         const removed = new Set(participantsToRemove);
+        const cachedParticipants = cached.participants;
         const nextParticipants = cachedParticipants.filter((participant) => !removed.has(participant));
         if (nextParticipants.length === cachedParticipants.length) {
             return;
         }
         if (nextParticipants.length === 0) {
-            await participantsStore.deleteGroupParticipants(groupJid);
+            await groupMetadataStore.deleteGroupMetadata(groupJid);
             return;
         }
-        await participantsStore.upsertGroupParticipants({
-            groupJid,
-            participants: nextParticipants,
-            updatedAtMs: Date.now()
-        });
+        await upsertParticipants(cached, groupJid, nextParticipants);
     };
-    const replaceParticipantUsersInCache = async (groupJid, cachedParticipants, participantsToReplace, replacementParticipants) => {
+    const replaceParticipantUsersInCache = async (groupJid, cached, participantsToReplace, replacementParticipants) => {
         const toReplace = new Set(participantsToReplace);
+        const cachedParticipants = cached.participants;
         const nextParticipants = cachedParticipants.filter((participant) => !toReplace.has(participant));
         const existing = new Set(nextParticipants);
         for (const participant of replacementParticipants) {
@@ -89,16 +93,12 @@ export function createGroupParticipantsCache(options) {
             return;
         }
         if (nextParticipants.length === 0) {
-            await participantsStore.deleteGroupParticipants(groupJid);
+            await groupMetadataStore.deleteGroupMetadata(groupJid);
             return;
         }
-        await participantsStore.upsertGroupParticipants({
-            groupJid,
-            participants: nextParticipants,
-            updatedAtMs: Date.now()
-        });
+        await upsertParticipants(cached, groupJid, nextParticipants);
     };
-    const resolveGroupJidForParticipantCacheEvent = (event) => {
+    const resolveGroupJidForGroupCacheEvent = (event) => {
         if (event.action === 'linked_group_promote' || event.action === 'linked_group_demote') {
             return event.contextGroupJid ?? event.groupJid ?? null;
         }
@@ -107,42 +107,69 @@ export function createGroupParticipantsCache(options) {
     const extractParticipantUsersFromGroupEvent = (event) => {
         const candidates = [];
         for (const participant of event.participants ?? []) {
-            if (participant.jid) {
-                candidates.push(participant.jid);
-            }
-            if (participant.lidJid) {
-                candidates.push(participant.lidJid);
-            }
-            if (participant.phoneJid) {
-                candidates.push(participant.phoneJid);
+            const canonical = participant.jid ?? participant.lidJid ?? participant.phoneJid;
+            if (canonical) {
+                candidates.push(canonical);
             }
         }
         return sanitizeParticipantUsers(candidates);
     };
     const refreshParticipantUsers = (groupJid) => dedup.run(`refresh:${groupJid}`, async () => {
-        const queried = await queryGroupParticipantJids(groupJid);
-        const participants = sanitizeParticipantUsers(queried);
-        await participantsStore.upsertGroupParticipants({
+        const queried = await queryGroupMetadata(groupJid);
+        const participants = sanitizeParticipantUsers(queried.participants);
+        await groupMetadataStore.upsertGroupMetadata({
             groupJid,
             participants,
+            ephemeral: queried.ephemeral,
             updatedAtMs: Date.now()
         });
         return participants;
     });
     const resolveParticipantUsers = (groupJid) => dedup.run(`resolve:${groupJid}`, async () => {
-        const cached = await participantsStore.getGroupParticipants(groupJid);
+        await pendingMutations.get(groupJid)?.catch(() => undefined);
+        const cached = await groupMetadataStore.getGroupMetadata(groupJid);
         if (cached && cached.participants.length > 0) {
             return sanitizeParticipantUsers(cached.participants);
         }
         return refreshParticipantUsers(groupJid);
     });
-    const mutateFromGroupEvent = async (event) => {
-        const groupJid = resolveGroupJidForParticipantCacheEvent(event);
+    const getEphemeral = async (groupJid) => {
+        const cached = await groupMetadataStore.getGroupMetadata(groupJid);
+        return cached?.ephemeral ?? null;
+    };
+    const resolveEphemeral = async (groupJid) => {
+        const cached = await groupMetadataStore.getGroupMetadata(groupJid);
+        if (cached) {
+            return cached.ephemeral ?? null;
+        }
+        await refreshParticipantUsers(groupJid);
+        const refreshed = await groupMetadataStore.getGroupMetadata(groupJid);
+        return refreshed?.ephemeral ?? null;
+    };
+    const applyGroupEvent = async (event) => {
+        const groupJid = resolveGroupJidForGroupCacheEvent(event);
         if (!groupJid) {
             return;
         }
         if (event.action === 'delete') {
-            await participantsStore.deleteGroupParticipants(groupJid);
+            await groupMetadataStore.deleteGroupMetadata(groupJid);
+            return;
+        }
+        if (event.action === 'ephemeral') {
+            const cached = await groupMetadataStore.getGroupMetadata(groupJid);
+            if (!cached) {
+                return;
+            }
+            const nextEphemeral = event.expirationSeconds;
+            if (cached.ephemeral === nextEphemeral) {
+                return;
+            }
+            await groupMetadataStore.upsertGroupMetadata({
+                groupJid,
+                participants: cached.participants,
+                ephemeral: nextEphemeral,
+                updatedAtMs: Date.now()
+            });
             return;
         }
         const participantUsers = extractParticipantUsersFromGroupEvent(event);
@@ -150,14 +177,16 @@ export function createGroupParticipantsCache(options) {
             if (participantUsers.length === 0) {
                 return;
             }
-            await participantsStore.upsertGroupParticipants({
+            const existing = await groupMetadataStore.getGroupMetadata(groupJid);
+            await groupMetadataStore.upsertGroupMetadata({
                 groupJid,
                 participants: participantUsers,
+                ephemeral: existing?.ephemeral,
                 updatedAtMs: Date.now()
             });
             return;
         }
-        const cached = await participantsStore.getGroupParticipants(groupJid);
+        const cached = await groupMetadataStore.getGroupMetadata(groupJid);
         if (!cached || cached.participants.length === 0) {
             return;
         }
@@ -165,26 +194,46 @@ export function createGroupParticipantsCache(options) {
         if (cachedParticipants.length === 0) {
             return;
         }
+        const cachedWithSanitized = {
+            ...cached,
+            participants: cachedParticipants
+        };
         if (event.action === 'add' ||
             event.action === 'promote' ||
             event.action === 'demote' ||
             event.action === 'linked_group_promote' ||
             event.action === 'linked_group_demote') {
-            await mergeParticipantUsersIntoCache(groupJid, cachedParticipants, participantUsers);
+            await mergeParticipantUsersIntoCache(groupJid, cachedWithSanitized, participantUsers);
             return;
         }
         if (event.action === 'remove') {
-            await removeParticipantUsersFromCache(groupJid, cachedParticipants, participantUsers);
+            await removeParticipantUsersFromCache(groupJid, cachedWithSanitized, participantUsers);
             return;
         }
         if (event.action === 'modify') {
             const authorUsers = event.authorJid ? sanitizeParticipantUsers([event.authorJid]) : [];
-            await replaceParticipantUsersInCache(groupJid, cachedParticipants, authorUsers, participantUsers);
+            await replaceParticipantUsersInCache(groupJid, cachedWithSanitized, authorUsers, participantUsers);
         }
     };
+    const mutateFromGroupEvent = (event) => {
+        const groupJid = resolveGroupJidForGroupCacheEvent(event);
+        if (!groupJid) {
+            return applyGroupEvent(event);
+        }
+        const prev = pendingMutations.get(groupJid) ?? Promise.resolve();
+        const next = prev.then(() => applyGroupEvent(event), () => applyGroupEvent(event));
+        pendingMutations.set(groupJid, next);
+        return next.finally(() => {
+            if (pendingMutations.get(groupJid) === next) {
+                pendingMutations.delete(groupJid);
+            }
+        });
+    };
     return {
         resolveParticipantUsers,
         refreshParticipantUsers,
+        getEphemeral,
+        resolveEphemeral,
         mutateFromGroupEvent
     };
 }