zapo-js 0.3.0 → 1.0.0

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/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/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,11 +1,11 @@
-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';
@@ -15,17 +15,18 @@ 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 { WaPreKeyMemoryStore } from './providers/memory/pre-key.store';
-export { WaSessionMemoryStore } from './providers/memory/session.store';
-export { WaIdentityMemoryStore } from './providers/memory/identity.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 { WaMessageSecretMemoryStore } from './providers/memory/message-secret.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/{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;
 }

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/{providers/memory → memory}/identity.store.d.ts

@@ -1,5 +1,5 @@
-import type { SignalAddress } from '../../../signal/types';
-import type { WaIdentityStore as WaIdentityStoreContract } from '../../contracts/identity.store';
+import type { SignalAddress } from '../../signal/types';
+import type { WaIdentityStore as WaIdentityStoreContract } from '../contracts/identity.store';
 export interface WaIdentityMemoryStoreOptions {
     readonly maxRemoteIdentities?: number;
 }

package/dist/types/store/{providers/memory → memory}/message-secret.store.d.ts

@@ -1,13 +1,23 @@
-import type { WaMessageSecretEntry, WaMessageSecretStore } from '../../contracts/message-secret.store';
+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 cleanupTimer;
+    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>;

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/{providers/memory → memory}/pre-key.store.d.ts

@@ -1,5 +1,5 @@
-import type { PreKeyRecord } from '../../../signal/types';
-import type { WaPreKeyStore as WaPreKeyStoreContract } from '../../contracts/pre-key.store';
+import type { PreKeyRecord } from '../../signal/types';
+import type { WaPreKeyStore as WaPreKeyStoreContract } from '../contracts/pre-key.store';
 export interface WaPreKeyMemoryStoreOptions {
     readonly maxPreKeys?: number;
 }

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,8 +1,16 @@
-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;
@@ -11,8 +19,13 @@ export declare class WaRetryMemoryStore implements WaRetryStore {
     private readonly ttlMs;
     private readonly maxOutboundMessages;
     private readonly maxInboundCounters;
-    private readonly cleanupTimer;
+    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/{providers/memory → memory}/session.store.d.ts

@@ -1,5 +1,5 @@
-import type { SignalAddress, SignalSessionRecord } from '../../../signal/types';
-import type { WaSessionStore as WaSessionStoreContract } from '../../contracts/session.store';
+import type { SignalAddress, SignalSessionRecord } from '../../signal/types';
+import type { WaSessionStore as WaSessionStoreContract } from '../contracts/session.store';
 export interface WaSessionMemoryStoreOptions {
     readonly maxSessions?: number;
 }

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

@@ -1,5 +1,5 @@
-import type { RegistrationInfo, SignedPreKeyRecord } from '../../../signal/types';
-import type { WaSignalStore as WaSignalStoreContract } from '../../contracts/signal.store';
+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;

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

@@ -1,4 +1,4 @@
-import type { WaThreadStore as Contract, WaStoredThreadRecord } 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,8 +1,8 @@
 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;
@@ -10,5 +10,5 @@ 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_RETRY_STORE: WaRetryStore;
-export declare const NOOP_PARTICIPANTS_STORE: WaParticipantsStore;
+export declare const NOOP_GROUP_METADATA_STORE: WaGroupMetadataStore;
 export declare const NOOP_DEVICE_LIST_STORE: WaDeviceListStore;