zapo-js 0.3.0 → 1.0.1

package/dist/client/events/picture.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parsePictureNotificationEvents = parsePictureNotificationEvents;
+const helpers_1 = require("../../transport/node/helpers");
+const primitives_1 = require("../../util/primitives");
+const PICTURE_ACTION_TAGS = [
+    'set',
+    'delete',
+    'request',
+    'set_avatar'
+];
+function parsePictureNotificationEvents(node) {
+    for (const action of PICTURE_ACTION_TAGS) {
+        const actionNode = (0, helpers_1.findNodeChild)(node, action);
+        if (!actionNode)
+            continue;
+        const event = {
+            rawNode: node,
+            stanzaId: node.attrs.id,
+            chatJid: node.attrs.from,
+            stanzaType: node.attrs.type,
+            offline: node.attrs.offline !== undefined,
+            action,
+            targetJid: actionNode.attrs.jid,
+            authorJid: actionNode.attrs.author,
+            timestampSeconds: (0, primitives_1.parseOptionalInt)(node.attrs.t),
+            pictureId: action === 'set' ? (0, primitives_1.parseOptionalInt)(actionNode.attrs.id) : undefined,
+            contactHash: actionNode.attrs.hash
+        };
+        return { events: [event], unhandled: [] };
+    }
+    return { events: [], unhandled: [] };
+}

package/dist/client/events/presence.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parsePresenceNode = parsePresenceNode;
+const jid_1 = require("../../protocol/jid");
+const presence_1 = require("../../protocol/presence");
+const primitives_1 = require("../../util/primitives");
+function parseLastSeen(value) {
+    if (value === presence_1.WA_PRESENCE_LAST_SENTINELS.DENY) {
+        return { kind: 'privacy_denied' };
+    }
+    if (value === presence_1.WA_PRESENCE_LAST_SENTINELS.NONE) {
+        return { kind: 'never_online' };
+    }
+    if (value === presence_1.WA_PRESENCE_LAST_SENTINELS.ERROR) {
+        return { kind: 'unknown' };
+    }
+    const unixSeconds = (0, primitives_1.parseOptionalInt)(value);
+    if (unixSeconds === undefined) {
+        return { kind: 'unknown' };
+    }
+    return { kind: 'timestamp', unixSeconds };
+}
+function parsePresenceNode(node) {
+    const from = node.attrs.from;
+    const isGroup = from !== undefined && (0, jid_1.isGroupJid)(from);
+    const type = node.attrs.type === presence_1.WA_PRESENCE_TYPES.UNAVAILABLE
+        ? presence_1.WA_PRESENCE_TYPES.UNAVAILABLE
+        : presence_1.WA_PRESENCE_TYPES.AVAILABLE;
+    const result = { type };
+    if (isGroup) {
+        const count = (0, primitives_1.parseOptionalInt)(node.attrs.count);
+        if (count !== undefined) {
+            result.groupOnlineCount = count;
+        }
+        else if (type === presence_1.WA_PRESENCE_TYPES.UNAVAILABLE) {
+            result.groupOnlineCount = 0;
+        }
+        return result;
+    }
+    if (type === presence_1.WA_PRESENCE_TYPES.UNAVAILABLE && node.attrs.last !== undefined) {
+        result.lastSeen = parseLastSeen(node.attrs.last);
+    }
+    return result;
+}

package/dist/client/events/receipt.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.aggregateReceiptTargets = aggregateReceiptTargets;
+const jid_1 = require("../../protocol/jid");
+function needsParticipant(target) {
+    if (target.isGroupChat !== undefined || target.isBroadcastChat !== undefined) {
+        return target.isGroupChat === true || target.isBroadcastChat === true;
+    }
+    return (0, jid_1.isGroupOrBroadcastJid)(target.chatJid);
+}
+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/client/media.js

@@ -4,14 +4,24 @@ exports.readFileHead = readFileHead;
 exports.parseWebpAnimation = parseWebpAnimation;
 exports.isReadableStream = isReadableStream;
 exports.cleanupTempFile = cleanupTempFile;
+exports.selectMediaUploadHost = selectMediaUploadHost;
+exports.buildMediaUploadUrl = buildMediaUploadUrl;
+exports.assertMediaUploadStatus = assertMediaUploadStatus;
+exports.parseMediaUploadJsonBody = parseMediaUploadJsonBody;
+exports.performPlaintextMediaUpload = performPlaintextMediaUpload;
 exports.resolveMediaInputs = resolveMediaInputs;
