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

package/dist/contacts.js

@@ -0,0 +1,166 @@
+/**
+ * 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';
+/**
+ * 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, db) {
+    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, contactUserId, db) {
+    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, userId, name, publicKeys, db) {
+    try {
+        // Check if contact already exists
+        const existing = await db.getContactByOwnerAndUserId(ownerUserId, userId);
+        if (existing) {
+            return { success: false, error: 'Contact already exists' };
+        }
+        const 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, contactUserId, newName, db) {
+    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, contactUserId, db, session) {
+    return await deleteContactUtil(ownerUserId, contactUserId, db, session);
+}

package/dist/core/SdkEventEmitter.d.ts

@@ -0,0 +1,36 @@
+/**
+ * SDK Event Emitter
+ *
+ * Type-safe event emitter for SDK events.
+ */
+import type { Message, Discussion, Contact } from '../db';
+export type SdkEventType = 'message' | 'messageSent' | 'messageFailed' | 'discussionRequest' | 'discussionStatusChanged' | 'sessionBroken' | 'sessionRenewed' | 'error';
+export interface SdkEventHandlers {
+    message: (message: Message) => void;
+    messageSent: (message: Message) => void;
+    messageFailed: (message: Message, error: Error) => void;
+    discussionRequest: (discussion: Discussion, contact: Contact) => void;
+    discussionStatusChanged: (discussion: Discussion) => void;
+    sessionBroken: (discussion: Discussion) => void;
+    sessionRenewed: (discussion: Discussion) => void;
+    error: (error: Error, context: string) => void;
+}
+export declare class SdkEventEmitter {
+    private handlers;
+    /**
+     * Register an event handler
+     */
+    on<K extends SdkEventType>(event: K, handler: SdkEventHandlers[K]): void;
+    /**
+     * Remove an event handler
+     */
+    off<K extends SdkEventType>(event: K, handler: SdkEventHandlers[K]): void;
+    /**
+     * Emit an event to all registered handlers
+     */
+    emit<K extends SdkEventType>(event: K, ...args: Parameters<SdkEventHandlers[K]>): void;
+    /**
+     * Remove all handlers for all events
+     */
+    clear(): void;
+}

package/dist/core/SdkEventEmitter.js

@@ -0,0 +1,59 @@
+/**
+ * SDK Event Emitter
+ *
+ * Type-safe event emitter for SDK events.
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Event Emitter Class
+// ─────────────────────────────────────────────────────────────────────────────
+export class SdkEventEmitter {
+    constructor() {
+        Object.defineProperty(this, "handlers", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {
+                message: new Set(),
+                messageSent: new Set(),
+                messageFailed: new Set(),
+                discussionRequest: new Set(),
+                discussionStatusChanged: new Set(),
+                sessionBroken: new Set(),
+                sessionRenewed: new Set(),
+                error: new Set(),
+            }
+        });
+    }
+    /**
+     * Register an event handler
+     */
+    on(event, handler) {
+        this.handlers[event].add(handler);
+    }
+    /**
+     * Remove an event handler
+     */
+    off(event, handler) {
+        this.handlers[event].delete(handler);
+    }
+    /**
+     * Emit an event to all registered handlers
+     */
+    emit(event, ...args) {
+        const handlers = this.handlers[event];
+        handlers.forEach(handler => {
+            try {
+                handler(...args);
+            }
+            catch (error) {
+                console.error(`[SdkEventEmitter] Error in ${event} handler:`, error);
+            }
+        });
+    }
+    /**
+     * Remove all handlers for all events
+     */
+    clear() {
+        Object.values(this.handlers).forEach(set => set.clear());
+    }
+}

package/dist/core/SdkPolling.d.ts

