@massalabs/gossip-sdk 0.0.1

package/src/api/messageProtocol/rest.ts

@@ -0,0 +1,209 @@
+/**
+ * REST API implementation of the message protocol
+ */
+
+import {
+  BulletinItem,
+  EncryptedMessage,
+  IMessageProtocol,
+  MessageProtocolResponse,
+} from './types';
+import { encodeToBase64, decodeFromBase64 } from '../../utils/base64';
+
+const BULLETIN_ENDPOINT = '/bulletin';
+const MESSAGES_ENDPOINT = '/messages';
+
+export type BulletinsPage = {
+  counter: string;
+  data: string;
+}[];
+
+type FetchMessagesResponse = {
+  key: string;
+  value: string;
+};
+
+export class RestMessageProtocol implements IMessageProtocol {
+  constructor(
+    private baseUrl: string,
+    private timeout: number = 10000,
+    private retryAttempts: number = 3
+  ) {}
+
+  // TODO: Implement a fetch with pagination to avoid fetching all messages at once
+  async fetchMessages(seekers: Uint8Array[]): Promise<EncryptedMessage[]> {
+    const url = `${this.baseUrl}${MESSAGES_ENDPOINT}/fetch`;
+
+    const response = await this.makeRequest<FetchMessagesResponse[]>(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ seekers: seekers.map(encodeToBase64) }),
+    });
+
+    if (!response.success || !response.data) {
+      throw new Error(response.error || 'Failed to fetch messages');
+    }
+
+    return response.data.map((item: FetchMessagesResponse) => {
+      const seeker = decodeFromBase64(item.key);
+      const ciphertext = decodeFromBase64(item.value);
+
+      return {
+        seeker,
+        ciphertext,
+      };
+    });
+  }
+
+  async sendMessage(message: EncryptedMessage): Promise<void> {
+    const url = `${this.baseUrl}${MESSAGES_ENDPOINT}/`;
+
+    const response = await this.makeRequest<void>(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        key: encodeToBase64(message.seeker),
+        value: encodeToBase64(message.ciphertext),
+      }),
+    });
+
+    if (!response.success) {
+      throw new Error(response.error || 'Failed to send message');
+    }
+  }
+
+  async sendAnnouncement(announcement: Uint8Array): Promise<string> {
+    const url = `${this.baseUrl}${BULLETIN_ENDPOINT}`;
+
+    const response = await this.makeRequest<{ counter: string }>(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        data: encodeToBase64(announcement),
+      }),
+    });
+
+    if (!response.success || !response.data) {
+      throw new Error(response.error || 'Failed to broadcast outgoing session');
+    }
+
+    return response.data.counter;
+  }
+
+  async fetchAnnouncements(
+    limit: number = 50,
+    cursor?: string
+  ): Promise<BulletinItem[]> {
+    const params = new URLSearchParams();
+
+    params.set('limit', limit.toString());
+    // Always pass 'after' parameter. If cursor is undefined, use '0' to fetch from the beginning.
+    // This ensures pagination works correctly: after=0 gets counters 1-20, after=20 gets 21-40, etc.
+    params.set('after', cursor ?? '0');
+
+    const url = `${this.baseUrl}${BULLETIN_ENDPOINT}?${params.toString()}`;
+
+    const response = await this.makeRequest<BulletinsPage>(url, {
+      method: 'GET',
+    });
+
+    if (!response.success || response.data == null) {
+      throw new Error(response.error || 'Failed to fetch announcements');
+    }
+
+    return response.data.map(item => ({
+      counter: item.counter,
+      data: decodeFromBase64(item.data),
+    }));
+  }
+
+  async fetchPublicKeyByUserId(userId: Uint8Array): Promise<string> {
+    const response = await this.makeRequest<{ value: string }>(
+      `${this.baseUrl}/auth/retrieve`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ key: encodeToBase64(userId) }),
+      }
+    );
+
+    if (!response.success || !response.data) {
+      throw new Error(response.error || 'Failed to fetch public key');
+    }
+
+    if (!response.data.value) {
+      throw new Error('Public key not found');
+    }
+
+    return response.data.value;
+  }
+
+  async postPublicKey(base64PublicKeys: string): Promise<string> {
+    const url = `${this.baseUrl}/auth`;
+
+    const response = await this.makeRequest<{ value: string }>(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ value: base64PublicKeys }),
+    });
+
+    if (!response.success || !response.data) {
+      const errorMessage = response.error || 'Failed to store public key';
+      throw new Error(errorMessage);
+    }
+
+    return response.data.value;
+  }
+
+  private async makeRequest<T>(
+    url: string,
+    options: RequestInit
+  ): Promise<MessageProtocolResponse<T>> {
+    let lastError: Error | null = null;
+
+    for (let attempt = 1; attempt <= this.retryAttempts; attempt++) {
+      try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+        const response = await fetch(url, {
+          ...options,
+          signal: controller.signal,
+        });
+
+        clearTimeout(timeoutId);
+
+        if (!response.ok) {
+          throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+
+        const data = await response.json();
+        return { success: true, data };
+      } catch (error) {
+        lastError = error as Error;
+        console.warn(`Request attempt ${attempt} failed:`, error);
+
+        if (attempt < this.retryAttempts) {
+          // Exponential backoff
+          const delay = Math.pow(2, attempt) * 1000;
+          await new Promise(resolve => setTimeout(resolve, delay));
+        }
+      }
+    }
+
+    return {
+      success: false,
+      error: lastError?.message || 'Request failed after all retry attempts',
+    };
+  }
+
+  async changeNode(nodeUrl?: string): Promise<MessageProtocolResponse> {
+    return {
+      success: true,
+      data:
+        'This message protocol provider use a single node, so changing the node to ' +
+        nodeUrl +
+        ' is not supported',
+    };
+  }
+}