+exports.shouldNormalizeVoiceNote = shouldNormalizeVoiceNote;
 exports.hasMediaProcessingTasks = hasMediaProcessingTasks;
+exports.getScopedMediaLogger = getScopedMediaLogger;
 exports.runMediaProcessor = runMediaProcessor;
+const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const promises_1 = require("node:fs/promises");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
+const node_stream_1 = require("node:stream");
 const promises_2 = require("node:stream/promises");
+const core_1 = require("../crypto/core");
 const bytes_1 = require("../util/bytes");
 const primitives_1 = require("../util/primitives");
 async function readFileHead(filePath, bytes) {
@@ -66,8 +76,8 @@ 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 = {};
 function isReadableStream(value) {
@@ -90,8 +100,135 @@ async function streamToTempFile(source) {
 async function cleanupTempFile(filePath) {
     await (0, promises_1.unlink)(filePath).catch(() => undefined);
 }
+function createSha256SizeMeter() {
+    const hash = (0, node_crypto_1.createHash)('sha256');
+    let byteLength = 0;
+    const transform = new node_stream_1.Transform({
+        transform(chunk, _enc, cb) {
+            const bytes = chunk instanceof Uint8Array ? chunk : (0, bytes_1.toChunkBytes)(chunk);
+            hash.update(bytes);
+            byteLength += bytes.byteLength;
+            cb(null, bytes);
+        }
+    });
+    return {
+        transform,
+        finalize: () => ({ fileSha256: (0, bytes_1.toBytesView)(hash.digest()), byteLength })
+    };
+}
+async function streamToTempFileWithSha256(source) {
+    const filePath = (0, node_path_1.join)((0, node_os_1.tmpdir)(), `zapo-media-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    const meter = createSha256SizeMeter();
+    try {
+        await (0, promises_2.pipeline)(source, meter.transform, (0, node_fs_1.createWriteStream)(filePath));
+    }
+    catch (error) {
+        await (0, promises_1.unlink)(filePath).catch(() => undefined);
+        throw error;
+    }
+    return { filePath, ...meter.finalize() };
+}
+async function preparePlaintextUploadSource(media) {
+    if (media instanceof Uint8Array) {
+        return { fileSha256: (0, core_1.sha256)(media), byteLength: media.byteLength, body: media };
+    }
+    if (typeof media === 'string') {
+        await assertReadableFile(media);
+        const result = await streamToTempFileWithSha256((0, node_fs_1.createReadStream)(media));
+        return {
+            fileSha256: result.fileSha256,
+            byteLength: result.byteLength,
+            body: (0, node_fs_1.createReadStream)(result.filePath),
+            cleanup: () => cleanupTempFile(result.filePath)
+        };
+    }
+    if (isReadableStream(media)) {
+        const result = await streamToTempFileWithSha256(media);
+        return {
+            fileSha256: result.fileSha256,
+            byteLength: result.byteLength,
+            body: (0, node_fs_1.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 (0, core_1.randomIntAsync)(0, MEDIA_UPLOAD_ID_MAX);
+    return value.toString(10);
+}
+function selectMediaUploadHost(mediaConn) {
+    return mediaConn.hosts.find((host) => !host.isFallback)?.hostname ?? mediaConn.hosts[0].hostname;
+}
+function buildMediaUploadUrl(host, path, auth, fileSha256, mediaId) {
+    const hashToken = (0, bytes_1.bytesToBase64UrlSafe)(fileSha256);
+    const base = `https://${host}${path}/${hashToken}?auth=${encodeURIComponent(auth)}&token=${encodeURIComponent(hashToken)}`;
+    return mediaId !== undefined ? `${base}&media_id=${mediaId}` : base;
+}
+function assertMediaUploadStatus(status, label) {
+    if (status < 200 || status >= 300) {
+        throw new Error(`${label} failed with status ${status}`);
+    }
+}
+function parseMediaUploadJsonBody(body, label) {
+    try {
+        return JSON.parse(bytes_1.TEXT_DECODER.decode(body));
+    }
+    catch (error) {
+        throw new Error(`${label} returned invalid json: ${(0, primitives_1.toError)(error).message}`);
+    }
+}
+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 (0, promises_1.stat)(filePath);
+        if (!stats.isFile()) {
+            throw new Error(`media path is not a regular file: ${filePath}`);
+        }
+    }
+    catch (error) {
+        const err = (0, primitives_1.toError)(error);
+        if (err.code === 'ENOENT') {
+            throw new Error(`media file not found: ${filePath}`);
+        }
+        throw err;
+    }
+}
 async function resolveMediaInputs(shouldProcess, raw) {
     if (typeof raw === 'string') {
+        await assertReadableFile(raw);
         return {
             processorInput: raw,
             uploadMedia: (0, node_fs_1.createReadStream)(raw)
@@ -149,6 +286,12 @@ function shouldGenerateWaveform(media, content) {
         content.type === 'audio' &&
         content.waveform === undefined);
 }
+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 &&
@@ -174,19 +317,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();
+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;
+}
 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) {
@@ -209,7 +366,7 @@ 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 &&
@@ -220,7 +377,7 @@ 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/client/messaging/fanout.js

@@ -5,7 +5,7 @@ const PromiseDedup_1 = require("../../infra/perf/PromiseDedup");
 const jid_1 = require("../../protocol/jid");
 const primitives_1 = require("../../util/primitives");
 function createDeviceFanoutResolver(options) {
-    const { signalDeviceSync, getCurrentMeJid, getCurrentMeLid, logger } = options;
+    const { signalDeviceSync, getCurrentCredentials, logger } = options;
     const dedup = new PromiseDedup_1.PromiseDedup();
     const resolveDirectFanoutDeviceJids = async (recipientJid, selfDeviceJidForRecipient) => {
         const recipientUserJid = (0, jid_1.toUserJid)(recipientJid);
@@ -40,7 +40,7 @@ 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: (0, primitives_1.toError)(error).message
             });
@@ -49,7 +49,8 @@ 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((0, jid_1.normalizeDeviceJid)(meJid));
@@ -61,7 +62,7 @@ function createDeviceFanoutResolver(options) {
                 });
             }
         }
