@voidly/agent-sdk 3.0.0 → 3.2.0

package/dist/index.d.mts

@@ -85,6 +85,17 @@ interface VoidlyAgentConfig {
     jitterMs?: number;
     /** Use long-poll for listen() instead of short-interval polling (default: true) */
     longPoll?: boolean;
+    /** Auto-persist ratchet state after every send/receive (default: 'memory' = no persistence) */
+    persist?: 'memory' | 'localStorage' | 'indexedDB' | 'file' | 'relay' | 'custom';
+    /** Custom persistence: called after each ratchet step with encrypted blob */
+    onPersist?: (encryptedState: string) => void | Promise<void>;
+    /** Custom persistence: called on startup to load encrypted blob */
+    onLoad?: () => string | null | Promise<string | null>;
+    /** File path for persist: 'file' (Node.js environments only) */
+    persistPath?: string;
+    /** Transport preference for listen() — tries in order, falls back automatically
+     * Default: ['sse', 'long-poll']. Options: 'websocket' | 'sse' | 'long-poll' */
+    transport?: ('websocket' | 'sse' | 'long-poll')[];
 }
 interface ListenOptions {
     /** Milliseconds between polls (default: 2000, min: 500) */
@@ -181,6 +192,16 @@ declare class VoidlyAgent {
     private _identityCache;
     private _seenMessageIds;
     private _decryptFailCount;
+    private _rpcHandlers;
+    private _rpcPending;
+    private _coverTrafficTimer;
+    private _rpcListener;
+    private _persistMode;
+    private _onPersist?;
+    private _onLoad?;
+    private _persistPath?;
+    private _persistKey;
+    private _transportPrefs;
     private constructor();
     /**
      * Register a new agent on the Voidly relay.
@@ -244,6 +265,26 @@ declare class VoidlyAgent {
         signedPrekeyPublic?: string;
         signedPrekeyId?: number;
     };
+    /** Derive persistence encryption key from signing secret */
+    private _derivePersistKey;
+    /** Auto-persist ratchet state (called after every ratchet mutation) */
+    private _persistRatchetState;
+    /** Load persisted ratchet state and restore into memory */
+    private _loadPersistedRatchetState;
+    /** IndexedDB put helper (browser only) */
+    private _idbPut;
+    /** IndexedDB get helper (browser only) */
+    private _idbGet;
+    /**
+     * Force-persist current ratchet state.
+     * Useful to call before process exit to ensure state is saved.
+     */
+    flushRatchetState(): Promise<void>;
+    /**
+     * Restore an agent from credentials with async persistence loading.
+     * Use this instead of `fromCredentials()` when using file/relay/custom persistence.
+     */
+    static fromCredentialsAsync(creds: Parameters<typeof VoidlyAgent.fromCredentials>[0], config?: VoidlyAgentConfig): Promise<VoidlyAgent>;
     /**
      * Get the number of messages that failed to decrypt.
      * Useful for detecting key mismatches, attacks, or corruption.
@@ -296,6 +337,8 @@ declare class VoidlyAgent {
         messageType?: string;
         unreadOnly?: boolean;
     }): Promise<DecryptedMessage[]>;
+    /** Decrypt raw message objects (shared by receive(), SSE, WebSocket transports) */
+    private _decryptMessages;
     /**
      * Delete a message by ID (must be sender or recipient).
      */
@@ -996,6 +1039,100 @@ declare class VoidlyAgent {
      * Stop all active listeners. Useful for clean shutdown.
      */
     stopAll(): void;
+    /**
+     * Invoke a function on a remote agent. Synchronous RPC over encrypted messaging.
+     * The remote agent must have registered a handler via `onInvoke()`.
+     *
+     * @example
+     * ```ts
+     * // Call a translator agent
+     * const result = await agent.invoke('did:voidly:translator', 'translate', {
+     *   text: 'Hello, world!',
+     *   to: 'ja',
+     * });
+     * console.log(result.translation); // こんにちは
+     *
+     * // With timeout
+     * const data = await agent.invoke(peerDid, 'analyze', { url: '...' }, 15000);
+     * ```
+     */
+    invoke(targetDid: string, method: string, params?: any, timeoutMs?: number): Promise<any>;
+    /**
+     * Register a handler for incoming RPC invocations.
+     * When another agent calls `invoke(yourDid, method, params)`, your handler runs.
+     *
+     * @example
+     * ```ts
+     * // Register a translation capability
+     * agent.onInvoke('translate', async (params, callerDid) => {
+     *   const result = await myTranslateFunction(params.text, params.to);
+     *   return { translation: result };
+     * });
+     *
+     * // Register a search capability
+     * agent.onInvoke('search', async (params) => {
+     *   return { results: await searchDatabase(params.query) };
+     * });
+     * ```
+     */
+    onInvoke(method: string, handler: (params: any, callerDid: string) => Promise<any>): void;
+    /**
+     * Remove an RPC handler.
+     */
+    offInvoke(method: string): void;
+    /** @internal Start listening for RPC requests and responses */
+    private _ensureRpcListener;
+    /**
+     * Send a message directly to a peer's webhook endpoint, bypassing the relay entirely.
+     * The relay never sees the message — true peer-to-peer encrypted delivery.
+     *
+     * Falls back to relay-based send if direct delivery fails.
+     *
+     * @example
+     * ```ts
+     * // Try direct first, fall back to relay
+     * const result = await agent.sendDirect('did:voidly:peer', 'Hello P2P!');
+     * console.log(result.direct); // true if delivered directly, false if via relay
+     * ```
+     */
+    sendDirect(recipientDid: string, message: string, options?: {
+        contentType?: string;
+        messageType?: string;
+        threadId?: string;
+        ttl?: number;
+    }): Promise<SendResult & {
+        direct: boolean;
+    }>;
+    /**
+     * Enable cover traffic — sends encrypted noise at random intervals.
+     * Makes real messages indistinguishable from cover traffic for any observer
+     * monitoring message timing and frequency.
+     *
+     * Cover messages are encrypted and padded identically to real messages.
+     * The relay cannot distinguish them from real traffic.
+     *
+     * @example
+     * ```ts
+     * // Send noise every ~30s (randomized ±50%)
+     * agent.enableCoverTraffic({ intervalMs: 30000 });
+     *
+     * // Stop cover traffic
+     * agent.disableCoverTraffic();
+     * ```
+     */
+    enableCoverTraffic(options?: {
+        intervalMs?: number;
+    }): void;
+    /**
+     * Disable cover traffic.
+     */
+    disableCoverTraffic(): void;
+    /**
+     * Fetch from primary relay with fallback to alternate relays.
+     * Unlike _timedFetch which only hits one URL, this tries all known relays.
+     * @internal
+     */
+    private _resilientFetch;
     /**
      * Start or resume a conversation with another agent.
      * Automatically manages thread IDs, message history, and reply chains.

package/dist/index.d.ts

@@ -85,6 +85,17 @@ interface VoidlyAgentConfig {
     jitterMs?: number;
     /** Use long-poll for listen() instead of short-interval polling (default: true) */
     longPoll?: boolean;
+    /** Auto-persist ratchet state after every send/receive (default: 'memory' = no persistence) */
+    persist?: 'memory' | 'localStorage' | 'indexedDB' | 'file' | 'relay' | 'custom';
+    /** Custom persistence: called after each ratchet step with encrypted blob */
+    onPersist?: (encryptedState: string) => void | Promise<void>;
+    /** Custom persistence: called on startup to load encrypted blob */
+    onLoad?: () => string | null | Promise<string | null>;
+    /** File path for persist: 'file' (Node.js environments only) */
+    persistPath?: string;
+    /** Transport preference for listen() — tries in order, falls back automatically
+     * Default: ['sse', 'long-poll']. Options: 'websocket' | 'sse' | 'long-poll' */
+    transport?: ('websocket' | 'sse' | 'long-poll')[];
 }
 interface ListenOptions {
     /** Milliseconds between polls (default: 2000, min: 500) */
@@ -181,6 +192,16 @@ declare class VoidlyAgent {
     private _identityCache;
     private _seenMessageIds;
     private _decryptFailCount;
+    private _rpcHandlers;
+    private _rpcPending;
+    private _coverTrafficTimer;
+    private _rpcListener;
+    private _persistMode;
+    private _onPersist?;
+    private _onLoad?;
+    private _persistPath?;
+    private _persistKey;
+    private _transportPrefs;
     private constructor();
     /**
      * Register a new agent on the Voidly relay.
@@ -244,6 +265,26 @@ declare class VoidlyAgent {
         signedPrekeyPublic?: string;
         signedPrekeyId?: number;
     };
+    /** Derive persistence encryption key from signing secret */
+    private _derivePersistKey;
+    /** Auto-persist ratchet state (called after every ratchet mutation) */
+    private _persistRatchetState;
+    /** Load persisted ratchet state and restore into memory */
+    private _loadPersistedRatchetState;
+    /** IndexedDB put helper (browser only) */
+    private _idbPut;
+    /** IndexedDB get helper (browser only) */
+    private _idbGet;
+    /**
+     * Force-persist current ratchet state.
+     * Useful to call before process exit to ensure state is saved.
+     */
+    flushRatchetState(): Promise<void>;
+    /**
+     * Restore an agent from credentials with async persistence loading.
+     * Use this instead of `fromCredentials()` when using file/relay/custom persistence.
+     */
+    static fromCredentialsAsync(creds: Parameters<typeof VoidlyAgent.fromCredentials>[0], config?: VoidlyAgentConfig): Promise<VoidlyAgent>;
     /**
      * Get the number of messages that failed to decrypt.
      * Useful for detecting key mismatches, attacks, or corruption.
@@ -296,6 +337,8 @@ declare class VoidlyAgent {
         messageType?: string;
         unreadOnly?: boolean;
     }): Promise<DecryptedMessage[]>;
+    /** Decrypt raw message objects (shared by receive(), SSE, WebSocket transports) */
+    private _decryptMessages;
     /**
      * Delete a message by ID (must be sender or recipient).
      */
@@ -996,6 +1039,100 @@ declare class VoidlyAgent {
      * Stop all active listeners. Useful for clean shutdown.
      */
     stopAll(): void;
+    /**
+     * Invoke a function on a remote agent. Synchronous RPC over encrypted messaging.
+     * The remote agent must have registered a handler via `onInvoke()`.
+     *
+     * @example
+     * ```ts
+     * // Call a translator agent
+     * const result = await agent.invoke('did:voidly:translator', 'translate', {
+     *   text: 'Hello, world!',
+     *   to: 'ja',
+     * });
+     * console.log(result.translation); // こんにちは
+     *
+     * // With timeout
+     * const data = await agent.invoke(peerDid, 'analyze', { url: '...' }, 15000);
+     * ```
+     */
+    invoke(targetDid: string, method: string, params?: any, timeoutMs?: number): Promise<any>;
+    /**
+     * Register a handler for incoming RPC invocations.
+     * When another agent calls `invoke(yourDid, method, params)`, your handler runs.
+     *
+     * @example
+     * ```ts
+     * // Register a translation capability
+     * agent.onInvoke('translate', async (params, callerDid) => {
+     *   const result = await myTranslateFunction(params.text, params.to);
+     *   return { translation: result };
+     * });
+     *
+     * // Register a search capability
+     * agent.onInvoke('search', async (params) => {
+     *   return { results: await searchDatabase(params.query) };
+     * });
+     * ```
+     */
+    onInvoke(method: string, handler: (params: any, callerDid: string) => Promise<any>): void;
+    /**
+     * Remove an RPC handler.
+     */
+    offInvoke(method: string): void;
+    /** @internal Start listening for RPC requests and responses */
+    private _ensureRpcListener;
+    /**
+     * Send a message directly to a peer's webhook endpoint, bypassing the relay entirely.
+     * The relay never sees the message — true peer-to-peer encrypted delivery.
+     *
+     * Falls back to relay-based send if direct delivery fails.
+     *
+     * @example
+     * ```ts
+     * // Try direct first, fall back to relay
+     * const result = await agent.sendDirect('did:voidly:peer', 'Hello P2P!');
+     * console.log(result.direct); // true if delivered directly, false if via relay
+     * ```
+     */
+    sendDirect(recipientDid: string, message: string, options?: {
+        contentType?: string;
+        messageType?: string;
+        threadId?: string;
+        ttl?: number;
+    }): Promise<SendResult & {
+        direct: boolean;
+    }>;
+    /**
+     * Enable cover traffic — sends encrypted noise at random intervals.
+     * Makes real messages indistinguishable from cover traffic for any observer
+     * monitoring message timing and frequency.
+     *
+     * Cover messages are encrypted and padded identically to real messages.
+     * The relay cannot distinguish them from real traffic.
+     *
+     * @example
+     * ```ts
+     * // Send noise every ~30s (randomized ±50%)
+     * agent.enableCoverTraffic({ intervalMs: 30000 });
+     *
+     * // Stop cover traffic
+     * agent.disableCoverTraffic();
+     * ```
+     */
+    enableCoverTraffic(options?: {
+        intervalMs?: number;
+    }): void;
+    /**
+     * Disable cover traffic.
+     */
+    disableCoverTraffic(): void;
+    /**
+     * Fetch from primary relay with fallback to alternate relays.
+     * Unlike _timedFetch which only hits one URL, this tries all known relays.
+     * @internal
+     */
+    private _resilientFetch;
     /**
      * Start or resume a conversation with another agent.
      * Automatically manages thread IDs, message history, and reply chains.