package/src/api/messageProtocol/types.ts

@@ -0,0 +1,70 @@
+/**
+ * Message Protocol Types and Interfaces
+ *
+ * Defines the core types and interfaces for message protocol operations.
+ */
+
+export type BulletinItem = {
+  counter: string;
+  data: Uint8Array;
+};
+
+export interface EncryptedMessage {
+  seeker: Uint8Array;
+  ciphertext: Uint8Array;
+}
+
+export interface MessageProtocolResponse<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: string;
+}
+
+/**
+ * Abstract interface for message protocol operations
+ */
+export interface IMessageProtocol {
+  /**
+   * Fetch encrypted messages for the provided set of seeker read keys
+   */
+  fetchMessages(seekers: Uint8Array[]): Promise<EncryptedMessage[]>;
+
+  /**
+   * Send an encrypted message to the key-value store
+   */
+  sendMessage(message: EncryptedMessage): Promise<void>;
+
+  /**
+   * Broadcast an outgoing session announcement produced by WASM.
+   * Returns the bulletin counter provided by the API.
+   */
+  sendAnnouncement(announcement: Uint8Array): Promise<string>;
+  /**
+   * Fetch incoming discussion announcements from the bulletin storage.
+   * Returns raw announcement bytes as provided by the API.
+   * @param limit - Maximum number of announcements to fetch (default: 20)
+   * @param cursor - Optional cursor (counter) to fetch announcements after this value
+   */
+  fetchAnnouncements(limit?: number, cursor?: string): Promise<BulletinItem[]>;
+
+  /**
+   * Fetch public key by userId hash (base64 string)
+   * @param userId - Decoded userId bytes
+   * @returns Base64-encoded public keys
+   */
+  fetchPublicKeyByUserId(userId: Uint8Array): Promise<string>;
+
+  /**
+   * Store public key in the auth API
+   * @param base64PublicKeys - Base64-encoded public keys
+   * @returns The hash key (hex string) returned by the API
+   */
+  postPublicKey(base64PublicKeys: string): Promise<string>;
+
+  /**
+   * Change the current node provider
+   * @param nodeUrl - The URL of the new node
+   * @returns MessageProtocolResponse with the new node information
+   */
+  changeNode(nodeUrl?: string): Promise<MessageProtocolResponse>;
+}

package/src/config/protocol.ts

