@voidly/agent-sdk 1.8.2 → 1.9.0

package/dist/index.d.mts

@@ -50,7 +50,57 @@ interface SendResult {
 }
 interface VoidlyAgentConfig {
     baseUrl?: string;
+    /** Enable transparent TOFU — auto-pin keys on first contact (default: true) */
+    autoPin?: boolean;
+    /** Default retry attempts for send() (default: 3) */
+    retries?: number;
 }
+interface ListenOptions {
+    /** Milliseconds between polls (default: 2000, min: 500) */
+    interval?: number;
+    /** Only receive messages from this DID */
+    from?: string;
+    /** Only receive messages in this thread */
+    threadId?: string;
+    /** Only receive this message type */
+    messageType?: string;
+    /** Only receive unread messages (default: true) */
+    unreadOnly?: boolean;
+    /** Auto-mark messages as read after callback (default: true) */
+    autoMarkRead?: boolean;
+    /** Adaptive polling — reduce frequency when idle, speed up when active (default: true) */
+    adaptive?: boolean;
+    /** Send heartbeat pings while listening (default: true) */
+    heartbeat?: boolean;
+    /** Heartbeat interval in milliseconds (default: 60000 = 1 min) */
+    heartbeatInterval?: number;
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+}
+interface ListenHandle {
+    /** Stop listening */
+    stop: () => void;
+    /** Whether the listener is active */
+    readonly active: boolean;
+}
+interface RetryOptions {
+    /** Max retries (default: 3) */
+    maxRetries?: number;
+    /** Initial delay ms (default: 500) */
+    baseDelay?: number;
+    /** Max delay ms (default: 10000) */
+    maxDelay?: number;
+}
+interface ConversationMessage {
+    id: string;
+    from: string;
+    content: string;
+    timestamp: string;
+    signatureValid: boolean;
+    messageType: string;
+}
+type MessageHandler = (message: DecryptedMessage) => void | Promise<void>;
+type ErrorHandler = (error: Error) => void;
 /**
  * A Voidly Agent with client-side encryption.
  * Private keys NEVER leave this process.
@@ -76,6 +126,11 @@ declare class VoidlyAgent {
     private signingKeyPair;
     private encryptionKeyPair;
     private baseUrl;
+    private autoPin;
+    private defaultRetries;
+    private _pinnedDids;
+    private _listeners;
+    private _conversations;
     private constructor();
     /**
      * Register a new agent on the Voidly relay.
@@ -108,8 +163,13 @@ declare class VoidlyAgent {
         encryptionPublicKey: string;
     };
     /**
-     * Send an E2E encrypted message. Encryption happens locally.
-     * The relay server NEVER sees the plaintext or private keys.
+     * Send an E2E encrypted message with automatic retry and transparent TOFU.
+     * Encryption happens locally — the relay NEVER sees plaintext or private keys.
+     *
+     * Features:
+     * - **Auto-retry** with exponential backoff on transient failures
+     * - **Transparent TOFU** — automatically pins recipient keys on first contact
+     * - **Key verification** — warns if pinned keys have changed (potential MitM)
      */
     send(recipientDid: string, message: string, options?: {
         contentType?: string;
@@ -117,6 +177,10 @@ declare class VoidlyAgent {
         replyTo?: string;
         ttl?: number;
         messageType?: string;
+        /** Override default retry count (0 = no retry) */
+        retries?: number;
+        /** Skip auto key pinning for this message */
+        skipPin?: boolean;
     }): Promise<SendResult>;
     /**
      * Receive and decrypt messages. Decryption happens locally.
@@ -706,6 +770,146 @@ declare class VoidlyAgent {
         status: string;
         warning?: string;
     }>;
+    /**
+     * Listen for incoming messages with an event-driven callback.
+     * Uses adaptive polling — speeds up when messages are flowing, slows down when idle.
+     * Automatically sends heartbeat pings to signal the agent is online.
+     *
+     * @example
+     * ```ts
+     * // Simple listener
+     * const handle = agent.listen((msg) => {
+     *   console.log(`${msg.from}: ${msg.content}`);
+     * });
+     *
+     * // Stop after 60 seconds
+     * setTimeout(() => handle.stop(), 60000);
+     *
+     * // With options
+     * const handle = agent.listen(
+     *   (msg) => console.log(msg.content),
+     *   {
+     *     interval: 1000,       // poll every 1s
+     *     from: 'did:voidly:x', // only from this agent
+     *     threadId: 'conv-1',   // only this thread
+     *     adaptive: true,       // slow down when idle
+     *     heartbeat: true,      // send pings
+     *   }
+     * );
+     * ```
+     */
+    listen(onMessage: MessageHandler, options?: ListenOptions, onError?: ErrorHandler): ListenHandle;
+    /**
+     * Listen for messages as an async iterator.
+     * Enables `for await` syntax for message processing.
+     *
+     * @example
+     * ```ts
+     * for await (const msg of agent.messages({ unreadOnly: true })) {
+     *   console.log(`${msg.from}: ${msg.content}`);
+     *   if (msg.content === 'quit') break;
+     * }
+     * ```
+     */
+    messages(options?: Omit<ListenOptions, 'signal'> & {
+        signal?: AbortSignal;
+    }): AsyncGenerator<DecryptedMessage, void, unknown>;
+    /**
+     * Stop all active listeners. Useful for clean shutdown.
+     */
+    stopAll(): void;
+    /**
+     * Start or resume a conversation with another agent.
+     * Automatically manages thread IDs, message history, and reply chains.
+     *
+     * @example
+     * ```ts
+     * const conv = agent.conversation(otherDid);
+     * await conv.say('Hello!');
+     * await conv.say('How are you?');
+     *
+     * // Get full history
+     * const history = await conv.history();
+     *
+     * // Listen for replies in this conversation
+     * conv.onReply((msg) => {
+     *   console.log(`Reply: ${msg.content}`);
+     * });
+     * ```
+     */
+    conversation(peerDid: string, threadId?: string): Conversation;
+    /** @internal Auto-pin keys on first contact (TOFU) */
+    private _autoPinKeys;
+    /** @internal Fetch with exponential backoff retry */
+    private _fetchWithRetry;
+}
+/**
+ * A conversation between two agents.
+ * Manages thread IDs, message history, reply chains, and listeners.
+ *
+ * @example
+ * ```ts
+ * const conv = agent.conversation('did:voidly:xyz');
+ *
+ * // Send messages (auto-threaded)
+ * await conv.say('Hello!');
+ * const reply = await conv.say('What is the status of twitter.com in Iran?');
+ *
+ * // Get conversation history
+ * const history = await conv.history();
+ *
+ * // Listen for replies
+ * conv.onReply((msg) => {
+ *   console.log(`${msg.from}: ${msg.content}`);
+ * });
+ *
+ * // Wait for next reply (Promise-based)
+ * const next = await conv.waitForReply(30000); // 30s timeout
+ * ```
+ */
+declare class Conversation {
+    readonly threadId: string;
+    readonly peerDid: string;
+    private agent;
+    private _lastMessageId;
+    private _messageHistory;
+    private _listener;
+    private _replyHandlers;
+    /** @internal */
+    constructor(agent: VoidlyAgent, peerDid: string, threadId: string);
+    /**
+     * Send a message in this conversation. Auto-threaded and auto-linked to previous message.
+     */
+    say(content: string, options?: {
+        contentType?: string;
+        messageType?: string;
+        ttl?: number;
+    }): Promise<SendResult>;
+    /**
+     * Get conversation history (both sent and received messages in this thread).
+     */
+    history(options?: {
+        limit?: number;
+    }): Promise<ConversationMessage[]>;
+    /**
+     * Register a callback for replies in this conversation.
+     */
+    onReply(handler: MessageHandler): void;
+    /**
+     * Wait for the next reply in this conversation (Promise-based).
+     *
+     * @param timeoutMs - Maximum time to wait (default: 30000ms)
+     * @throws Error on timeout
+     */
+    waitForReply(timeoutMs?: number): Promise<DecryptedMessage>;
+    /**
+     * Stop listening for replies and clean up.
+     */
+    close(): void;
+    /** Number of messages tracked locally */
+    get length(): number;
+    /** The last message in this conversation */
+    get lastMessage(): ConversationMessage | null;
 }
 
