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

package/src/services/refresh.ts

@@ -1,234 +0,0 @@
-/**
- * Session Refresh Service
- *
- * Class-based service to periodically refresh sessions and handle
- * keep-alive messages and broken sessions.
- */
-
-import {
-  type Discussion,
-  type GossipDatabase,
-  MessageDirection,
-  MessageStatus,
-  MessageType,
-} from '../db';
-import { sessionStatusToString } from '../wasm/session';
-import type { SessionModule } from '../wasm/session';
-import { SessionStatus } from '../assets/generated/wasm/gossip_wasm';
-import { decodeUserId, encodeUserId } from '../utils/userId';
-import { MessageService } from './message';
-import { Logger } from '../utils/logs';
-import { GossipSdkEvents } from '../types/events';
-
-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 {
-  private messageService: MessageService;
-  private session: SessionModule;
-  private events: GossipSdkEvents;
-
-  constructor(
-    _db: GossipDatabase,
-    messageService: MessageService,
-    session: SessionModule,
-    events: GossipSdkEvents = {}
-  ) {
-    // 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: Discussion[]): Promise<void> {
-    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: string[] = [];
-    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/types/events.ts

@@ -1,108 +0,0 @@
-/**
- * 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 {
-  // ─────────────────────────────────────────────────────────────────
-  // Message Events
-  // ─────────────────────────────────────────────────────────────────
-
-  /**
-   * 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;
-
-  // ─────────────────────────────────────────────────────────────────
-  // Discussion Events
-  // ─────────────────────────────────────────────────────────────────
-
-  /**
-   * 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;
-
-  // ─────────────────────────────────────────────────────────────────
-  // Session Events
-  // ─────────────────────────────────────────────────────────────────
-
-  /**
-   * 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;
-
-  // ─────────────────────────────────────────────────────────────────
-  // Error Events
-  // ─────────────────────────────────────────────────────────────────
-
-  /**
-   * 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/src/types.ts

@@ -1,70 +0,0 @@
-/**
- * SDK Types
- *
- * Re-exports types from internal SDK modules for external consumers.
- */
-
-// Database entity types
-export type {
-  Contact,
-  Message,
-  Discussion,
-  UserProfile,
-  PendingEncryptedMessage,
-  PendingAnnouncement,
-  ActiveSeeker,
-  AuthMethod,
-} from './db';
-
-// Database enums
-export {
-  DiscussionStatus,
-  MessageDirection,
-  MessageStatus,
-  DiscussionDirection,
-  MessageType,
-} from './db';
-
-// Service result types
-export type { PublicKeyResult } from './services/auth';
-export type { MessageResult, SendMessageResult } from './services/message';
-export type { AnnouncementReceptionResult } from './services/announcement';
-
-// Utility result types
-export type {
-  UpdateContactNameResult,
-  DeleteContactResult,
-} from './utils/contacts';
-export type { UpdateDiscussionNameResult } from './utils/discussions';
-
-// API types
-export type {
-  IMessageProtocol,
-  EncryptedMessage,
-  MessageProtocolResponse,
-  BulletinItem,
-} from './api/messageProtocol/types';
-
-// Wallet types (pure TypeScript types for the app to use)
-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/src/utils/base64.ts

@@ -1,39 +0,0 @@
-/**
- * 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: Uint8Array): string {
-  return btoa(
-    Array.from(data)
-      .map(byte => String.fromCharCode(byte))
-      .join('')
-  );
-}
-
-export function decodeFromBase64(b64: string): Uint8Array {
-  const decoded = atob(b64);
-  return new Uint8Array(Array.from(decoded).map(char => char.charCodeAt(0)));
-}
-
-export function encodeToBase64Url(data: Uint8Array): string {
-  return btoa(
-    Array.from(data)
-      .map(byte => String.fromCharCode(byte))
-      .join('')
-  )
-    .replace(/=/g, '')
-    .replace(/\+/g, '-')
-    .replace(/\//g, '_');
-}
-
-export function decodeFromBase64Url(base64url: string): Uint8Array {
-  const base64 = base64url
-    .replace(/-/g, '+')
-    .replace(/_/g, '/')
-    .padEnd(base64url.length + ((4 - (base64url.length % 4)) % 4), '=');
-
-  return decodeFromBase64(base64);
-}

package/src/utils/contacts.ts

@@ -1,161 +0,0 @@
-/**
- * Contact Utilities
- *
- * Functions for managing contacts including updating names and deleting contacts.
- */
-
-import { type GossipDatabase } from '../db';
-import { decodeUserId } from './userId';
-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 async function updateContactName(
-  ownerUserId: string,
-  contactUserId: string,
-  newName: string,
-  db: GossipDatabase
-): Promise<UpdateContactNameResult> {
-  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: string,
-  contactUserId: string,
-  db: GossipDatabase,
-  session: SessionModule
-): Promise<DeleteContactResult> {
-  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/src/utils/discussions.ts

@@ -1,55 +0,0 @@
-/**
- * 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 async function updateDiscussionName(
-  discussionId: number,
-  newName: string | undefined,
-  db: GossipDatabase
-): Promise<UpdateDiscussionNameResult> {
-  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.',
-    };
-  }
-}