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

package/dist/services/refresh.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Session Refresh Service
+ *
+ * Class-based service to periodically refresh sessions and handle
+ * keep-alive messages and broken sessions.
+ */
+import { type Discussion, type GossipDatabase } from '../db';
+import type { SessionModule } from '../wasm/session';
+import { MessageService } from './message';
+import { GossipSdkEvents } from '../types/events';
+/**
+ * Service for refreshing sessions and handling keep-alive messages.
+ *
+ * @example
+ * ```typescript
+ * const refreshService = new RefreshService(db, messageService, session);
+ *
+ * // Handle session refresh for active discussions
+ * await refreshService.handleSessionRefresh(activeDiscussions);
+ * ```
+ */
+export declare class RefreshService {
+    private messageService;
+    private session;
+    private events;
+    constructor(_db: GossipDatabase, messageService: MessageService, session: SessionModule, events?: GossipSdkEvents);
+    /**
+     * Handle session refresh for a given user:
+     * - Calls the SessionModule.refresh() function to get peers that require keep-alive.
+     * - For each discussion of the user:
+     *   - If the peer session status is Killed, marks the discussion as BROKEN.
+     *   - If the discussion is not BROKEN and its peer requires a keep-alive,
+     *     sends a keep-alive message via the session manager.
+     *
+     * Errors are logged via the Logger instance (log.error) but do not throw, so callers can safely
+     * invoke this periodically (e.g. from background tasks).
+     *
+     * @param activeDiscussions - Array of active discussions
+     */
+    handleSessionRefresh(activeDiscussions: Discussion[]): Promise<void>;
+}

package/dist/services/refresh.js