-        const meLid = getCurrentMeLid();
+        const meLid = credentials?.meLid;
         if (meLid && meLid.includes('@')) {
             try {
                 meDeviceJids.add((0, jid_1.normalizeDeviceJid)(meLid));
@@ -95,9 +96,6 @@ function createDeviceFanoutResolver(options) {
                 }
                 for (const deviceJid of entry.deviceJids) {
                     const normalizedDeviceJid = (0, jid_1.normalizeDeviceJid)(deviceJid);
-                    if ((0, jid_1.isHostedDeviceJid)(normalizedDeviceJid)) {
-                        continue;
-                    }
                     if (meDeviceJids.has(normalizedDeviceJid)) {
                         continue;
                     }
@@ -107,7 +105,7 @@ 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: (0, primitives_1.toError)(error).message
             });
@@ -131,14 +129,15 @@ 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 = (0, jid_1.toUserJid)(meJid);
         const meDevices = new Set();
         meDevices.add((0, jid_1.normalizeDeviceJid)(meJid));
-        const meLid = getCurrentMeLid();
+        const meLid = credentials?.meLid;
         if (meLid && meLid.includes('@')) {
             try {
                 meDevices.add((0, jid_1.normalizeDeviceJid)(meLid));

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

@@ -1,12 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createGroupParticipantsCache = createGroupParticipantsCache;
+exports.createGroupMetadataCache = createGroupMetadataCache;
 const PromiseDedup_1 = require("../../infra/perf/PromiseDedup");
 const jid_1 = require("../../protocol/jid");
 const primitives_1 = require("../../util/primitives");
-function createGroupParticipantsCache(options) {
-    const { participantsStore, queryGroupParticipantJids, logger } = options;
+function createGroupMetadataCache(options) {
+    const { groupMetadataStore, queryGroupMetadata, logger } = options;
     const dedup = new PromiseDedup_1.PromiseDedup();
+    const pendingMutations = new Map();
     const sanitizeParticipantUsers = (participants) => {
         const deduped = new Set();
         for (const participant of participants) {
@@ -36,10 +37,19 @@ 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) {
@@ -52,33 +62,27 @@ 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) {
@@ -92,16 +96,12 @@ 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;
         }
@@ -110,42 +110,69 @@ 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);
@@ -153,14 +180,16 @@ 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;
         }
@@ -168,26 +197,46 @@ 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
     };
 }