@melandlabs/integrations-whatsapp 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,354 @@
+import { MessagePlatformAdapter, Messages, MessageTarget, MessageEvent } from '@melandlabs/integrations-channels';
+import { ExtractedMessageInfo } from '@melandlabs/integrations-channels/sources/types';
+import { BaileysAuthStateProvider, FileIngester, ClientRegistry, ConfigProvider } from '@melandlabs/integrations/core';
+import { WASocket, WAMessage } from '@whiskeysockets/baileys';
+export { WhatsAppConversationStore } from './conversation-store.js';
+export { WhatsAppClientRegistry } from './client-registry.js';
+export { markdownToWhatsApp } from './markdown.js';
+
+/**
+ * WhatsApp Adapter using @whiskeysockets/baileys (WebSocket protocol)
+ *
+ * Replaces whatsapp-web.js (Puppeteer/Chromium) with Baileys WebSocket.
+ * No browser = no automation detection surface.
+ *
+ * This adapter is platform-agnostic - web-specific dependencies are provided
+ * via interfaces (CredentialStore, FileIngester, ClientRegistry, etc.)
+ */
+
+type WhatsAppDialogInfo = {
+    id: string;
+    name: string;
+    type: "private" | "group";
+};
+type WhatsAppUserInfo = {
+    wid: string;
+    pushName?: string;
+    formattedNumber?: string;
+};
+type WhatsAppLoginCallbacks = {
+    onQr?: (qr: string) => Promise<void> | void;
+    onCode?: (code: string) => Promise<void> | void;
+    onSession?: (session: unknown) => Promise<void> | void;
+    onReady?: (info: WhatsAppUserInfo) => Promise<void> | void;
+    onError?: (error: Error) => Promise<void> | void;
+};
+/**
+ * Module-level registry of active WhatsAppAdapters by sessionId.
+ * Used by QR login to expose the adapter for socket re-registration by accountId.
+ */
+declare const activeAdapters: Map<string, WhatsAppAdapter>;
+
+declare class WhatsAppAdapter extends MessagePlatformAdapter {
+    sock: WASocket | null;
+    botId: string;
+    messages: Messages;
+    name: string;
+    private sessionId;
+    private authStateProvider;
+    private authState;
+    private isReady;
+    /** In-memory chat list (replaces makeInMemoryStore in v7). Updated via chats.upsert events. */
+    private chats;
+    private asyncIteratorState;
+    /** On-demand history backfill budget, reset per getChatsByChunk cycle. */
+    private backfillRequestsThisCycle;
+    /** Persistent message store; created here when no listener attached one. */
+    private messageStore;
+    /** Override for the message store base dir (tests). */
+    private historyStoreDir?;
+    /** False when sessionId fell back to a random uuid (no botId/sessionKey). */
+    private hasStableSessionId;
+    private isAuthenticated;
+    private initializationPromise;
+    /** Exposed so other adapters (e.g. insights bot) can await socket readiness. */
+    get pendingInitialization(): Promise<void> | null;
+    private loginDeferred;
+    private ownerUserId?;
+    private ownerUserType?;
+    private eventCleanup;
+    /** Pending reconnect socket creation, used to prevent concurrent reconnects */
+    private _pendingReconnect;
+    private reconnectTimer;
+    private isClosed;
+    /** Cache of recently sent messages for msgRetry requests (max 256 entries). */
+    private sentMessageCache;
+    private fileIngester?;
+    private clientRegistry?;
+    private configProvider?;
+    constructor(opts?: {
+        botId?: string;
+        ownerUserId?: string;
+        ownerUserType?: string;
+        /** Override sessionId — used by insight bot to reuse QR login's session */
+        sessionKey?: string;
+        authStateProvider: BaileysAuthStateProvider;
+        fileIngester?: FileIngester;
+        clientRegistry?: ClientRegistry;
+        configProvider?: ConfigProvider;
+        /** Override the persistent message store base dir (used by tests) */
+        historyStoreDir?: string;
+    });
+    /**
+     * Register the socket under an additional key (e.g. account.id).
+     * Call this after QR login succeeds and integration account is created,
+     * so self-listener and insight bot can find the socket by accountId.
+     */
+    setRegisterSocketAs(key: string): void;
+    /**
+     * Find an active adapter by sessionId and register its socket under accountId.
+     * Called from guest-guide after integration account is created.
+     */
+    static registerSocketByAccountId(sessionId: string, accountId: string): void;
+    private ensureAuthState;
+    /**
+     * Create and connect the Baileys socket with in-memory store.
+     * Auth state must be loaded (await ensureAuthState()) before calling this.
+     */
+    private createSocket;
+    private registerInternalEvents;
+    private saveAuthState;
+    /**
+     * Register connection/creds listeners on an existing socket.
+     * Called when a socket is reused from the registry.
+     */
+    setupListenersOnSocket(sock: WASocket): void;
+    private handleLoginReady;
+    private isTauriMode;
+    private timeBeforeHours;
+    /**
+     * Wait for the initial history sync to populate this.chats.
+     * History arrives via phone-pushed messaging-history.set events
+     * (syncFullHistory: true); there is no server API to request it —
+     * resyncAppState only syncs app state (mute/archive/contacts) and
+     * gets rate-limited (rate-overlimit) when called repeatedly.
+     */
+    private waitForInitialHistorySync;
+    /**
+     * Make sure the socket carries a persistent message history store. The
+     * phone pushes the full history exactly once, seconds after pairing — so
+     * the store must be attached when the socket is created, not later by the
+     * self-message listener (whose frontend-triggered init loses that race).
+     * Keyed by sessionId so every adapter instance for the same WhatsApp
+     * session reads the same persisted data.
+     */
+    private ensureMessageStore;
+    /**
+     * Restore this.chats from the persisted message history store (attached to
+     * the socket by the self-message listener). Lets insight refreshes work
+     * right after a restart, before any new history sync events arrive.
+     */
+    private hydrateChatsFromStore;
+    /**
+     * On-demand history backfill via the official Baileys API: when local
+     * coverage for a chat does not reach the requested window start, page
+     * backwards from the oldest locally stored message (the required anchor)
+     * with sock.fetchMessageHistory. The phone responds asynchronously through
+     * an ON_DEMAND messaging-history.set, which the attached store persists —
+     * so arrival is detected by polling the store's oldest message.
+     */
+    private backfillChatHistory;
+    /**
+     * Wait for the phone's answer to a fetchMessageHistory request: either the
+     * store's oldest message gets older (new history arrived), or an ON_DEMAND
+     * messaging-history.set lands without older messages (end of history).
+     */
+    private waitForBackfillResponse;
+    private ensureReady;
+    startQrLogin(callbacks?: WhatsAppLoginCallbacks): Promise<string>;
+    startPairingCodeLogin(phoneNumber: string, callbacks?: WhatsAppLoginCallbacks): Promise<string>;
+    getUserInfo(): WhatsAppUserInfo;
+    sendMessages(target: MessageTarget, id: string, messages: Messages): Promise<void>;
+    sendMessage(target: MessageTarget, id: string, message: string): Promise<void>;
+    replyMessages(event: MessageEvent, messages: Messages, quoteOrigin?: boolean): Promise<void>;
+    run(): Promise<void>;
+    isUsingLocalAuth(): boolean;
+    /**
+     * Start the socket without waiting for connection (for self-listener use).
+     * Creates the socket and registers it in the client registry.
+     * Always sets up listeners (even when socket was already connected)
+     * so callers receive events.
+     */
+    startSocket(): Promise<WASocket>;
+    /**
+     * Attach this adapter to an already-connected socket (from registry).
+     * Used by QR login to reuse the self-listener's socket instead of creating a new one.
+     */
+    attachToSocket(sock: WASocket): void;
+    /**
+     * Kill the socket. If targetSock is provided, only kill that socket's listeners
+     * (used during reconnect to avoid killing the new socket's listeners).
+     * If no targetSock, kills the current socket.
+     */
+    kill(targetSock?: WASocket): Promise<boolean>;
+    getSessionIdentifier(): string;
+    getDialogs(): Promise<WhatsAppDialogInfo[]>;
+    getChatsByChunk(since: number, chunkSize?: number): Promise<{
+        messages: ExtractedMessageInfo[];
+        hasMore: boolean;
+    }>;
+    getChatsByChunkHours(hours?: number): Promise<{
+        messages: ExtractedMessageInfo[];
+        hasMore: boolean;
+    }>;
+    getChatsByTime(cutoffDate: number): Promise<ExtractedMessageInfo[]>;
+    getChatsByHours(hours?: number): Promise<ExtractedMessageInfo[]>;
+    getChatsByDays(days?: number): Promise<ExtractedMessageInfo[]>;
+    resetChunkIterator(): void;
+    private extractMessageInfo;
+    private getMessageText;
+    private resolveChatId;
+    private prepareMediaMessage;
+    private prepareFileMessage;
+    private guessMimeType;
+    authStateExists(): Promise<boolean>;
+    /**
+     * @deprecated Use authStateExists instead
+     */
+    sessionExists(): Promise<boolean>;
+    forceSaveSession(): Promise<void>;
+    /** Save session to disk. Call after QR login completes. */
+    saveSession(): Promise<void>;
+    checkSessionStatus(): Promise<{
+        exists: boolean;
+        ready: boolean;
+        authenticated: boolean;
+    }>;
+    restoreSession(): Promise<boolean>;
+    ingestMessageAttachments(msg: WAMessage): Promise<any[]>;
+    getSocket(): WASocket | null;
+}
+
+/**
+ * WhatsApp Message History Store
+ *
+ * File-backed replacement for the minimal in-memory Baileys store (Baileys v7
+ * removed makeInMemoryStore). Full WAMessage objects stay in memory for
+ * real-time consumers; a sanitized copy (binary payloads dropped, Long
+ * timestamps normalized to numbers) is persisted per chat so message history
+ * and the chat list survive process restarts. Persisted messages also provide
+ * the anchor (oldest message key + timestamp) required by Baileys'
+ * sock.fetchMessageHistory on-demand backfill API.
+ *
+ * Layout:
+ *   <baseDir>/<accountId>/chats.json
+ *   <baseDir>/<accountId>/messages/<base64url(jid)>.json
+ *
+ * ARCHITECTURE EXCEPTION (per repo rule: exceptions must be explicit).
+ * Data is stored as plain JSON, unencrypted.
+ * - Why: matches the Baileys auth state in local/Tauri mode, which already
+ *   sits unencrypted in the same data dir and grants full account access.
+ * - Impact scope: in cloud deployments the auth state lives in Redis, so this
+ *   directory is an additional at-rest exposure of message content on the
+ *   server filesystem.
+ * - Temporary: yes — the follow-up is to encrypt at rest in cloud mode using
+ *   packages/security (key management decision pending), or scope this store
+ *   to local/Tauri mode only.
+ * - Mitigation today: per-chat cap (500 msgs), binary payloads stripped, and
+ *   mandatory lifecycle cleanup — callers must invoke
+ *   WhatsAppMessageHistoryStore.purgeAccountData() when the integration
+ *   account is disconnected so no message content outlives the account
+ *   (purge also destroys live in-process instances; see tests in
+ *   message-history-store.test.ts).
+ * - Known gaps for the encryption follow-up: whole-user account deletion
+ *   paths that bypass integration disconnect do not purge; in multi-instance
+ *   cloud deployments purge only clears the current instance's filesystem.
+ *
+ * Limitation: sanitization strips media keys/thumbnails, so messages
+ * hydrated from disk cannot be passed to downloadMediaMessage — only text
+ * extraction and backfill anchoring work on persisted history.
+ */
+
+type PersistedChatInfo = {
+    id: string;
+    name?: string;
+};
+declare class WhatsAppMessageHistoryStore {
+    private readonly accountDir;
+    private readonly messagesDir;
+    private messages;
+    /** Per-chat id sets mirroring `messages`, for O(1) dedup on insert. */
+    private messageIds;
+    private hydratedJids;
+    private chats;
+    private chatsHydrated;
+    private dirtyJids;
+    private chatsDirty;
+    private flushTimer;
+    private consecutiveFlushFailures;
+    private closed;
+    private readonly persistEnabled;
+    /** ON_DEMAND history responses seen — backfill's "phone answered" signal. */
+    private onDemandResponses;
+    /**
+     * Delete all persisted history for an account. Must be called when the
+     * integration account is disconnected/removed so message content does not
+     * outlive the account on disk. Live store instances for the account are
+     * destroyed first — otherwise their pending debounced flushes (or messages
+     * still arriving on an undisposed socket) would resurrect the files.
+     */
+    static purgeAccountData(accountId: string, baseDir?: string): void;
+    constructor(opts: {
+        accountId: string;
+        baseDir?: string;
+        persist?: boolean;
+    });
+    /**
+     * Permanently disable this store: stop pending flushes, drop in-memory
+     * data, and turn all writes into no-ops. Called by purgeAccountData so a
+     * disconnected account's messages cannot be re-persisted.
+     */
+    /** True once destroy() has run — writes are no-ops; do not attach/reuse. */
+    get isClosed(): boolean;
+    destroy(): void;
+    /**
+     * Attach event listeners to a WASocket to populate the store. History
+     * arrives via phone-pushed messaging-history.set (initial pairing and
+     * ON_DEMAND backfill responses); real-time messages via messages.upsert.
+     */
+    attach(sock: WASocket): void;
+    addMessages(msgs: WAMessage[]): void;
+    addChats(chats: Array<{
+        id?: string | null;
+        name?: string | null;
+    }>): void;
+    /** Same interface as the old in-memory store (used by Baileys consumers). */
+    loadMessages(jid: string, count: number, _opts: object): Promise<WAMessage[]>;
+    /** Chronologically oldest stored message — the fetchMessageHistory anchor. */
+    getOldestMessage(jid: string): WAMessage | undefined;
+    /**
+     * Number of ON_DEMAND history sync responses received since this store
+     * instance was created. Used by backfill to distinguish "phone answered
+     * with nothing older" (end of history) from "phone never answered".
+     */
+    getOnDemandResponseCount(): number;
+    /**
+     * False once the per-chat cap is reached: addMessages trims the oldest
+     * entries, so backfilled history would be discarded immediately and the
+     * oldest anchor would never move — requesting more is pointless.
+     */
+    canStoreOlderMessages(jid: string): boolean;
+    /** Persisted chat list, used to rebuild adapter state after a restart. */
+    loadChats(): PersistedChatInfo[];
+    /** Write all pending changes to disk immediately. */
+    flush(): void;
+    /**
+     * Write up to maxFiles dirty chats. The initial full history sync can dirty
+     * hundreds of chats at once; writing them all synchronously in one tick
+     * would stall the event loop right in the middle of onboarding, so the
+     * debounced timer writes in batches and reschedules for the remainder.
+     * Explicit flush() still drains everything (teardown must not lose data).
+     */
+    private writePending;
+    /**
+     * Write via temp file + rename so a crash can't leave truncated JSON.
+     * The pid suffix keeps multi-worker processes from racing on the same
+     * temp path (each still last-write-wins on the final file).
+     */
+    private writeFileAtomic;
+    private scheduleFlush;
+    private hydrate;
+    private hydrateChats;
+}
+
+export { type PersistedChatInfo, WhatsAppAdapter, type WhatsAppDialogInfo, WhatsAppMessageHistoryStore, type WhatsAppUserInfo, activeAdapters };