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

package/dist/db.js

@@ -0,0 +1,311 @@
+/**
+ * Gossip Database
+ *
+ * IndexedDB database implementation using Dexie for the Gossip messenger.
+ * Provides tables for contacts, messages, discussions, user profiles, and more.
+ */
+import Dexie from 'dexie';
+// Unified discussion interface combining protocol state and UI metadata
+export var DiscussionStatus;
+(function (DiscussionStatus) {
+    DiscussionStatus["PENDING"] = "pending";
+    DiscussionStatus["ACTIVE"] = "active";
+    DiscussionStatus["CLOSED"] = "closed";
+    DiscussionStatus["BROKEN"] = "broken";
+    DiscussionStatus["SEND_FAILED"] = "sendFailed";
+    DiscussionStatus["RECONNECTING"] = "reconnecting";
+})(DiscussionStatus || (DiscussionStatus = {}));
+export var MessageDirection;
+(function (MessageDirection) {
+    MessageDirection["INCOMING"] = "incoming";
+    MessageDirection["OUTGOING"] = "outgoing";
+})(MessageDirection || (MessageDirection = {}));
+export var MessageStatus;
+(function (MessageStatus) {
+    MessageStatus["WAITING_SESSION"] = "waiting_session";
+    MessageStatus["SENDING"] = "sending";
+    MessageStatus["SENT"] = "sent";
+    MessageStatus["DELIVERED"] = "delivered";
+    MessageStatus["READ"] = "read";
+    MessageStatus["FAILED"] = "failed";
+})(MessageStatus || (MessageStatus = {}));
+export var DiscussionDirection;
+(function (DiscussionDirection) {
+    DiscussionDirection["INITIATED"] = "initiated";
+    DiscussionDirection["RECEIVED"] = "received";
+})(DiscussionDirection || (DiscussionDirection = {}));
+export var MessageType;
+(function (MessageType) {
+    MessageType["TEXT"] = "text";
+    MessageType["KEEP_ALIVE"] = "keep_alive";
+    MessageType["IMAGE"] = "image";
+    MessageType["FILE"] = "file";
+    MessageType["AUDIO"] = "audio";
+    MessageType["VIDEO"] = "video";
+})(MessageType || (MessageType = {}));
+// Define the database class
+export class GossipDatabase extends Dexie {
+    constructor() {
+        super('GossipDatabase');
+        // Define tables
+        Object.defineProperty(this, "contacts", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "messages", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "userProfile", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "discussions", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "pendingEncryptedMessages", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "pendingAnnouncements", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "activeSeekers", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.version(13).stores({
+            contacts: '++id, ownerUserId, userId, name, isOnline, lastSeen, createdAt, [ownerUserId+userId] , [ownerUserId+name]',
+            messages: '++id, ownerUserId, contactUserId, type, direction, status, timestamp, seeker, [ownerUserId+contactUserId], [ownerUserId+status], [ownerUserId+contactUserId+status], [ownerUserId+seeker], [ownerUserId+contactUserId+direction], [ownerUserId+direction+status]',
+            userProfile: 'userId, username, status, lastSeen',
+            discussions: '++id, ownerUserId, &[ownerUserId+contactUserId], status, [ownerUserId+status], lastSyncTimestamp, unreadCount, lastMessageTimestamp, createdAt, updatedAt',
+            pendingEncryptedMessages: '++id, fetchedAt, seeker',
+            pendingAnnouncements: '++id, fetchedAt, &announcement',
+            activeSeekers: '++id, seeker',
+        });
+        // Add hooks for automatic timestamps
+        this.contacts.hook('creating', function (_primKey, obj, _trans) {
+            obj.createdAt = new Date();
+        });
+        this.userProfile.hook('creating', function (_primKey, obj, _trans) {
+            obj.createdAt = new Date();
+            obj.updatedAt = new Date();
+        });
+        this.userProfile.hook('updating', function (modifications, _primKey, _obj, _trans) {
+            modifications.updatedAt = new Date();
+        });
+        this.discussions.hook('creating', function (_primKey, obj, _trans) {
+            obj.createdAt = new Date();
+            obj.updatedAt = new Date();
+        });
+        this.discussions.hook('updating', function (modifications, _primKey, _obj, _trans) {
+            modifications.updatedAt = new Date();
+        });
+    }
+    // Helper methods for common operations
+    /** CONTACTS */
+    async getContactsByOwner(ownerUserId) {
+        return await this.contacts
+            .where('ownerUserId')
+            .equals(ownerUserId)
+            .toArray();
+    }
+    async getContactByOwnerAndUserId(ownerUserId, userId) {
+        return await this.contacts
+            .where('[ownerUserId+userId]')
+            .equals([ownerUserId, userId])
+            .first();
+    }
+    /** DISCUSSIONS */
+    async getDiscussionsByOwner(ownerUserId) {
+        const all = await this.discussions
+            .where('ownerUserId')
+            .equals(ownerUserId)
+            .toArray();
+        return all.sort((a, b) => {
+            if (a.lastMessageTimestamp && b.lastMessageTimestamp) {
+                return (b.lastMessageTimestamp.getTime() - a.lastMessageTimestamp.getTime());
+            }
+            if (a.lastMessageTimestamp)
+                return -1;
+            if (b.lastMessageTimestamp)
+                return 1;
+            return b.createdAt.getTime() - a.createdAt.getTime();
+        });
+    }
+    async getUnreadCountByOwner(ownerUserId) {
+        const discussions = await this.discussions
+            .where('ownerUserId')
+            .equals(ownerUserId)
+            .toArray();
+        return discussions.reduce((total, d) => total + d.unreadCount, 0);
+    }
+    async getDiscussionByOwnerAndContact(ownerUserId, contactUserId) {
+        if (!ownerUserId || !contactUserId) {
+            return undefined;
+        }
+        return await this.discussions
+            .where('[ownerUserId+contactUserId]')
+            .equals([ownerUserId, contactUserId])
+            .first();
+    }
+    /**
+     * Get all active discussions with their sync status
+     * @returns Array of active discussions
+     */
+    async getActiveDiscussionsByOwner(ownerUserId) {
+        return await this.discussions
+            .where('[ownerUserId+status]')
+            .equals([ownerUserId, DiscussionStatus.ACTIVE])
+            .toArray();
+    }
+    async markMessagesAsRead(ownerUserId, contactUserId) {
+        await this.messages
+            .where('[ownerUserId+contactUserId+status]')
+            .equals([ownerUserId, contactUserId, MessageStatus.DELIVERED])
+            .and(msg => msg.direction === MessageDirection.INCOMING)
+            .modify({ status: MessageStatus.READ });
+        await this.discussions
+            .where('[ownerUserId+contactUserId]')
+            .equals([ownerUserId, contactUserId])
+            .modify({ unreadCount: 0 });
+    }
+    async getMessagesForContactByOwner(ownerUserId, contactUserId, limit = 50) {
+        return await this.messages
+            .where('[ownerUserId+contactUserId]')
+            .equals([ownerUserId, contactUserId])
+            .reverse()
+            .limit(limit)
+            .toArray();
+    }
+    async addMessage(message) {
+        const messageId = await this.messages.add(message);
+        // Get existing discussion
+        const discussion = await this.getDiscussionByOwnerAndContact(message.ownerUserId, message.contactUserId);
+        if (discussion) {
+            await this.discussions.update(discussion.id, {
+                lastMessageId: messageId,
+                lastMessageContent: message.content,
+                lastMessageTimestamp: message.timestamp,
+                unreadCount: message.direction === MessageDirection.INCOMING
+                    ? discussion.unreadCount + 1
+                    : discussion.unreadCount,
+                updatedAt: new Date(),
+            });
+        }
+        else {
+            // Note: For new messages, a discussion should already exist from the protocol
+            // If not, we'll create a minimal one (this shouldn't normally happen)
+            console.log('Warning: Creating discussion for contact without protocol setup:', message.contactUserId);
+            await this.discussions.put({
+                ownerUserId: message.ownerUserId,
+                contactUserId: message.contactUserId,
+                direction: message.direction === MessageDirection.INCOMING
+                    ? DiscussionDirection.RECEIVED
+                    : DiscussionDirection.INITIATED,
+                status: DiscussionStatus.PENDING,
+                nextSeeker: undefined,
+                lastMessageId: messageId,
+                lastMessageContent: message.content,
+                lastMessageTimestamp: message.timestamp,
+                unreadCount: message.direction === MessageDirection.INCOMING ? 1 : 0,
+                createdAt: new Date(),
+                updatedAt: new Date(),
+            });
+        }
+        return messageId;
+    }
+    /**
+     * Update the last sync timestamp for a discussion
+     * @param discussionId - The discussion ID
+     * @param timestamp - The sync timestamp
+     */
+    async updateLastSyncTimestamp(discussionId, timestamp) {
+        await this.discussions.update(discussionId, {
+            lastSyncTimestamp: timestamp,
+            updatedAt: new Date(),
+        });
+    }
+    async deleteDb() {
+        await this.close();
+        await this.delete();
+    }
+    /**
+     * Set all active seekers, replacing any existing ones
+     * @param seekers - Array of seeker Uint8Arrays to store
+     */
+    async setActiveSeekers(seekers) {
+        await this.transaction('rw', this.activeSeekers, async () => {
+            // Clear all existing seekers
+            await this.activeSeekers.clear();
+            // Bulk add all new seekers
+            if (seekers.length > 0) {
+                await this.activeSeekers.bulkAdd(seekers.map(seeker => ({
+                    seeker,
+                })));
+            }
+        });
+    }
+    /**
+     * Get all active seekers from the database
+     * @returns Array of seeker Uint8Arrays
+     */
+    async getActiveSeekers() {
+        const activeSeekers = await this.activeSeekers.toArray();
+        return activeSeekers.map(item => item.seeker);
+    }
+}
+// Database instance - initialized lazily or via setDb()
+let _db = null;
+let _warnedGlobalDbAccess = false;
+/**
+ * Get the database instance.
+ * Creates a default instance if none was set via setDb().
+ */
+export function getDb() {
+    if (!_db) {
+        _db = new GossipDatabase();
+    }
+    return _db;
+}
+/**
+ * Set the database instance.
+ * Call this before using any SDK functions if you need a custom db instance.
+ */
+export function setDb(database) {
+    _db = database;
+}
+/**
+ * Get the database instance.
+ * Creates a default instance if none was set via setDb().
+ */
+export const db = new Proxy({}, {
+    get(_target, prop) {
+        if (!_warnedGlobalDbAccess) {
+            _warnedGlobalDbAccess = true;
+            console.warn('[GossipSdk] Global db access is deprecated. Use createGossipSdk() or setDb().');
+        }
+        const target = getDb();
+        const value = Reflect.get(target, prop);
+        if (typeof value === 'function') {
+            return value.bind(target);
+        }
+        return value;
+    },
+});

package/dist/gossipSdk.d.ts

@@ -0,0 +1,274 @@
+/**
+ * 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 { GossipDatabase, type Contact, type Discussion, type Message } from './db';
+import { type SdkConfig, type DeepPartial } from './config/sdk';
+import { EncryptionKey } from './wasm/encryption';
+import { type AnnouncementReceptionResult } from './services/announcement';
+import { type MessageResult, type SendMessageResult } from './services/message';
+import { AuthService } from './services/auth';
+import type { DeleteContactResult, UpdateContactNameResult } from './utils/contacts';
+import { type ValidationResult } from './utils/validation';
+import type { UserPublicKeys } from './assets/generated/wasm/gossip_wasm';
+import { type SdkEventType, type SdkEventHandlers } from './core/SdkEventEmitter';
+export type { SdkEventType, SdkEventHandlers };
+export interface GossipSdkInitOptions {
+    /** Database instance */
+    db: GossipDatabase;
+    /** Protocol API base URL (shorthand for config.protocol.baseUrl) */
+    protocolBaseUrl?: string;
+    /** SDK configuration (optional - uses defaults if not provided) */
+    config?: DeepPartial<SdkConfig>;
+}
+export interface OpenSessionOptions {
+    /** BIP39 mnemonic phrase */
+    mnemonic: string;
+    /** Existing encrypted session blob (for restoring session) */
+    encryptedSession?: Uint8Array;
+    /** Encryption key for decrypting session */
+    encryptionKey?: EncryptionKey;
+    /** Callback when session state changes (for persistence) */
+    onPersist?: (encryptedBlob: Uint8Array, encryptionKey: EncryptionKey) => Promise<void>;
+    /** Encryption key for persisting session (required if onPersist is provided) */
+    persistEncryptionKey?: EncryptionKey;
+}
+declare class GossipSdkImpl {
+    private state;
+    private eventEmitter;
+    private pollingManager;
+    private messageQueues;
+    private _auth;
+    private _announcement;
+    private _discussion;
+    private _message;
+    private _refresh;
+    private _messagesAPI;
+    private _discussionsAPI;
+    private _announcementsAPI;
+    private _contactsAPI;
+    private _refreshAPI;
+    /**
+     * Initialize the SDK. Call once at app startup.
+     */
+    init(options: GossipSdkInitOptions): Promise<void>;
+    /**
+     * Open a session (login).
+     * Generates keys from mnemonic and initializes session.
+     */
+    openSession(options: OpenSessionOptions): Promise<void>;
+    /**
+     * Create cached service API wrappers.
+     * Called once during openSession to avoid creating new objects on each getter access.
+     */
+    private createServiceAPIWrappers;
+    /**
+     * Close the current session (logout).
+     */
+    closeSession(): Promise<void>;
+    /** Current user ID (encoded). Throws if no session is open. */
+    get userId(): string;
+    /** Current user ID (raw bytes). Throws if no session is open. */
+    get userIdBytes(): Uint8Array;
+    /** User's public keys. Throws if no session is open. */
+    get publicKeys(): UserPublicKeys;
+    /** Whether a session is currently open */
+    get isSessionOpen(): boolean;
+    /** Whether SDK is initialized */
+    get isInitialized(): boolean;
+    /**
+     * Get encrypted session blob for persistence.
+     * Throws if no session is open.
+     */
+    getEncryptedSession(encryptionKey: EncryptionKey): Uint8Array;
+    /**
+     * 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: EncryptionKey, onPersist: (encryptedBlob: Uint8Array, encryptionKey: EncryptionKey) => Promise<void>): void;
+    /** Auth service (available after init, before session) */
+    get auth(): AuthService;
+    /** Message service */
+    get messages(): MessageServiceAPI;
+    /** Discussion service */
+    get discussions(): DiscussionServiceAPI;
+    /** Announcement service */
+    get announcements(): AnnouncementServiceAPI;
+    /** Contact management */
+    get contacts(): ContactsAPI;
+    /** Refresh/sync service */
+    get refresh(): RefreshServiceAPI;
+    /** Utility functions */
+    get utils(): SdkUtils;
+    /** Current SDK configuration (read-only) */
+    get config(): SdkConfig;
+    /** Polling control API */
+    get polling(): PollingAPI;
+    /**
+     * Start polling for messages, announcements, and session refresh.
+     * Uses intervals from config.polling.
+     */
+    private startPolling;
+    /**
+     * Register an event handler
+     */
+    on<K extends SdkEventType>(event: K, handler: SdkEventHandlers[K]): void;
+    /**
+     * Remove an event handler
+     */
+    off<K extends SdkEventType>(event: K, handler: SdkEventHandlers[K]): void;
+    private requireSession;
+    /**
+     * Handle automatic session renewal when session is lost.
+     * Called by onSessionRenewalNeeded event.
+     */
+    private handleSessionRenewal;
+    /**
+     * 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.
+     */
+    private handleSessionAccept;
+    /**
+     * 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)
+     */
+    private handleSessionBecameActive;
+    private handleSessionPersist;
+    /**
+     * 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.
+     */
+    private resetStuckSendingMessages;
+}
+interface MessageServiceAPI {
+    /** Send a message */
+    send(message: Omit<Message, 'id'>): Promise<SendMessageResult>;
+    /** Fetch and decrypt messages from the protocol */
+    fetch(): Promise<MessageResult>;
+    /** Resend failed messages */
+    resend(messages: Map<string, Message[]>): Promise<void>;
+    /** Find a message by its seeker */
+    findBySeeker(seeker: Uint8Array, ownerUserId: string): Promise<Message | undefined>;
+}
+interface DiscussionServiceAPI {
+    /** Start a new discussion with a contact */
+    start(contact: Contact, message?: string): Promise<{
+        discussionId: number;
+        announcement: Uint8Array;
+    }>;
+    /** Accept an incoming discussion request */
+    accept(discussion: Discussion): Promise<void>;
+    /** Renew a broken discussion */
+    renew(contactUserId: string): Promise<void>;
+    /** Check if a discussion is in a stable state */
+    isStable(ownerUserId: string, contactUserId: string): Promise<boolean>;
+    /** List all discussions for the owner */
+    list(ownerUserId: string): Promise<Discussion[]>;
+    /** Get a specific discussion */
+    get(ownerUserId: string, contactUserId: string): Promise<Discussion | undefined>;
+}
+interface AnnouncementServiceAPI {
+    /** Fetch and process announcements from the protocol */
+    fetch(): Promise<AnnouncementReceptionResult>;
+    /** Resend failed announcements */
+    resend(failedDiscussions: Discussion[]): Promise<void>;
+}
+interface ContactsAPI {
+    /** List all contacts for the owner */
+    list(ownerUserId: string): Promise<Contact[]>;
+    /** Get a specific contact */
+    get(ownerUserId: string, contactUserId: string): Promise<Contact | null>;
+    /** Add a new contact */
+    add(ownerUserId: string, userId: string, name: string, publicKeys: UserPublicKeys): Promise<{
+        success: boolean;
+        error?: string;
+        contact?: Contact;
+    }>;
+    /** Update a contact's name */
+    updateName(ownerUserId: string, contactUserId: string, newName: string): Promise<UpdateContactNameResult>;
+    /** Delete a contact and all related data */
+    delete(ownerUserId: string, contactUserId: string): Promise<DeleteContactResult>;
+}
+interface RefreshServiceAPI {
+    /** Handle session refresh (keep-alive, broken sessions, etc.) */
+    handleSessionRefresh(activeDiscussions: Discussion[]): Promise<void>;
+}
+interface SdkUtils {
+    /** Validate a user ID format */
+    validateUserId(userId: string): ValidationResult;
+    /** Validate a username format */
+    validateUsername(username: string): ValidationResult;
+    /** Encode raw bytes to user ID string */
+    encodeUserId(rawId: Uint8Array): string;
+    /** Decode user ID string to raw bytes */
+    decodeUserId(encodedId: string): Uint8Array;
+}
+interface PollingAPI {
+    /** Start polling for messages, announcements, and session refresh */
+    start(): void;
+    /** Stop all polling */
+    stop(): void;
+    /** Whether polling is currently running */
+    isRunning: boolean;
+}
+/** The singleton GossipSdk instance */
+export declare const gossipSdk: GossipSdkImpl;
+export { GossipSdkImpl };