@@ -0,0 +1,35 @@
+/**
+ * SDK Polling Manager
+ *
+ * Manages polling timers for messages, announcements, and session refresh.
+ */
+import type { SdkConfig } from '../config/sdk';
+import type { Discussion } from '../db';
+export interface PollingCallbacks {
+    /** Fetch messages from protocol */
+    fetchMessages: () => Promise<void>;
+    /** Fetch and process announcements */
+    fetchAnnouncements: () => Promise<void>;
+    /** Handle session refresh for active discussions */
+    handleSessionRefresh: (discussions: Discussion[]) => Promise<void>;
+    /** Get active discussions for session refresh */
+    getActiveDiscussions: () => Promise<Discussion[]>;
+    /** Called when a polling error occurs */
+    onError: (error: Error, context: string) => void;
+}
+export declare class SdkPolling {
+    private timers;
+    private callbacks;
+    /**
+     * Start polling with the given configuration and callbacks.
+     */
+    start(config: SdkConfig, callbacks: PollingCallbacks): void;
+    /**
+     * Stop all polling timers.
+     */
+    stop(): void;
+    /**
+     * Check if polling is currently running.
+     */
+    isRunning(): boolean;
+}

package/dist/core/SdkPolling.js

@@ -0,0 +1,100 @@
+/**
+ * SDK Polling Manager
+ *
+ * Manages polling timers for messages, announcements, and session refresh.
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Polling Manager Class
+// ─────────────────────────────────────────────────────────────────────────────
+export class SdkPolling {
+    constructor() {
+        Object.defineProperty(this, "timers", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {
+                messages: null,
+                announcements: null,
+                sessionRefresh: null,
+            }
+        });
+        Object.defineProperty(this, "callbacks", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+    }
+    /**
+     * Start polling with the given configuration and callbacks.
+     */
+    start(config, callbacks) {
+        // Stop any existing timers first
+        this.stop();
+        this.callbacks = callbacks;
+        console.log('[SdkPolling] Starting polling', {
+            messagesIntervalMs: config.polling.messagesIntervalMs,
+            announcementsIntervalMs: config.polling.announcementsIntervalMs,
+            sessionRefreshIntervalMs: config.polling.sessionRefreshIntervalMs,
+        });
+        // Start message polling
+        this.timers.messages = setInterval(async () => {
+            try {
+                await this.callbacks?.fetchMessages();
+            }
+            catch (error) {
+                console.error('[SdkPolling] Message polling error:', error);
+                this.callbacks?.onError(error instanceof Error ? error : new Error(String(error)), 'message_polling');
+            }
+        }, config.polling.messagesIntervalMs);
+        // Start announcement polling
+        this.timers.announcements = setInterval(async () => {
+            try {
+                await this.callbacks?.fetchAnnouncements();
+            }
+            catch (error) {
+                console.error('[SdkPolling] Announcement polling error:', error);
+                this.callbacks?.onError(error instanceof Error ? error : new Error(String(error)), 'announcement_polling');
+            }
+        }, config.polling.announcementsIntervalMs);
+        // Start session refresh polling
+        this.timers.sessionRefresh = setInterval(async () => {
+            try {
+                const discussions = await this.callbacks?.getActiveDiscussions();
+                if (discussions && discussions.length > 0) {
+                    await this.callbacks?.handleSessionRefresh(discussions);
+                }
+            }
+            catch (error) {
+                console.error('[SdkPolling] Session refresh polling error:', error);
+                this.callbacks?.onError(error instanceof Error ? error : new Error(String(error)), 'session_refresh_polling');
+            }
+        }, config.polling.sessionRefreshIntervalMs);
+    }
+    /**
+     * Stop all polling timers.
+     */
+    stop() {
+        if (this.timers.messages) {
+            clearInterval(this.timers.messages);
+            this.timers.messages = null;
+        }
+        if (this.timers.announcements) {
+            clearInterval(this.timers.announcements);
+            this.timers.announcements = null;
+        }
+        if (this.timers.sessionRefresh) {
+            clearInterval(this.timers.sessionRefresh);
+            this.timers.sessionRefresh = null;
+        }
+        this.callbacks = null;
+    }
+    /**
+     * Check if polling is currently running.
+     */
+    isRunning() {
+        return (this.timers.messages !== null ||
+            this.timers.announcements !== null ||
+            this.timers.sessionRefresh !== null);
+    }
+}

package/{src/core/index.ts → dist/core/index.d.ts}

@@ -1,9 +1,7 @@
 /**
  * Core SDK components
  */
-
 export { SdkEventEmitter } from './SdkEventEmitter';
 export type { SdkEventType, SdkEventHandlers } from './SdkEventEmitter';