@@ -0,0 +1,205 @@
+/**
+ * Session Refresh Service
+ *
+ * Class-based service to periodically refresh sessions and handle
+ * keep-alive messages and broken sessions.
+ */
+import { MessageDirection, MessageStatus, MessageType, } from '../db';
+import { sessionStatusToString } from '../wasm/session';
+import { SessionStatus } from '../assets/generated/wasm/gossip_wasm';
+import { decodeUserId, encodeUserId } from '../utils/userId';
+import { Logger } from '../utils/logs';
+const logger = new Logger('RefreshService');
+/**
+ * Service for refreshing sessions and handling keep-alive messages.
+ *
+ * @example
+ * ```typescript
+ * const refreshService = new RefreshService(db, messageService, session);
+ *
+ * // Handle session refresh for active discussions
+ * await refreshService.handleSessionRefresh(activeDiscussions);
+ * ```
+ */
+export class RefreshService {
+    constructor(_db, messageService, session, events = {}) {
+        Object.defineProperty(this, "messageService", {
+            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
+        });
+        // Note: db parameter kept for API compatibility but not currently used
+        this.messageService = messageService;
+        this.session = session;
+        this.events = events;
+    }
+    /**
+     * Handle session refresh for a given user:
+     * - Calls the SessionModule.refresh() function to get peers that require keep-alive.
+     * - For each discussion of the user:
+     *   - If the peer session status is Killed, marks the discussion as BROKEN.
+     *   - If the discussion is not BROKEN and its peer requires a keep-alive,
+     *     sends a keep-alive message via the session manager.
+     *
+     * Errors are logged via the Logger instance (log.error) but do not throw, so callers can safely
+     * invoke this periodically (e.g. from background tasks).
+     *
+     * @param activeDiscussions - Array of active discussions
+     */
+    async handleSessionRefresh(activeDiscussions) {
+        const log = logger.forMethod('handleSessionRefresh');
+        const ownerUserId = this.session.userIdEncoded;
+        log.info('calling session refresh', {
+            ownerUserId: ownerUserId,
+            discussions: activeDiscussions.map(discussion => discussion.contactUserId),
+        });
+        if (!activeDiscussions.length) {
+            return;
+        }
+        if (!ownerUserId) {
+            log.error('ownerUserId is empty, skipping session refresh');
+            return;
+        }
+        // Log session status BEFORE refresh for debugging
+        const statusBefore = activeDiscussions.map(d => {
+            try {
+                const peerId = decodeUserId(d.contactUserId);
+                const status = this.session.peerSessionStatus(peerId);
+                return {
+                    contact: d.contactUserId.slice(0, 12),
+                    status: sessionStatusToString(status),
+                };
+            }
+            catch {
+                return { contact: d.contactUserId.slice(0, 12), status: 'ERROR' };
+            }
+        });
+        console.log('[SessionStatus] Before refresh():', statusBefore);
+        let keepAlivePeerIds = [];
+        try {
+            // Ask the session manager which peers require keep-alive messages
+            // WARNING: refresh() may KILL sessions based on timeout logic!
+            const refreshResult = await this.session.refresh();
+            keepAlivePeerIds = refreshResult.map(peer => encodeUserId(peer));
+        }
+        catch (error) {
+            log.error('error while refreshing session', { error });
+            return;
+        }
+        // Log session status AFTER refresh for debugging
+        const statusAfter = activeDiscussions.map(d => {
+            try {
+                const peerId = decodeUserId(d.contactUserId);
+                const status = this.session.peerSessionStatus(peerId);
+                return {
+                    contact: d.contactUserId.slice(0, 12),
+                    status: sessionStatusToString(status),
+                };
+            }
+            catch {
+                return { contact: d.contactUserId.slice(0, 12), status: 'ERROR' };
+            }
+        });
+        console.log('[SessionStatus] After refresh():', statusAfter);
+        /* refresh function kill sessions that have no incoming messages for a long time
+        So we need to mark corresponding discussions as broken if it is the case */
+        for (const discussion of activeDiscussions) {
+            try {
+                // Decode contact userId to the peerId format expected by SessionModule
+                const peerId = decodeUserId(discussion.contactUserId);
+                // Check current session status for this peer
+                const status = this.session.peerSessionStatus(peerId);
+                // Per spec: when session is Killed/Saturated/UnknownPeer/NoSession,
+                // trigger auto-renewal instead of marking as BROKEN
+                const needsRenewal = [
+                    SessionStatus.Killed,
+                    SessionStatus.Saturated,
+                    SessionStatus.NoSession,
+                    SessionStatus.UnknownPeer,
+                ].includes(status);
+                if (needsRenewal) {
+                    // Log clearly to console for debugging
+                    console.warn(`[SessionStatus] ${discussion.contactUserId.slice(0, 16)}... -> ${sessionStatusToString(status)} (triggering renewal)`);
+                    log.info('session needs renewal, triggering auto-renewal', {
+                        ownerUserId: discussion.ownerUserId,
+                        contactUserId: discussion.contactUserId,
+                        sessionStatus: sessionStatusToString(status),
+                    });
+                    // Trigger auto-renewal (spec: call create_session)
+                    this.events.onSessionRenewalNeeded?.(discussion.contactUserId);
+                    continue;
+                }
+                // PeerRequested for an active discussion is a state inconsistency:
+                // - DB says discussion is ACTIVE (we accepted)
+                // - Session manager says PeerRequested (we haven't accepted)
+                // This should not happen - throw to surface the bug rather than hide it
+                if (status === SessionStatus.PeerRequested) {
+                    const error = new Error(`Unexpected PeerRequested status for active discussion with ${discussion.contactUserId}. ` +
+                        `This indicates a state inconsistency between the database and session manager.`);
+                    log.error('state inconsistency detected', {
+                        error,
+                        discussionId: discussion.id,
+                    });
+                    throw error;
+                }
+            }
+            catch (error) {
+                log.error('error while processing discussion', {
+                    error: error,
+                    discussionId: discussion.id,
+                });
+                // Re-throw state inconsistency errors - they should surface
+                if (error instanceof Error &&
+                    error.message.includes('state inconsistency')) {
+                    throw error;
+                }
+                continue;
+            }
+            // Check if this peer requires a keep-alive
+            const needsKeepAlive = keepAlivePeerIds.some(peer => peer === discussion.contactUserId);
+            if (!needsKeepAlive) {
+                continue;
+            }
+            log.info('discussion does require a keep-alive message.', {
+                ownerUserId: discussion.ownerUserId,
+                contactUserId: discussion.contactUserId,
+            });
+            try {
+                // Send a keep-alive message via the session manager
+                await this.messageService.sendMessage({
+                    ownerUserId: discussion.ownerUserId,
+                    contactUserId: discussion.contactUserId,
+                    content: '',
+                    type: MessageType.KEEP_ALIVE,
+                    direction: MessageDirection.OUTGOING,
+                    status: MessageStatus.SENDING,
+                    timestamp: new Date(),
+                });
+                log.info('keep-alive message sent successfully.', {
+                    ownerUserId: discussion.ownerUserId,
+                    contactUserId: discussion.contactUserId,
+                });
+            }
+            catch (error) {
+                log.error('failed to send keep-alive message', {
+                    error: error,
+                    discussionId: discussion.id,
+                    sessionStatus: sessionStatusToString(this.session.peerSessionStatus(decodeUserId(discussion.contactUserId))),
+                });
+            }
+        }
+    }
+}

