zapo-js 0.3.0 → 1.0.0

package/dist/esm/store/createStore.js

@@ -1,11 +1,15 @@
+import { withIdentityCache } from './cache/identity.cache.js';
+import { withPrivacyTokenCache } from './cache/privacy-token.cache.js';
+import { withSenderKeyCache } from './cache/sender-key.cache.js';
+import { withSessionCache } from './cache/session.cache.js';
 import { withAppStateLock } from './locks/appstate.lock.js';
 import { withAuthLock } from './locks/auth.lock.js';
 import { withContactLock } from './locks/contact.lock.js';
 import { withDeviceListLock } from './locks/device-list.lock.js';
+import { withGroupMetadataLock } from './locks/group-metadata.lock.js';
 import { withIdentityLock } from './locks/identity.lock.js';
 import { withMessageSecretLock } from './locks/message-secret.lock.js';
 import { withMessageLock } from './locks/message.lock.js';
-import { withParticipantsLock } from './locks/participants.lock.js';
 import { withPreKeyLock } from './locks/pre-key.lock.js';
 import { withPrivacyTokenLock } from './locks/privacy-token.lock.js';
 import { withRetryLock } from './locks/retry.lock.js';
@@ -13,28 +17,42 @@ import { withSenderKeyLock } from './locks/sender-key.lock.js';
 import { withSessionLock } from './locks/session.lock.js';
 import { withSignalLock } from './locks/signal.lock.js';
 import { withThreadLock } from './locks/thread.lock.js';
-import { NOOP_CONTACT_STORE, NOOP_DEVICE_LIST_STORE, NOOP_MESSAGE_SECRET_STORE, NOOP_MESSAGE_STORE, NOOP_PARTICIPANTS_STORE, NOOP_RETRY_STORE, NOOP_THREAD_STORE } from './noop.store.js';
-import { WaAppStateMemoryStore } from './providers/memory/appstate.store.js';
-import { WaContactMemoryStore } from './providers/memory/contact.store.js';
-import { WaDeviceListMemoryStore } from './providers/memory/device-list.store.js';
-import { WaIdentityMemoryStore } from './providers/memory/identity.store.js';
-import { WaMessageSecretMemoryStore } from './providers/memory/message-secret.store.js';
-import { WaMessageMemoryStore } from './providers/memory/message.store.js';
-import { WaParticipantsMemoryStore } from './providers/memory/participants.store.js';
-import { WaPreKeyMemoryStore } from './providers/memory/pre-key.store.js';
-import { WaPrivacyTokenMemoryStore } from './providers/memory/privacy-token.store.js';
-import { WaRetryMemoryStore } from './providers/memory/retry.store.js';
-import { SenderKeyMemoryStore } from './providers/memory/sender-key.store.js';
-import { WaSessionMemoryStore } from './providers/memory/session.store.js';
-import { WaSignalMemoryStore } from './providers/memory/signal.store.js';
-import { WaThreadMemoryStore } from './providers/memory/thread.store.js';
+import { WaAppStateMemoryStore } from './memory/appstate.store.js';
+import { WaAuthMemoryStore } from './memory/auth.store.js';
+import { WaContactMemoryStore } from './memory/contact.store.js';
+import { WaDeviceListMemoryStore } from './memory/device-list.store.js';
+import { WaGroupMetadataMemoryStore } from './memory/group-metadata.store.js';
+import { WaIdentityMemoryStore } from './memory/identity.store.js';
+import { WaMessageSecretMemoryStore } from './memory/message-secret.store.js';
+import { WaMessageMemoryStore } from './memory/message.store.js';
+import { WaPreKeyMemoryStore } from './memory/pre-key.store.js';
+import { WaPrivacyTokenMemoryStore } from './memory/privacy-token.store.js';
+import { WaRetryMemoryStore } from './memory/retry.store.js';
+import { SenderKeyMemoryStore } from './memory/sender-key.store.js';
+import { WaSessionMemoryStore } from './memory/session.store.js';
+import { WaSignalMemoryStore } from './memory/signal.store.js';
+import { WaThreadMemoryStore } from './memory/thread.store.js';
+import { NOOP_CONTACT_STORE, NOOP_DEVICE_LIST_STORE, NOOP_GROUP_METADATA_STORE, NOOP_MESSAGE_SECRET_STORE, NOOP_MESSAGE_STORE, NOOP_RETRY_STORE, NOOP_THREAD_STORE } from './noop.store.js';
 import { resolvePositive } from '../util/coercion.js';
 const DEFAULT_CACHE_TTLS_MS = Object.freeze({
     retryMs: 60 * 1000,
-    participantsMs: 5 * 60 * 1000,
+    groupMetadataMs: 5 * 60 * 1000,
     deviceListMs: 5 * 60 * 1000,
     messageSecretMs: 30 * 60 * 1000
 });