-
 export { SdkPolling } from './SdkPolling';
 export type { PollingCallbacks } from './SdkPolling';

package/dist/core/index.js

@@ -0,0 +1,5 @@
+/**
+ * Core SDK components
+ */
+export { SdkEventEmitter } from './SdkEventEmitter';
+export { SdkPolling } from './SdkPolling';

package/dist/crypto/bip39.d.ts

@@ -0,0 +1,34 @@
+/**
+ * BIP39 utilities for mnemonic generation, validation, and seed derivation
+ * Using @scure/bip39 for browser compatibility
+ */
+import { Account } from '@massalabs/massa-web3';
+export declare const PRIVATE_KEY_VERSION = 0;
+/**
+ * Generate a new BIP39 mnemonic phrase
+ * @param strength - Entropy strength in bits (128, 160, 192, 224, 256)
+ * @returns Generated mnemonic phrase
+ */
+export declare function generateMnemonic(strength?: number): string;
+/**
+ * Validate a BIP39 mnemonic phrase
+ * @param mnemonic - The mnemonic phrase to validate
+ * @returns True if valid, false otherwise
+ */
+export declare function validateMnemonic(mnemonic: string): boolean;
+/**
+ * Generate a seed from mnemonic and optional passphrase
+ * @param mnemonic - The BIP39 mnemonic phrase
+ * @param passphrase - Optional passphrase (empty string if not provided)
+ * @returns Uint8Array seed
+ */
+export declare function mnemonicToSeed(mnemonic: string, passphrase?: string): Uint8Array;
+/**
+ * Create a Massa blockchain account from a mnemonic phrase
+ *
+ * @param mnemonic - The BIP39 mnemonic phrase
+ * @param passphrase - Optional passphrase for additional security
+ * @returns Massa Account object
+ * @throws Error if mnemonic is invalid
+ */
+export declare function accountFromMnemonic(mnemonic: string, passphrase?: string): Promise<Account>;

package/dist/crypto/bip39.js

@@ -0,0 +1,62 @@
+/**
+ * BIP39 utilities for mnemonic generation, validation, and seed derivation
+ * Using @scure/bip39 for browser compatibility
+ */
+import { generateMnemonic as generateMnemonicScure, mnemonicToSeedSync, validateMnemonic as validateMnemonicScure, } from '@scure/bip39';
+import { wordlist } from '@scure/bip39/wordlists/english.js';
+import { Account, PrivateKey } from '@massalabs/massa-web3';
+import varint from 'varint';
+export const PRIVATE_KEY_VERSION = 0;
+/**
+ * Generate a new BIP39 mnemonic phrase
+ * @param strength - Entropy strength in bits (128, 160, 192, 224, 256)
+ * @returns Generated mnemonic phrase
+ */
+export function generateMnemonic(strength = 256) {
+    // @scure/bip39 generateMnemonic expects strength in bits (128, 160, 192, 224, 256)
+    return generateMnemonicScure(wordlist, strength);
+}
+/**
+ * Validate a BIP39 mnemonic phrase
+ * @param mnemonic - The mnemonic phrase to validate
+ * @returns True if valid, false otherwise
+ */
+export function validateMnemonic(mnemonic) {
+    return validateMnemonicScure(mnemonic, wordlist);
+}
+/**
+ * Generate a seed from mnemonic and optional passphrase
+ * @param mnemonic - The BIP39 mnemonic phrase
+ * @param passphrase - Optional passphrase (empty string if not provided)
+ * @returns Uint8Array seed
+ */
+export function mnemonicToSeed(mnemonic, passphrase = '') {
+    return mnemonicToSeedSync(mnemonic, passphrase);
+}
+/**
+ * Create a Massa blockchain account from a mnemonic phrase
+ *
+ * @param mnemonic - The BIP39 mnemonic phrase
+ * @param passphrase - Optional passphrase for additional security
+ * @returns Massa Account object
+ * @throws Error if mnemonic is invalid
+ */
+export async function accountFromMnemonic(mnemonic, passphrase) {
+    try {
+        if (!validateMnemonic(mnemonic)) {
+            throw new Error('Invalid mnemonic phrase');
+        }
+        const seed = mnemonicToSeed(mnemonic, passphrase);
+        const versionArray = varint.encode(PRIVATE_KEY_VERSION);
+        const privateKeyBytes = seed.slice(0, 32);
+        const privateKey = new Uint8Array([...versionArray, ...privateKeyBytes]);
+        const pkey = PrivateKey.fromBytes(privateKey);
+        const account = await Account.fromPrivateKey(pkey);
+        return account;
+    }
+    catch (error) {
+        console.error('Error in accountFromMnemonic:', error);
+        console.error('Error stack:', error instanceof Error ? error.stack : 'No stack');
+        throw error;
+    }
+}