package/{src/sw.ts → dist/sw.d.ts}

@@ -7,11 +7,4 @@
  * It re-exports only the message protocol types and helpers required by
  * the Gossip PWA service worker.
  */
-
-export {
-  RestMessageProtocol,
-  type EncryptedMessage,
-  type IMessageProtocol,
-  type MessageProtocolResponse,
-  type BulletinItem,
-} from './api/messageProtocol';
+export { RestMessageProtocol, type EncryptedMessage, type IMessageProtocol, type MessageProtocolResponse, type BulletinItem, } from './api/messageProtocol';

package/dist/sw.js

@@ -0,0 +1,10 @@
+/**
+ * Service Worker entry for Gossip SDK
+ *
+ * This entry is safe for use in service workers and other lightweight
+ * environments where the full SDK (including WASM bindings) is not needed.
+ *
+ * It re-exports only the message protocol types and helpers required by
+ * the Gossip PWA service worker.
+ */
+export { RestMessageProtocol, } from './api/messageProtocol';

package/dist/types/events.d.ts

@@ -0,0 +1,80 @@
+/**
+ * SDK Event Types
+ *
+ * Event handlers for SDK events. These are used by the SDK to notify
+ * the host application about state changes.
+ */
+import { Message, Discussion, Contact } from '../db';
+/**
+ * Event handlers for SDK events.
+ *
+ * The SDK emits events when things happen (messages received, discussions created, etc.)
+ * Your app can listen to these events and update its own state (zustand, redux, etc.)
+ *
+ * This pattern keeps the SDK decoupled from any specific state management solution.
+ */
+export interface GossipSdkEvents {
+    /**
+     * Called when a new message is received from a contact.
+     * Use this to update your message list UI.
+     */
+    onMessageReceived?: (message: Message) => void;
+    /**
+     * Called when a message is successfully sent.
+     * Use this to update message status in UI (sending → sent).
+     */
+    onMessageSent?: (message: Message) => void;
+    /**
+     * Called when sending a message fails.
+     * Use this to show error state and allow retry.
+     */
+    onMessageFailed?: (message: Message, error: Error) => void;
+    /**
+     * Called when someone sends you a discussion request (announcement).
+     * Use this to show the request in your discussion list.
+     */
+    onDiscussionRequest?: (discussion: Discussion, contact: Contact) => void;
+    /**
+     * Called when a discussion status changes (accepted, broken, etc.).
+     * Use this to update discussion state in UI.
+     */
+    onDiscussionStatusChanged?: (discussion: Discussion) => void;
+    /**
+     * Called when a session with a contact is broken and needs renewal.
+     * Use this to show appropriate UI state.
+     * @deprecated Use onSessionRenewalNeeded for auto-renewal flow
+     */
+    onSessionBroken?: (discussion: Discussion) => void;
+    /**
+     * Called when a session is successfully renewed.
+     */
+    onSessionRenewed?: (discussion: Discussion) => void;
+    /**
+     * Called when a session needs to be renewed (auto-renewal).
+     * The SDK will automatically attempt to renew the session.
+     * Messages are queued with WAITING_SESSION status until session is active.
+     */
+    onSessionRenewalNeeded?: (contactUserId: string) => void;
+    /**
+     * Called when a peer has requested a session and we need to accept it.
+     * This is different from renewal - the peer has sent us an announcement
+     * and we need to respond (via DiscussionService.accept()).
+     * NOT calling this correctly can cause stuck sessions (both sides waiting).
+     */
+    onSessionAcceptNeeded?: (contactUserId: string) => void;
+    /**
+     * Called when a session becomes Active after peer accepts our announcement.
+     * This happens when we initiated a session (SelfRequested) and the peer
+     * accepted it by sending their announcement back.
+     * Use this to process any messages that were queued as WAITING_SESSION.
+     */
+    onSessionBecameActive?: (contactUserId: string) => void;
+    /**
+     * Called when an error occurs in any SDK operation.
+     * Use this for logging, error reporting, or showing error toasts.
+     *
+     * @param error - The error that occurred
+     * @param context - Where the error occurred (e.g., 'message.send', 'announcement.fetch')
+     */
+    onError?: (error: Error, context: string) => void;
+}

