zapo-js 0.2.0 → 1.0.0

package/dist/types/signal/session/SignalRatchet.d.ts

@@ -8,11 +8,10 @@ export interface DecryptOutcome {
         readonly usedPreKey: number | null;
     } | null;
 }
-export declare function splitMsgKey(index: number, bytes: Uint8Array): SignalMessageKey;
-export declare function deriveMsgKey(index: number, chainKey: Uint8Array): Promise<{
+export declare function deriveMsgKey(index: number, chainKey: Uint8Array): {
     readonly nextChainKey: Uint8Array;
     readonly messageKey: SignalMessageKey;
-}>;
+};
 export declare function selectMessageKey(chain: SignalRecvChain, targetCounter: number): Promise<{
     readonly messageKey: SignalMessageKey;
     readonly updatedChain: SignalRecvChain;

package/dist/types/signal/session/SignalSerializer.d.ts

@@ -1,6 +1,7 @@
 import type { ParsedPreKeySignalMessage, ParsedSignalMessage, PreKeyRecord, SignedPreKeyRecord } from '../types';
+import type { WaPreKeyStore } from '../../store/contracts/pre-key.store';
 import type { WaSignalStore } from '../../store/contracts/signal.store';
 export declare function deserializeMsg(versionContentMac: Uint8Array): ParsedSignalMessage;
 export declare function deserializePkMsg(versionContent: Uint8Array): ParsedPreKeySignalMessage;
 export declare function requireSignedPreKey(store: WaSignalStore, id: number): Promise<SignedPreKeyRecord>;
-export declare function requirePreKey(store: WaSignalStore, id: number): Promise<PreKeyRecord>;
+export declare function requirePreKey(store: WaPreKeyStore, id: number): Promise<PreKeyRecord>;

package/dist/types/signal/session/SignalSession.d.ts

@@ -10,7 +10,6 @@ interface IncomingRatchetKeys {
     readonly ratchet: SignalSerializedKeyPair;
 }
 export declare function snapshotToRecord(snapshot: SignalSessionSnapshot): SignalSessionRecord;
-export declare function detachSession(session: SignalSessionRecord): SignalSessionSnapshot;
 export declare function findMatchingSession(session: SignalSessionRecord | null, sessionBaseKey: Uint8Array): SignalSessionRecord | null;
 export declare function requireLocalIdentity(store: WaSignalStore): Promise<LocalIdentityContext>;
 export declare function initiateSessionOutgoing(local: LocalIdentityContext, remoteBundle: {

package/dist/types/signal/session/encoding.d.ts

@@ -0,0 +1,28 @@
+import { type Proto } from '../..';
+import type { SignalMessageKey, SignalRecvChain, SignalSessionRecord, SignalSessionSnapshot } from '../types';
+export interface SignalSessionRow extends Record<string, unknown> {
+    readonly user: unknown;
+    readonly server: unknown;
+    readonly device: unknown;
+    readonly record: unknown;
+}
+export interface SignalIdentityRow extends Record<string, unknown> {
+    readonly identity_key: unknown;
+}
+export declare function encodeSignalSessionSnapshot(session: SignalSessionSnapshot): Proto.ISessionStructure;
+export declare function encodeSignalRecvChain(chain: SignalRecvChain): Proto.SessionStructure.IChain;
+export declare function decodeSignalMessageKey(messageKey: Proto.SessionStructure.Chain.IMessageKey, field: string): SignalMessageKey;
+export declare function decodeSignalRecvChain(chain: Proto.SessionStructure.IChain, field: string): SignalRecvChain;
+export declare function decodeSignalSessionSnapshot(session: Proto.ISessionStructure, field: string): SignalSessionSnapshot;
+/**
+ * Serializes a {@link SignalSessionRecord} (current + previous sessions) into
+ * the Signal `RecordStructure` protobuf encoding used by the session stores.
+ */
+export declare function encodeSignalSessionRecord(record: SignalSessionRecord): Uint8Array;
+/**
+ * Decodes a Signal `RecordStructure` payload (as stored on disk) back into a
+ * {@link SignalSessionRecord}. Throws when the current session is missing.
+ */
+export declare function decodeSignalSessionRecord(raw: unknown): SignalSessionRecord;
+/** Reads a stored remote identity blob into a Uint8Array (validates byte-shape). */
+export declare function decodeSignalRemoteIdentity(raw: unknown): Uint8Array;

package/dist/types/signal/session/resolver.d.ts

@@ -3,19 +3,35 @@ import type { SignalIdentitySyncApi } from '../api/SignalIdentitySyncApi';
 import type { SignalSessionSyncApi } from '../api/SignalSessionSyncApi';
 import type { SignalProtocol } from '../session/SignalProtocol';
 import type { SignalAddress, SignalSessionRecord } from '../types';
-import type { WaSignalStore } from '../../store/contracts/signal.store';
+import type { WaIdentityStore } from '../../store/contracts/identity.store';
+import type { WaSessionStore } from '../../store/contracts/session.store';
 export interface SignalResolvedSessionTarget {
     readonly jid: string;
     readonly address: SignalAddress;
     readonly session: SignalSessionRecord;
 }
+/**
+ * Resolves Signal sessions for one or more JIDs, fetching missing prekey
+ * bundles, enforcing identity continuity, and deduplicating concurrent
+ * fetches for the same address.
+ */
 export type SignalSessionResolver = {
+    /**
+     * Ensures a session exists for `address` (fetching the prekey bundle if
+     * needed). `reasonIdentity` triggers a remote identity refresh first.
+     */
     ensureSession(address: SignalAddress, jid: string, expectedIdentity?: Uint8Array, reasonIdentity?: boolean): Promise<void>;
+    /**
+     * Batched session resolver – issues a single key-bundle fetch for all
+     * missing JIDs. Returns the resolved targets that now have a session.
+     */
     ensureSessionsBatch(targetJids: readonly string[], expectedIdentityByJid?: ReadonlyMap<string, Uint8Array>): Promise<readonly SignalResolvedSessionTarget[]>;
 };
+/** Builds a {@link SignalSessionResolver} backed by the given Signal APIs and stores. */
 export declare function createSignalSessionResolver(options: {
     readonly signalProtocol: SignalProtocol;
-    readonly signalStore: WaSignalStore;
+    readonly sessionStore: WaSessionStore;
+    readonly identityStore: WaIdentityStore;
     readonly signalIdentitySync: SignalIdentitySyncApi;
     readonly signalSessionSync: SignalSessionSyncApi;
     readonly logger: Logger;

package/dist/types/signal/types.d.ts

@@ -1,4 +1,5 @@
 import type { SignalKeyPair } from '../crypto/curves/types';
+import type { Proto } from '..';
 export interface RegistrationInfo {
     readonly registrationId: number;
     readonly identityKeyPair: SignalKeyPair;
@@ -37,8 +38,14 @@ export interface SignalRecvChain {
     readonly ratchetPubKey: Uint8Array;
     readonly nextMsgIndex: number;
     readonly chainKey: Uint8Array;
-    readonly unusedMsgKeys: readonly SignalMessageKey[];
-}
+    readonly unusedMsgKeys: readonly Proto.SessionStructure.Chain.IMessageKey[];
+}
+/**
+ * Raw protobuf recv chain kept as-is to avoid eager decode.
+ * Use {@link decodeSignalRecvChain} only for the chain that
+ * actually needs to be read/modified.
+ */
+export type RawSignalRecvChain = Proto.SessionStructure.IChain;
 export interface SignalSendChain {
     readonly ratchetKey: SignalSerializedKeyPair;
     readonly nextMsgIndex: number;
@@ -54,14 +61,19 @@ export interface SignalSessionSnapshot {
     readonly remote: SignalPeer;
     readonly rootKey: Uint8Array;
     readonly sendChain: SignalSendChain;
-    readonly recvChains: readonly SignalRecvChain[];
+    readonly recvChains: readonly RawSignalRecvChain[];
     readonly initialExchangeInfo: SignalInitialExchangeInfo | null;
     readonly prevSendChainHighestIndex: number;
     readonly aliceBaseKey: Uint8Array | null;
 }
 export interface SignalSessionRecord extends SignalSessionSnapshot {
-    readonly prevSessions: readonly SignalSessionSnapshot[];
+    readonly prevSessions: readonly RawSignalSessionSnapshot[];
 }
+/**
+ * Raw protobuf session snapshot kept as-is to avoid eager decode.
+ * Only decoded on demand in rare fallback paths (session mismatch).
+ */
+export type RawSignalSessionSnapshot = Proto.ISessionStructure;
 export interface SignalPreKeyBundle {
     readonly regId: number;
     readonly identity: Uint8Array;

package/dist/types/store/cache/identity.cache.d.ts

@@ -0,0 +1,15 @@
+import type { WaIdentityStore } from '../contracts/identity.store';
+import type { WithDestroyLifecycle } from '../types';
+/**
+ * Read-through / write-through in-process cache for a persistent remote
+ * identity backend. Reuses {@link WaIdentityMemoryStore} as the bounded-LRU
+ * L1. Remote identities are read alongside sessions on the send path (the
+ * identity-mismatch guard), so caching them complements
+ * {@link withSessionCache}.
+ *
+ * The identity store has no per-key delete: identities are overwritten on
+ * re-establishment, so a peer's key change propagates through the
+ * write-through `setRemoteIdentity`. See {@link withSessionCache} for the
+ * shared coherence model and the single-writer-per-session assumption.
+ */
+export declare function withIdentityCache(backend: WaIdentityStore, maxEntries?: number): WithDestroyLifecycle<WaIdentityStore>;

package/dist/types/store/cache/privacy-token.cache.d.ts

@@ -0,0 +1,15 @@
+import type { WaPrivacyTokenStore } from '../contracts/privacy-token.store';
+import type { WithDestroyLifecycle } from '../types';
+/**
+ * Read-through cache for a persistent privacy-token backend. Reuses
+ * {@link WaPrivacyTokenMemoryStore} as the bounded-LRU L1.
+ *
+ * Unlike the signal caches this is **invalidate-on-write, not
+ * write-through**: `upsert` merges partial fields into the existing row on
+ * the backend, so caching the partial incoming record would diverge from the
+ * backend's merged result. Instead each upsert drops the L1 entry and the
+ * next read re-populates from the merged backend truth. See
+ * {@link withSessionCache} for the shared coherence model and the
+ * single-writer-per-session assumption.
+ */
+export declare function withPrivacyTokenCache(backend: WaPrivacyTokenStore, maxEntries?: number): WithDestroyLifecycle<WaPrivacyTokenStore>;

package/dist/types/store/cache/sender-key.cache.d.ts

@@ -0,0 +1,18 @@
+import type { WaSenderKeyStore } from '../contracts/sender-key.store';
+import type { WithDestroyLifecycle } from '../types';
+/**
+ * Read-through / write-through in-process cache for a persistent sender-key
+ * backend. Reuses {@link SenderKeyMemoryStore} as the bounded-LRU L1 so the
+ * per-(group, sender) lookups repeated across a group fan-out skip the
+ * backend round-trip.
+ *
+ * Only the point reads are cached. `getGroupSenderKeyList` returns the
+ * *complete* set for a group, which a partial point cache would under-report,
+ * so it goes straight to the backend. Upserts replace the whole record (no
+ * merge), so they are write-through; the sweep deletes
+ * (`deleteDeviceSenderKey`/`markForgetSenderKey`) run on the backend for the
+ * authoritative count and then invalidate the matching L1 entries via the
+ * memory store's own sweep. See {@link withSessionCache} for the shared
+ * coherence model and the single-writer-per-session assumption.
+ */
+export declare function withSenderKeyCache(backend: WaSenderKeyStore, maxEntries?: number): WithDestroyLifecycle<WaSenderKeyStore>;

package/dist/types/store/cache/session.cache.d.ts

@@ -0,0 +1,23 @@
+import type { WaSessionStore } from '../contracts/session.store';
+import type { WithDestroyLifecycle } from '../types';
+/**
+ * Read-through / write-through in-process cache for a persistent session
+ * backend. Reuses {@link WaSessionMemoryStore} as the bounded-LRU L1 so that
+ * repeated reads of the same peer on the send/recv path skip the backend
+ * round-trip.
+ *
+ * Coherence model (single process):
+ * - every mutation (set/delete/clear) writes the backend then the L1 in
+ *   lock-step and bumps a generation counter;
+ * - a read only populates the L1 when no mutation interleaved its backend
+ *   fetch (generation unchanged) and the slot is still empty, so an in-flight
+ *   read can never resurrect a concurrently deleted entry nor overwrite a
+ *   fresher concurrent write;
+ * - there is no negative caching: a miss always re-hits the backend.
+ *
+ * This cache assumes a single writer per `sessionId` (the library's
+ * connection model). Do not share one backend across processes for the same
+ * session with the cache enabled - there is no cross-process invalidation
+ * channel, so another process's writes would leave this L1 stale.
+ */
+export declare function withSessionCache(backend: WaSessionStore, maxEntries?: number): WithDestroyLifecycle<WaSessionStore>;

package/dist/types/store/contracts/contact.store.d.ts

@@ -9,7 +9,21 @@ export interface WaStoredContactRecord {
 export interface WaContactStore {
     upsert(record: WaStoredContactRecord): Promise<void>;
     upsertBatch(records: readonly WaStoredContactRecord[]): Promise<void>;
+    /**
+     * Lookup by jid. Contacts are persisted in LID-canonical form when both
+     * LID and PN are known (one row, `jid=<lid>` + `phoneNumber=<pn>`), so
+     * passing the PN form falls through to {@link getByPhoneNumber} when no
+     * row matches the PN jid directly. Callers do not need to know which
+     * form was used to write the row.
+     */
     getByJid(jid: string): Promise<WaStoredContactRecord | null>;
+    /**
+     * Lookup the contact whose `phoneNumber` field equals `pn`. Returns the
+     * LID-canonical row when the cross-reference is known, `null` otherwise.
+     * Used by {@link getByJid} for the PN-fallback path and exposed publicly
+     * for callers that already know the PN form.
+     */
+    getByPhoneNumber(pn: string): Promise<WaStoredContactRecord | null>;
     deleteByJid(jid: string): Promise<number>;
     clear(): Promise<void>;
 }

package/dist/types/store/contracts/device-list.store.d.ts

@@ -1,5 +1,12 @@
 export interface WaDeviceListSnapshot {
     readonly userJid: string;
+    /**
+     * The equivalent user-base JID in the other addressing form (PN if `userJid`
+     * is LID and vice versa). Populated by the lid usync resolver at send time.
+     * Used by retry-receipt eligibility to match the same user across
+     * `@s.whatsapp.net` and `@lid` forms.
+     */
+    readonly altUserJid?: string;
     readonly deviceJids: readonly string[];
     readonly updatedAtMs: number;
 }
@@ -7,6 +14,12 @@ export interface WaDeviceListStore {
     destroy?(): Promise<void>;
     upsertUserDevicesBatch(snapshots: readonly WaDeviceListSnapshot[]): Promise<void>;
     getUserDevicesBatch(userJids: readonly string[], nowMs?: number): Promise<readonly (WaDeviceListSnapshot | null)[]>;
+    /**
+     * Resolves a snapshot by either `userJid` (primary) or `altUserJid`
+     * (alternate addressing). Returns the snapshot whose user matches `jid` in
+     * either form, or `null` when unknown / expired.
+     */
+    findByAnyUserJid(jid: string, nowMs?: number): Promise<WaDeviceListSnapshot | null>;
     deleteUserDevices(userJid: string): Promise<number>;
     cleanupExpired(nowMs: number): Promise<number>;
     clear(): Promise<void>;

package/dist/types/store/contracts/group-metadata.store.d.ts

@@ -0,0 +1,14 @@
+export interface WaGroupMetadataSnapshot {
+    readonly groupJid: string;
+    readonly participants: readonly string[];
+    readonly ephemeral?: number;
+    readonly updatedAtMs: number;
+}
+export interface WaGroupMetadataStore {
+    destroy?(): Promise<void>;
+    upsertGroupMetadata(snapshot: WaGroupMetadataSnapshot): Promise<void>;
+    getGroupMetadata(groupJid: string, nowMs?: number): Promise<WaGroupMetadataSnapshot | null>;
+    deleteGroupMetadata(groupJid: string): Promise<number>;
+    cleanupExpired(nowMs: number): Promise<number>;
+    clear(): Promise<void>;
+}

package/dist/types/store/contracts/identity.store.d.ts

@@ -0,0 +1,11 @@
+import type { SignalAddress } from '../../signal/types';
+export interface WaIdentityStore {
+    getRemoteIdentity(address: SignalAddress): Promise<Uint8Array | null>;
+    getRemoteIdentities(addresses: readonly SignalAddress[]): Promise<readonly (Uint8Array | null)[]>;
+    setRemoteIdentity(address: SignalAddress, identityKey: Uint8Array): Promise<void>;
+    setRemoteIdentities(entries: readonly {
+        readonly address: SignalAddress;
+        readonly identityKey: Uint8Array;
+    }[]): Promise<void>;
+    clear(): Promise<void>;
+}

package/dist/types/store/contracts/message-secret.store.d.ts

@@ -0,0 +1,16 @@
+export interface WaMessageSecretEntry {
+    readonly secret: Uint8Array;
+    readonly senderJid: string;
+}
+export interface WaMessageSecretStore {
+    get(messageId: string, nowMs?: number): Promise<WaMessageSecretEntry | null>;
+    getBatch(messageIds: readonly string[], nowMs?: number): Promise<readonly (WaMessageSecretEntry | null)[]>;
+    set(messageId: string, entry: WaMessageSecretEntry): Promise<void>;
+    setBatch(entries: readonly {
+        readonly messageId: string;
+        readonly entry: WaMessageSecretEntry;
+    }[]): Promise<void>;
+    cleanupExpired(nowMs: number): Promise<number>;
+    clear(): Promise<void>;
+    destroy?(): Promise<void>;
+}

package/dist/types/store/contracts/message.store.d.ts

@@ -5,8 +5,6 @@ export interface WaStoredMessageRecord {
     readonly participantJid?: string;
     readonly fromMe: boolean;
     readonly timestampMs?: number;
-    readonly encType?: string;
-    readonly plaintext?: Uint8Array;
     readonly messageBytes?: Uint8Array;
 }
 export interface WaMessageStore {

package/dist/types/store/contracts/pre-key.store.d.ts

@@ -0,0 +1,13 @@
+import type { PreKeyRecord } from '../../signal/types';
+export interface WaPreKeyStore {
+    putPreKey(record: PreKeyRecord): Promise<void>;
+    getOrGenPreKeys(count: number, generator: (keyId: number) => PreKeyRecord | Promise<PreKeyRecord>): Promise<readonly PreKeyRecord[]>;
+    getPreKeyById(keyId: number): Promise<PreKeyRecord | null>;
+    getPreKeysById(keyIds: readonly number[]): Promise<readonly (PreKeyRecord | null)[]>;
+    consumePreKeyById(keyId: number): Promise<PreKeyRecord | null>;
+    getOrGenSinglePreKey(generator: (keyId: number) => PreKeyRecord | Promise<PreKeyRecord>): Promise<PreKeyRecord>;
+    markKeyAsUploaded(keyId: number): Promise<void>;
+    setServerHasPreKeys(value: boolean): Promise<void>;
+    getServerHasPreKeys(): Promise<boolean>;
+    clear(): Promise<void>;
+}

package/dist/types/store/contracts/session.store.d.ts

@@ -0,0 +1,14 @@
+import type { SignalAddress, SignalSessionRecord } from '../../signal/types';
+export interface WaSessionStore {
+    hasSession(address: SignalAddress): Promise<boolean>;
+    hasSessions(addresses: readonly SignalAddress[]): Promise<readonly boolean[]>;
+    getSession(address: SignalAddress): Promise<SignalSessionRecord | null>;
+    getSessionsBatch(addresses: readonly SignalAddress[]): Promise<readonly (SignalSessionRecord | null)[]>;
+    setSession(address: SignalAddress, session: SignalSessionRecord): Promise<void>;
+    setSessionsBatch(entries: readonly {
+        readonly address: SignalAddress;
+        readonly session: SignalSessionRecord;
+    }[]): Promise<void>;
+    deleteSession(address: SignalAddress): Promise<void>;
+    clear(): Promise<void>;
+}

package/dist/types/store/contracts/signal.store.d.ts

@@ -1,10 +1,4 @@
-import type { PreKeyRecord, RegistrationInfo, SignalAddress, SignalSessionRecord, SignedPreKeyRecord } from '../../signal/types';
-export interface WaSignalMetaSnapshot {
-    readonly serverHasPreKeys: boolean;
-    readonly signedPreKeyRotationTs: number | null;
-    readonly registrationInfo: RegistrationInfo | null;
-    readonly signedPreKey: SignedPreKeyRecord | null;
-}
+import type { RegistrationInfo, SignedPreKeyRecord } from '../../signal/types';
 export interface WaSignalStore {
     getRegistrationInfo(): Promise<RegistrationInfo | null>;
     setRegistrationInfo(info: RegistrationInfo): Promise<void>;
@@ -13,32 +7,5 @@ export interface WaSignalStore {
     getSignedPreKeyById(keyId: number): Promise<SignedPreKeyRecord | null>;
     setSignedPreKeyRotationTs(value: number | null): Promise<void>;
     getSignedPreKeyRotationTs(): Promise<number | null>;
-    putPreKey(record: PreKeyRecord): Promise<void>;
-    getOrGenPreKeys(count: number, generator: (keyId: number) => PreKeyRecord | Promise<PreKeyRecord>): Promise<readonly PreKeyRecord[]>;
-    getPreKeyById(keyId: number): Promise<PreKeyRecord | null>;
-    getPreKeysById(keyIds: readonly number[]): Promise<readonly (PreKeyRecord | null)[]>;
-    consumePreKeyById(keyId: number): Promise<PreKeyRecord | null>;
-    getOrGenSinglePreKey(generator: (keyId: number) => PreKeyRecord | Promise<PreKeyRecord>): Promise<PreKeyRecord>;
-    markKeyAsUploaded(keyId: number): Promise<void>;
-    setServerHasPreKeys(value: boolean): Promise<void>;
-    getServerHasPreKeys(): Promise<boolean>;
-    getSignalMeta(): Promise<WaSignalMetaSnapshot>;
-    hasSession(address: SignalAddress): Promise<boolean>;
-    hasSessions(addresses: readonly SignalAddress[]): Promise<readonly boolean[]>;
-    getSession(address: SignalAddress): Promise<SignalSessionRecord | null>;
-    getSessionsBatch(addresses: readonly SignalAddress[]): Promise<readonly (SignalSessionRecord | null)[]>;
-    setSession(address: SignalAddress, session: SignalSessionRecord): Promise<void>;
-    setSessionsBatch(entries: readonly {
-        readonly address: SignalAddress;
-        readonly session: SignalSessionRecord;
-    }[]): Promise<void>;
-    deleteSession(address: SignalAddress): Promise<void>;
-    getRemoteIdentity(address: SignalAddress): Promise<Uint8Array | null>;
-    getRemoteIdentities(addresses: readonly SignalAddress[]): Promise<readonly (Uint8Array | null)[]>;
-    setRemoteIdentity(address: SignalAddress, identityKey: Uint8Array): Promise<void>;
-    setRemoteIdentities(entries: readonly {
-        readonly address: SignalAddress;
-        readonly identityKey: Uint8Array;
-    }[]): Promise<void>;
     clear(): Promise<void>;
 }

package/dist/types/store/createStore.d.ts

@@ -1,2 +1,54 @@
-import type { WaCreateStoreOptions, WaStore } from './types';
-export declare function createStore<B extends string>(options: WaCreateStoreOptions<B>): WaStore;
+import type { WaCreateStoreOptions, WaCreateStoreOptionsStrict, WaStore } from './types';
+/**
+ * Builds a {@link WaStore} from the configured providers/backends. Each call
+ * to `store.session(sessionId)` returns a cached, lock-wrapped per-domain
+ * store bundle for that session. Cache domains default to bounded memory
+ * with the TTLs in `options.memory.cacheTtlMs`.
+ *
+ * **Defaults policy:**
+ * - With `backends` empty (or absent), every domain falls back to memory
+ *   (mailbox domains to `'none'`). The session lives only in memory and the
+ *   device re-pairs on every restart.
+ * - With `backends` set, **every persistence domain must be assigned
+ *   explicitly** in `providers` (auth/signal/preKey/session/identity/
+ *   senderKey/appState/privacyToken/messages/threads/contacts). The factory
+ *   throws listing the missing keys. Pass `'memory'` to keep the in-tree
+ *   memory provider for that domain, `'none'` to skip it, or the backend
+ *   name to persist. Cache domains (retry/groupMetadata/deviceList/
+ *   messageSecret) stay opt-in and default to memory - they are small,
+ *   hot, and cheap to rebuild.
+ *
+ * @example
+ * ```ts
+ * // Persistent setup with @zapo-js/store-sqlite (recommended for production)
+ * import { createSqliteStore } from '@zapo-js/store-sqlite'
+ * import { createStore } from '..'
+ *
+ * const store = createStore({
+ *     backends: { sqlite: createSqliteStore({ path: '.auth/state.sqlite' }) },
+ *     providers: {
+ *         auth: 'sqlite',
+ *         signal: 'sqlite',
+ *         preKey: 'sqlite',
+ *         session: 'sqlite',
+ *         identity: 'sqlite',
+ *         senderKey: 'sqlite',
+ *         appState: 'sqlite',
+ *         privacyToken: 'sqlite',
+ *         messages: 'sqlite',   // 'none' to skip the message archive
+ *         threads: 'sqlite',    // 'none' to skip
+ *         contacts: 'sqlite'    // 'none' to skip
+ *     }
+ *     // cacheProviders omitted - retry/groupMetadata/deviceList/
+ *     // messageSecret default to memory
+ * })
+ *
+ * // Memory-only (tests / ephemeral sessions - credentials lost on restart)
+ * const memStore = createStore({})
+ * ```
+ */
+export declare function createStore(options?: Omit<WaCreateStoreOptions<never>, 'backends' | 'providers'> & {
+    readonly backends?: undefined;
+    readonly providers?: undefined;
+}): WaStore;
+export declare function createStore<B extends string>(options: WaCreateStoreOptionsStrict<B>): WaStore;

package/dist/types/store/index.d.ts

@@ -1,23 +1,32 @@
-export type { WaCreateStoreOptions, WaStore, WaStoreBackend, WaCacheDomain, WaStoreDomain, WaStoreMemoryLimitSelection, WaStoreSession } from './types';
+export type { WaCreateStoreOptions, WaCreateStoreOptionsStrict, WaStore, WaStoreBackend, WaCacheDomain, WaStoreDomain, WaStoreMemoryLimitSelection, WaStoreSession } from './types';
 export { createStore } from './createStore';
 export type { WaAuthStore } from './contracts/auth.store';
 export type { WaContactStore, WaStoredContactRecord } from './contracts/contact.store';
 export type { WaDeviceListSnapshot, WaDeviceListStore } from './contracts/device-list.store';
+export type { WaMessageSecretEntry, WaMessageSecretStore } from './contracts/message-secret.store';
 export type { WaMessageStore, WaStoredMessageRecord } from './contracts/message.store';
-export type { WaParticipantsSnapshot, WaParticipantsStore } from './contracts/participants.store';
+export type { WaGroupMetadataSnapshot, WaGroupMetadataStore } from './contracts/group-metadata.store';
 export type { WaAppStateCollectionStateUpdate, WaAppStateCollectionStoreState, WaAppStateStore } from './contracts/appstate.store';
+export type { WaIdentityStore } from './contracts/identity.store';
+export type { WaPreKeyStore } from './contracts/pre-key.store';
 export type { WaSenderKeyStore } from './contracts/sender-key.store';
-export type { WaSignalMetaSnapshot, WaSignalStore } from './contracts/signal.store';
+export type { WaSessionStore } from './contracts/session.store';
+export type { WaSignalStore } from './contracts/signal.store';
 export type { WaRetryStore } from './contracts/retry.store';
 export type { WaStoredThreadRecord, WaThreadStore } from './contracts/thread.store';
 export type { WaPrivacyTokenStore, WaStoredPrivacyTokenRecord } from './contracts/privacy-token.store';
-export { WaAppStateMemoryStore } from './providers/memory/appstate.store';
-export { WaSignalMemoryStore } from './providers/memory/signal.store';
-export { SenderKeyMemoryStore } from './providers/memory/sender-key.store';
-export { WaRetryMemoryStore } from './providers/memory/retry.store';
-export { WaParticipantsMemoryStore } from './providers/memory/participants.store';
-export { WaDeviceListMemoryStore } from './providers/memory/device-list.store';
-export { WaContactMemoryStore } from './providers/memory/contact.store';
-export { WaMessageMemoryStore } from './providers/memory/message.store';
-export { WaThreadMemoryStore } from './providers/memory/thread.store';
-export { WaPrivacyTokenMemoryStore } from './providers/memory/privacy-token.store';
+export { WaAppStateMemoryStore } from './memory/appstate.store';
+export { WaAuthMemoryStore } from './memory/auth.store';
+export { WaSignalMemoryStore } from './memory/signal.store';
+export { WaPreKeyMemoryStore } from './memory/pre-key.store';
+export { WaSessionMemoryStore } from './memory/session.store';
+export { WaIdentityMemoryStore } from './memory/identity.store';
+export { SenderKeyMemoryStore } from './memory/sender-key.store';
+export { WaRetryMemoryStore } from './memory/retry.store';
+export { WaGroupMetadataMemoryStore } from './memory/group-metadata.store';
+export { WaDeviceListMemoryStore } from './memory/device-list.store';
+export { WaContactMemoryStore } from './memory/contact.store';
+export { WaMessageSecretMemoryStore } from './memory/message-secret.store';
+export { WaMessageMemoryStore } from './memory/message.store';
+export { WaThreadMemoryStore } from './memory/thread.store';
+export { WaPrivacyTokenMemoryStore } from './memory/privacy-token.store';

package/dist/types/store/locks/group-metadata.lock.d.ts

@@ -0,0 +1,2 @@
+import type { WaGroupMetadataStore } from '../contracts/group-metadata.store';
+export declare function withGroupMetadataLock(store: WaGroupMetadataStore): WaGroupMetadataStore;

package/dist/types/store/locks/identity.lock.d.ts

@@ -0,0 +1,3 @@
+import type { WaIdentityStore } from '../contracts/identity.store';
+import type { WithDestroyLifecycle } from '../types';
+export declare function withIdentityLock(store: WaIdentityStore): WithDestroyLifecycle<WaIdentityStore>;

package/dist/types/store/locks/message-secret.lock.d.ts

@@ -0,0 +1,3 @@
+import type { WaMessageSecretStore } from '../contracts/message-secret.store';
+import type { WithDestroyLifecycle } from '../types';
+export declare function withMessageSecretLock(store: WaMessageSecretStore): WithDestroyLifecycle<WaMessageSecretStore>;

package/dist/types/store/locks/pre-key.lock.d.ts

@@ -0,0 +1,3 @@
+import type { WaPreKeyStore } from '../contracts/pre-key.store';
+import type { WithDestroyLifecycle } from '../types';
+export declare function withPreKeyLock(store: WaPreKeyStore): WithDestroyLifecycle<WaPreKeyStore>;

package/dist/types/store/locks/session.lock.d.ts

@@ -0,0 +1,3 @@
+import type { WaSessionStore } from '../contracts/session.store';
+import type { WithDestroyLifecycle } from '../types';
+export declare function withSessionLock(store: WaSessionStore): WithDestroyLifecycle<WaSessionStore>;

package/dist/types/store/{providers/memory → memory}/appstate.store.d.ts

@@ -1,5 +1,5 @@
-import type { AppStateCollectionName, WaAppStateStoreData, WaAppStateSyncKey } from '../../../appstate/types';
-import type { WaAppStateCollectionStateUpdate, WaAppStateCollectionStoreState, WaAppStateStore } from '../../contracts/appstate.store';
+import type { AppStateCollectionName, WaAppStateStoreData, WaAppStateSyncKey } from '../../appstate/types';
+import type { WaAppStateCollectionStateUpdate, WaAppStateCollectionStoreState, WaAppStateStore } from '../contracts/appstate.store';
 export interface WaAppStateMemoryStoreOptions {
     readonly maxSyncKeys?: number;
     readonly maxCollectionEntries?: number;

package/dist/types/store/memory/auth.store.d.ts

@@ -0,0 +1,18 @@
+import type { WaAuthCredentials } from '../../auth/types';
+import type { WaAuthStore } from '../contracts/auth.store';
+/**
+ * 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 declare class WaAuthMemoryStore implements WaAuthStore {
+    private credentials;
+    load(): Promise<WaAuthCredentials | null>;
+    save(credentials: WaAuthCredentials): Promise<void>;
+    clear(): Promise<void>;
+}

package/dist/types/store/{providers/memory → memory}/contact.store.d.ts

@@ -1,14 +1,19 @@
-import type { WaContactStore as Contract, WaStoredContactRecord } from '../../contracts/contact.store';
+import type { WaContactStore as Contract, WaStoredContactRecord } from '../contracts/contact.store';
 export interface WaContactMemoryStoreOptions {
     readonly maxContacts?: number;
 }
 export declare class WaContactMemoryStore implements Contract {
     private readonly contacts;
+    /** Secondary index: phone_number -> primary jid (typically the LID form). */
+    private readonly phoneIndex;
     private readonly maxContacts;
     constructor(options?: WaContactMemoryStoreOptions);
+    private writeRecord;
     upsert(record: WaStoredContactRecord): Promise<void>;
     upsertBatch(records: readonly WaStoredContactRecord[]): Promise<void>;
     getByJid(jid: string): Promise<WaStoredContactRecord | null>;
+    getByPhoneNumber(pn: string): Promise<WaStoredContactRecord | null>;
+    private getByPhoneNumberSync;
     deleteByJid(jid: string): Promise<number>;
     clear(): Promise<void>;
 }

package/dist/types/store/{providers/memory → memory}/device-list.store.d.ts

@@ -1,17 +1,30 @@
-import type { WaDeviceListSnapshot, WaDeviceListStore } from '../../contracts/device-list.store';
+import type { Logger } from '../../infra/log/types';
+import type { WaDeviceListSnapshot, WaDeviceListStore } from '../contracts/device-list.store';
 export interface WaDeviceListMemoryStoreOptions {
     readonly maxUsers?: number;
+    /**
+     * Logger for capacity-saturation warnings. Emits a single `warn` the
+     * first time the bounded map evicts an entry; subsequent evictions are
+     * silent to avoid spam.
+     */
+    readonly logger?: Logger;
 }
 export declare class WaDeviceListMemoryStore implements WaDeviceListStore {
     private readonly records;
+    private readonly altIndex;
     private readonly ttlMs;
     private readonly maxUsers;
-    private readonly cleanupTimer;
+    private readonly cleanup;
+    private readonly logger;
+    private capacityWarned;
     constructor(ttlMs?: number, options?: WaDeviceListMemoryStoreOptions);
+    private warnCapacity;
     upsertUserDevicesBatch(snapshots: readonly WaDeviceListSnapshot[]): Promise<void>;
     getUserDevicesBatch(userJids: readonly string[], nowMs?: number): Promise<readonly (WaDeviceListSnapshot | null)[]>;
+    findByAnyUserJid(jid: string, nowMs?: number): Promise<WaDeviceListSnapshot | null>;
     deleteUserDevices(userJid: string): Promise<number>;
     cleanupExpired(nowMs: number): Promise<number>;
     clear(): Promise<void>;
     destroy(): Promise<void>;
+    private readLive;
 }