package/dist/crypto/encryption.d.ts

@@ -0,0 +1,37 @@
+/**
+ * High-level encryption utilities
+ *
+ * Provides convenient wrappers for encrypting and decrypting strings
+ * using the WASM encryption primitives.
+ */
+import { EncryptionKey } from '../wasm/encryption';
+/**
+ * Encrypt a plaintext string using AES-256-SIV
+ *
+ * @param plaintext - The string to encrypt
+ * @param key - The encryption key (64 bytes)
+ * @param salt - Optional salt/nonce bytes (will generate random if not provided)
+ * @returns Object containing encrypted data and nonce bytes
+ */
+export declare function encrypt(plaintext: string, key: EncryptionKey, salt?: Uint8Array): Promise<{
+    encryptedData: Uint8Array;
+    nonce: Uint8Array;
+}>;
+/**
+ * Decrypt encrypted data back to a string
+ *
+ * @param encryptedData - The encrypted data bytes
+ * @param salt - The nonce/salt used during encryption
+ * @param key - The encryption key (must match encryption key)
+ * @returns The decrypted plaintext string
+ * @throws Error if decryption fails (wrong key, corrupted data, etc.)
+ */
+export declare function decrypt(encryptedData: Uint8Array, salt: Uint8Array, key: EncryptionKey): Promise<string>;
+/**
+ * Derive an encryption key from a seed string and nonce
+ *
+ * @param seedString - The seed string (e.g., password)
+ * @param nonce - The nonce/salt for key derivation
+ * @returns The derived encryption key
+ */
+export declare function deriveKey(seedString: string, nonce: Uint8Array): Promise<EncryptionKey>;

package/dist/crypto/encryption.js

@@ -0,0 +1,46 @@
+/**
+ * High-level encryption utilities
+ *
+ * Provides convenient wrappers for encrypting and decrypting strings
+ * using the WASM encryption primitives.
+ */
+import { decryptAead, encryptAead, EncryptionKey, generateNonce, Nonce, } from '../wasm/encryption';
+/**
+ * Encrypt a plaintext string using AES-256-SIV
+ *
+ * @param plaintext - The string to encrypt
+ * @param key - The encryption key (64 bytes)
+ * @param salt - Optional salt/nonce bytes (will generate random if not provided)
+ * @returns Object containing encrypted data and nonce bytes
+ */
+export async function encrypt(plaintext, key, salt) {
+    const nonce = salt ? Nonce.from_bytes(salt) : await generateNonce();
+    const encryptedData = await encryptAead(key, nonce, new TextEncoder().encode(plaintext), new Uint8Array());
+    return { encryptedData, nonce: nonce.to_bytes() };
+}
+/**
+ * Decrypt encrypted data back to a string
+ *
+ * @param encryptedData - The encrypted data bytes
+ * @param salt - The nonce/salt used during encryption
+ * @param key - The encryption key (must match encryption key)
+ * @returns The decrypted plaintext string
+ * @throws Error if decryption fails (wrong key, corrupted data, etc.)
+ */
+export async function decrypt(encryptedData, salt, key) {
+    const plain = await decryptAead(key, Nonce.from_bytes(salt), encryptedData, new Uint8Array());
+    if (!plain) {
+        throw new Error('Failed to decrypt data');
+    }
+    return new TextDecoder().decode(plain);
+}
+/**
+ * Derive an encryption key from a seed string and nonce
+ *
+ * @param seedString - The seed string (e.g., password)
+ * @param nonce - The nonce/salt for key derivation
+ * @returns The derived encryption key
+ */
+export async function deriveKey(seedString, nonce) {
+    return await EncryptionKey.from_seed(seedString, nonce);
+}