@massalabs/gossip-sdk 0.0.1 → 0.0.2-dev.20260128111120

package/dist/gossipSdk.js

@@ -0,0 +1,690 @@
+/**
+ * GossipSdk - Singleton SDK with clean lifecycle API
+ *
+ * @example
+ * ```typescript
+ * import { gossipSdk } from 'gossip-sdk';
+ *
+ * // Initialize once at app startup
+ * await gossipSdk.init({
+ *   db,
+ *   protocolBaseUrl: 'https://api.example.com',
+ * });
+ *
+ * // Open session (login) - SDK handles keys/session internally
+ * await gossipSdk.openSession({
+ *   mnemonic: 'word1 word2 ...',
+ *   onPersist: async (blob) => { /* save to db *\/ },
+ * });
+ *
+ * // Or restore existing session
+ * await gossipSdk.openSession({
+ *   mnemonic: 'word1 word2 ...',
+ *   encryptedSession: savedBlob,
+ *   encryptionKey: key,
+ *   onPersist: async (blob) => { /* save to db *\/ },
+ * });
+ *
+ * // Use clean API
+ * await gossipSdk.messages.send(contactId, 'Hello!');
+ * await gossipSdk.discussions.start(contact);
+ * const contacts = await gossipSdk.contacts.list(ownerUserId);
+ *
+ * // Events
+ * gossipSdk.on('message', (msg) => { ... });
+ * gossipSdk.on('discussionRequest', (discussion, contact) => { ... });
+ *
+ * // Logout
+ * await gossipSdk.closeSession();
+ * ```
+ */
+import { MessageStatus, } from './db';
+import { setDb } from './db';
+import { createMessageProtocol } from './api/messageProtocol';
+import { setProtocolBaseUrl } from './config/protocol';
+import { defaultSdkConfig, mergeConfig, } from './config/sdk';
+import { startWasmInitialization, ensureWasmInitialized } from './wasm/loader';
+import { generateUserKeys } from './wasm/userKeys';
+import { SessionModule } from './wasm/session';
+import { AnnouncementService, } from './services/announcement';
+import { DiscussionService } from './services/discussion';
+import { MessageService, } from './services/message';
+import { RefreshService } from './services/refresh';
+import { AuthService } from './services/auth';
+import { validateUserIdFormat, validateUsernameFormat, } from './utils/validation';
+import { QueueManager } from './utils/queue';
+import { encodeUserId, decodeUserId } from './utils/userId';
+import { getContacts, getContact, addContact, updateContactName, deleteContact, } from './contacts';
+import { SdkEventEmitter, } from './core/SdkEventEmitter';
+import { SdkPolling } from './core/SdkPolling';
+// ─────────────────────────────────────────────────────────────────────────────
+// SDK Class
+// ─────────────────────────────────────────────────────────────────────────────
+class GossipSdkImpl {
+    constructor() {
+        Object.defineProperty(this, "state", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: { status: 'uninitialized' }
+        });
+        // Core components
+        Object.defineProperty(this, "eventEmitter", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new SdkEventEmitter()
+        });
+        Object.defineProperty(this, "pollingManager", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new SdkPolling()
+        });
+        Object.defineProperty(this, "messageQueues", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new QueueManager()
+        });
+        // Services (created when session opens)
+        Object.defineProperty(this, "_auth", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "_announcement", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "_discussion", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "_message", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "_refresh", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        // Cached service API wrappers (created in openSession)
+        Object.defineProperty(this, "_messagesAPI", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "_discussionsAPI", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "_announcementsAPI", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "_contactsAPI", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "_refreshAPI", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Lifecycle
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Initialize the SDK. Call once at app startup.
+     */
+    async init(options) {
+        if (this.state.status !== 'uninitialized') {
+            console.warn('[GossipSdk] Already initialized');
+            return;
+        }
+        // Merge config with defaults
+        const config = mergeConfig(options.config);
+        // Configure database
+        setDb(options.db);
+        // Configure protocol URL (prefer explicit option, then config)
+        const baseUrl = options.protocolBaseUrl ?? config.protocol.baseUrl;
+        if (baseUrl) {
+            setProtocolBaseUrl(baseUrl);
+        }
+        // Start WASM initialization
+        startWasmInitialization();
+        // Create message protocol
+        const messageProtocol = createMessageProtocol();
+        // Create auth service (doesn't need session)
+        this._auth = new AuthService(options.db, messageProtocol);
+        this.state = {
+            status: 'initialized',
+            db: options.db,
+            messageProtocol,
+            config,
+        };
+    }
+    /**
+     * Open a session (login).
+     * Generates keys from mnemonic and initializes session.
+     */
+    async openSession(options) {
+        if (this.state.status === 'uninitialized') {
+            throw new Error('SDK not initialized. Call init() first.');
+        }
+        if (this.state.status === 'session_open') {
+            throw new Error('Session already open. Call closeSession() first.');
+        }
+        if (options.encryptedSession && !options.encryptionKey) {
+            throw new Error('encryptionKey is required when encryptedSession is provided.');
+        }
+        if (options.onPersist && !options.persistEncryptionKey) {
+            throw new Error('persistEncryptionKey is required when onPersist is provided.');
+        }
+        const { db, messageProtocol } = this.state;
+        // Validate session restore options - must have both or neither
+        if (options.encryptedSession && !options.encryptionKey) {
+            throw new Error('encryptedSession provided without encryptionKey. Session restore requires both.');
+        }
+        if (options.encryptionKey && !options.encryptedSession) {
+            console.warn('[GossipSdk] encryptionKey provided without encryptedSession - key will be ignored');
+        }
+        // Validate persistence options - warn if incomplete
+        if (options.onPersist && !options.persistEncryptionKey) {
+            console.warn('[GossipSdk] onPersist provided without persistEncryptionKey - session will not be persisted');
+        }
+        if (options.persistEncryptionKey && !options.onPersist) {
+            console.warn('[GossipSdk] persistEncryptionKey provided without onPersist callback - key will be unused');
+        }
+        // Ensure WASM is ready
+        await ensureWasmInitialized();
+        // Generate keys from mnemonic
+        const userKeys = await generateUserKeys(options.mnemonic);
+        // Create session with persistence callback
+        // IMPORTANT: This callback is awaited by the session module before network sends
+        const session = new SessionModule(userKeys, async () => {
+            await this.handleSessionPersist();
+        });
+        // Restore existing session state if provided
+        if (options.encryptedSession && options.encryptionKey) {
+            // Create a minimal profile-like object for load()
+            const profileForLoad = {
+                session: options.encryptedSession,
+            };
+            session.load(profileForLoad, options.encryptionKey);
+        }
+        // Create event handlers that wire to our event system
+        const serviceEvents = {
+            onMessageReceived: (message) => {
+                this.eventEmitter.emit('message', message);
+            },
+            onMessageSent: (message) => {
+                this.eventEmitter.emit('messageSent', message);
+            },
+            onMessageFailed: (message, error) => {
+                this.eventEmitter.emit('messageFailed', message, error);
+            },
+            onDiscussionRequest: (discussion, contact) => {
+                this.eventEmitter.emit('discussionRequest', discussion, contact);
+            },
+            onDiscussionStatusChanged: (discussion) => {
+                this.eventEmitter.emit('discussionStatusChanged', discussion);
+            },
+            onSessionBroken: (discussion) => {
+                this.eventEmitter.emit('sessionBroken', discussion);
+            },
+            onSessionRenewed: (discussion) => {
+                this.eventEmitter.emit('sessionRenewed', discussion);
+            },
+            onError: (error, context) => {
+                this.eventEmitter.emit('error', error, context);
+            },
+            // Auto-renewal: when session is lost, automatically renew it
+            onSessionRenewalNeeded: (contactUserId) => {
+                console.log('[GossipSdk] Session renewal needed for', contactUserId);
+                this.handleSessionRenewal(contactUserId);
+            },
+            // Auto-accept: when peer sent us an announcement, accept/respond to establish session
+            onSessionAcceptNeeded: (contactUserId) => {
+                console.log('[GossipSdk] Session accept needed for', contactUserId);
+                this.handleSessionAccept(contactUserId);
+            },
+            // Session became active: peer accepted our announcement, process waiting messages
+            onSessionBecameActive: (contactUserId) => {
+                console.log('[GossipSdk] Session became active for', contactUserId);
+                this.handleSessionBecameActive(contactUserId);
+            },
+        };
+        // Get config from initialized state
+        const { config } = this.state;
+        // Create services with config
+        this._announcement = new AnnouncementService(db, messageProtocol, session, serviceEvents, config);
+        this._discussion = new DiscussionService(db, this._announcement, session, serviceEvents);
+        this._message = new MessageService(db, messageProtocol, session, this._discussion, serviceEvents, config);
+        this._refresh = new RefreshService(db, this._message, session, serviceEvents);
+        // Reset any messages stuck in SENDING status to FAILED
+        // This handles app crash/close during message send
+        await this.resetStuckSendingMessages(db);
+        this.state = {
+            status: 'session_open',
+            db,
+            messageProtocol,
+            config,
+            session,
+            userKeys,
+            persistEncryptionKey: options.persistEncryptionKey,
+            onPersist: options.onPersist,
+        };
+        // Create cached service API wrappers
+        this.createServiceAPIWrappers(db, session);
+        // Auto-start polling if enabled in config
+        if (config.polling.enabled) {
+            this.startPolling();
+        }
+    }
+    /**
+     * Create cached service API wrappers.
+     * Called once during openSession to avoid creating new objects on each getter access.
+     */
+    createServiceAPIWrappers(db, session) {
+        this._messagesAPI = {
+            send: message => this.messageQueues.enqueue(message.contactUserId, () => this._message.sendMessage(message)),
+            fetch: () => this._message.fetchMessages(),
+            resend: async (messages) => {
+                const promises = [];
+                for (const [contactId, contactMessages] of messages.entries()) {
+                    const singleContactMap = new Map([[contactId, contactMessages]]);
+                    promises.push(this.messageQueues.enqueue(contactId, () => this._message.resendMessages(singleContactMap)));
+                }
+                await Promise.all(promises);
+            },
+            findBySeeker: (seeker, ownerUserId) => this._message.findMessageBySeeker(seeker, ownerUserId),
+        };
+        this._discussionsAPI = {
+            start: (contact, message) => this._discussion.initialize(contact, message),
+            accept: discussion => this._discussion.accept(discussion),
+            renew: contactUserId => this._discussion.renew(contactUserId),
+            isStable: (ownerUserId, contactUserId) => this._discussion.isStableState(ownerUserId, contactUserId),
+            list: ownerUserId => db.getDiscussionsByOwner(ownerUserId),
+            get: (ownerUserId, contactUserId) => db.getDiscussionByOwnerAndContact(ownerUserId, contactUserId),
+        };
+        this._announcementsAPI = {
+            fetch: () => this._announcement.fetchAndProcessAnnouncements(),
+            resend: failedDiscussions => this._announcement.resendAnnouncements(failedDiscussions),
+        };
+        this._contactsAPI = {
+            list: ownerUserId => getContacts(ownerUserId, db),
+            get: (ownerUserId, contactUserId) => getContact(ownerUserId, contactUserId, db),
+            add: (ownerUserId, userId, name, publicKeys) => addContact(ownerUserId, userId, name, publicKeys, db),
+            updateName: (ownerUserId, contactUserId, newName) => updateContactName(ownerUserId, contactUserId, newName, db),
+            delete: (ownerUserId, contactUserId) => deleteContact(ownerUserId, contactUserId, db, session),
+        };
+        this._refreshAPI = {
+            handleSessionRefresh: activeDiscussions => this._refresh.handleSessionRefresh(activeDiscussions),
+        };
+    }
+    /**
+     * Close the current session (logout).
+     */
+    async closeSession() {
+        if (this.state.status !== 'session_open') {
+            return;
+        }
+        // Stop polling first
+        this.pollingManager.stop();
+        // Cleanup session
+        this.state.session.cleanup();
+        // Clear services
+        this._announcement = null;
+        this._discussion = null;
+        this._message = null;
+        this._refresh = null;
+        // Clear cached API wrappers
+        this._messagesAPI = null;
+        this._discussionsAPI = null;
+        this._announcementsAPI = null;
+        this._contactsAPI = null;
+        this._refreshAPI = null;
+        // Clear message queues
+        this.messageQueues.clear();
+        // Reset to initialized state
+        this.state = {
+            status: 'initialized',
+            db: this.state.db,
+            messageProtocol: this.state.messageProtocol,
+            config: this.state.config,
+        };
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Session Info
+    // ─────────────────────────────────────────────────────────────────
+    /** Current user ID (encoded). Throws if no session is open. */
+    get userId() {
+        const state = this.requireSession();
+        return state.session.userIdEncoded;
+    }
+    /** Current user ID (raw bytes). Throws if no session is open. */
+    get userIdBytes() {
+        const state = this.requireSession();
+        return state.session.userId;
+    }
+    /** User's public keys. Throws if no session is open. */
+    get publicKeys() {
+        const state = this.requireSession();
+        return state.session.ourPk;
+    }
+    /** Whether a session is currently open */
+    get isSessionOpen() {
+        return this.state.status === 'session_open';
+    }
+    /** Whether SDK is initialized */
+    get isInitialized() {
+        return this.state.status !== 'uninitialized';
+    }
+    /**
+     * Get encrypted session blob for persistence.
+     * Throws if no session is open.
+     */
+    getEncryptedSession(encryptionKey) {
+        const state = this.requireSession();
+        return state.session.toEncryptedBlob(encryptionKey);
+    }
+    /**
+     * Configure session persistence after session is opened.
+     * Use this when you need to set up persistence after account creation.
+     *
+     * @param encryptionKey - Key to encrypt session blob
+     * @param onPersist - Callback to save encrypted session blob
+     */
+    configurePersistence(encryptionKey, onPersist) {
+        if (this.state.status !== 'session_open') {
+            throw new Error('No session open. Call openSession() first.');
+        }
+        // Update state with persistence config
+        this.state = {
+            ...this.state,
+            persistEncryptionKey: encryptionKey,
+            onPersist,
+        };
+        console.log('[GossipSdk] Session persistence configured');
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Services (accessible only when session is open)
+    // ─────────────────────────────────────────────────────────────────
+    /** Auth service (available after init, before session) */
+    get auth() {
+        if (!this._auth) {
+            throw new Error('SDK not initialized');
+        }
+        return this._auth;
+    }
+    /** Message service */
+    get messages() {
+        this.requireSession();
+        if (!this._messagesAPI) {
+            throw new Error('Messages API not initialized');
+        }
+        return this._messagesAPI;
+    }
+    /** Discussion service */
+    get discussions() {
+        this.requireSession();
+        if (!this._discussionsAPI) {
+            throw new Error('Discussions API not initialized');
+        }
+        return this._discussionsAPI;
+    }
+    /** Announcement service */
+    get announcements() {
+        this.requireSession();
+        if (!this._announcementsAPI) {
+            throw new Error('Announcements API not initialized');
+        }
+        return this._announcementsAPI;
+    }
+    /** Contact management */
+    get contacts() {
+        this.requireSession();
+        if (!this._contactsAPI) {
+            throw new Error('Contacts API not initialized');
+        }
+        return this._contactsAPI;
+    }
+    /** Refresh/sync service */
+    get refresh() {
+        this.requireSession();
+        if (!this._refreshAPI) {
+            throw new Error('Refresh API not initialized');
+        }
+        return this._refreshAPI;
+    }
+    /** Utility functions */
+    get utils() {
+        return {
+            validateUserId: validateUserIdFormat,
+            validateUsername: validateUsernameFormat,
+            encodeUserId,
+            decodeUserId,
+        };
+    }
+    /** Current SDK configuration (read-only) */
+    get config() {
+        if (this.state.status === 'uninitialized') {
+            return defaultSdkConfig;
+        }
+        return this.state.config;
+    }
+    /** Polling control API */
+    get polling() {
+        return {
+            start: () => this.startPolling(),
+            stop: () => this.pollingManager.stop(),
+            isRunning: this.pollingManager.isRunning(),
+        };
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Polling
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Start polling for messages, announcements, and session refresh.
+     * Uses intervals from config.polling.
+     */
+    startPolling() {
+        if (this.state.status !== 'session_open') {
+            console.warn('[GossipSdk] Cannot start polling - no session open');
+            return;
+        }
+        const { config, db, session } = this.state;
+        this.pollingManager.start(config, {
+            fetchMessages: async () => {
+                await this._message?.fetchMessages();
+            },
+            fetchAnnouncements: async () => {
+                await this._announcement?.fetchAndProcessAnnouncements();
+            },
+            handleSessionRefresh: async (discussions) => {
+                await this._refresh?.handleSessionRefresh(discussions);
+            },
+            getActiveDiscussions: async () => {
+                return db.getActiveDiscussionsByOwner(session.userIdEncoded);
+            },
+            onError: (error, context) => {
+                this.eventEmitter.emit('error', error, context);
+            },
+        });
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Events
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Register an event handler
+     */
+    on(event, handler) {
+        this.eventEmitter.on(event, handler);
+    }
+    /**
+     * Remove an event handler
+     */
+    off(event, handler) {
+        this.eventEmitter.off(event, handler);
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Private Helpers
+    // ─────────────────────────────────────────────────────────────────
+    requireSession() {
+        if (this.state.status !== 'session_open') {
+            throw new Error('No session open. Call openSession() first.');
+        }
+        return this.state;
+    }
+    /**
+     * Handle automatic session renewal when session is lost.
+     * Called by onSessionRenewalNeeded event.
+     */
+    async handleSessionRenewal(contactUserId) {
+        if (this.state.status !== 'session_open')
+            return;
+        try {
+            await this._discussion.renew(contactUserId);
+            console.log('[GossipSdk] Session renewed for', contactUserId);
+            // After successful renewal, process any waiting messages
+            const sentCount = await this._message.processWaitingMessages(contactUserId);
+            if (sentCount > 0) {
+                console.log(`[GossipSdk] Sent ${sentCount} waiting messages after renewal`);
+            }
+        }
+        catch (error) {
+            console.error('[GossipSdk] Session renewal failed:', error);
+            this.eventEmitter.emit('error', error instanceof Error ? error : new Error(String(error)), 'session_renewal');
+        }
+    }
+    /**
+     * Handle automatic session accept when peer has sent us an announcement.
+     * Called by onSessionAcceptNeeded event.
+     * This is different from renewal - we respond to their session request.
+     */
+    async handleSessionAccept(contactUserId) {
+        if (this.state.status !== 'session_open')
+            return;
+        try {
+            const ownerUserId = this.state.session.userIdEncoded;
+            const discussion = await this.state.db.getDiscussionByOwnerAndContact(ownerUserId, contactUserId);
+            if (!discussion) {
+                console.warn('[GossipSdk] No discussion found for accept, contactUserId:', contactUserId);
+                return;
+            }
+            // Accept the discussion (sends our announcement back to establish session)
+            await this._discussion.accept(discussion);
+            console.log('[GossipSdk] Session accepted for', contactUserId);
+            // After successful accept, process any waiting messages
+            const sentCount = await this._message.processWaitingMessages(contactUserId);
+            if (sentCount > 0) {
+                console.log(`[GossipSdk] Sent ${sentCount} waiting messages after accept`);
+            }
+        }
+        catch (error) {
+            console.error('[GossipSdk] Session accept failed:', error);
+            this.eventEmitter.emit('error', error instanceof Error ? error : new Error(String(error)), 'session_accept');
+        }
+    }
+    /**
+     * Handle session becoming Active after peer accepts our announcement.
+     * Called by onSessionBecameActive event.
+     *
+     * This is different from handleSessionAccept:
+     * - handleSessionAccept: WE accept a session (peer initiated)
+     * - handleSessionBecameActive: PEER accepts our session (we initiated)
+     */
+    async handleSessionBecameActive(contactUserId) {
+        if (this.state.status !== 'session_open')
+            return;
+        try {
+            // Process any messages that were queued as WAITING_SESSION
+            const sentCount = await this._message.processWaitingMessages(contactUserId);
+            if (sentCount > 0) {
+                console.log(`[GossipSdk] Sent ${sentCount} waiting messages after session became active`);
+            }
+        }
+        catch (error) {
+            console.error('[GossipSdk] Processing waiting messages failed:', error);
+            this.eventEmitter.emit('error', error instanceof Error ? error : new Error(String(error)), 'session_became_active');
+        }
+    }
+    async handleSessionPersist() {
+        if (this.state.status !== 'session_open')
+            return;
+        const { onPersist, persistEncryptionKey, session } = this.state;
+        if (!onPersist || !persistEncryptionKey)
+            return;
+        try {
+            const blob = session.toEncryptedBlob(persistEncryptionKey);
+            console.log(`[SessionPersist] Saving session blob (${blob.length} bytes)`);
+            await onPersist(blob, persistEncryptionKey);
+        }
+        catch (error) {
+            console.error('[GossipSdk] Session persistence failed:', error);
+        }
+    }
+    /**
+     * Reset any messages stuck in SENDING status to FAILED.
+     * This handles the case where the app crashed or was closed during message send.
+     * Per spec: SENDING should never be persisted - if we find it on startup, it failed.
+     */
+    /**
+     * Reset messages stuck in SENDING status to WAITING_SESSION.
+     *
+     * Per spec: SENDING is a transient state that should never be persisted.
+     * If the app crashes/closes during a send, the message would be stuck forever.
+     *
+     * By resetting to WAITING_SESSION:
+     * - Message will be re-encrypted with current session keys
+     * - Message will be automatically sent when session is active
+     * - No manual user intervention required
+     *
+     * We also clear encryptedMessage and seeker since they may be stale.
+     */
+    async resetStuckSendingMessages(db) {
+        try {
+            const count = await db.messages
+                .where('status')
+                .equals(MessageStatus.SENDING)
+                .modify({
+                status: MessageStatus.WAITING_SESSION,
+                encryptedMessage: undefined,
+                seeker: undefined,
+            });
+            if (count > 0) {
+                console.log(`[GossipSdk] Reset ${count} stuck SENDING message(s) to WAITING_SESSION for auto-retry`);
+            }
+        }
+        catch (error) {
+            console.error('[GossipSdk] Failed to reset stuck messages:', error);
+        }
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Singleton Export
+// ─────────────────────────────────────────────────────────────────────────────
+/** The singleton GossipSdk instance */
+export const gossipSdk = new GossipSdkImpl();
+// Also export the class for testing
+export { GossipSdkImpl };