@@ -0,0 +1,97 @@
+/**
+ * Protocol API Configuration
+ *
+ * Centralized configuration for the message protocol API endpoints.
+ * This allows easy switching between different protocol implementations.
+ */
+
+export interface ProtocolConfig {
+  baseUrl: string;
+  timeout: number;
+  retryAttempts: number;
+}
+
+// Default API URL for the hosted REST protocol.
+// Override via setProtocolBaseUrl() or environment variables.
+const DEFAULT_API_URL = 'https://api.usegossip.com';
+
+// Mutable config that can be updated at runtime
+let currentBaseUrl: string | null = null;
+
+function buildProtocolApiBaseUrl(): string {
+  // If runtime override is set, use it
+  if (currentBaseUrl !== null) {
+    return currentBaseUrl;
+  }
+
+  // Try to get from environment variable (Vite)
+  let apiUrl: string | undefined;
+  try {
+    // Check if import.meta.env is available (Vite environment)
+    if (
+      typeof import.meta !== 'undefined' &&
+      import.meta.env?.VITE_GOSSIP_API_URL
+    ) {
+      apiUrl = import.meta.env.VITE_GOSSIP_API_URL;
+    }
+  } catch {
+    // import.meta.env not available (Node.js without Vite)
+  }
+
+  // Check process.env for Node.js environment
+  if (
+    !apiUrl &&
+    typeof process !== 'undefined' &&
+    process.env?.GOSSIP_API_URL
+  ) {
+    apiUrl = process.env.GOSSIP_API_URL;
+  }
+
+  // Fall back to default
+  if (!apiUrl) apiUrl = DEFAULT_API_URL;
+
+  // Normalize trailing slashes to avoid `//api`
+  const trimmed = apiUrl.replace(/\/+$/, '');
+  return `${trimmed}/api`;
+}
+
+export const protocolConfig: ProtocolConfig = {
+  get baseUrl() {
+    return buildProtocolApiBaseUrl();
+  },
+  timeout: 10000,
+  retryAttempts: 3,
+};
+
+export enum MessageProtocolType {
+  REST = 'rest',
+  MOCK = 'mock',
+}
+
+export const defaultMessageProtocol: MessageProtocolType =
+  MessageProtocolType.REST;
+
+/**
+ * Set the base URL for the protocol API at runtime.
+ * This overrides environment variables and defaults.
+ *
+ * @param baseUrl - The base URL to use (e.g., 'https://api.example.com/api')
+ *
+ * @example
+ * ```typescript
+ * import { setProtocolBaseUrl } from 'gossip-sdk';
+ *
+ * // Set custom API endpoint
+ * setProtocolBaseUrl('https://my-server.com/api');
+ * ```
+ */
+export function setProtocolBaseUrl(baseUrl: string): void {
+  currentBaseUrl = baseUrl;
+}
+
+/**
+ * Reset the base URL to use environment variables or defaults.
+ */
+export function resetProtocolBaseUrl(): void {
+  currentBaseUrl = null;
+}

package/src/config/sdk.ts

