@massalabs/gossip-sdk 0.0.2-dev.20260128094509 → 0.0.2-dev.20260128160824

package/dist/services/auth.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Auth Service
+ *
+ * Handles storing and retrieving public keys by userId hash via the auth API.
+ */
+import { UserPublicKeys } from '#wasm';
+import { IMessageProtocol } from '../api/messageProtocol/types';
+import { type GossipDatabase } from '../db';
+export type PublicKeyResult = {
+    publicKey: UserPublicKeys;
+    error?: never;
+} | {
+    publicKey?: never;
+    error: string;
+};
+export declare class AuthService {
+    private db;
+    messageProtocol: IMessageProtocol;
+    constructor(db: GossipDatabase, messageProtocol: IMessageProtocol);
+    /**
+     * Fetch public key by userId
+     * @param userId - Bech32-encoded userId (e.g., "gossip1...")
+     */
+    fetchPublicKeyByUserId(userId: string): Promise<PublicKeyResult>;
+    /**
+     * Ensure public key is published (check first, then publish if needed)
+     * @param publicKeys - UserPublicKeys instance
+     * @param userId - Bech32-encoded userId (e.g., "gossip1...")
+     */
+    ensurePublicKeyPublished(publicKeys: UserPublicKeys, userId: string): Promise<void>;
+}
+export declare const PUBLIC_KEY_NOT_FOUND_ERROR = "Public key not found";
+export declare const PUBLIC_KEY_NOT_FOUND_MESSAGE = "Contact public key not found. It may not be published yet.";
+export declare const FAILED_TO_FETCH_ERROR = "Failed to fetch";
+export declare const FAILED_TO_FETCH_MESSAGE = "Failed to retrieve contact public key. Check your internet connection or try again later.";
+export declare const FAILED_TO_RETRIEVE_CONTACT_PUBLIC_KEY_ERROR = "Failed to retrieve contact public key";
+export declare function getPublicKeyErrorMessage(error: unknown): string;

package/dist/services/auth.js

@@ -0,0 +1,76 @@
+/**
+ * Auth Service
+ *
+ * Handles storing and retrieving public keys by userId hash via the auth API.
+ */
+import { UserPublicKeys } from '#wasm';
+import { decodeUserId } from '../utils/userId';
+import { encodeToBase64, decodeFromBase64 } from '../utils/base64';
+export class AuthService {
+    constructor(db, messageProtocol) {
+        Object.defineProperty(this, "db", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: db
+        });
+        Object.defineProperty(this, "messageProtocol", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: messageProtocol
+        });
+    }
+    /**
+     * Fetch public key by userId
+     * @param userId - Bech32-encoded userId (e.g., "gossip1...")
+     */
+    async fetchPublicKeyByUserId(userId) {
+        try {
+            const base64PublicKey = await this.messageProtocol.fetchPublicKeyByUserId(decodeUserId(userId));
+            return {
+                publicKey: UserPublicKeys.from_bytes(decodeFromBase64(base64PublicKey)),
+            };
+        }
+        catch (err) {
+            return {
+                error: getPublicKeyErrorMessage(err),
+            };
+        }
+    }
+    /**
+     * Ensure public key is published (check first, then publish if needed)
+     * @param publicKeys - UserPublicKeys instance
+     * @param userId - Bech32-encoded userId (e.g., "gossip1...")
+     */
+    async ensurePublicKeyPublished(publicKeys, userId) {
+        const profile = await this.db.userProfile.get(userId);
+        if (!profile)
+            throw new Error('User profile not found');
+        const lastPush = profile.lastPublicKeyPush;
+        if (lastPush && !moreThanOneWeekAgo(lastPush)) {
+            return;
+        }
+        await this.messageProtocol.postPublicKey(encodeToBase64(publicKeys.to_bytes()));
+        await this.db.userProfile.update(userId, { lastPublicKeyPush: new Date() });
+    }
+}
+const ONE_WEEK_IN_MILLIS = 7 * 24 * 60 * 60 * 1000;
+function moreThanOneWeekAgo(date) {
+    return Date.now() - date.getTime() >= ONE_WEEK_IN_MILLIS;
+}
+export const PUBLIC_KEY_NOT_FOUND_ERROR = 'Public key not found';
+export const PUBLIC_KEY_NOT_FOUND_MESSAGE = 'Contact public key not found. It may not be published yet.';
+export const FAILED_TO_FETCH_ERROR = 'Failed to fetch';
+export const FAILED_TO_FETCH_MESSAGE = 'Failed to retrieve contact public key. Check your internet connection or try again later.';
+export const FAILED_TO_RETRIEVE_CONTACT_PUBLIC_KEY_ERROR = 'Failed to retrieve contact public key';
+export function getPublicKeyErrorMessage(error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    if (errorMessage.includes(PUBLIC_KEY_NOT_FOUND_ERROR)) {
+        return PUBLIC_KEY_NOT_FOUND_MESSAGE;
+    }
+    if (errorMessage.includes(FAILED_TO_FETCH_ERROR)) {
+        return FAILED_TO_FETCH_MESSAGE;
+    }
+    return `${FAILED_TO_RETRIEVE_CONTACT_PUBLIC_KEY_ERROR}. ${errorMessage}`;
+}