+const REQUIRED_PROVIDER_DOMAINS = [
+    'auth',
+    'signal',
+    'preKey',
+    'session',
+    'identity',
+    'senderKey',
+    'appState',
+    'messages',
+    'threads',
+    'contacts',
+    'privacyToken'
+];
 function hasDestroy(value) {
     return (!!value &&
         typeof value === 'object' &&
@@ -46,6 +64,9 @@ async function destroyIfSupported(value) {
         return;
     await value.destroy();
 }
+function usesBackend(provider) {
+    return !!provider && provider !== 'memory' && provider !== 'none';
+}
 function resolveStore(sessionId, backends, provider, domain, kind, fallback) {
     if (!provider || provider === 'memory' || provider === 'none') {
         return fallback();
@@ -61,12 +82,29 @@ function resolveStore(sessionId, backends, provider, domain, kind, fallback) {
     return factory(sessionId);
 }
 export function createStore(options) {
+    options = options ?? {};
     const backends = (options.backends ?? {});
     const providers = options.providers ?? {};
     const cacheProviders = options.cacheProviders ?? {};
+    const cacheLayer = options.cacheLayer ?? {};
+    const storeLogger = options.logger?.child({ scope: 'store' });
+    const memoryLogger = storeLogger?.child({ provider: 'memory' });
+    if (Object.keys(backends).length > 0) {
+        const missingProviders = REQUIRED_PROVIDER_DOMAINS.filter((domain) => providers[domain] === undefined);
+        if (missingProviders.length > 0) {
+            throw new Error(`createStore: when backends is set, every persistence domain must be assigned ` +
+                `explicitly via providers. Missing: ${missingProviders
+                    .map((d) => `providers.${d}`)
+                    .join(', ')}. Pass a backend name (e.g. 'sqlite') to persist, or ` +
+                `'memory' to use the in-tree memory provider. For the mailbox domains ` +
+                `(messages/threads/contacts) 'none' skips the domain entirely; for the ` +
+                `other domains 'none' falls back to memory. Cache providers ` +
+                `(retry/groupMetadata/deviceList/messageSecret) stay opt-in and default to memory.`);
+        }
+    }
     const cacheTtlsMs = Object.freeze({
         retry: resolvePositive(options.memory?.cacheTtlMs?.retryMs, DEFAULT_CACHE_TTLS_MS.retryMs, 'memory.cacheTtlMs.retryMs'),
-        participants: resolvePositive(options.memory?.cacheTtlMs?.participantsMs, DEFAULT_CACHE_TTLS_MS.participantsMs, 'memory.cacheTtlMs.participantsMs'),
+        groupMetadata: resolvePositive(options.memory?.cacheTtlMs?.groupMetadataMs, DEFAULT_CACHE_TTLS_MS.groupMetadataMs, 'memory.cacheTtlMs.groupMetadataMs'),
         deviceList: resolvePositive(options.memory?.cacheTtlMs?.deviceListMs, DEFAULT_CACHE_TTLS_MS.deviceListMs, 'memory.cacheTtlMs.deviceListMs'),
         messageSecret: resolvePositive(options.memory?.cacheTtlMs?.messageSecretMs, DEFAULT_CACHE_TTLS_MS.messageSecretMs, 'memory.cacheTtlMs.messageSecretMs')
     });
@@ -85,9 +123,7 @@ export function createStore(options) {
             if (cached)
                 return cached;
             const ml = options.memory?.limits ?? {};
-            const rawAuth = resolveStore(id, backends, providers.auth, 'auth', 'stores', () => {
-                throw new Error('providers.auth is required — register a backend or set providers.auth');
-            });
+            const rawAuth = resolveStore(id, backends, providers.auth ?? 'memory', 'auth', 'stores', () => new WaAuthMemoryStore());
             const rawSignal = resolveStore(id, backends, providers.signal ?? 'memory', 'signal', 'stores', () => new WaSignalMemoryStore());
             const rawPreKey = resolveStore(id, backends, providers.preKey ?? 'memory', 'preKey', 'stores', () => new WaPreKeyMemoryStore({ maxPreKeys: ml.signalPreKeys }));
             const rawSession = resolveStore(id, backends, providers.session ?? 'memory', 'session', 'stores', () => new WaSessionMemoryStore({ maxSessions: ml.signalSessions }));
@@ -115,39 +151,57 @@ export function createStore(options) {
             const rawRetry = resolveStore(id, backends, cacheProviders.retry ?? 'memory', 'retry', 'caches', () => cacheProviders.retry === 'memory' || !cacheProviders.retry
                 ? new WaRetryMemoryStore(cacheTtlsMs.retry, {
                     maxOutboundMessages: ml.retryOutboundMessages,
-                    maxInboundCounters: ml.retryInboundCounters
+                    maxInboundCounters: ml.retryInboundCounters,
+                    logger: memoryLogger?.child({ domain: 'retry', sessionId: id })
                 })
                 : NOOP_RETRY_STORE);
-            const rawParticipants = resolveStore(id, backends, cacheProviders.participants ?? 'memory', 'participants', 'caches', () => cacheProviders.participants === 'memory'
-                ? new WaParticipantsMemoryStore(cacheTtlsMs.participants, {
-                    maxGroups: ml.participantsGroups
+            const rawGroupMetadata = resolveStore(id, backends, cacheProviders.groupMetadata ?? 'memory', 'groupMetadata', 'caches', () => cacheProviders.groupMetadata === 'memory' || !cacheProviders.groupMetadata
+                ? new WaGroupMetadataMemoryStore(cacheTtlsMs.groupMetadata, {
+                    maxGroups: ml.groupMetadataGroups,
+                    logger: memoryLogger?.child({
+                        domain: 'groupMetadata',
+                        sessionId: id
+                    })
                 })
-                : NOOP_PARTICIPANTS_STORE);
+                : NOOP_GROUP_METADATA_STORE);
             const rawDeviceList = resolveStore(id, backends, cacheProviders.deviceList ?? 'memory', 'deviceList', 'caches', () => cacheProviders.deviceList === 'memory'
                 ? new WaDeviceListMemoryStore(cacheTtlsMs.deviceList, {
-                    maxUsers: ml.deviceListUsers
+                    maxUsers: ml.deviceListUsers,
+                    logger: memoryLogger?.child({ domain: 'deviceList', sessionId: id })
                 })
                 : NOOP_DEVICE_LIST_STORE);
-            const rawMessageSecret = resolveStore(id, backends, cacheProviders.messageSecret ?? 'none', 'messageSecret', 'caches', () => cacheProviders.messageSecret === 'memory'
+            const rawMessageSecret = resolveStore(id, backends, cacheProviders.messageSecret ?? 'memory', 'messageSecret', 'caches', () => cacheProviders.messageSecret === 'memory' || !cacheProviders.messageSecret
                 ? new WaMessageSecretMemoryStore(cacheTtlsMs.messageSecret, {
-                    maxSecrets: ml.messageSecrets
+                    maxSecrets: ml.messageSecrets,
+                    logger: memoryLogger?.child({
+                        domain: 'messageSecret',
+                        sessionId: id
+                    })
                 })
                 : NOOP_MESSAGE_SECRET_STORE);
             const authStore = withAuthLock(rawAuth);
             const signalStore = withSignalLock(rawSignal);
             const preKeyStore = withPreKeyLock(rawPreKey);
-            const sessionStore = withSessionLock(rawSession);
-            const identityStore = withIdentityLock(rawIdentity);
-            const senderKeyStore = withSenderKeyLock(rawSenderKey);
+            const sessionStore = withSessionLock(cacheLayer.session && usesBackend(providers.session)
+                ? withSessionCache(rawSession, cacheLayer.limits?.session)
+                : rawSession);
+            const identityStore = withIdentityLock(cacheLayer.identity && usesBackend(providers.identity)
+                ? withIdentityCache(rawIdentity, cacheLayer.limits?.identity)
+                : rawIdentity);
+            const senderKeyStore = withSenderKeyLock(cacheLayer.senderKey && usesBackend(providers.senderKey)
+                ? withSenderKeyCache(rawSenderKey, cacheLayer.limits?.senderKey)
+                : rawSenderKey);
             const appStateStore = withAppStateLock(rawAppState);
             const retryStore = withRetryLock(rawRetry);
-            const participantsStore = withParticipantsLock(rawParticipants);
+            const groupMetadataStore = withGroupMetadataLock(rawGroupMetadata);
             const deviceListStore = withDeviceListLock(rawDeviceList);
             const messageStore = withMessageLock(rawMessages);
             const messageSecretStore = withMessageSecretLock(rawMessageSecret);
             const threadStore = withThreadLock(rawThreads);
             const contactStore = withContactLock(rawContacts);
-            const privacyTokenStore = withPrivacyTokenLock(rawPrivacyToken);
+            const privacyTokenStore = withPrivacyTokenLock(cacheLayer.privacyToken && usesBackend(providers.privacyToken)
+                ? withPrivacyTokenCache(rawPrivacyToken, cacheLayer.limits?.privacyToken)
+                : rawPrivacyToken);
             let cachesDestroyed = false;
             let sessionDestroyed = false;
             const destroyCaches = async () => {
@@ -156,13 +210,13 @@ export function createStore(options) {
                 cachesDestroyed = true;
                 await Promise.all([
                     retryStore.clear(),
-                    participantsStore.clear(),
+                    groupMetadataStore.clear(),
                     deviceListStore.clear(),
                     messageSecretStore.clear()
                 ]);
                 await Promise.all([
                     destroyIfSupported(retryStore),
-                    destroyIfSupported(participantsStore),
+                    destroyIfSupported(groupMetadataStore),
                     destroyIfSupported(deviceListStore),
                     destroyIfSupported(messageSecretStore)
                 ]);
@@ -195,7 +249,7 @@ export function createStore(options) {
                 senderKey: senderKeyStore,
                 appState: appStateStore,
                 retry: retryStore,
-                participants: participantsStore,
+                groupMetadata: groupMetadataStore,
                 deviceList: deviceListStore,
                 messages: messageStore,
                 messageSecret: messageSecretStore,

package/dist/esm/store/index.js

@@ -1,15 +1,16 @@
 export { createStore } from './createStore.js';
-export { WaAppStateMemoryStore } from './providers/memory/appstate.store.js';
-export { WaSignalMemoryStore } from './providers/memory/signal.store.js';
-export { WaPreKeyMemoryStore } from './providers/memory/pre-key.store.js';
-export { WaSessionMemoryStore } from './providers/memory/session.store.js';
-export { WaIdentityMemoryStore } from './providers/memory/identity.store.js';
-export { SenderKeyMemoryStore } from './providers/memory/sender-key.store.js';
-export { WaRetryMemoryStore } from './providers/memory/retry.store.js';
-export { WaParticipantsMemoryStore } from './providers/memory/participants.store.js';
-export { WaDeviceListMemoryStore } from './providers/memory/device-list.store.js';
-export { WaContactMemoryStore } from './providers/memory/contact.store.js';
-export { WaMessageSecretMemoryStore } from './providers/memory/message-secret.store.js';
-export { WaMessageMemoryStore } from './providers/memory/message.store.js';
-export { WaThreadMemoryStore } from './providers/memory/thread.store.js';
-export { WaPrivacyTokenMemoryStore } from './providers/memory/privacy-token.store.js';
+export { WaAppStateMemoryStore } from './memory/appstate.store.js';
+export { WaAuthMemoryStore } from './memory/auth.store.js';
+export { WaSignalMemoryStore } from './memory/signal.store.js';
+export { WaPreKeyMemoryStore } from './memory/pre-key.store.js';
+export { WaSessionMemoryStore } from './memory/session.store.js';
+export { WaIdentityMemoryStore } from './memory/identity.store.js';
+export { SenderKeyMemoryStore } from './memory/sender-key.store.js';
+export { WaRetryMemoryStore } from './memory/retry.store.js';
+export { WaGroupMetadataMemoryStore } from './memory/group-metadata.store.js';
+export { WaDeviceListMemoryStore } from './memory/device-list.store.js';
+export { WaContactMemoryStore } from './memory/contact.store.js';
+export { WaMessageSecretMemoryStore } from './memory/message-secret.store.js';
+export { WaMessageMemoryStore } from './memory/message.store.js';
+export { WaThreadMemoryStore } from './memory/thread.store.js';
+export { WaPrivacyTokenMemoryStore } from './memory/privacy-token.store.js';

package/dist/esm/store/locks/contact.lock.js

@@ -9,6 +9,7 @@ export function withContactLock(store) {
         upsert: (record) => gate.runShared(() => lock.run(`contact:${record.jid}`, () => store.upsert(record))),
         upsertBatch: (records) => gate.runShared(() => lock.runMany(records.map((record) => `contact:${record.jid}`), () => store.upsertBatch(records))),
         getByJid: (jid) => gate.runShared(() => store.getByJid(jid)),
+        getByPhoneNumber: (pn) => gate.runShared(() => store.getByPhoneNumber(pn)),
         deleteByJid: (jid) => gate.runShared(() => lock.run(`contact:${jid}`, () => store.deleteByJid(jid))),
         clear: () => gate.runExclusive(() => lock.run(WA_CONTACT_CLEAR_KEY, () => store.clear())),
         destroy: async () => {

package/dist/esm/store/locks/device-list.lock.js

@@ -13,6 +13,7 @@ export function withDeviceListLock(store) {
         },
         upsertUserDevicesBatch: (snapshots) => gate.runShared(() => lock.runMany(snapshots.map((snapshot) => `deviceList:user:${snapshot.userJid}`), () => store.upsertUserDevicesBatch(snapshots))),
         getUserDevicesBatch: (userJids, nowMs) => gate.runShared(() => store.getUserDevicesBatch(userJids, nowMs)),
+        findByAnyUserJid: (jid, nowMs) => gate.runShared(() => store.findByAnyUserJid(jid, nowMs)),
         deleteUserDevices: (userJid) => gate.runShared(() => lock.run(`deviceList:user:${userJid}`, () => store.deleteUserDevices(userJid))),
         cleanupExpired: (nowMs) => gate.runExclusive(() => lock.run(WA_DEVICE_LIST_CLEANUP_KEY, () => store.cleanupExpired(nowMs))),
         clear: () => gate.runExclusive(() => lock.run(WA_DEVICE_LIST_CLEAR_KEY, () => store.clear()))

package/dist/esm/store/locks/group-metadata.lock.js

@@ -0,0 +1,20 @@
+import { SharedExclusiveGate } from '../../infra/perf/SharedExclusiveGate.js';
+import { StoreLock } from '../../infra/perf/StoreLock.js';
+const WA_GROUP_METADATA_CLEAR_KEY = 'group-metadata:clear';
+const WA_GROUP_METADATA_CLEANUP_KEY = 'group-metadata:cleanup';
+export function withGroupMetadataLock(store) {
+    const lock = new StoreLock();
+    const gate = new SharedExclusiveGate();
+    return {
+        destroy: async () => {
+            await gate.close();
+            await lock.shutdown();
+            await store.destroy?.();
+        },
+        upsertGroupMetadata: (snapshot) => gate.runShared(() => lock.run(`group-metadata:group:${snapshot.groupJid}`, () => store.upsertGroupMetadata(snapshot))),
+        getGroupMetadata: (groupJid, nowMs) => gate.runShared(() => store.getGroupMetadata(groupJid, nowMs)),
+        deleteGroupMetadata: (groupJid) => gate.runShared(() => lock.run(`group-metadata:group:${groupJid}`, () => store.deleteGroupMetadata(groupJid))),
+        cleanupExpired: (nowMs) => gate.runExclusive(() => lock.run(WA_GROUP_METADATA_CLEANUP_KEY, () => store.cleanupExpired(nowMs))),
+        clear: () => gate.runExclusive(() => lock.run(WA_GROUP_METADATA_CLEAR_KEY, () => store.clear()))
+    };
+}

package/dist/esm/store/{providers/memory → memory}/appstate.store.js

@@ -1,8 +1,8 @@
-import { APP_STATE_EMPTY_LT_HASH } from '../../../appstate/constants.js';
-import { pickActiveSyncKey } from '../../../appstate/utils.js';
-import { bytesToHex, uint8Equal } from '../../../util/bytes.js';
-import { resolvePositive } from '../../../util/coercion.js';
-import { setBoundedMapEntry } from '../../../util/collections.js';
+import { APP_STATE_EMPTY_LT_HASH } from '../../appstate/constants.js';
+import { pickActiveSyncKey } from '../../appstate/utils.js';
+import { bytesToHex, uint8Equal } from '../../util/bytes.js';
+import { resolvePositive } from '../../util/coercion.js';
+import { setBoundedMapEntry } from '../../util/collections.js';
 const DEFAULT_APPSTATE_MEMORY_STORE_LIMITS = Object.freeze({
     syncKeys: 4096,
     collectionEntries: 50000

package/dist/esm/store/memory/auth.store.js

@@ -0,0 +1,24 @@
+/**
+ * In-memory {@link WaAuthStore} implementation. Holds a single
+ * {@link WaAuthCredentials} per instance in a field – nothing is persisted.
+ *
+ * @sensitive Holds private key material from {@link WaAuthCredentials} in
+ * RAM. Never log instances, never `JSON.stringify`. Pairing credentials are
+ * lost when the process exits, so the next connect will re-pair from scratch
+ * (QR/link-code). Prefer a persistent backend (e.g. `@zapo-js/store-sqlite`)
+ * for production.
+ */
+export class WaAuthMemoryStore {
+    constructor() {
+        this.credentials = null;
+    }
+    async load() {
+        return this.credentials;
+    }
+    async save(credentials) {
+        this.credentials = credentials;
+    }
+    async clear() {
+        this.credentials = null;
+    }
+}

package/dist/esm/store/memory/contact.store.js

@@ -0,0 +1,79 @@
+import { isUserJid } from '../../protocol/jid.js';
+import { resolvePositive } from '../../util/coercion.js';
+import { setBoundedMapEntry } from '../../util/collections.js';
+const DEFAULT_CONTACT_MEMORY_STORE_LIMITS = Object.freeze({
+    contacts: 20000
+});
+function mergeContactRecords(previous, incoming) {
+    if (!previous)
+        return incoming;
+    return {
+        jid: incoming.jid,
+        displayName: incoming.displayName ?? previous.displayName,
+        pushName: incoming.pushName ?? previous.pushName,
+        lid: incoming.lid ?? previous.lid,
+        phoneNumber: incoming.phoneNumber ?? previous.phoneNumber,
+        lastUpdatedMs: Math.max(previous.lastUpdatedMs, incoming.lastUpdatedMs)
+    };
+}
+export class WaContactMemoryStore {
+    constructor(options = {}) {
+        this.contacts = new Map();
+        /** Secondary index: phone_number -> primary jid (typically the LID form). */
+        this.phoneIndex = new Map();
+        this.maxContacts = resolvePositive(options.maxContacts, DEFAULT_CONTACT_MEMORY_STORE_LIMITS.contacts, 'WaContactMemoryStoreOptions.maxContacts');
+    }
+    writeRecord(record) {
+        const previous = this.contacts.get(record.jid);
+        const merged = mergeContactRecords(previous, record);
+        setBoundedMapEntry(this.contacts, merged.jid, merged, this.maxContacts);
+        if (previous?.phoneNumber &&
+            previous.phoneNumber !== merged.phoneNumber &&
+            this.phoneIndex.get(previous.phoneNumber) === merged.jid) {
+            this.phoneIndex.delete(previous.phoneNumber);
+        }
+        if (merged.phoneNumber) {
+            this.phoneIndex.set(merged.phoneNumber, merged.jid);
+        }
+    }
+    async upsert(record) {
+        this.writeRecord(record);
+    }
+    async upsertBatch(records) {
+        for (const record of records) {
+            this.writeRecord(record);
+        }
+    }
+    async getByJid(jid) {
+        const direct = this.contacts.get(jid);
+        if (direct)
+            return direct;
+        if (isUserJid(jid)) {
+            return this.getByPhoneNumberSync(jid);
+        }
+        return null;
+    }
+    async getByPhoneNumber(pn) {
+        return this.getByPhoneNumberSync(pn);
+    }
+    getByPhoneNumberSync(pn) {
+        const jid = this.phoneIndex.get(pn);
+        if (!jid)
+            return null;
+        return this.contacts.get(jid) ?? null;
+    }
+    async deleteByJid(jid) {
+        const existing = this.contacts.get(jid);
+        if (!existing)
+            return 0;
+        this.contacts.delete(jid);
+        if (existing.phoneNumber && this.phoneIndex.get(existing.phoneNumber) === jid) {
+            this.phoneIndex.delete(existing.phoneNumber);
+        }
+        return 1;
+    }
+    async clear() {
+        this.contacts.clear();
+        this.phoneIndex.clear();
+    }
+}

package/dist/esm/store/memory/device-list.store.js

@@ -0,0 +1,103 @@
+import { resolvePositive } from '../../util/coercion.js';
+import { createPeriodicCleanup, setBoundedMapEntry } from '../../util/collections.js';
+const DEFAULTS = Object.freeze({
+    ttlMs: 5 * 60 * 1000,
+    maxUsers: 16384
+});
+export class WaDeviceListMemoryStore {
+    constructor(ttlMs = DEFAULTS.ttlMs, options = {}) {
+        if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+            throw new Error('device-list ttlMs must be a positive finite number');
+        }
+        this.records = new Map();
+        this.altIndex = new Map();
+        this.ttlMs = ttlMs;
+        this.maxUsers = resolvePositive(options.maxUsers, DEFAULTS.maxUsers, 'WaDeviceListMemoryStoreOptions.maxUsers');
+        this.logger = options.logger;
+        this.capacityWarned = false;
+        this.cleanup = createPeriodicCleanup(ttlMs, () => {
+            void this.cleanupExpired(Date.now());
+        });
+    }
+    warnCapacity() {
+        if (this.capacityWarned || !this.logger)
+            return;
+        this.capacityWarned = true;
+        this.logger.warn('device list store at capacity, evicting oldest', {
+            max: this.maxUsers
+        });
+    }
+    async upsertUserDevicesBatch(snapshots) {
+        for (let index = 0; index < snapshots.length; index += 1) {
+            const snapshot = snapshots[index];
+            const previous = this.records.get(snapshot.userJid);
+            if (previous?.altUserJid && previous.altUserJid !== snapshot.altUserJid) {
+                this.altIndex.delete(previous.altUserJid);
+            }
+            setBoundedMapEntry(this.records, snapshot.userJid, {
+                ...snapshot,
+                expiresAtMs: snapshot.updatedAtMs + this.ttlMs
+            }, this.maxUsers, () => this.warnCapacity());
+            if (snapshot.altUserJid) {
+                this.altIndex.set(snapshot.altUserJid, snapshot.userJid);
+            }
+        }
+    }
+    async getUserDevicesBatch(userJids, nowMs = Date.now()) {
+        const snapshots = new Array(userJids.length);
+        for (let index = 0; index < userJids.length; index += 1) {
+            snapshots[index] = this.readLive(userJids[index], nowMs);
+        }
+        return snapshots;
+    }
+    async findByAnyUserJid(jid, nowMs = Date.now()) {
+        const direct = this.readLive(jid, nowMs);
+        if (direct)
+            return direct;
+        const primary = this.altIndex.get(jid);
+        if (!primary)
+            return null;
+        return this.readLive(primary, nowMs);
+    }
+    async deleteUserDevices(userJid) {
+        const record = this.records.get(userJid);
+        if (!record)
+            return 0;
+        if (record.altUserJid)
+            this.altIndex.delete(record.altUserJid);
+        this.records.delete(userJid);
+        return 1;
+    }
+    async cleanupExpired(nowMs) {
+        let removed = 0;
+        for (const [userJid, record] of this.records) {
+            if (record.expiresAtMs > nowMs)
+                continue;
+            if (record.altUserJid)
+                this.altIndex.delete(record.altUserJid);
+            this.records.delete(userJid);
+            removed += 1;
+        }
+        return removed;
+    }
+    async clear() {
+        this.records.clear();
+        this.altIndex.clear();
+    }
+    async destroy() {
+        this.cleanup.destroy();
+        await this.clear();
+    }
+    readLive(userJid, nowMs) {
+        const record = this.records.get(userJid);
+        if (!record)
+            return null;
+        if (record.expiresAtMs <= nowMs) {
+            if (record.altUserJid)
+                this.altIndex.delete(record.altUserJid);
+            this.records.delete(userJid);
+            return null;
+        }
+        return record;
+    }
+}

package/dist/esm/store/{providers/memory/participants.store.js → memory/group-metadata.store.js}

@@ -1,29 +1,38 @@
-import { resolvePositive } from '../../../util/coercion.js';
-import { resolveCleanupIntervalMs, setBoundedMapEntry } from '../../../util/collections.js';
+import { resolvePositive } from '../../util/coercion.js';
+import { createPeriodicCleanup, setBoundedMapEntry } from '../../util/collections.js';
 const DEFAULTS = Object.freeze({
     ttlMs: 5 * 60 * 1000,
     maxGroups: 4096
 });
-export class WaParticipantsMemoryStore {
+export class WaGroupMetadataMemoryStore {
     constructor(ttlMs = DEFAULTS.ttlMs, options = {}) {
         if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
-            throw new Error('participants ttlMs must be a positive finite number');
+            throw new Error('groupMetadata ttlMs must be a positive finite number');
         }
         this.records = new Map();
         this.ttlMs = ttlMs;
-        this.maxGroups = resolvePositive(options.maxGroups, DEFAULTS.maxGroups, 'WaParticipantsMemoryStoreOptions.maxGroups');
-        this.cleanupTimer = setInterval(() => {
+        this.maxGroups = resolvePositive(options.maxGroups, DEFAULTS.maxGroups, 'WaGroupMetadataMemoryStoreOptions.maxGroups');
+        this.logger = options.logger;
+        this.capacityWarned = false;
+        this.cleanup = createPeriodicCleanup(ttlMs, () => {
             void this.cleanupExpired(Date.now());
-        }, resolveCleanupIntervalMs(ttlMs));
-        this.cleanupTimer.unref();
+        });
     }
-    async upsertGroupParticipants(snapshot) {
+    warnCapacity() {
+        if (this.capacityWarned || !this.logger)
+            return;
+        this.capacityWarned = true;
+        this.logger.warn('group metadata store at capacity, evicting oldest', {
+            max: this.maxGroups
+        });
+    }
+    async upsertGroupMetadata(snapshot) {
         setBoundedMapEntry(this.records, snapshot.groupJid, {
             ...snapshot,
             expiresAtMs: snapshot.updatedAtMs + this.ttlMs
-        }, this.maxGroups);
+        }, this.maxGroups, () => this.warnCapacity());
     }
-    async getGroupParticipants(groupJid, nowMs = Date.now()) {
+    async getGroupMetadata(groupJid, nowMs = Date.now()) {
         const record = this.records.get(groupJid);
         if (!record) {
             return null;
@@ -34,7 +43,7 @@ export class WaParticipantsMemoryStore {
         }
         return record;
     }
-    async deleteGroupParticipants(groupJid) {
+    async deleteGroupMetadata(groupJid) {
         return this.records.delete(groupJid) ? 1 : 0;
     }
     async cleanupExpired(nowMs) {
@@ -51,7 +60,7 @@ export class WaParticipantsMemoryStore {
         this.records.clear();
     }
     async destroy() {
-        clearInterval(this.cleanupTimer);
+        this.cleanup.destroy();
         await this.clear();
     }
 }

package/dist/esm/store/{providers/memory → memory}/identity.store.js

@@ -1,6 +1,6 @@
-import { signalAddressKey } from '../../../protocol/jid.js';
-import { resolvePositive } from '../../../util/coercion.js';
-import { setBoundedMapEntry } from '../../../util/collections.js';
+import { signalAddressKey } from '../../protocol/jid.js';
+import { resolvePositive } from '../../util/coercion.js';
+import { setBoundedMapEntry } from '../../util/collections.js';
 const DEFAULT_MAX_REMOTE_IDENTITIES = 8192;
 export class WaIdentityMemoryStore {
     constructor(options = {}) {