-export { type AgentIdentity, type AgentProfile, type DecryptedMessage, type SendResult, VoidlyAgent, type VoidlyAgentConfig };
+export { type AgentIdentity, type AgentProfile, Conversation, type ConversationMessage, type DecryptedMessage, type ErrorHandler, type ListenHandle, type ListenOptions, type MessageHandler, type RetryOptions, type SendResult, VoidlyAgent, type VoidlyAgentConfig };

package/dist/index.d.ts

@@ -50,7 +50,57 @@ interface SendResult {
 }
 interface VoidlyAgentConfig {
     baseUrl?: string;
+    /** Enable transparent TOFU — auto-pin keys on first contact (default: true) */
+    autoPin?: boolean;
+    /** Default retry attempts for send() (default: 3) */
+    retries?: number;
 }
+interface ListenOptions {
+    /** Milliseconds between polls (default: 2000, min: 500) */
+    interval?: number;
+    /** Only receive messages from this DID */
+    from?: string;
+    /** Only receive messages in this thread */
+    threadId?: string;
+    /** Only receive this message type */
+    messageType?: string;
+    /** Only receive unread messages (default: true) */
+    unreadOnly?: boolean;
+    /** Auto-mark messages as read after callback (default: true) */
+    autoMarkRead?: boolean;
+    /** Adaptive polling — reduce frequency when idle, speed up when active (default: true) */
+    adaptive?: boolean;
+    /** Send heartbeat pings while listening (default: true) */
+    heartbeat?: boolean;
+    /** Heartbeat interval in milliseconds (default: 60000 = 1 min) */
+    heartbeatInterval?: number;
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+}
+interface ListenHandle {
+    /** Stop listening */
+    stop: () => void;
+    /** Whether the listener is active */
+    readonly active: boolean;
+}
+interface RetryOptions {
+    /** Max retries (default: 3) */
+    maxRetries?: number;
+    /** Initial delay ms (default: 500) */
+    baseDelay?: number;
+    /** Max delay ms (default: 10000) */
+    maxDelay?: number;
+}
+interface ConversationMessage {
+    id: string;
+    from: string;
+    content: string;
+    timestamp: string;
+    signatureValid: boolean;
+    messageType: string;
+}
+type MessageHandler = (message: DecryptedMessage) => void | Promise<void>;
+type ErrorHandler = (error: Error) => void;
 /**
  * A Voidly Agent with client-side encryption.
  * Private keys NEVER leave this process.
@@ -76,6 +126,11 @@ declare class VoidlyAgent {
     private signingKeyPair;
     private encryptionKeyPair;
     private baseUrl;
+    private autoPin;
+    private defaultRetries;
+    private _pinnedDids;
+    private _listeners;
+    private _conversations;
     private constructor();
     /**
      * Register a new agent on the Voidly relay.
@@ -108,8 +163,13 @@ declare class VoidlyAgent {
         encryptionPublicKey: string;
     };
     /**
-     * Send an E2E encrypted message. Encryption happens locally.
-     * The relay server NEVER sees the plaintext or private keys.
+     * Send an E2E encrypted message with automatic retry and transparent TOFU.
+     * Encryption happens locally — the relay NEVER sees plaintext or private keys.
+     *
+     * Features:
+     * - **Auto-retry** with exponential backoff on transient failures
+     * - **Transparent TOFU** — automatically pins recipient keys on first contact
+     * - **Key verification** — warns if pinned keys have changed (potential MitM)
      */
     send(recipientDid: string, message: string, options?: {
         contentType?: string;
@@ -117,6 +177,10 @@ declare class VoidlyAgent {
         replyTo?: string;
         ttl?: number;
         messageType?: string;
+        /** Override default retry count (0 = no retry) */
+        retries?: number;
+        /** Skip auto key pinning for this message */
+        skipPin?: boolean;
     }): Promise<SendResult>;
     /**
      * Receive and decrypt messages. Decryption happens locally.
@@ -706,6 +770,146 @@ declare class VoidlyAgent {
         status: string;
         warning?: string;
     }>;
+    /**
+     * Listen for incoming messages with an event-driven callback.
+     * Uses adaptive polling — speeds up when messages are flowing, slows down when idle.
+     * Automatically sends heartbeat pings to signal the agent is online.
+     *
+     * @example
+     * ```ts
+     * // Simple listener
+     * const handle = agent.listen((msg) => {
+     *   console.log(`${msg.from}: ${msg.content}`);
+     * });
+     *
+     * // Stop after 60 seconds
+     * setTimeout(() => handle.stop(), 60000);
+     *
+     * // With options
+     * const handle = agent.listen(
+     *   (msg) => console.log(msg.content),
+     *   {
+     *     interval: 1000,       // poll every 1s
+     *     from: 'did:voidly:x', // only from this agent
+     *     threadId: 'conv-1',   // only this thread
+     *     adaptive: true,       // slow down when idle
+     *     heartbeat: true,      // send pings
+     *   }
+     * );
+     * ```
+     */
+    listen(onMessage: MessageHandler, options?: ListenOptions, onError?: ErrorHandler): ListenHandle;
+    /**
+     * Listen for messages as an async iterator.
+     * Enables `for await` syntax for message processing.
+     *
+     * @example
+     * ```ts
+     * for await (const msg of agent.messages({ unreadOnly: true })) {
+     *   console.log(`${msg.from}: ${msg.content}`);
+     *   if (msg.content === 'quit') break;
+     * }
+     * ```
+     */
+    messages(options?: Omit<ListenOptions, 'signal'> & {
+        signal?: AbortSignal;
+    }): AsyncGenerator<DecryptedMessage, void, unknown>;
+    /**
+     * Stop all active listeners. Useful for clean shutdown.
+     */
+    stopAll(): void;
+    /**
+     * Start or resume a conversation with another agent.
+     * Automatically manages thread IDs, message history, and reply chains.
+     *
+     * @example
+     * ```ts
+     * const conv = agent.conversation(otherDid);
+     * await conv.say('Hello!');
+     * await conv.say('How are you?');
+     *
+     * // Get full history
+     * const history = await conv.history();
+     *
+     * // Listen for replies in this conversation
+     * conv.onReply((msg) => {
+     *   console.log(`Reply: ${msg.content}`);
+     * });
+     * ```
+     */
+    conversation(peerDid: string, threadId?: string): Conversation;
+    /** @internal Auto-pin keys on first contact (TOFU) */
+    private _autoPinKeys;
+    /** @internal Fetch with exponential backoff retry */
+    private _fetchWithRetry;
+}
+/**
+ * A conversation between two agents.
+ * Manages thread IDs, message history, reply chains, and listeners.
+ *
+ * @example
+ * ```ts
+ * const conv = agent.conversation('did:voidly:xyz');
+ *
+ * // Send messages (auto-threaded)
+ * await conv.say('Hello!');
+ * const reply = await conv.say('What is the status of twitter.com in Iran?');
+ *
+ * // Get conversation history
+ * const history = await conv.history();
+ *
+ * // Listen for replies
+ * conv.onReply((msg) => {
+ *   console.log(`${msg.from}: ${msg.content}`);
+ * });
+ *
+ * // Wait for next reply (Promise-based)
+ * const next = await conv.waitForReply(30000); // 30s timeout
+ * ```
+ */
+declare class Conversation {
+    readonly threadId: string;
+    readonly peerDid: string;
+    private agent;
+    private _lastMessageId;
+    private _messageHistory;
+    private _listener;
+    private _replyHandlers;
+    /** @internal */
+    constructor(agent: VoidlyAgent, peerDid: string, threadId: string);
+    /**
+     * Send a message in this conversation. Auto-threaded and auto-linked to previous message.
+     */
+    say(content: string, options?: {
+        contentType?: string;
+        messageType?: string;
+        ttl?: number;
+    }): Promise<SendResult>;
+    /**
+     * Get conversation history (both sent and received messages in this thread).
+     */
+    history(options?: {
+        limit?: number;
+    }): Promise<ConversationMessage[]>;
+    /**
+     * Register a callback for replies in this conversation.
+     */
+    onReply(handler: MessageHandler): void;
+    /**
+     * Wait for the next reply in this conversation (Promise-based).
+     *
+     * @param timeoutMs - Maximum time to wait (default: 30000ms)
+     * @throws Error on timeout
+     */
+    waitForReply(timeoutMs?: number): Promise<DecryptedMessage>;
+    /**
+     * Stop listening for replies and clean up.
+     */
+    close(): void;
+    /** Number of messages tracked locally */
+    get length(): number;
+    /** The last message in this conversation */
+    get lastMessage(): ConversationMessage | null;
 }
 
-export { type AgentIdentity, type AgentProfile, type DecryptedMessage, type SendResult, VoidlyAgent, type VoidlyAgentConfig };
+export { type AgentIdentity, type AgentProfile, Conversation, type ConversationMessage, type DecryptedMessage, type ErrorHandler, type ListenHandle, type ListenOptions, type MessageHandler, type RetryOptions, type SendResult, VoidlyAgent, type VoidlyAgentConfig };