@@ -0,0 +1,131 @@
+/**
+ * SDK Configuration
+ *
+ * Centralized configuration for the Gossip SDK.
+ * All values have sensible defaults that can be overridden.
+ */
+
+/**
+ * Protocol configuration for network requests
+ */
+export interface ProtocolConfig {
+  /** API base URL (default: from environment or https://api.usegossip.com) */
+  baseUrl?: string;
+  /** Request timeout in milliseconds (default: 10000) */
+  timeout: number;
+  /** Number of retry attempts for failed requests (default: 3) */
+  retryAttempts: number;
+}
+
+/**
+ * Polling configuration for automatic message/announcement fetching
+ */
+export interface PollingConfig {
+  /** Enable automatic polling (default: false) */
+  enabled: boolean;
+  /** Interval for fetching messages in milliseconds (default: 5000) */
+  messagesIntervalMs: number;
+  /** Interval for fetching announcements in milliseconds (default: 10000) */
+  announcementsIntervalMs: number;
+  /** Interval for session refresh/keep-alive in milliseconds (default: 30000) */
+  sessionRefreshIntervalMs: number;
+}
+
+/**
+ * Message fetching configuration
+ */
+export interface MessagesConfig {
+  /** Delay between fetch iterations in milliseconds (default: 100) */
+  fetchDelayMs: number;
+  /** Maximum number of fetch iterations per call (default: 30) */
+  maxFetchIterations: number;
+  /**
+   * Time window in milliseconds for duplicate detection (default: 30000 = 30 seconds).
+   * Messages with same content from same sender within this window are considered duplicates.
+   * This handles edge case where app crashes after network send but before DB update,
+   * resulting in message being re-sent on restart.
+   */
+  deduplicationWindowMs: number;
+}
+
+/**
+ * Announcement configuration
+ */
+export interface AnnouncementsConfig {
+  /** Maximum announcements to fetch per request (default: 500) */
+  fetchLimit: number;
+  /** Time before marking failed announcements as broken in ms (default: 3600000 = 1 hour) */
+  brokenThresholdMs: number;
+}
+
+/**
+ * Complete SDK configuration
+ */
+export interface SdkConfig {
+  /** Network/protocol settings */
+  protocol: ProtocolConfig;
+  /** Automatic polling settings */
+  polling: PollingConfig;
+  /** Message fetching settings */
+  messages: MessagesConfig;
+  /** Announcement settings */
+  announcements: AnnouncementsConfig;
+}
+
+/**
+ * Default SDK configuration values
+ */
+export const defaultSdkConfig: SdkConfig = {
+  protocol: {
+    timeout: 10000,
+    retryAttempts: 3,
+  },
+  polling: {
+    enabled: false,
+    messagesIntervalMs: 5000,
+    announcementsIntervalMs: 10000,
+    sessionRefreshIntervalMs: 30000,
+  },
+  messages: {
+    fetchDelayMs: 100,
+    maxFetchIterations: 30,
+    deduplicationWindowMs: 30000, // 30 seconds
+  },
+  announcements: {
+    fetchLimit: 500,
+    brokenThresholdMs: 60 * 60 * 1000, // 1 hour
+  },
+};
+
+/**
+ * Deep merge partial config with defaults
+ */
+export function mergeConfig(partial?: DeepPartial<SdkConfig>): SdkConfig {
+  if (!partial) return { ...defaultSdkConfig };
+
+  return {
+    protocol: {
+      ...defaultSdkConfig.protocol,
+      ...partial.protocol,
+    },
+    polling: {
+      ...defaultSdkConfig.polling,
+      ...partial.polling,
+    },
+    messages: {
+      ...defaultSdkConfig.messages,
+      ...partial.messages,
+    },
+    announcements: {
+      ...defaultSdkConfig.announcements,
+      ...partial.announcements,
+    },
+  };
+}
+
+/**
+ * Helper type for deep partial objects
+ */
+export type DeepPartial<T> = {
+  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};

package/src/contacts.ts