package/dist/types/events.js

@@ -0,0 +1,7 @@
+/**
+ * SDK Event Types
+ *
+ * Event handlers for SDK events. These are used by the SDK to notify
+ * the host application about state changes.
+ */
+export {};

package/dist/types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * SDK Types
+ *
+ * Re-exports types from internal SDK modules for external consumers.
+ */
+export type { Contact, Message, Discussion, UserProfile, PendingEncryptedMessage, PendingAnnouncement, ActiveSeeker, AuthMethod, } from './db';
+export { DiscussionStatus, MessageDirection, MessageStatus, DiscussionDirection, MessageType, } from './db';
+export type { PublicKeyResult } from './services/auth';
+export type { MessageResult, SendMessageResult } from './services/message';
+export type { AnnouncementReceptionResult } from './services/announcement';
+export type { UpdateContactNameResult, DeleteContactResult, } from './utils/contacts';
+export type { UpdateDiscussionNameResult } from './utils/discussions';
+export type { IMessageProtocol, EncryptedMessage, MessageProtocolResponse, BulletinItem, } from './api/messageProtocol/types';
+export type Ticker = string;
+export interface TokenMeta {
+    address: string;
+    name: string;
+    ticker: Ticker;
+    icon: string;
+    decimals: number;
+    isNative: boolean;
+}
+export interface TokenState extends TokenMeta {
+    balance: bigint | null;
+    priceUsd: number | null;
+    valueUsd: number | null;
+}
+export interface FeeConfig {
+    type: 'preset' | 'custom';
+    preset?: 'low' | 'standard' | 'high';
+    customFee?: string;
+}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * SDK Types
+ *
+ * Re-exports types from internal SDK modules for external consumers.
+ */
+// Database enums
+export { DiscussionStatus, MessageDirection, MessageStatus, DiscussionDirection, MessageType, } from './db';

package/dist/utils/base64.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Base64 encoding/decoding utilities
+ *
+ * Provides functions for converting between Uint8Array and Base64 strings.
+ * Supports both standard and URL-safe Base64 encoding.
+ */
+export declare function encodeToBase64(data: Uint8Array): string;
+export declare function decodeFromBase64(b64: string): Uint8Array;
+export declare function encodeToBase64Url(data: Uint8Array): string;
+export declare function decodeFromBase64Url(base64url: string): Uint8Array;

package/dist/utils/base64.js

