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

package/dist/gossipSdk.d.ts

@@ -0,0 +1,274 @@
+/**
+ * GossipSdk - Singleton SDK with clean lifecycle API
+ *
+ * @example
+ * ```typescript
+ * import { gossipSdk } from 'gossip-sdk';
+ *
+ * // Initialize once at app startup
+ * await gossipSdk.init({
+ *   db,
+ *   protocolBaseUrl: 'https://api.example.com',
+ * });
+ *
+ * // Open session (login) - SDK handles keys/session internally
+ * await gossipSdk.openSession({
+ *   mnemonic: 'word1 word2 ...',
+ *   onPersist: async (blob) => { /* save to db *\/ },
+ * });
+ *
+ * // Or restore existing session
+ * await gossipSdk.openSession({
+ *   mnemonic: 'word1 word2 ...',
+ *   encryptedSession: savedBlob,
+ *   encryptionKey: key,
+ *   onPersist: async (blob) => { /* save to db *\/ },
+ * });
+ *
+ * // Use clean API
+ * await gossipSdk.messages.send(contactId, 'Hello!');
+ * await gossipSdk.discussions.start(contact);
+ * const contacts = await gossipSdk.contacts.list(ownerUserId);
+ *
+ * // Events
+ * gossipSdk.on('message', (msg) => { ... });
+ * gossipSdk.on('discussionRequest', (discussion, contact) => { ... });
+ *
+ * // Logout
+ * await gossipSdk.closeSession();
+ * ```
+ */
+import { GossipDatabase, type Contact, type Discussion, type Message } from './db';
+import { type SdkConfig, type DeepPartial } from './config/sdk';
+import { EncryptionKey } from './wasm/encryption';
+import { type AnnouncementReceptionResult } from './services/announcement';
+import { type MessageResult, type SendMessageResult } from './services/message';
+import { AuthService } from './services/auth';
+import type { DeleteContactResult, UpdateContactNameResult } from './utils/contacts';
+import { type ValidationResult } from './utils/validation';
+import type { UserPublicKeys } from '#wasm';
+import { type SdkEventType, type SdkEventHandlers } from './core/SdkEventEmitter';
+export type { SdkEventType, SdkEventHandlers };
+export interface GossipSdkInitOptions {
+    /** Database instance */
+    db: GossipDatabase;
+    /** Protocol API base URL (shorthand for config.protocol.baseUrl) */
+    protocolBaseUrl?: string;
+    /** SDK configuration (optional - uses defaults if not provided) */
+    config?: DeepPartial<SdkConfig>;
+}
+export interface OpenSessionOptions {
+    /** BIP39 mnemonic phrase */
+    mnemonic: string;
+    /** Existing encrypted session blob (for restoring session) */
+    encryptedSession?: Uint8Array;
+    /** Encryption key for decrypting session */
+    encryptionKey?: EncryptionKey;
+    /** Callback when session state changes (for persistence) */
+    onPersist?: (encryptedBlob: Uint8Array, encryptionKey: EncryptionKey) => Promise<void>;
+    /** Encryption key for persisting session (required if onPersist is provided) */
+    persistEncryptionKey?: EncryptionKey;
+}
+declare class GossipSdkImpl {
+    private state;
+    private eventEmitter;
+    private pollingManager;
+    private messageQueues;
+    private _auth;
+    private _announcement;
+    private _discussion;
+    private _message;
+    private _refresh;
+    private _messagesAPI;
+    private _discussionsAPI;
+    private _announcementsAPI;
+    private _contactsAPI;
+    private _refreshAPI;
+    /**
+     * Initialize the SDK. Call once at app startup.
+     */
+    init(options: GossipSdkInitOptions): Promise<void>;
+    /**
+     * Open a session (login).
+     * Generates keys from mnemonic and initializes session.
+     */
+    openSession(options: OpenSessionOptions): Promise<void>;
+    /**
+     * Create cached service API wrappers.
+     * Called once during openSession to avoid creating new objects on each getter access.
+     */
+    private createServiceAPIWrappers;
+    /**
+     * Close the current session (logout).
+     */
+    closeSession(): Promise<void>;
+    /** Current user ID (encoded). Throws if no session is open. */
+    get userId(): string;
+    /** Current user ID (raw bytes). Throws if no session is open. */
+    get userIdBytes(): Uint8Array;
+    /** User's public keys. Throws if no session is open. */
+    get publicKeys(): UserPublicKeys;
+    /** Whether a session is currently open */
+    get isSessionOpen(): boolean;
+    /** Whether SDK is initialized */
+    get isInitialized(): boolean;
+    /**
+     * Get encrypted session blob for persistence.
+     * Throws if no session is open.
+     */
+    getEncryptedSession(encryptionKey: EncryptionKey): Uint8Array;
+    /**
+     * Configure session persistence after session is opened.
+     * Use this when you need to set up persistence after account creation.
+     *
+     * @param encryptionKey - Key to encrypt session blob
+     * @param onPersist - Callback to save encrypted session blob
+     */
+    configurePersistence(encryptionKey: EncryptionKey, onPersist: (encryptedBlob: Uint8Array, encryptionKey: EncryptionKey) => Promise<void>): void;
+    /** Auth service (available after init, before session) */
+    get auth(): AuthService;
+    /** Message service */
+    get messages(): MessageServiceAPI;
+    /** Discussion service */
+    get discussions(): DiscussionServiceAPI;
+    /** Announcement service */
+    get announcements(): AnnouncementServiceAPI;
+    /** Contact management */
+    get contacts(): ContactsAPI;
+    /** Refresh/sync service */
+    get refresh(): RefreshServiceAPI;
+    /** Utility functions */
+    get utils(): SdkUtils;
+    /** Current SDK configuration (read-only) */
+    get config(): SdkConfig;
+    /** Polling control API */
+    get polling(): PollingAPI;
+    /**
+     * Start polling for messages, announcements, and session refresh.
+     * Uses intervals from config.polling.
+     */
+    private startPolling;
+    /**
+     * 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;
+    private requireSession;
+    /**
+     * Handle automatic session renewal when session is lost.
+     * Called by onSessionRenewalNeeded event.
+     */
+    private handleSessionRenewal;
+    /**
+     * Handle automatic session accept when peer has sent us an announcement.
+     * Called by onSessionAcceptNeeded event.
+     * This is different from renewal - we respond to their session request.
+     */
+    private handleSessionAccept;
+    /**
+     * Handle session becoming Active after peer accepts our announcement.
+     * Called by onSessionBecameActive event.
+     *
+     * This is different from handleSessionAccept:
+     * - handleSessionAccept: WE accept a session (peer initiated)
+     * - handleSessionBecameActive: PEER accepts our session (we initiated)
+     */
+    private handleSessionBecameActive;
+    private handleSessionPersist;
+    /**
+     * Reset any messages stuck in SENDING status to FAILED.
+     * This handles the case where the app crashed or was closed during message send.
+     * Per spec: SENDING should never be persisted - if we find it on startup, it failed.
+     */
+    /**
+     * Reset messages stuck in SENDING status to WAITING_SESSION.
+     *
+     * Per spec: SENDING is a transient state that should never be persisted.
+     * If the app crashes/closes during a send, the message would be stuck forever.
+     *
+     * By resetting to WAITING_SESSION:
+     * - Message will be re-encrypted with current session keys
+     * - Message will be automatically sent when session is active
+     * - No manual user intervention required
+     *
+     * We also clear encryptedMessage and seeker since they may be stale.
+     */
+    private resetStuckSendingMessages;
+}
+interface MessageServiceAPI {
+    /** Send a message */
+    send(message: Omit<Message, 'id'>): Promise<SendMessageResult>;
+    /** Fetch and decrypt messages from the protocol */
+    fetch(): Promise<MessageResult>;
+    /** Resend failed messages */
+    resend(messages: Map<string, Message[]>): Promise<void>;
+    /** Find a message by its seeker */
+    findBySeeker(seeker: Uint8Array, ownerUserId: string): Promise<Message | undefined>;
+}
+interface DiscussionServiceAPI {
+    /** Start a new discussion with a contact */
+    start(contact: Contact, message?: string): Promise<{
+        discussionId: number;
+        announcement: Uint8Array;
+    }>;
+    /** Accept an incoming discussion request */
+    accept(discussion: Discussion): Promise<void>;
+    /** Renew a broken discussion */
+    renew(contactUserId: string): Promise<void>;
+    /** Check if a discussion is in a stable state */
+    isStable(ownerUserId: string, contactUserId: string): Promise<boolean>;
+    /** List all discussions for the owner */
+    list(ownerUserId: string): Promise<Discussion[]>;
+    /** Get a specific discussion */
+    get(ownerUserId: string, contactUserId: string): Promise<Discussion | undefined>;
+}
+interface AnnouncementServiceAPI {
+    /** Fetch and process announcements from the protocol */
+    fetch(): Promise<AnnouncementReceptionResult>;
+    /** Resend failed announcements */
+    resend(failedDiscussions: Discussion[]): Promise<void>;
+}
+interface ContactsAPI {
+    /** List all contacts for the owner */
+    list(ownerUserId: string): Promise<Contact[]>;
+    /** Get a specific contact */
+    get(ownerUserId: string, contactUserId: string): Promise<Contact | null>;
+    /** Add a new contact */
+    add(ownerUserId: string, userId: string, name: string, publicKeys: UserPublicKeys): Promise<{
+        success: boolean;
+        error?: string;
+        contact?: Contact;
+    }>;
+    /** Update a contact's name */
+    updateName(ownerUserId: string, contactUserId: string, newName: string): Promise<UpdateContactNameResult>;
+    /** Delete a contact and all related data */
+    delete(ownerUserId: string, contactUserId: string): Promise<DeleteContactResult>;
+}
+interface RefreshServiceAPI {
+    /** Handle session refresh (keep-alive, broken sessions, etc.) */
+    handleSessionRefresh(activeDiscussions: Discussion[]): Promise<void>;
+}
+interface SdkUtils {
+    /** Validate a user ID format */
+    validateUserId(userId: string): ValidationResult;
+    /** Validate a username format */
+    validateUsername(username: string): ValidationResult;
+    /** Encode raw bytes to user ID string */
+    encodeUserId(rawId: Uint8Array): string;
+    /** Decode user ID string to raw bytes */
+    decodeUserId(encodedId: string): Uint8Array;
+}
+interface PollingAPI {
+    /** Start polling for messages, announcements, and session refresh */
+    start(): void;
+    /** Stop all polling */
+    stop(): void;
+    /** Whether polling is currently running */
+    isRunning: boolean;
+}
+/** The singleton GossipSdk instance */
+export declare const gossipSdk: GossipSdkImpl;
+export { GossipSdkImpl };