@@ -0,0 +1,210 @@
+/**
+ * Contact Management SDK
+ *
+ * Functions for managing contacts including CRUD operations.
+ *
+ * @example
+ * ```typescript
+ * import { getContacts, addContact, deleteContact } from 'gossip-sdk';
+ *
+ * // Get all contacts
+ * const contacts = await getContacts(userId);
+ *
+ * // Add a new contact
+ * const result = await addContact(userId, contactUserId, 'Alice', publicKeys);
+ *
+ * // Delete a contact
+ * await deleteContact(userId, contactUserId);
+ * ```
+ */
+
+import {
+  updateContactName as updateContactNameUtil,
+  deleteContact as deleteContactUtil,
+} from './utils/contacts';
+import { type Contact, type GossipDatabase } from './db';
+import type {
+  UpdateContactNameResult,
+  DeleteContactResult,
+} from './utils/contacts';
+import type { UserPublicKeys } from './assets/generated/wasm/gossip_wasm';
+import type { SessionModule } from './wasm/session';
+
+// Re-export result types
+export type { UpdateContactNameResult, DeleteContactResult };
+
+/**
+ * Get all contacts for an owner.
+ *
+ * @param ownerUserId - The user ID of the contact owner
+ * @param db - Database instance
+ * @returns Array of contacts
+ *
+ * @example
+ * ```typescript
+ * const contacts = await getContacts(myUserId, db);
+ * contacts.forEach(c => console.log(c.name, c.userId));
+ * ```
+ */
+export async function getContacts(
+  ownerUserId: string,
+  db: GossipDatabase
+): Promise<Contact[]> {
+  try {
+    return await db.getContactsByOwner(ownerUserId);
+  } catch (error) {
+    console.error('Error getting contacts:', error);
+    return [];
+  }
+}
+
+/**
+ * Get a specific contact by owner and contact user IDs.
+ *
+ * @param ownerUserId - The user ID of the contact owner
+ * @param contactUserId - The user ID of the contact
+ * @param db - Database instance
+ * @returns Contact or null if not found
+ *
+ * @example
+ * ```typescript
+ * const contact = await getContact(myUserId, theirUserId, db);
+ * if (contact) {
+ *   console.log('Found contact:', contact.name);
+ * }
+ * ```
+ */
+export async function getContact(
+  ownerUserId: string,
+  contactUserId: string,
+  db: GossipDatabase
+): Promise<Contact | null> {
+  try {
+    const contact = await db.getContactByOwnerAndUserId(
+      ownerUserId,
+      contactUserId
+    );
+    return contact ?? null;
+  } catch (error) {
+    console.error('Error getting contact:', error);
+    return null;
+  }
+}
+
+/**
+ * Add a new contact.
+ *
+ * @param ownerUserId - The user ID of the contact owner
+ * @param userId - The user ID of the contact (Bech32-encoded)
+ * @param name - Display name for the contact
+ * @param publicKeys - The contact's public keys
+ * @param db - Database instance
+ * @returns Result with success status and optional contact
+ *
+ * @example
+ * ```typescript
+ * const result = await addContact(
+ *   myUserId,
+ *   'gossip1abc...',
+ *   'Alice',
+ *   alicePublicKeys,
+ *   db
+ * );
+ * if (result.success) {
+ *   console.log('Contact added:', result.contact?.name);
+ * } else if (result.error === 'Contact already exists') {
+ *   console.log('Contact already exists');
+ * }
+ * ```
+ */
+export async function addContact(
+  ownerUserId: string,
+  userId: string,
+  name: string,
+  publicKeys: UserPublicKeys,
+  db: GossipDatabase
+): Promise<{ success: boolean; error?: string; contact?: Contact }> {
+  try {
+    // Check if contact already exists
+    const existing = await db.getContactByOwnerAndUserId(ownerUserId, userId);
+    if (existing) {
+      return { success: false, error: 'Contact already exists' };
+    }
+
+    const contact: Contact = {
+      ownerUserId,
+      userId,
+      name,
+      publicKeys: publicKeys.to_bytes(),
+      isOnline: false,
+      lastSeen: new Date(),
+      createdAt: new Date(),
+    };
+
+    const id = await db.contacts.add(contact);
+    const newContact = await db.contacts.get(id);
+    return { success: true, contact: newContact };
+  } catch (error) {
+    console.error('Error adding contact:', error);
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Unknown error',
+    };
+  }
+}
+
+/**
+ * Update contact name.
+ *
+ * @param ownerUserId - The user ID of the contact owner
+ * @param contactUserId - The user ID of the contact
+ * @param newName - New name for the contact
+ * @param db - Database instance
+ * @returns Result with success status and trimmed name
+ *
+ * @example
+ * ```typescript
+ * const result = await updateContactName(myUserId, theirUserId, 'Alice Smith', db);
+ * if (result.ok) {
+ *   console.log('Updated to:', result.trimmedName);
+ * } else {
+ *   console.error('Failed:', result.message);
+ * }
+ * ```
+ */
+export async function updateContactName(
+  ownerUserId: string,
+  contactUserId: string,
+  newName: string,
+  db: GossipDatabase
+): Promise<UpdateContactNameResult> {
+  return await updateContactNameUtil(ownerUserId, contactUserId, newName, db);
+}
+
+/**
+ * Delete a contact and all associated discussions and messages.
+ *
+ * @param ownerUserId - The user ID of the contact owner
+ * @param contactUserId - The user ID of the contact to delete
+ * @param db - Database instance
+ * @param session - Session module for peer management
+ * @returns Result with success status
+ *
+ * @example
+ * ```typescript
+ * const result = await deleteContact(myUserId, theirUserId, db, session);
+ * if (result.ok) {
+ *   console.log('Contact deleted');
+ * } else {
+ *   console.error('Failed:', result.message);
+ * }
+ * ```
+ */
+export async function deleteContact(
+  ownerUserId: string,
+  contactUserId: string,
+  db: GossipDatabase,
+  session: SessionModule
+): Promise<DeleteContactResult> {
+  return await deleteContactUtil(ownerUserId, contactUserId, db, session);
+}