zapo-js 0.2.0 → 1.0.0

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

@@ -0,0 +1,27 @@
+import type { Logger } from '../../infra/log/types';
+import type { WaGroupMetadataSnapshot, WaGroupMetadataStore } from '../contracts/group-metadata.store';
+export interface WaGroupMetadataMemoryStoreOptions {
+    readonly maxGroups?: 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 WaGroupMetadataMemoryStore implements WaGroupMetadataStore {
+    private readonly records;
+    private readonly ttlMs;
+    private readonly maxGroups;
+    private readonly cleanup;
+    private readonly logger;
+    private capacityWarned;
+    constructor(ttlMs?: number, options?: WaGroupMetadataMemoryStoreOptions);
+    private warnCapacity;
+    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>;
+    destroy(): Promise<void>;
+}

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

@@ -0,0 +1,18 @@
+import type { SignalAddress } from '../../signal/types';
+import type { WaIdentityStore as WaIdentityStoreContract } from '../contracts/identity.store';
+export interface WaIdentityMemoryStoreOptions {
+    readonly maxRemoteIdentities?: number;
+}
+export declare class WaIdentityMemoryStore implements WaIdentityStoreContract {
+    private readonly remoteIdentities;
+    private readonly maxRemoteIdentities;
+    constructor(options?: WaIdentityMemoryStoreOptions);
+    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/memory/message-secret.store.d.ts

@@ -0,0 +1,31 @@
+import type { Logger } from '../../infra/log/types';
+import type { WaMessageSecretEntry, WaMessageSecretStore } from '../contracts/message-secret.store';
+export interface WaMessageSecretMemoryStoreOptions {
+    readonly maxSecrets?: 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 WaMessageSecretMemoryStore implements WaMessageSecretStore {
+    private readonly secrets;
+    private readonly ttlMs;
+    private readonly maxSecrets;
+    private readonly cleanup;
+    private readonly logger;
+    private capacityWarned;
+    constructor(ttlMs?: number, options?: WaMessageSecretMemoryStoreOptions);
+    private warnCapacity;
+    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/{providers/memory → memory}/message.store.d.ts

@@ -1,4 +1,4 @@
-import type { WaMessageStore as Contract, WaStoredMessageRecord } from '../../contracts/message.store';
+import type { WaMessageStore as Contract, WaStoredMessageRecord } from '../contracts/message.store';
 export interface WaMessageMemoryStoreOptions {
     readonly maxMessages?: number;
 }

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

@@ -0,0 +1,23 @@
+import type { PreKeyRecord } from '../../signal/types';
+import type { WaPreKeyStore as WaPreKeyStoreContract } from '../contracts/pre-key.store';
+export interface WaPreKeyMemoryStoreOptions {
+    readonly maxPreKeys?: number;
+}
+export declare class WaPreKeyMemoryStore implements WaPreKeyStoreContract {
+    private readonly preKeys;
+    private readonly uploadedPreKeys;
+    private serverHasPreKeys;
+    private nextPreKeyId;
+    private readonly maxPreKeys;
+    constructor(options?: WaPreKeyMemoryStoreOptions);
+    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/{providers/memory → memory}/privacy-token.store.d.ts

@@ -1,4 +1,4 @@
-import type { WaPrivacyTokenStore, WaStoredPrivacyTokenRecord } from '../../contracts/privacy-token.store';
+import type { WaPrivacyTokenStore, WaStoredPrivacyTokenRecord } from '../contracts/privacy-token.store';
 export declare class WaPrivacyTokenMemoryStore implements WaPrivacyTokenStore {
     private readonly records;
     private readonly maxEntries;

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

@@ -1,12 +1,31 @@
-import type { WaRetryOutboundMessageRecord, WaRetryOutboundState } from '../../../retry/types';
-import type { WaRetryStore } from '../../contracts/retry.store';
+import type { Logger } from '../../infra/log/types';
+import type { WaRetryOutboundMessageRecord, WaRetryOutboundState } from '../../retry/types';
+import type { WaRetryStore } from '../contracts/retry.store';
+export interface WaRetryMemoryStoreOptions {
+    readonly maxOutboundMessages?: number;
+    readonly maxInboundCounters?: number;
+    /**
+     * Logger for capacity-saturation warnings. Emits a single `warn` the
+     * first time either bounded map evicts an entry (signals you've hit
+     * `maxOutboundMessages` / `maxInboundCounters`). Subsequent evictions
+     * are silent to avoid spam.
+     */
+    readonly logger?: Logger;
+}
 export declare class WaRetryMemoryStore implements WaRetryStore {
     private readonly outboundMessages;
     private readonly eligibleSets;
     private readonly inboundCounters;
     private readonly ttlMs;
-    private readonly cleanupTimer;
-    constructor(ttlMs?: number);
+    private readonly maxOutboundMessages;
+    private readonly maxInboundCounters;
+    private readonly cleanup;
+    private readonly logger;
+    private outboundCapacityWarned;
+    private inboundCapacityWarned;
+    constructor(ttlMs?: number, options?: WaRetryMemoryStoreOptions);
+    private warnOutboundCapacity;
+    private warnInboundCapacity;
     getTtlMs(): number;
     supportsRawReplayPayload(): boolean;
     getOutboundRequesterStatus(messageId: string, requesterDeviceJid: string): Promise<{

package/dist/types/store/{providers/memory → memory}/sender-key.store.d.ts

@@ -1,5 +1,5 @@
-import type { SenderKeyDistributionRecord, SenderKeyRecord, SignalAddress } from '../../../signal/types';
-import type { WaSenderKeyStore as WaSenderKeyStoreContract } from '../../contracts/sender-key.store';
+import type { SenderKeyDistributionRecord, SenderKeyRecord, SignalAddress } from '../../signal/types';
+import type { WaSenderKeyStore as WaSenderKeyStoreContract } from '../contracts/sender-key.store';
 export interface WaSenderKeyMemoryStoreOptions {
     readonly maxSenderKeys?: number;
     readonly maxSenderDistributions?: number;

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

@@ -0,0 +1,21 @@
+import type { SignalAddress, SignalSessionRecord } from '../../signal/types';
+import type { WaSessionStore as WaSessionStoreContract } from '../contracts/session.store';
+export interface WaSessionMemoryStoreOptions {
+    readonly maxSessions?: number;
+}
+export declare class WaSessionMemoryStore implements WaSessionStoreContract {
+    private readonly signalSessions;
+    private readonly maxSessions;
+    constructor(options?: WaSessionMemoryStoreOptions);
+    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/memory/signal.store.d.ts

@@ -0,0 +1,16 @@
+import type { RegistrationInfo, SignedPreKeyRecord } from '../../signal/types';
+import type { WaSignalStore as WaSignalStoreContract } from '../contracts/signal.store';
+export declare class WaSignalMemoryStore implements WaSignalStoreContract {
+    private registrationInfo;
+    private signedPreKey;
+    private signedPreKeyRotationTs;
+    constructor();
+    getRegistrationInfo(): Promise<RegistrationInfo | null>;
+    setRegistrationInfo(info: RegistrationInfo): Promise<void>;
+    getSignedPreKey(): Promise<SignedPreKeyRecord | null>;
+    setSignedPreKey(record: SignedPreKeyRecord): Promise<void>;
+    getSignedPreKeyById(keyId: number): Promise<SignedPreKeyRecord | null>;
+    setSignedPreKeyRotationTs(value: number | null): Promise<void>;
+    getSignedPreKeyRotationTs(): Promise<number | null>;
+    clear(): Promise<void>;
+}

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

@@ -1,4 +1,4 @@
-import type { WaStoredThreadRecord, WaThreadStore as Contract } from '../../contracts/thread.store';
+import type { WaThreadStore as Contract, WaStoredThreadRecord } from '../contracts/thread.store';
 export interface WaThreadMemoryStoreOptions {
     readonly maxThreads?: number;
 }

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

@@ -1,10 +1,14 @@
 import type { WaContactStore } from './contracts/contact.store';
 import type { WaDeviceListStore } from './contracts/device-list.store';
+import type { WaGroupMetadataStore } from './contracts/group-metadata.store';
+import type { WaMessageSecretStore } from './contracts/message-secret.store';
 import type { WaMessageStore } from './contracts/message.store';
-import type { WaParticipantsStore } from './contracts/participants.store';
+import type { WaRetryStore } from './contracts/retry.store';
 import type { WaThreadStore } from './contracts/thread.store';
+export declare const NOOP_MESSAGE_SECRET_STORE: WaMessageSecretStore;
 export declare const NOOP_MESSAGE_STORE: WaMessageStore;
 export declare const NOOP_THREAD_STORE: WaThreadStore;
 export declare const NOOP_CONTACT_STORE: WaContactStore;
-export declare const NOOP_PARTICIPANTS_STORE: WaParticipantsStore;
+export declare const NOOP_RETRY_STORE: WaRetryStore;
+export declare const NOOP_GROUP_METADATA_STORE: WaGroupMetadataStore;
 export declare const NOOP_DEVICE_LIST_STORE: WaDeviceListStore;

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

@@ -1,12 +1,17 @@
+import type { Logger } from '../infra/log/types';
 import type { WaAppStateStore } from './contracts/appstate.store';
 import type { WaAuthStore } from './contracts/auth.store';
 import type { WaContactStore } from './contracts/contact.store';
 import type { WaDeviceListStore } from './contracts/device-list.store';
+import type { WaGroupMetadataStore } from './contracts/group-metadata.store';
+import type { WaIdentityStore } from './contracts/identity.store';
+import type { WaMessageSecretStore } from './contracts/message-secret.store';
 import type { WaMessageStore } from './contracts/message.store';
-import type { WaParticipantsStore } from './contracts/participants.store';
+import type { WaPreKeyStore } from './contracts/pre-key.store';
 import type { WaPrivacyTokenStore } from './contracts/privacy-token.store';
 import type { WaRetryStore } from './contracts/retry.store';
 import type { WaSenderKeyStore } from './contracts/sender-key.store';
+import type { WaSessionStore } from './contracts/session.store';
 import type { WaSignalStore } from './contracts/signal.store';
 import type { WaThreadStore } from './contracts/thread.store';
 export type WithDestroyLifecycle<T> = T & {
@@ -15,12 +20,16 @@ export type WithDestroyLifecycle<T> = T & {
 export interface WaStoreSession {
     readonly auth: WaAuthStore;
     readonly signal: WaSignalStore;
+    readonly preKey: WaPreKeyStore;
+    readonly session: WaSessionStore;
+    readonly identity: WaIdentityStore;
     readonly senderKey: WaSenderKeyStore;
     readonly appState: WaAppStateStore;
     readonly retry: WaRetryStore;
-    readonly participants: WaParticipantsStore;
+    readonly groupMetadata: WaGroupMetadataStore;
     readonly deviceList: WaDeviceListStore;
     readonly messages: WaMessageStore;
+    readonly messageSecret: WaMessageSecretStore;
     readonly threads: WaThreadStore;
     readonly contacts: WaContactStore;
     readonly privacyToken: WaPrivacyTokenStore;
@@ -36,6 +45,9 @@ export interface WaStoreBackend {
     readonly stores: {
         readonly auth: (sessionId: string) => WaAuthStore;
         readonly signal: (sessionId: string) => WaSignalStore;
+        readonly preKey: (sessionId: string) => WaPreKeyStore;
+        readonly session: (sessionId: string) => WaSessionStore;
+        readonly identity: (sessionId: string) => WaIdentityStore;
         readonly senderKey: (sessionId: string) => WaSenderKeyStore;
         readonly appState: (sessionId: string) => WaAppStateStore;
         readonly messages: (sessionId: string) => WaMessageStore;
@@ -45,38 +57,287 @@ export interface WaStoreBackend {
     };
     readonly caches: {
         readonly retry: (sessionId: string) => WaRetryStore;
-        readonly participants: (sessionId: string) => WaParticipantsStore;
+        readonly groupMetadata: (sessionId: string) => WaGroupMetadataStore;
         readonly deviceList: (sessionId: string) => WaDeviceListStore;
+        readonly messageSecret: (sessionId: string) => WaMessageSecretStore;
     };
 }
 export type WaStoreDomain = keyof WaStoreBackend['stores'];
 export type WaCacheDomain = keyof WaStoreBackend['caches'];
 export interface WaCreateStoreOptions<B extends string = string> {
+    /**
+     * Named persistent backends (e.g. `{ sqlite: createSqliteStore(...) }`).
+     * Each key here is a backend id you can reference under {@link providers}
+     * and {@link cacheProviders}. The literal strings `'memory'` and `'none'`
+     * are reserved and don't need a backend entry.
+     */
     readonly backends?: Readonly<Record<B, WaStoreBackend>>;
+    /**
+     * Per-domain provider selection for the persistent (non-cache) stores.
+     * Every domain falls back to `'memory'` (or `'none'` for the mailbox
+     * domains) when omitted.
+     */
     readonly providers?: {
+        /**
+         * Holds the device's pairing credentials: noise key pair, signed
+         * identity, registration info, signed prekey, ADV secret, server
+         * static key, routing info, account metadata. **This is what proves
+         * "I am this paired device" to WhatsApp.** Lose it and the next
+         * connect has to re-pair from scratch (QR/link-code). Default:
+         * `'memory'` – fine for tests / one-shot scripts, but persist it
+         * (e.g. `@zapo-js/store-sqlite`) in production so the device
+         * survives a process restart.
+         */
         readonly auth?: B | 'memory';
+        /**
+         * Signal protocol identities and the meta row (`server_has_prekeys`,
+         * `next_prekey_id`, signed-prekey rotation timestamp). Splits with
+         * {@link session}/{@link identity}/{@link preKey} in backends that
+         * partition the Signal state; some backends collapse them. Default:
+         * `'memory'` – fine for short-lived sessions; persist it in
+         * production so re-keying / digest checks survive restarts.
+         */
         readonly signal?: B | 'memory';
+        /**
+         * Signal one-time prekey pool. The server hands these out to peers
+         * starting fresh sessions with you. Losing them forces fallback to
+         * the signed-prekey-only flow (slower / less forward-secret per
+         * session). Default: `'memory'`.
+         */
+        readonly preKey?: B | 'memory';
+        /**
+         * Signal sessions (the per-peer Double Ratchet state). Losing this
+         * forces a transparent re-handshake on the next message to/from that
+         * peer – your identity key doesn't change, so no "security code
+         * changed" notice fires on the peer. Default: `'memory'`.
+         */
+        readonly session?: B | 'memory';
+        /**
+         * Remote identity keys per peer device. The library compares the
+         * stored key against the server-reported one on every send to detect
+         * device-takeover (`identity mismatch`). Default: `'memory'`.
+         */
+        readonly identity?: B | 'memory';
+        /**
+         * Sender-key state for group encryption: your own outgoing sender
+         * key per group + incoming sender keys from other participants + the
+         * delivery bookkeeping. Losing it makes you re-distribute your
+         * sender key to every member on the next group send. Default:
+         * `'memory'`.
+         */
         readonly senderKey?: B | 'memory';
+        /**
+         * App-state sync keys + per-collection version/hash/index map
+         * (mute, archive, pin, contacts, labels, ...). This is what lets
+         * the lib emit `mutation` events and keep parity with the phone.
+         * Wiping it triggers a full re-sync on next connect (slow, lots of
+         * traffic). Default: `'memory'`.
+         */
         readonly appState?: B | 'memory';
+        /**
+         * Optional archive of every message you received/sent. Required if
+         * you want to call `client.message.send(..., { quote })` later for
+         * messages this device never had in RAM, or to look up message
+         * secrets for addon decryption after a restart. Default: `'none'`
+         * (no archive – events fire but aren't stored).
+         */
         readonly messages?: B | 'memory' | 'none';
+        /**
+         * Per-chat thread metadata (last message id/time, unread count,
+         * disappearing-mode setting). Used by some UIs to render a chat
+         * list; not required for messaging. Default: `'none'`.
+         */
         readonly threads?: B | 'memory' | 'none';
+        /**
+         * Contact book mirror (push names, phone numbers, business labels).
+         * Populated by app-state mutations and history sync. Not required
+         * for messaging but useful for display names without an extra
+         * profile fetch. Default: `'none'`.
+         */
         readonly contacts?: B | 'memory' | 'none';
+        /**
+         * Trusted-contact-token cache – short-lived tokens the lib issues
+         * to peers so they can verify that messages from you are authentic.
+         * Persisting avoids re-issuing on every reconnect (saves IQs).
+         * Default: `'memory'`.
+         */
         readonly privacyToken?: B | 'memory';
     };
+    /**
+     * Provider selection for the bounded cache domains – TTL-evicted state
+     * the library re-derives on demand if missing. All default to
+     * `'memory'`. Set a domain to `'none'` to disable that cache entirely
+     * (the lib will keep working but re-fetch / re-compute every time);
+     * point at a `B` backend when you want the cache to survive a process
+     * restart (typically only useful for `retry`).
+     */
     readonly cacheProviders?: {
-        readonly retry?: B | 'memory';
-        readonly participants?: B | 'memory' | 'none';
+        /**
+         * Outbound-message replay cache plus inbound retry-counters. When
+         * the peer sends a `<receipt type="retry">` asking for a re-send,
+         * the lib looks up the stored payload here and replays it without
+         * re-encrypting from scratch. Losing this means retry receipts that
+         * arrive after restart get dropped (peer falls back to a placeholder
+         * message). Default: `'memory'`.
+         */
+        readonly retry?: B | 'memory' | 'none';
+        /**
+         * Group metadata (subject, participants, settings) keyed by group
+         * JID. Populated by `client.group.queryGroupMetadata`/server pushes
+         * and consumed during fan-out so the library knows who to encrypt
+         * to. Disabling forces a metadata IQ on every group send – the
+         * server **rate-limits** this aggressively and active group accounts
+         * will get throttled (or temporarily blocked) without a cache.
+         * Default: `'memory'`.
+         */
+        readonly groupMetadata?: B | 'memory' | 'none';
+        /**
+         * Per-user device list (which `:device` JIDs each contact has online).
+         * Populated by usync queries; consumed on every send to pick the
+         * fan-out set. Disabling forces a usync round-trip per recipient on
+         * every send. Default: `'memory'`.
+         */
         readonly deviceList?: B | 'memory' | 'none';
+        /**
+         * Message-secret cache: maps `stanzaId → { senderJid, secret }` so
+         * addon decryption (poll votes, reactions, encrypted edits, ...) can
+         * find the parent message's 32-byte secret. Falls back to the
+         * `messages` store when set. Disable only if `messages` is persistent
+         * – otherwise addon auto-decrypt loses parents after restart.
+         * Default: `'memory'`.
+         */
+        readonly messageSecret?: B | 'memory' | 'none';
     };
+    /**
+     * Opt-in in-process read-through cache in front of a *persistent* backend
+     * for the hot signal domains. Each enabled domain wraps its backend store
+     * with a bounded-LRU L1 (the in-tree memory provider) so repeated reads of
+     * the same peer on the send/recv path skip the backend round-trip; writes
+     * stay write-through (or invalidate-on-write for `privacyToken`) so the
+     * backend remains authoritative.
+     *
+     * A domain flag is a no-op unless that domain resolves to a real backend
+     * in {@link providers} - caching a `'memory'`/`'none'` provider in front of
+     * itself buys nothing and is skipped.
+     *
+     * **Single-writer assumption:** the L1 is per-process and has no
+     * cross-process invalidation channel. Enable this only when a single
+     * process owns a given `sessionId`'s backend rows (the library's
+     * connection model). Do **not** enable it when multiple processes share
+     * one backend for the *same* session - another process's writes would
+     * leave this cache stale. Different sessions sharing one backend are fine.
+     * All flags default to `false`.
+     *
+     * Distinct from {@link cacheProviders}: that selects *where* the bounded
+     * cache domains live; this layers an in-memory read cache *in front of*
+     * the persistent domains.
+     *
+     * Only the four domains below are exposed. The other persistent domains
+     * are deliberately excluded, each for a verified reason:
+     * - `signal`: the per-send `getRegistrationInfo` read is already memoized
+     *   write-through inside the signal lock (`signal.lock.ts`), and the
+     *   remaining reads (`getSignedPreKey`/`getSignedPreKeyById`/rotation ts)
+     *   change only on the rare signed-prekey rotation and fire on inbound
+     *   session-init, not per message - a second cache would add nothing.
+     * - `appState`: the sync client already caches collection state for the
+     *   sync-context lifetime, the only scope where reads both repeat and stay
+     *   coherent. Across sync cycles the version is incremented and persisted,
+     *   so a persistent cache yields ~0 hits, and the version is sent on the
+     *   wire (server-authoritative) - a stale one forces a refetch loop.
+     * - `preKey`: one-time prekeys are read exactly once then consumed
+     *   (deleted) on the inbound path, so there is nothing to re-read; serving
+     *   a consumed prekey from a stale cache would reuse a one-time key and
+     *   break forward secrecy. There is no safe, useful read here.
+     * - `auth` is loaded once per connect and kept in memory; the mailbox
+     *   domains (`messages`/`threads`/`contacts`) are cold, large reads off
+     *   the crypto path with write-behind already; and the cache domains
+     *   (retry/groupMetadata/deviceList/messageSecret) default to in-process
+     *   memory already, so an L1 in front would be a cache over a cache.
+     */
+    readonly cacheLayer?: {
+        /** Cache Signal Double-Ratchet sessions (key→record). Write-through. */
+        readonly session?: boolean;
+        /** Cache remote identity keys (key→bytes). Write-through. */
+        readonly identity?: boolean;
+        /** Cache per-(group, sender) sender keys + distributions. Write-through. */
+        readonly senderKey?: boolean;
+        /** Cache trusted-contact tokens (jid→record). Invalidate-on-write. */
+        readonly privacyToken?: boolean;
+        /**
+         * Per-domain L1 entry caps (LRU eviction once exceeded). Defaults to
+         * the matching memory-provider default when unset.
+         */
+        readonly limits?: {
+            readonly session?: number;
+            readonly identity?: number;
+            readonly senderKey?: number;
+            readonly privacyToken?: number;
+        };
+    };
+    /**
+     * Memory-store tuning for the built-in `'memory'` providers. `limits`
+     * caps per-domain entry counts (LRU eviction once exceeded); `cacheTtlMs`
+     * controls how long cache entries live before being evicted. Tune these
+     * up for high-traffic accounts (lots of groups / contacts) and down on
+     * memory-constrained runtimes.
+     */
+    /**
+     * Logger for store-wide events: provider topology at boot, in-memory
+     * capacity saturation warnings, and downstream slow-operation warnings
+     * cascaded through backend factories. When unset, the store layer is
+     * silent. Backend packages (e.g. `@zapo-js/store-sqlite`,
+     * `@zapo-js/store-redis`) receive a `child({ scope: 'store', provider:
+     * '<name>' })` if they accept the same convention in their own factory.
+     */
+    readonly logger?: Logger;
     readonly memory?: {
         readonly limits?: WaStoreMemoryLimitSelection;
         readonly cacheTtlMs?: {
+            /**
+             * Retry tracker TTL – how long an outbound replay payload stays
+             * resendable after the original send. Default: 60 000 (1 min).
+             * Match this to your worst-case clock skew + network delay
+             * between you and slow peers; longer = more replay coverage at
+             * the cost of more memory.
+             */
             readonly retryMs?: number;
-            readonly participantsMs?: number;
+            /**
+             * Group metadata cache TTL – how long a cached subject/
+             * participant list is trusted before a fresh IQ is issued.
+             * Default: 300 000 (5 min). Shorter = fresher participant lists,
+             * more IQ traffic; longer = better throughput, slightly stale
+             * data between server-pushed group events.
+             */
+            readonly groupMetadataMs?: number;
+            /**
+             * Device list cache TTL – how long a cached per-user device set
+             * is reused before re-running usync. Default: 300 000 (5 min).
+             * Devices changing during this window are still picked up via
+             * the push-notification path; the TTL only affects the
+             * proactive refresh window.
+             */
             readonly deviceListMs?: number;
+            /**
+             * Message-secret TTL – how long the addon-decryption cache
+             * keeps a parent message's secret around. Default: 1 800 000
+             * (30 min). Cover the typical reaction/edit window for active
+             * chats; addons arriving after expiry fall back to the
+             * `messages` store lookup (or quietly fail when it's `'none'`).
+             */
+            readonly messageSecretMs?: number;
         };
     };
 }
+/**
+ * Strict overload shape for {@link createStore} when at least one backend
+ * is registered. Every persistence domain in `providers` is `Required` -
+ * the compiler refuses partial coverage and the IDE highlights the missing
+ * keys. Cache domains stay opt-in (default `'memory'`).
+ */
+export interface WaCreateStoreOptionsStrict<B extends string> extends Omit<WaCreateStoreOptions<B>, 'backends' | 'providers'> {
+    readonly backends: Readonly<Record<B, WaStoreBackend>>;
+    readonly providers: Required<NonNullable<WaCreateStoreOptions<B>['providers']>>;
+}
 export interface WaStoreMemoryLimitSelection {
     readonly appStateSyncKeys?: number;
     readonly appStateCollectionEntries?: number;
@@ -85,9 +346,12 @@ export interface WaStoreMemoryLimitSelection {
     readonly signalRemoteIdentities?: number;
     readonly senderKeys?: number;
     readonly senderDistributions?: number;
-    readonly participantsGroups?: number;
+    readonly groupMetadataGroups?: number;
     readonly deviceListUsers?: number;
     readonly messages?: number;
+    readonly messageSecrets?: number;
+    readonly retryOutboundMessages?: number;
+    readonly retryInboundCounters?: number;
     readonly threads?: number;
     readonly contacts?: number;
     readonly privacyTokens?: number;

package/dist/types/transport/WaComms.d.ts

@@ -2,6 +2,11 @@ import type { Logger } from '../infra/log/types';
 import type { WaCommsConfig, WaCommsState } from './types';
 type StanzaHandler = (payload: Uint8Array) => void | Promise<void>;
 type InflateFrame = (compressed: Uint8Array) => Uint8Array | Promise<Uint8Array>;
+/**
+ * Owns the WebSocket + Noise handshake lifecycle: opens the socket, drives
+ * the noise pairing/login exchange, persists routing-info/server-static
+ * updates, and delivers post-handshake binary frames to the caller.
+ */
 export declare class WaComms {
     private readonly config;
     private readonly logger;

package/dist/types/transport/WaWebSocket.d.ts

@@ -1,10 +1,16 @@
 import type { Logger } from '../infra/log/types';
 import type { SocketCloseInfo, SocketOpenInfo, WaSocketConfig, WaSocketHandlers } from './types';
+/**
+ * Thin wrapper around a `RawWebSocket` (or Node `ws` constructor) used by
+ * {@link WaComms}. Iterates the configured URL list on failure and applies a
+ * connect/idle timeout.
+ */
 export declare class WaWebSocket {
     private readonly config;
     private readonly socketUrls;
     private readonly logger;
     private readonly webSocketCtor;
+    private readonly customWebSocketCtor;
     private readonly socketRuntime;
     private readonly connectingSockets;
     private handlers;

package/dist/types/transport/binary/constants.d.ts

@@ -13,7 +13,13 @@ export declare const BINARY_8 = 252;
 export declare const BINARY_20 = 253;
 export declare const BINARY_32 = 254;
 export declare const NIBBLE_8 = 255;
-export declare const NIBBLE_ALPHABET: readonly string[];
-export declare const HEX_ALPHABET: readonly string[];
+export declare const JID_U_DOMAIN_TYPE_PN = 0;
+export declare const JID_U_DOMAIN_TYPE_LID = 1;
+export declare const JID_U_DOMAIN_TYPE_HOSTED = 128;
+export declare const JID_U_DOMAIN_TYPE_HOSTED_LID = 129;
+export declare const JID_U_DOMAIN_TYPE_HOSTED_MASK = 128;
+export declare const JID_U_DOMAIN_TYPE_LID_MASK = 1;
+export declare const NIBBLE_ALPHABET: readonly ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "-", ".", "�", "�", "�", "�"];
+export declare const HEX_ALPHABET: readonly ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "A", "B", "C", "D", "E", "F"];
 export declare const SINGLE_BYTE_TOKEN_MAP: ReadonlyMap<string, number>;
 export declare const DICTIONARY_TOKEN_MAPS: readonly ReadonlyMap<string, number>[];

package/dist/types/transport/binary/decoder.d.ts

@@ -1,3 +1,8 @@
 import type { BinaryNode } from '../types';
+/** Decodes raw WhatsApp binary node bytes into a {@link BinaryNode}. */
 export declare function decodeBinaryNode(data: Uint8Array): BinaryNode;
+/**
+ * Decodes a framed stanza: reads the 1-byte flag, inflates the body when the
+ * `0x02` compression bit is set, then parses the result as a {@link BinaryNode}.
+ */
 export declare function decodeBinaryNodeStanza(stanza: Uint8Array): Promise<BinaryNode>;

package/dist/types/transport/binary/encoder.d.ts

@@ -1,3 +1,8 @@
 import type { BinaryNode } from '../types';
+/** Encodes a {@link BinaryNode} into its raw WhatsApp binary representation. */
 export declare function encodeBinaryNode(node: BinaryNode): Uint8Array;
+/**
+ * Encodes a {@link BinaryNode} as a transport stanza – prefixes the bytes
+ * with the 1-byte flag (`0x00`) the WebSocket framing expects.
+ */
 export declare function encodeBinaryNodeStanza(node: BinaryNode): Uint8Array;