package/dist/services/discussion.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Discussion Service
+ *
+ * Class-based service for initializing, accepting, and managing discussions.
+ */
+import { type Discussion, type Contact, type GossipDatabase } from '../db';
+import { AnnouncementService } from './announcement';
+import { SessionModule } from '../wasm/session';
+import { GossipSdkEvents } from '../types/events';
+/**
+ * Service for managing discussions between users.
+ *
+ * @example
+ * ```typescript
+ * const discussionService = new DiscussionService(db, announcementService, session);
+ *
+ * // Initialize a new discussion
+ * const result = await discussionService.initialize(contact, 'Hello!');
+ *
+ * // Accept a discussion request
+ * await discussionService.accept(discussion);
+ *
+ * // Renew a broken discussion
+ * await discussionService.renew(contactUserId);
+ * ```
+ */
+export declare class DiscussionService {
+    private db;
+    private announcementService;
+    private session;
+    private events;
+    constructor(db: GossipDatabase, announcementService: AnnouncementService, session: SessionModule, events?: GossipSdkEvents);
+    /**
+     * Initialize a discussion with a contact using SessionManager
+     * @param contact - The contact to start a discussion with
+     * @param message - Optional message to include in the announcement
+     * @returns The discussion ID and the created announcement
+     */
+    initialize(contact: Contact, message?: string): Promise<{
+        discussionId: number;
+        announcement: Uint8Array;
+    }>;
+    /**
+     * Accept a discussion request from a contact using SessionManager
+     * @param discussion - The discussion to accept
+     */
+    accept(discussion: Discussion): Promise<void>;
+    /**
+     * Renew a discussion by resetting sent outgoing messages and sending a new announcement.
+     * @param contactUserId - The user ID of the contact whose discussion should be renewed.
+     */
+    renew(contactUserId: string): Promise<void>;
+    /**
+     * Check if new messages can be sent to session manager for encryption.
+     * Returns false if the discussion is broken or if there are failed messages
+     * that have not been encrypted.
+     *
+     * @param ownerUserId - The owner user ID
+     * @param contactUserId - The contact user ID
+     * @returns true if discussion is in stable state for sending messages
+     */
+    isStableState(ownerUserId: string, contactUserId: string): Promise<boolean>;
+}

package/dist/services/discussion.js

