zapo-js 0.2.0 → 1.0.0

package/dist/esm/client/media.js

@@ -0,0 +1,384 @@
+import { createHash } from 'node:crypto';
+import { createReadStream, createWriteStream } from 'node:fs';
+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 { 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');
+    try {
+        const buf = new Uint8Array(bytes);
+        const { bytesRead } = await fh.read(buf, 0, bytes, 0);
+        return buf.subarray(0, bytesRead);
+    }
+    finally {
+        await fh.close();
+    }
+}
+const RIFF_HEADER_SIZE = 12;
+const CHUNK_HEADER_SIZE = 8;
+const CHUNK_ID_SIZE = 4;
+const ANMF_ID = [0x41, 0x4e, 0x4d, 0x46];
+export function parseWebpAnimation(data) {
+    if (data.byteLength < RIFF_HEADER_SIZE + CHUNK_HEADER_SIZE)
+        return null;
+    let offset = RIFF_HEADER_SIZE;
+    if (data[offset] !== 0x56 ||
+        data[offset + 1] !== 0x50 ||
+        data[offset + 2] !== 0x38 ||
+        data[offset + 3] !== 0x58) {
+        return null;
+    }
+    // Skip VP8X chunk: 8 byte header + 10 byte payload
+    offset += CHUNK_HEADER_SIZE + 10;
+    while (offset + CHUNK_HEADER_SIZE <= data.byteLength) {
+        const isAnmf = data[offset] === ANMF_ID[0] &&
+            data[offset + 1] === ANMF_ID[1] &&
+            data[offset + 2] === ANMF_ID[2] &&
+            data[offset + 3] === ANMF_ID[3];
+        const sizeOffset = offset + CHUNK_ID_SIZE;
+        if (sizeOffset + 4 > data.byteLength)
+            return null;
+        let chunkSize = (data[sizeOffset] |
+            (data[sizeOffset + 1] << 8) |
+            (data[sizeOffset + 2] << 16) |
+            (data[sizeOffset + 3] << 24)) >>>
+            0;
+        if (chunkSize % 2 !== 0)
+            chunkSize += 1;
+        const nextOffset = offset + CHUNK_HEADER_SIZE + chunkSize;
+        if (nextOffset <= offset || nextOffset > data.byteLength)
+            return null;
+        if (isAnmf) {
+            return { isAnimated: true, firstFrameLength: nextOffset };
+        }
+        offset = nextOffset;
+    }
+    return null;
+}
+const IMAGE_THUMB_MAX_EDGE = 320;
+const VIDEO_THUMB_MAX_EDGE = 48;
+const STICKER_THUMB_MAX_EDGE = 100;
+const EMPTY_PROCESSED = {};
+export function isReadableStream(value) {
+    return (!!value &&
+        typeof value === 'object' &&
+        'pipe' in value &&
+        typeof value.pipe === 'function');
+}
+async function streamToTempFile(source) {
+    const filePath = join(tmpdir(), `zapo-media-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    try {
+        await pipeline(source, createWriteStream(filePath));
+    }
+    catch (error) {
+        await unlink(filePath).catch(() => undefined);
+        throw error;
+    }
+    return filePath;
+}
+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)
+        };
+    }
+    if (isReadableStream(raw)) {
+        if (shouldProcess) {
+            const tempFilePath = await streamToTempFile(raw);
+            return {
+                processorInput: tempFilePath,
+                uploadMedia: createReadStream(tempFilePath),
+                tempFilePath
+            };
+        }
+        return { uploadMedia: raw };
+    }
+    const bytes = toBytesView(raw);
+    return { processorInput: bytes, uploadMedia: bytes };
+}
+function shouldGenerateThumbnail(media, content) {
+    if (!media?.processor || media.generateThumbnail === false) {
+        return false;
+    }
+    switch (content.type) {
+        case 'image':
+            return content.jpegThumbnail === undefined && !!media.processor.generateImageThumbnail;
+        case 'video':
+        case 'ptv':
+            return content.jpegThumbnail === undefined && !!media.processor.generateVideoThumbnail;
+        case 'document':
+            return !!media.processor.generateImageThumbnail;
+        default:
+            return false;
+    }
+}
+function shouldProbeMedia(media, content) {
+    if (!media?.processor?.probeMedia || media.generateProbe === false) {
+        return false;
+    }
+    switch (content.type) {
+        case 'video':
+        case 'ptv':
+            return (content.seconds === undefined ||
+                content.width === undefined ||
+                content.height === undefined);
+        case 'audio':
+            return content.seconds === undefined;
+        default:
+            return false;
+    }
+}
+function shouldGenerateWaveform(media, content) {
+    return (!!media?.processor?.computeWaveform &&
+        media.generateWaveform !== false &&
+        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 &&
+        content.type === 'sticker' &&
+        content.pngThumbnail === undefined);
+}
+export function hasMediaProcessingTasks(media, content) {
+    return (shouldGenerateThumbnail(media, content) ||
+        shouldProbeMedia(media, content) ||
+        shouldGenerateWaveform(media, content) ||
+        shouldGenerateStickerThumbnail(media, content));
+}
+async function runProcessorStep(step, content, logger, fn) {
+    try {
+        return await fn();
+    }
+    catch (error) {
+        logger.error('media processor step failed, skipping step', {
+            type: content.type,
+            step,
+            message: toError(error).message
+        });
+        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, ctx))
+        : null;
+    const probeTask = shouldProbeMedia(media, content)
+        ? runProcessorStep('probe', content, logger, () => processor.probeMedia(input, ctx))
+        : null;
+    const [thumb, probe] = await Promise.all([thumbTask, probeTask]);
+    if (thumb) {
+        result.jpegThumbnail = thumb.jpegThumbnail;
+        if (!isVideo && !probe) {
+            result.width = thumb.width;
+            result.height = thumb.height;
+        }
+    }
+    if (probe) {
+        if (probe.durationSeconds !== undefined &&
+            !('seconds' in content && content.seconds !== undefined)) {
+            result.seconds = Math.floor(probe.durationSeconds);
+        }
+        if (!('width' in content && content.width !== undefined) && probe.width !== undefined) {
+            result.width = probe.width;
+        }
+        if (!('height' in content && content.height !== undefined) && probe.height !== undefined) {
+            result.height = probe.height;
+        }
+    }
+    if (shouldGenerateWaveform(media, content)) {
+        const waveformResult = await runProcessorStep('waveform', content, logger, () => processor.computeWaveform(input, ctx));
+        if (waveformResult) {
+            result.waveform = waveformResult.waveform;
+            if (result.seconds === undefined &&
+                !('seconds' in content && content.seconds !== undefined)) {
+                result.seconds = Math.floor(waveformResult.durationSeconds);
+            }
+        }
+    }
+    if (content.type === 'sticker') {
+        if (shouldGenerateStickerThumbnail(media, content)) {
+            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;
+                result.height = stickerThumb.height;
+            }
+        }
+        if (content.isAnimated === undefined) {
+            const header = typeof input === 'string' ? await readFileHead(input, 100) : input;
+            const anim = parseWebpAnimation(header);
+            if (anim) {
+                result.isAnimated = true;
+                result.firstFrameLength = anim.firstFrameLength;
+            }
+            else {
+                result.isAnimated = false;
+            }
+        }
+    }
+    return result;
+}

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,8 +1,8 @@
 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 sanitizeParticipantUsers = (participants) => {
         const deduped = new Set();
@@ -33,10 +33,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 +58,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 +92,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;
         }
@@ -120,29 +119,60 @@ export function createGroupParticipantsCache(options) {
         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);
+        const cached = await groupMetadataStore.getGroupMetadata(groupJid);
         if (cached && cached.participants.length > 0) {
             return sanitizeParticipantUsers(cached.participants);
         }
         return refreshParticipantUsers(groupJid);
     });
+    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 mutateFromGroupEvent = async (event) => {
-        const groupJid = resolveGroupJidForParticipantCacheEvent(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 +180,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 +197,32 @@ 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);
         }
     };
     return {
         resolveParticipantUsers,
         refreshParticipantUsers,
+        getEphemeral,
+        resolveEphemeral,
         mutateFromGroupEvent
     };
 }