@@ -0,0 +1,30 @@
+/**
+ * Base64 encoding/decoding utilities
+ *
+ * Provides functions for converting between Uint8Array and Base64 strings.
+ * Supports both standard and URL-safe Base64 encoding.
+ */
+export function encodeToBase64(data) {
+    return btoa(Array.from(data)
+        .map(byte => String.fromCharCode(byte))
+        .join(''));
+}
+export function decodeFromBase64(b64) {
+    const decoded = atob(b64);
+    return new Uint8Array(Array.from(decoded).map(char => char.charCodeAt(0)));
+}
+export function encodeToBase64Url(data) {
+    return btoa(Array.from(data)
+        .map(byte => String.fromCharCode(byte))
+        .join(''))
+        .replace(/=/g, '')
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_');
+}
+export function decodeFromBase64Url(base64url) {
+    const base64 = base64url
+        .replace(/-/g, '+')
+        .replace(/_/g, '/')
+        .padEnd(base64url.length + ((4 - (base64url.length % 4)) % 4), '=');
+    return decodeFromBase64(base64);
+}

package/dist/utils/contacts.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Contact Utilities
+ *
+ * Functions for managing contacts including updating names and deleting contacts.
+ */
+import { type GossipDatabase } from '../db';
+import type { SessionModule } from '../wasm/session';
+export type UpdateContactNameResult = {
+    success: true;
+    trimmedName: string;
+} | {
+    success: false;
+    reason: 'empty' | 'duplicate' | 'error';
+    message: string;
+};
+export type DeleteContactResult = {
+    success: true;
+} | {
+    success: false;
+    reason: 'not_found' | 'error';
+    message: string;
+};
+/**
+ * Update the name of a contact
+ *
+ * @param ownerUserId - Owner user ID
+ * @param contactUserId - Contact user ID
+ * @param newName - New name for the contact
+ * @param db - Database instance
+ * @returns Result with success status
+ */
+export declare function updateContactName(ownerUserId: string, contactUserId: string, newName: string, db: GossipDatabase): Promise<UpdateContactNameResult>;
+/**
+ * Delete a contact and all associated discussions and messages
+ *
+ * @param ownerUserId - Owner user ID
+ * @param contactUserId - Contact user ID
+ * @param db - Database instance
+ * @param session - Session module for peer management
+ * @returns Result with success status
+ */
+export declare function deleteContact(ownerUserId: string, contactUserId: string, db: GossipDatabase, session: SessionModule): Promise<DeleteContactResult>;

package/dist/utils/contacts.js

