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

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Gossip SDK
+ *
+ * Main entry point for the Gossip SDK.
+ * Works in both browser and Node.js environments.
+ *
+ * WASM is loaded via the #wasm subpath import which resolves conditionally:
+ * - Browser: web target (uses import.meta.url)
+ * - Node: nodejs target (uses fs, no import.meta.url)
+ *
+ * @example
+ * ```typescript
+ * import { gossipSdk } from '@massalabs/gossip-sdk';
+ *
+ * await gossipSdk.init({ db, protocolBaseUrl: 'https://api.example.com' });
+ * await gossipSdk.openSession({ mnemonic: '...' });
+ * await gossipSdk.messages.send(contactId, 'Hello!');
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { gossipSdk, GossipSdkImpl } from './gossipSdk';
+export type { GossipSdkInitOptions, OpenSessionOptions, SdkEventType, SdkEventHandlers, } from './gossipSdk';
+export type { GossipSdkEvents } from './types/events';
+export { AuthService } from './services/auth';
+export type { PublicKeyResult } from './services/auth';
+export { getPublicKeyErrorMessage, PUBLIC_KEY_NOT_FOUND_ERROR, PUBLIC_KEY_NOT_FOUND_MESSAGE, FAILED_TO_FETCH_ERROR, FAILED_TO_FETCH_MESSAGE, FAILED_TO_RETRIEVE_CONTACT_PUBLIC_KEY_ERROR, } from './services/auth';
+export { AnnouncementService, EstablishSessionError, } from './services/announcement';
+export type { AnnouncementReceptionResult } from './services/announcement';
+export { MessageService } from './services/message';
+export type { MessageResult, SendMessageResult } from './services/message';
+export { DiscussionService } from './services/discussion';
+export { RefreshService } from './services/refresh';
+export { getContacts, getContact, addContact, updateContactName, deleteContact, } from './contacts';
+export type { UpdateContactNameResult, DeleteContactResult, } from './utils/contacts';
+export { updateDiscussionName } from './utils/discussions';
+export type { UpdateDiscussionNameResult } from './utils/discussions';
+export * from './types';
+export { createMessageProtocol, restMessageProtocol, RestMessageProtocol, MessageProtocol, } from './api/messageProtocol';
+export type { IMessageProtocol, EncryptedMessage, MessageProtocolResponse, BulletinItem, } from './api/messageProtocol';
+export { setProtocolBaseUrl, resetProtocolBaseUrl, MessageProtocolType, protocolConfig, } from './config/protocol';
+export type { ProtocolConfig } from './config/protocol';
+export { defaultSdkConfig, mergeConfig } from './config/sdk';
+export type { SdkConfig, PollingConfig, MessagesConfig, AnnouncementsConfig, DeepPartial, } from './config/sdk';
+export { setDb, getDb, db, GossipDatabase } from './db';
+export { SessionModule, sessionStatusToString } from './wasm/session';
+export { initializeWasm, ensureWasmInitialized, startWasmInitialization, } from './wasm/loader';
+export { EncryptionKey, Nonce, generateEncryptionKey, generateEncryptionKeyFromSeed, encryptionKeyFromBytes, generateNonce, nonceFromBytes, encryptAead, decryptAead, } from './wasm/encryption';
+export { generateUserKeys, UserKeys } from './wasm/userKeys';
+export { encodeUserId, decodeUserId, isValidUserId, formatUserId, generate as generateUserId, } from './utils/userId';
+export { validateUsernameFormat, validatePassword, validateUserIdFormat, validateUsernameAvailability, validateUsernameFormatAndAvailability, } from './utils/validation';
+export type { ValidationResult } from './utils/validation';
+export { encodeToBase64, decodeFromBase64, encodeToBase64Url, decodeFromBase64Url, } from './utils/base64';
+export type { Result } from './utils/type';
+export { MESSAGE_TYPE_KEEP_ALIVE, serializeKeepAliveMessage, serializeRegularMessage, serializeReplyMessage, serializeForwardMessage, deserializeMessage, } from './utils/messageSerialization';
+export type { DeserializedMessage } from './utils/messageSerialization';
+export { generateMnemonic, validateMnemonic, mnemonicToSeed, accountFromMnemonic, PRIVATE_KEY_VERSION, } from './crypto/bip39';
+export { encrypt, decrypt, deriveKey } from './crypto/encryption';
+export { UserPublicKeys, UserSecretKeys, SessionStatus, SessionConfig, SessionManagerWrapper, SendMessageOutput, ReceiveMessageOutput, AnnouncementResult, generate_user_keys, } from '#wasm';

package/dist/index.js

@@ -0,0 +1,61 @@
+/**
+ * Gossip SDK
+ *
+ * Main entry point for the Gossip SDK.
+ * Works in both browser and Node.js environments.
+ *
+ * WASM is loaded via the #wasm subpath import which resolves conditionally:
+ * - Browser: web target (uses import.meta.url)
+ * - Node: nodejs target (uses fs, no import.meta.url)
+ *
+ * @example
+ * ```typescript
+ * import { gossipSdk } from '@massalabs/gossip-sdk';
+ *
+ * await gossipSdk.init({ db, protocolBaseUrl: 'https://api.example.com' });
+ * await gossipSdk.openSession({ mnemonic: '...' });
+ * await gossipSdk.messages.send(contactId, 'Hello!');
+ * ```
+ *
+ * @packageDocumentation
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// SDK Singleton - Primary API
+// ─────────────────────────────────────────────────────────────────────────────
+export { gossipSdk, GossipSdkImpl } from './gossipSdk';
+// Services
+export { AuthService } from './services/auth';
+export { getPublicKeyErrorMessage, PUBLIC_KEY_NOT_FOUND_ERROR, PUBLIC_KEY_NOT_FOUND_MESSAGE, FAILED_TO_FETCH_ERROR, FAILED_TO_FETCH_MESSAGE, FAILED_TO_RETRIEVE_CONTACT_PUBLIC_KEY_ERROR, } from './services/auth';
+export { AnnouncementService, EstablishSessionError, } from './services/announcement';
+export { MessageService } from './services/message';
+export { DiscussionService } from './services/discussion';
+export { RefreshService } from './services/refresh';
+// Contact Management
+export { getContacts, getContact, addContact, updateContactName, deleteContact, } from './contacts';
+// Discussion utilities
+export { updateDiscussionName } from './utils/discussions';
+// Types
+export * from './types';
+// Message Protocol
+export { createMessageProtocol, restMessageProtocol, RestMessageProtocol, MessageProtocol, } from './api/messageProtocol';
+// Config
+export { setProtocolBaseUrl, resetProtocolBaseUrl, MessageProtocolType, protocolConfig, } from './config/protocol';
+export { defaultSdkConfig, mergeConfig } from './config/sdk';
+// Database
+export { setDb, getDb, db, GossipDatabase } from './db';
+// WASM utilities
+export { SessionModule, sessionStatusToString } from './wasm/session';
+export { initializeWasm, ensureWasmInitialized, startWasmInitialization, } from './wasm/loader';
+export { EncryptionKey, Nonce, generateEncryptionKey, generateEncryptionKeyFromSeed, encryptionKeyFromBytes, generateNonce, nonceFromBytes, encryptAead, decryptAead, } from './wasm/encryption';
+export { generateUserKeys, UserKeys } from './wasm/userKeys';
+// Utility functions
+export { encodeUserId, decodeUserId, isValidUserId, formatUserId, generate as generateUserId, } from './utils/userId';
+export { validateUsernameFormat, validatePassword, validateUserIdFormat, validateUsernameAvailability, validateUsernameFormatAndAvailability, } from './utils/validation';
+export { encodeToBase64, decodeFromBase64, encodeToBase64Url, decodeFromBase64Url, } from './utils/base64';
+// Message serialization
+export { MESSAGE_TYPE_KEEP_ALIVE, serializeKeepAliveMessage, serializeRegularMessage, serializeReplyMessage, serializeForwardMessage, deserializeMessage, } from './utils/messageSerialization';
+// Crypto utilities
+export { generateMnemonic, validateMnemonic, mnemonicToSeed, accountFromMnemonic, PRIVATE_KEY_VERSION, } from './crypto/bip39';
+export { encrypt, decrypt, deriveKey } from './crypto/encryption';
+// WASM types re-exported for convenience
+export { UserPublicKeys, UserSecretKeys, SessionStatus, SessionConfig, SessionManagerWrapper, SendMessageOutput, ReceiveMessageOutput, AnnouncementResult, generate_user_keys, } from '#wasm';

package/dist/services/announcement.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Announcement Service
+ *
+ * Handles broadcasting and processing of session announcements.
+ */
+import { type Discussion, type GossipDatabase } from '../db';
+import { IMessageProtocol } from '../api/messageProtocol';
+import { UserPublicKeys } from '#wasm';
+import { SessionModule } from '../wasm/session';
+import { GossipSdkEvents } from '../types/events';
+import { SdkConfig } from '../config/sdk';
+export interface AnnouncementReceptionResult {
+    success: boolean;
+    newAnnouncementsCount: number;
+    error?: string;
+}
+export declare const EstablishSessionError = "Session manager failed to establish outgoing session";
+export declare class AnnouncementService {
+    private db;
+    private messageProtocol;
+    private session;
+    private isProcessingAnnouncements;
+    private events;
+    private config;
+    constructor(db: GossipDatabase, messageProtocol: IMessageProtocol, session: SessionModule, events?: GossipSdkEvents, config?: SdkConfig);
+    setMessageProtocol(messageProtocol: IMessageProtocol): void;
+    sendAnnouncement(announcement: Uint8Array): Promise<{
+        success: boolean;
+        counter?: string;
+        error?: string;
+    }>;
+    establishSession(contactPublicKeys: UserPublicKeys, userData?: Uint8Array): Promise<{
+        success: boolean;
+        error?: string;
+        announcement: Uint8Array;
+    }>;
+    fetchAndProcessAnnouncements(): Promise<AnnouncementReceptionResult>;
+    resendAnnouncements(failedDiscussions: Discussion[]): Promise<void>;
+    private _fetchAnnouncements;
+    private _generateTemporaryContactName;
+    private _processIncomingAnnouncement;
+    private _handleReceivedDiscussion;
+}

package/dist/services/announcement.js

@@ -0,0 +1,491 @@
+/**
+ * Announcement Service
+ *
+ * Handles broadcasting and processing of session announcements.
+ */
+import { DiscussionStatus, DiscussionDirection, } from '../db';
+import { decodeUserId, encodeUserId } from '../utils/userId';
+import { SessionStatus } from '#wasm';
+import { sessionStatusToString } from '../wasm/session';
+import { Logger } from '../utils/logs';
+import { defaultSdkConfig } from '../config/sdk';
+const logger = new Logger('AnnouncementService');
+export const EstablishSessionError = 'Session manager failed to establish outgoing session';
+export class AnnouncementService {
+    constructor(db, messageProtocol, session, events = {}, config = defaultSdkConfig) {
+        Object.defineProperty(this, "db", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "messageProtocol", {
+            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, "isProcessingAnnouncements", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "events", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "config", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.db = db;
+        this.messageProtocol = messageProtocol;
+        this.session = session;
+        this.events = events;
+        this.config = config;
+    }
+    setMessageProtocol(messageProtocol) {
+        this.messageProtocol = messageProtocol;
+    }
+    async sendAnnouncement(announcement) {
+        const log = logger.forMethod('sendAnnouncement');
+        try {
+            const counter = await this.messageProtocol.sendAnnouncement(announcement);
+            log.info('broadcast successful', { counter });
+            return { success: true, counter };
+        }
+        catch (error) {
+            log.error('broadcast failed', error);
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : 'Unknown error',
+            };
+        }
+    }
+    async establishSession(contactPublicKeys, userData) {
+        const log = logger.forMethod('establishSession');
+        const contactUserId = encodeUserId(contactPublicKeys.derive_id());
+        // CRITICAL: await to ensure session state is persisted before sending
+        const announcement = await this.session.establishOutgoingSession(contactPublicKeys, userData);
+        if (announcement.length === 0) {
+            log.error('empty announcement returned', { contactUserId });
+            return {
+                success: false,
+                error: EstablishSessionError,
+                announcement,
+            };
+        }
+        const result = await this.sendAnnouncement(announcement);
+        if (!result.success) {
+            log.error('failed to broadcast announcement', {
+                contactUserId,
+                error: result.error,
+            });
+            return {
+                success: false,
+                error: result.error,
+                announcement,
+            };
+        }
+        log.info('announcement sent successfully', { contactUserId });
+        return { success: true, announcement };
+    }
+    async fetchAndProcessAnnouncements() {
+        const log = logger.forMethod('fetchAndProcessAnnouncements');
+        if (this.isProcessingAnnouncements) {
+            log.info('fetch already in progress, skipping');
+            return { success: true, newAnnouncementsCount: 0 };
+        }
+        const errors = [];
+        let announcements = [];
+        let fetchedCounters = [];
+        this.isProcessingAnnouncements = true;
+        try {
+            const pending = await this.db.pendingAnnouncements.toArray();
+            const successfullyProcessedPendingIds = [];
+            if (pending.length > 0) {
+                log.info(`processing ${pending.length} pending announcements from IndexedDB`);
+                // Process pending announcements one by one, tracking successes
+                let newAnnouncementsCount = 0;
+                for (const item of pending) {
+                    try {
+                        const result = await this._processIncomingAnnouncement(item.announcement);
+                        // Mark as successfully processed (even if announcement was for unknown peer)
+                        // Only keep if processing threw an error
+                        if (item.id !== undefined) {
+                            successfullyProcessedPendingIds.push(item.id);
+                        }
+                        if (result.success && result.contactUserId) {
+                            newAnnouncementsCount++;
+                            log.info(`processed pending announcement #${newAnnouncementsCount}`, {
+                                contactUserId: result.contactUserId,
+                            });
+                        }
+                        if (item.counter)
+                            fetchedCounters.push(item.counter);
+                        if (result.error)
+                            errors.push(result.error);
+                    }
+                    catch (error) {
+                        // Don't mark as processed - will be retried next time
+                        log.error('failed to process pending announcement, will retry', {
+                            id: item.id,
+                            error,
+                        });
+                        errors.push(error instanceof Error ? error.message : 'Unknown error');
+                    }
+                }
+                // Delete only successfully processed pending announcements
+                if (successfullyProcessedPendingIds.length > 0) {
+                    await this.db.pendingAnnouncements.bulkDelete(successfullyProcessedPendingIds);
+                    log.info(`deleted ${successfullyProcessedPendingIds.length} processed pending announcements`);
+                }
+                if (fetchedCounters.length > 0) {
+                    const highestCounter = fetchedCounters.reduce((a, b) => Number(a) > Number(b) ? a : b);
+                    await this.db.userProfile.update(this.session.userIdEncoded, {
+                        lastBulletinCounter: highestCounter,
+                    });
+                    log.info('updated lastBulletinCounter', { highestCounter });
+                }
+                return {
+                    success: errors.length === 0 || newAnnouncementsCount > 0,
+                    newAnnouncementsCount,
+                    error: errors.length > 0 ? errors.join(', ') : undefined,
+                };
+            }
+            // No pending - fetch from API
+            const cursor = (await this.db.userProfile.get(this.session.userIdEncoded))
+                ?.lastBulletinCounter;
+            const fetched = await this._fetchAnnouncements(cursor);
+            announcements = fetched.map(a => a.data);
+            fetchedCounters = fetched.map(a => a.counter);
+            let newAnnouncementsCount = 0;
+            for (const announcement of announcements) {
+                try {
+                    const result = await this._processIncomingAnnouncement(announcement);
+                    if (result.success && result.contactUserId) {
+                        newAnnouncementsCount++;
+                        log.info(`processed new announcement #${newAnnouncementsCount}`, {
+                            contactUserId: result.contactUserId,
+                        });
+                    }
+                    if (result.error)
+                        errors.push(result.error);
+                }
+                catch (error) {
+                    errors.push(error instanceof Error ? error.message : 'Unknown error');
+                }
+            }
+            if (fetchedCounters.length > 0) {
+                const highestCounter = fetchedCounters.reduce((a, b) => Number(a) > Number(b) ? a : b);
+                await this.db.userProfile.update(this.session.userIdEncoded, {
+                    lastBulletinCounter: highestCounter,
+                });
+                log.info('updated lastBulletinCounter', { highestCounter });
+            }
+            return {
+                success: errors.length === 0 || newAnnouncementsCount > 0,
+                newAnnouncementsCount,
+                error: errors.length > 0 ? errors.join(', ') : undefined,
+            };
+        }
+        catch (error) {
+            log.error('unexpected error during fetch/process', error);
+            return {
+                success: false,
+                newAnnouncementsCount: 0,
+                error: error instanceof Error ? error.message : 'Unknown error',
+            };
+        }
+        finally {
+            this.isProcessingAnnouncements = false;
+        }
+    }
+    async resendAnnouncements(failedDiscussions) {
+        const log = logger.forMethod('resendAnnouncements');
+        if (!failedDiscussions.length) {
+            log.info('no failed discussions to resend');
+            return;
+        }
+        log.info(`starting resend for ${failedDiscussions.length} failed discussions`);
+        const sentDiscussions = [];
+        const brokenDiscussions = [];
+        for (const discussion of failedDiscussions) {
+            const { ownerUserId, contactUserId } = discussion;
+            try {
+                const result = await this.sendAnnouncement(discussion.initiationAnnouncement);
+                if (result.success) {
+                    log.info('resent successfully', { ownerUserId, contactUserId });
+                    sentDiscussions.push(discussion);
+                    continue;
+                }
+                log.info('network send failed (retry)', { ownerUserId, contactUserId });
+                const ageMs = Date.now() - (discussion.updatedAt.getTime() ?? 0);
+                if (ageMs > this.config.announcements.brokenThresholdMs) {
+                    log.info(`marking as broken (too old: ${Math.round(ageMs / 60000)}min)`, {
+                        ownerUserId,
+                        contactUserId,
+                    });
+                    brokenDiscussions.push(discussion.id);
+                }
+            }
+            catch (error) {
+                log.error('exception during resend', {
+                    error: error instanceof Error ? error.message : 'Unknown error',
+                    ownerUserId,
+                    contactUserId,
+                });
+            }
+        }
+        if (sentDiscussions.length > 0 || brokenDiscussions.length > 0) {
+            await this.db.transaction('rw', this.db.discussions, async () => {
+                const now = new Date();
+                if (sentDiscussions.length > 0) {
+                    await Promise.all(sentDiscussions.map(async (discussion) => {
+                        const status = this.session.peerSessionStatus(decodeUserId(discussion.contactUserId));
+                        const statusStr = sessionStatusToString(status);
+                        if (status !== SessionStatus.Active &&
+                            status !== SessionStatus.SelfRequested) {
+                            log.info('skipping DB update - session not ready', {
+                                contactUserId: discussion.contactUserId,
+                                status: statusStr,
+                            });
+                            return;
+                        }
+                        const newStatus = status === SessionStatus.Active
+                            ? DiscussionStatus.ACTIVE
+                            : DiscussionStatus.PENDING;
+                        await this.db.discussions.update(discussion.id, {
+                            status: newStatus,
+                            updatedAt: now,
+                        });
+                        log.info('updated discussion status in DB', {
+                            contactUserId: discussion.contactUserId,
+                            newStatus,
+                        });
+                        // Emit status change event
+                        const updatedDiscussion = await this.db.discussions.get(discussion.id);
+                        if (updatedDiscussion) {
+                            this.events.onDiscussionStatusChanged?.(updatedDiscussion);
+                        }
+                    }));
+                }
+                if (brokenDiscussions.length > 0) {
+                    // Per spec: announcement failures should trigger session renewal, not BROKEN status
+                    // Clear the failed announcement and trigger renewal
+                    log.info(`${brokenDiscussions.length} announcements timed out, triggering renewal`);
+                    await Promise.all(brokenDiscussions.map(async (id) => {
+                        await this.db.discussions.update(id, {
+                            initiationAnnouncement: undefined,
+                            updatedAt: now,
+                        });
+                        // Emit renewal needed event
+                        const discussion = await this.db.discussions.get(id);
+                        if (discussion) {
+                            this.events.onSessionRenewalNeeded?.(discussion.contactUserId);
+                        }
+                    }));
+                }
+            });
+        }
+        log.info('resend completed', {
+            sent: sentDiscussions.length,
+            broken: brokenDiscussions.length,
+        });
+    }
+    async _fetchAnnouncements(cursor, limit) {
+        const fetchLimit = limit ?? this.config.announcements.fetchLimit;
+        const log = logger.forMethod('_fetchAnnouncements');
+        try {
+            const items = await this.messageProtocol.fetchAnnouncements(fetchLimit, cursor);
+            return items;
+        }
+        catch (error) {
+            log.error('network fetch failed', error);
+            return [];
+        }
+    }
+    async _generateTemporaryContactName(ownerUserId) {
+        const newRequestContacts = await this.db.contacts
+            .where('ownerUserId')
+            .equals(ownerUserId)
+            .filter(contact => contact.name.startsWith('New Request'))
+            .toArray();
+        const numbers = newRequestContacts
+            .map(contact => {
+            const match = contact.name.match(/^New Request (\d+)$/);
+            return match ? parseInt(match[1], 10) : 0;
+        })
+            .filter(number => number > 0);
+        const next = numbers.length ? Math.max(...numbers) + 1 : 1;
+        return `New Request ${next}`;
+    }
+    async _processIncomingAnnouncement(announcementData) {
+        const log = logger.forMethod('_processIncomingAnnouncement');
+        const result = await this.session.feedIncomingAnnouncement(announcementData);
+        if (!result) {
+            return { success: true };
+        }
+        log.info('announcement intended for us — decrypting');
+        let rawMessage;
+        if (result.user_data?.length > 0) {
+            try {
+                rawMessage = new TextDecoder().decode(result.user_data);
+            }
+            catch (error) {
+                log.error('failed to decode user data', error);
+            }
+        }
+        // Parse announcement message format:
+        // - JSON format: {"u":"username","m":"message"} (current)
+        // - Legacy colon format: "username:message" (backwards compat)
+        // - Plain text: "message" (oldest format)
+        // The username is used as the initial contact name if present.
+        // TODO: Remove legacy colon and plain text format support once all clients are updated
+        let extractedUsername;
+        let announcementMessage;
+        if (rawMessage) {
+            // Try JSON format first (starts with '{')
+            if (rawMessage.startsWith('{')) {
+                try {
+                    const parsed = JSON.parse(rawMessage);
+                    extractedUsername = parsed.u?.trim() || undefined;
+                    announcementMessage = parsed.m?.trim() || undefined;
+                }
+                catch {
+                    // Invalid JSON, treat as plain text
+                    announcementMessage = rawMessage;
+                }
+            }
+            else {
+                // Legacy format: check for colon separator
+                const colonIndex = rawMessage.indexOf(':');
+                if (colonIndex !== -1) {
+                    extractedUsername =
+                        rawMessage.slice(0, colonIndex).trim() || undefined;
+                    announcementMessage =
+                        rawMessage.slice(colonIndex + 1).trim() || undefined;
+                }
+                else {
+                    // Plain text (oldest format)
+                    announcementMessage = rawMessage;
+                }
+            }
+        }
+        const announcerPkeys = result.announcer_public_keys;
+        const contactUserIdRaw = announcerPkeys.derive_id();
+        const contactUserId = encodeUserId(contactUserIdRaw);
+        const sessionStatus = this.session.peerSessionStatus(contactUserIdRaw);
+        // Log clearly for debugging
+        console.log(`[Announcement] Received from ${contactUserId.slice(0, 12)}... -> session status: ${sessionStatusToString(sessionStatus)}`);
+        log.info('session updated', {
+            contactUserId,
+            status: sessionStatusToString(sessionStatus),
+        });
+        let contact = await this.db.getContactByOwnerAndUserId(this.session.userIdEncoded, contactUserId);
+        const isNewContact = !contact;
+        if (isNewContact) {
+            // Use extracted username if present, otherwise generate temporary name
+            const name = extractedUsername ||
+                (await this._generateTemporaryContactName(this.session.userIdEncoded));
+            await this.db.contacts.add({
+                ownerUserId: this.session.userIdEncoded,
+                userId: contactUserId,
+                name,
+                publicKeys: announcerPkeys.to_bytes(),
+                avatar: undefined,
+                isOnline: false,
+                lastSeen: new Date(),
+                createdAt: new Date(),
+            });
+            contact = await this.db.getContactByOwnerAndUserId(this.session.userIdEncoded, contactUserId);
+            log.info('created new contact', { contactUserId, name });
+        }
+        if (!contact) {
+            log.error('contact lookup failed after creation');
+            throw new Error('Could not find or create contact');
+        }
+        const { discussionId } = await this._handleReceivedDiscussion(this.session.userIdEncoded, contactUserId, announcementMessage);
+        // Emit event for new discussion request
+        if (this.events.onDiscussionRequest) {
+            const discussion = await this.db.discussions.get(discussionId);
+            if (discussion && contact) {
+                this.events.onDiscussionRequest(discussion, contact);
+            }
+        }
+        // Auto-accept ONLY for existing contacts (session recovery scenario).
+        // For NEW contacts, the user must manually accept the discussion request.
+        // This completes the handshake by sending our announcement back.
+        if (sessionStatus === SessionStatus.PeerRequested && !isNewContact) {
+            log.info('session is PeerRequested for existing contact, triggering auto-accept', { contactUserId });
+            this.events.onSessionAcceptNeeded?.(contactUserId);
+        }
+        else if (sessionStatus === SessionStatus.PeerRequested && isNewContact) {
+            log.info('session is PeerRequested for NEW contact, waiting for manual accept', { contactUserId });
+        }
+        // When session becomes Active after peer accepts our announcement,
+        // trigger processing of WAITING_SESSION messages.
+        // This happens when we initiated (SelfRequested) and peer accepted.
+        if (sessionStatus === SessionStatus.Active) {
+            log.info('session is now Active, triggering WAITING_SESSION message processing', { contactUserId });
+            this.events.onSessionBecameActive?.(contactUserId);
+        }
+        return {
+            success: true,
+            discussionId,
+            contactUserId,
+        };
+    }
+    async _handleReceivedDiscussion(ownerUserId, contactUserId, announcementMessage) {
+        const log = logger.forMethod('handleReceivedDiscussion');
+        const discussionId = await this.db.transaction('rw', this.db.discussions, async () => {
+            const existing = await this.db.getDiscussionByOwnerAndContact(ownerUserId, contactUserId);
+            if (existing) {
+                const updateData = { updatedAt: new Date() };
+                if (announcementMessage)
+                    updateData.announcementMessage = announcementMessage;
+                if (existing.status === DiscussionStatus.PENDING &&
+                    existing.direction === DiscussionDirection.INITIATED) {
+                    updateData.status = DiscussionStatus.ACTIVE;
+                    log.info('transitioning to ACTIVE', {
+                        discussionId: existing.id,
+                        contactUserId,
+                    });
+                }
+                else {
+                    log.info('updating existing discussion', {
+                        discussionId: existing.id,
+                        status: existing.status,
+                        direction: existing.direction,
+                    });
+                }
+                await this.db.discussions.update(existing.id, updateData);
+                return existing.id;
+            }
+            log.info('creating new RECEIVED/PENDING discussion', { contactUserId });
+            return await this.db.discussions.add({
+                ownerUserId,
+                contactUserId,
+                direction: DiscussionDirection.RECEIVED,
+                status: DiscussionStatus.PENDING,
+                nextSeeker: undefined,
+                announcementMessage,
+                unreadCount: 0,
+                createdAt: new Date(),
+                updatedAt: new Date(),
+            });
+        });
+        return { discussionId };
+    }
+}