@@ -0,0 +1,297 @@
+/**
+ * Discussion Service
+ *
+ * Class-based service for initializing, accepting, and managing discussions.
+ */
+import { DiscussionStatus, MessageDirection, MessageStatus, DiscussionDirection, } from '../db';
+import { UserPublicKeys, SessionStatus } from '#wasm';
+import { EstablishSessionError } from './announcement';
+import { sessionStatusToString } from '../wasm/session';
+import { decodeUserId } from '../utils/userId';
+import { Logger } from '../utils/logs';
+const logger = new Logger('DiscussionService');
+/**
+ * Service for managing discussions between users.
+ *
+ * @example
+ * ```typescript
+ * const discussionService = new DiscussionService(db, announcementService, session);
+ *
+ * // Initialize a new discussion
+ * const result = await discussionService.initialize(contact, 'Hello!');
+ *
+ * // Accept a discussion request
+ * await discussionService.accept(discussion);
+ *
+ * // Renew a broken discussion
+ * await discussionService.renew(contactUserId);
+ * ```
+ */
+export class DiscussionService {
+    constructor(db, announcementService, session, events = {}) {
+        Object.defineProperty(this, "db", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "announcementService", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "session", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "events", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.db = db;
+        this.announcementService = announcementService;
+        this.session = session;
+        this.events = events;
+    }
+    /**
+     * Initialize a discussion with a contact using SessionManager
+     * @param contact - The contact to start a discussion with
+     * @param message - Optional message to include in the announcement
+     * @returns The discussion ID and the created announcement
+     */
+    async initialize(contact, message) {
+        const log = logger.forMethod('initialize');
+        try {
+            const userId = this.session.userIdEncoded;
+            // Encode message as UTF-8 if provided
+            const userData = message
+                ? new TextEncoder().encode(message)
+                : new Uint8Array(0);
+            log.info(`${userId} is establishing session with contact ${contact.name}`);
+            const result = await this.announcementService.establishSession(UserPublicKeys.from_bytes(contact.publicKeys), userData);
+            let status = DiscussionStatus.PENDING;
+            if (!result.success) {
+                log.error(`Failed to establish session with contact ${contact.name}, got error: ${result.error}`);
+                // if the error is due to the session manager failed to establish outgoing session, throw the error
+                if (result.error && result.error.includes(EstablishSessionError))
+                    throw new Error(EstablishSessionError);
+                status = DiscussionStatus.SEND_FAILED;
+            }
+            else {
+                log.info(`session established with contact and announcement sent: ${result.announcement.length}... bytes`);
+            }
+            // Parse announcement message to extract only the actual message content.
+            // The message parameter may be JSON format: {"u":"username","m":"message"}
+            // We only want to store the "m" (message) field, not the full JSON.
+            let parsedAnnouncementMessage;
+            if (message) {
+                if (message.startsWith('{')) {
+                    try {
+                        const parsed = JSON.parse(message);
+                        parsedAnnouncementMessage = parsed.m?.trim() || undefined;
+                    }
+                    catch {
+                        // Invalid JSON, treat as plain text
+                        parsedAnnouncementMessage = message;
+                    }
+                }
+                else {
+                    parsedAnnouncementMessage = message;
+                }
+            }
+            // Persist discussion immediately with the announcement for reliable retry
+            const discussionId = await this.db.discussions.add({
+                ownerUserId: userId,
+                contactUserId: contact.userId,
+                direction: DiscussionDirection.INITIATED,
+                status: status,
+                nextSeeker: undefined,
+                initiationAnnouncement: result.announcement,
+                announcementMessage: parsedAnnouncementMessage,
+                unreadCount: 0,
+                createdAt: new Date(),
+                updatedAt: new Date(),
+            });
+            log.info(`discussion created with id: ${discussionId}`);
+            // Emit status change event
+            const discussion = await this.db.discussions.get(discussionId);
+            if (discussion) {
+                this.events.onDiscussionStatusChanged?.(discussion);
+            }
+            return { discussionId, announcement: result.announcement };
+        }
+        catch (error) {
+            log.error(`Failed to initialize discussion, error: ${error}`);
+            throw new Error('Discussion initialization failed, error: ' + error);
+        }
+    }
+    /**
+     * Accept a discussion request from a contact using SessionManager
+     * @param discussion - The discussion to accept
+     */
+    async accept(discussion) {
+        const log = logger.forMethod('accept');
+        try {
+            const contact = await this.db.getContactByOwnerAndUserId(discussion.ownerUserId, discussion.contactUserId);
+            if (!contact)
+                throw new Error(`Contact ${discussion.contactUserId} not found for ownerUserId ${discussion.ownerUserId}`);
+            const result = await this.announcementService.establishSession(UserPublicKeys.from_bytes(contact.publicKeys));
+            let status = DiscussionStatus.ACTIVE;
+            if (!result.success) {
+                log.error(`Failed to establish session with contact ${contact.name}, got error: ${result.error}`);
+                // if the error is due to the session manager failed to establish outgoing session, throw the error
+                if (result.error && result.error.includes(EstablishSessionError))
+                    throw new Error(EstablishSessionError);
+                status = DiscussionStatus.SEND_FAILED;
+            }
+            else {
+                log.info(`session established with contact and announcement sent: ${result.announcement.length}... bytes`);
+            }
+            // update discussion status
+            await this.db.discussions.update(discussion.id, {
+                status: status,
+                initiationAnnouncement: result.announcement,
+                updatedAt: new Date(),
+            });
+            log.info(`discussion updated in db with status: ${status}`);
+            // Emit status change event
+            const updatedDiscussion = await this.db.discussions.get(discussion.id);
+            if (updatedDiscussion) {
+                this.events.onDiscussionStatusChanged?.(updatedDiscussion);
+            }
+            return;
+        }
+        catch (error) {
+            log.error(`Failed to accept pending discussion, error: ${error}`);
+            throw new Error('Failed to accept pending discussion, error: ' + error);
+        }
+    }
+    /**
+     * Renew a discussion by resetting sent outgoing messages and sending a new announcement.
+     * @param contactUserId - The user ID of the contact whose discussion should be renewed.
+     */
+    async renew(contactUserId) {
+        const log = logger.forMethod('renew');
+        const ownerUserId = this.session.userIdEncoded;
+        const contact = await this.db.getContactByOwnerAndUserId(ownerUserId, contactUserId);
+        if (!contact)
+            throw new Error('Contact not found');
+        const existingDiscussion = await this.db.getDiscussionByOwnerAndContact(ownerUserId, contactUserId);
+        if (!existingDiscussion)
+            throw new Error('Discussion with contact ' + contact.name + ' not found');
+        log.info(`renewing discussion between ${ownerUserId} and ${contactUserId}`);
+        // reset session by creating and sending a new announcement
+        const result = await this.announcementService.establishSession(UserPublicKeys.from_bytes(contact.publicKeys));
+        // if the error is due to the session manager failed to establish outgoing session, throw the error
+        if (result.error && result.error.includes(EstablishSessionError))
+            throw new Error(EstablishSessionError);
+        // get the new session status
+        const sessionStatus = this.session.peerSessionStatus(decodeUserId(contactUserId));
+        log.info(`session status for discussion between ${ownerUserId} and ${contactUserId} after reinitiation is ${sessionStatusToString(sessionStatus)}`);
+        // Determine discussion status based on send result and session state:
+        // - SEND_FAILED: announcement couldn't be sent
+        // - ACTIVE: session fully established (peer responded)
+        // - RECONNECTING: true renewal, waiting for peer's response
+        // - PENDING: first contact retry, waiting for peer's response
+        let status;
+        if (!result.success) {
+            status = DiscussionStatus.SEND_FAILED;
+        }
+        else if (sessionStatus === SessionStatus.Active) {
+            // Session fully established (peer already responded)
+            status = DiscussionStatus.ACTIVE;
+        }
+        else if (existingDiscussion.status === DiscussionStatus.ACTIVE) {
+            // True renewal: had working session before, now recovering
+            status = DiscussionStatus.RECONNECTING;
+        }
+        else {
+            // First contact retry: never had working session
+            status = DiscussionStatus.PENDING;
+        }
+        await this.db.transaction('rw', [this.db.discussions, this.db.messages], async () => {
+            await this.db.discussions.update(existingDiscussion.id, {
+                status: status,
+                direction: DiscussionDirection.INITIATED,
+                initiationAnnouncement: result.announcement,
+                updatedAt: new Date(),
+            });
+            log.info(`discussion updated with status: ${status}`);
+            /* Reset outgoing messages that haven't been acknowledged by the peer.
+             * When session is renewed, messages encrypted with the old session
+             * may not be decryptable by the peer with the new session.
+             *
+             * Messages to reset (not acknowledged):
+             * - SENDING: Was in progress, needs re-encryption with new session
+             * - FAILED: Previous send failed, needs re-encryption
+             * - SENT: On network but not acknowledged - peer may not have received
+             *
+             * Messages to keep (acknowledged by peer):
+             * - DELIVERED: Peer confirmed receipt
+             * - READ: Peer read it
+             */
+            const messagesToReset = await this.db.messages
+                .where('[ownerUserId+contactUserId]')
+                .equals([ownerUserId, contactUserId])
+                .and(message => message.direction === MessageDirection.OUTGOING &&
+                (message.status === MessageStatus.SENDING ||
+                    message.status === MessageStatus.FAILED ||
+                    message.status === MessageStatus.SENT))
+                .modify({
+                status: MessageStatus.WAITING_SESSION,
+                encryptedMessage: undefined,
+                seeker: undefined,
+            });
+            log.info(`reset ${messagesToReset} messages to WAITING_SESSION`);
+        });
+        // Emit events after transaction completes
+        const updatedDiscussion = await this.db.discussions.get(existingDiscussion.id);
+        if (updatedDiscussion) {
+            this.events.onDiscussionStatusChanged?.(updatedDiscussion);
+            this.events.onSessionRenewed?.(updatedDiscussion);
+        }
+    }
+    /**
+     * Check if new messages can be sent to session manager for encryption.
+     * Returns false if the discussion is broken or if there are failed messages
+     * that have not been encrypted.
+     *
+     * @param ownerUserId - The owner user ID
+     * @param contactUserId - The contact user ID
+     * @returns true if discussion is in stable state for sending messages
+     */
+    async isStableState(ownerUserId, contactUserId) {
+        const log = logger.forMethod('isStableState');
+        const discussion = await this.db.getDiscussionByOwnerAndContact(ownerUserId, contactUserId);
+        if (!discussion)
+            throw new Error('Discussion not found');
+        if (discussion.status === DiscussionStatus.BROKEN) {
+            log.info(`Discussion with ownerUserId ${ownerUserId} and contactUserId ${contactUserId} is broken`);
+            return false;
+        }
+        const messages = await this.db.messages
+            .where('[ownerUserId+contactUserId+direction]')
+            .equals([
+            discussion.ownerUserId,
+            discussion.contactUserId,
+            MessageDirection.OUTGOING,
+        ])
+            .sortBy('id');
+        /* If the discussion has been broken, all non delivered messages have been marked as failed and
+        their encryptedMessage field has been deleted.
+        If there are some unencrypted unsent messages in the conversation, the discussion is not stable
+        i.e. we should not encrypt any new message via session manager before these messages are not resent */
+        if (messages.length > 0 &&
+            !messages[messages.length - 1].encryptedMessage &&
+            messages[messages.length - 1].status === MessageStatus.FAILED) {
+            log.info(`Discussion with ownerUserId ${ownerUserId} and contactUserId ${contactUserId} has no encryptedMessage failed messages`);
+            return false;
+        }
+        return true;
+    }
+}

package/dist/services/message.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Message Reception Service
+ *
+ * Handles fetching encrypted messages from the protocol and decrypting them.
+ * This service works both in host app contexts and SDK/automation context.
+ */
+import { type Message, type GossipDatabase } from '../db';
+import { IMessageProtocol } from '../api/messageProtocol';
+import { SessionModule } from '../wasm';
+import { DiscussionService } from './discussion';
+import { GossipSdkEvents } from '../types/events';
+import { SdkConfig } from '../config/sdk';
+export interface MessageResult {
+    success: boolean;
+    newMessagesCount: number;
+    error?: string;
+}
+export interface SendMessageResult {
+    success: boolean;
+    message?: Message;
+    error?: string;
+}
+export declare class MessageService {
+    private db;
+    private messageProtocol;
+    private session;
+    private discussionService;
+    private events;
+    private config;
+    constructor(db: GossipDatabase, messageProtocol: IMessageProtocol, session: SessionModule, discussionService: DiscussionService, events?: GossipSdkEvents, config?: SdkConfig);
+    fetchMessages(): Promise<MessageResult>;
+    private decryptMessages;
+    private storeDecryptedMessages;
+    findMessageBySeeker(seeker: Uint8Array, ownerUserId: string): Promise<Message | undefined>;
+    /**
+     * Check if a message is a duplicate based on content and timestamp.
+     *
+     * A message is considered duplicate if:
+     * - Same sender (contactUserId)
+     * - Same content
+     * - Incoming direction
+     * - Timestamp within deduplication window (default 30 seconds)
+     *
+     * This handles the edge case where:
+     * 1. Sender sends message successfully to network
+     * 2. Sender app crashes before updating DB status to SENT
+     * 3. On restart, message is reset to WAITING_SESSION and re-sent
+     * 4. Receiver gets the same message twice with different seekers
+     *
+     * @param ownerUserId - The owner's user ID
+     * @param contactUserId - The sender's user ID
+     * @param content - The message content
+     * @param timestamp - The message timestamp
+     * @returns true if a duplicate exists
+     */
+    private isDuplicateMessage;
+    private acknowledgeMessages;
+    sendMessage(message: Message): Promise<SendMessageResult>;
+    private serializeMessage;
+    resendMessages(messages: Map<string, Message[]>): Promise<void>;
+    /**
+     * Process messages that are waiting for an active session.
+     * Called when a session becomes Active to send queued messages.
+     * Per spec: when session becomes Active, encrypt and send WAITING_SESSION messages.
+     *
+     * @param contactUserId - The contact whose session became active
+     * @returns Number of messages successfully sent
+     */
+    processWaitingMessages(contactUserId: string): Promise<number>;
+    /**
+     * Get count of messages waiting for session with a specific contact.
+     */
+    getWaitingMessageCount(contactUserId: string): Promise<number>;
+}