@@ -0,0 +1,113 @@
+/**
+ * Contact Utilities
+ *
+ * Functions for managing contacts including updating names and deleting contacts.
+ */
+import { decodeUserId } from './userId';
+/**
+ * Update the name of a contact
+ *
+ * @param ownerUserId - Owner user ID
+ * @param contactUserId - Contact user ID
+ * @param newName - New name for the contact
+ * @param db - Database instance
+ * @returns Result with success status
+ */
+export async function updateContactName(ownerUserId, contactUserId, newName, db) {
+    if (!ownerUserId || !contactUserId) {
+        return {
+            success: false,
+            reason: 'error',
+            message: 'Invalid parameters.',
+        };
+    }
+    const trimmed = newName.trim();
+    if (!trimmed)
+        return {
+            success: false,
+            reason: 'empty',
+            message: 'Name cannot be empty.',
+        };
+    try {
+        const list = await db.getContactsByOwner(ownerUserId);
+        const duplicate = list.find(contact => contact.userId !== contactUserId &&
+            contact.name.toLowerCase() === trimmed.toLowerCase());
+        if (duplicate)
+            return {
+                success: false,
+                reason: 'duplicate',
+                message: 'This name is already used by another contact.',
+            };
+        await db.contacts
+            .where('[ownerUserId+userId]')
+            .equals([ownerUserId, contactUserId])
+            .modify({ name: trimmed });
+        return { success: true, trimmedName: trimmed };
+    }
+    catch (e) {
+        console.error('updateContactName failed', e);
+        return {
+            success: false,
+            reason: 'error',
+            message: 'Failed to update name. Please try again.',
+        };
+    }
+}
+/**
+ * Delete a contact and all associated discussions and messages
+ *
+ * @param ownerUserId - Owner user ID
+ * @param contactUserId - Contact user ID
+ * @param db - Database instance
+ * @param session - Session module for peer management
+ * @returns Result with success status
+ */
+export async function deleteContact(ownerUserId, contactUserId, db, session) {
+    try {
+        if (!ownerUserId || !contactUserId) {
+            return {
+                success: false,
+                reason: 'error',
+                message: 'Invalid parameters.',
+            };
+        }
+        // Verify contact exists
+        const contact = await db.getContactByOwnerAndUserId(ownerUserId, contactUserId);
+        if (!contact) {
+            return {
+                success: false,
+                reason: 'not_found',
+                message: 'Contact not found.',
+            };
+        }
+        // Delete in a transaction to ensure atomicity
+        await db.transaction('rw', [db.contacts, db.discussions, db.messages], async () => {
+            // Delete the contact
+            await db.contacts
+                .where('[ownerUserId+userId]')
+                .equals([ownerUserId, contactUserId])
+                .delete();
+            // Delete related discussions
+            await db.discussions
+                .where('[ownerUserId+contactUserId]')
+                .equals([ownerUserId, contactUserId])
+                .delete();
+            // Delete related messages
+            await db.messages
+                .where('[ownerUserId+contactUserId]')
+                .equals([ownerUserId, contactUserId])
+                .delete();
+        });
+        // Discard peer from session manager and persist
+        await session.peerDiscard(decodeUserId(contactUserId));
+        return { success: true };
+    }
+    catch (e) {
+        console.error('deleteContact failed', e);
+        return {
+            success: false,
+            reason: 'error',
+            message: 'Failed to delete contact. Please try again.',
+        };
+    }
+}

package/dist/utils/discussions.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Discussion Utilities
+ *
+ * Functions for managing discussion metadata.
+ */
+import { type GossipDatabase } from '../db';
+export type UpdateDiscussionNameResult = {
+    success: true;
+    trimmedName: string | undefined;
+} | {
+    success: false;
+    reason: 'not_found' | 'error';
+    message: string;
+};
+/**
+ * Update the custom name of a discussion.
+ * Pass an empty string or undefined to clear the custom name (will revert to contact name).
+ *
+ * @param discussionId - The discussion ID to update
+ * @param newName - The new custom name (or empty/undefined to clear)
+ * @param db - Database instance
+ * @returns Result with success status
+ */
+export declare function updateDiscussionName(discussionId: number, newName: string | undefined, db: GossipDatabase): Promise<UpdateDiscussionNameResult>;

package/dist/utils/discussions.js

@@ -0,0 +1,38 @@
+/**
+ * Discussion Utilities
+ *
+ * Functions for managing discussion metadata.
+ */
+/**
+ * Update the custom name of a discussion.
+ * Pass an empty string or undefined to clear the custom name (will revert to contact name).
+ *
+ * @param discussionId - The discussion ID to update
+ * @param newName - The new custom name (or empty/undefined to clear)
+ * @param db - Database instance
+ * @returns Result with success status
+ */
+export async function updateDiscussionName(discussionId, newName, db) {
+    const trimmed = newName?.trim();
+    const customName = trimmed && trimmed.length > 0 ? trimmed : undefined;
+    try {
+        const discussion = await db.discussions.get(discussionId);
+        if (!discussion) {
+            return {
+                success: false,
+                reason: 'not_found',
+                message: 'Discussion not found.',
+            };
+        }
+        await db.discussions.update(discussionId, { customName });
+        return { success: true, trimmedName: customName };
+    }
+    catch (e) {
+        console.error('updateDiscussionName failed', e);
+        return {
+            success: false,
+            reason: 'error',
+            message: 'Failed to update name. Please try again.',
+        };
+    }
+}