@voidly/agent-sdk 1.8.2 → 2.0.0

package/dist/index.d.mts

@@ -50,7 +50,63 @@ 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;
+    /** Fallback relays — if primary fails, try these in order */
+    fallbackRelays?: string[];
+    /** Enable message padding to resist traffic analysis (default: true) */
+    padding?: boolean;
+    /** Enable sealed sender — hide sender DID from relay metadata (default: false) */
+    sealedSender?: boolean;
 }
+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 +132,16 @@ declare class VoidlyAgent {
     private signingKeyPair;
     private encryptionKeyPair;
     private baseUrl;
+    private autoPin;
+    private defaultRetries;
+    private fallbackRelays;
+    private paddingEnabled;
+    private sealedSender;
+    private _pinnedDids;
+    private _listeners;
+    private _conversations;
+    private _offlineQueue;
+    private _ratchetStates;
     private constructor();
     /**
      * Register a new agent on the Voidly relay.
@@ -108,8 +174,17 @@ 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 hardened security.
+     * Encryption happens locally — the relay NEVER sees plaintext or private keys.
+     *
+     * Security features:
+     * - **Message padding** — ciphertext padded to power-of-2 boundary (traffic analysis resistance)
+     * - **Hash ratchet** — per-conversation forward secrecy (compromise key[n] can't derive key[n-1])
+     * - **Sealed sender** — optionally hide sender DID from relay metadata
+     * - **Auto-retry** with exponential backoff on transient failures
+     * - **Multi-relay fallback** — try backup relays if primary is down
+     * - **Offline queue** — queue messages if all relays fail
+     * - **Transparent TOFU** — auto-pin recipient keys on first contact
      */
     send(recipientDid: string, message: string, options?: {
         contentType?: string;
@@ -117,6 +192,14 @@ 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;
+        /** Force sealed sender for this message */
+        sealedSender?: boolean;
+        /** Disable padding for this message */
+        noPadding?: boolean;
     }): Promise<SendResult>;
     /**
      * Receive and decrypt messages. Decryption happens locally.
@@ -706,6 +789,168 @@ 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;
+    /**
+     * Drain the offline message queue — retry sending queued messages.
+     * Call this when connectivity is restored.
+     * Returns: number of messages successfully sent.
+     */
+    drainQueue(): Promise<{
+        sent: number;
+        failed: number;
+        remaining: number;
+    }>;
+    /** Number of messages waiting in the offline queue */
+    get queueLength(): number;
+    /**
+     * Returns what the relay can and cannot see about this agent.
+     * Call this to understand your threat model. Total transparency.
+     */
+    threatModel(): {
+        relayCanSee: string[];
+        relayCannotSee: string[];
+        protections: string[];
+        gaps: string[];
+    };
+}
+/**
+ * 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,63 @@ 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;
+    /** Fallback relays — if primary fails, try these in order */
+    fallbackRelays?: string[];
+    /** Enable message padding to resist traffic analysis (default: true) */
+    padding?: boolean;
+    /** Enable sealed sender — hide sender DID from relay metadata (default: false) */
+    sealedSender?: boolean;
 }
+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 +132,16 @@ declare class VoidlyAgent {
     private signingKeyPair;
     private encryptionKeyPair;
     private baseUrl;
+    private autoPin;
+    private defaultRetries;
+    private fallbackRelays;
+    private paddingEnabled;
+    private sealedSender;
+    private _pinnedDids;
+    private _listeners;
+    private _conversations;
+    private _offlineQueue;
+    private _ratchetStates;
     private constructor();
     /**
      * Register a new agent on the Voidly relay.
@@ -108,8 +174,17 @@ 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 hardened security.
+     * Encryption happens locally — the relay NEVER sees plaintext or private keys.
+     *
+     * Security features:
+     * - **Message padding** — ciphertext padded to power-of-2 boundary (traffic analysis resistance)
+     * - **Hash ratchet** — per-conversation forward secrecy (compromise key[n] can't derive key[n-1])
+     * - **Sealed sender** — optionally hide sender DID from relay metadata
+     * - **Auto-retry** with exponential backoff on transient failures
+     * - **Multi-relay fallback** — try backup relays if primary is down
+     * - **Offline queue** — queue messages if all relays fail
+     * - **Transparent TOFU** — auto-pin recipient keys on first contact
      */
     send(recipientDid: string, message: string, options?: {
         contentType?: string;
@@ -117,6 +192,14 @@ 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;
+        /** Force sealed sender for this message */
+        sealedSender?: boolean;
+        /** Disable padding for this message */
+        noPadding?: boolean;
     }): Promise<SendResult>;
     /**
      * Receive and decrypt messages. Decryption happens locally.
@@ -706,6 +789,168 @@ 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;
+    /**
+     * Drain the offline message queue — retry sending queued messages.
+     * Call this when connectivity is restored.
+     * Returns: number of messages successfully sent.
+     */
+    drainQueue(): Promise<{
+        sent: number;
+        failed: number;
+        remaining: number;
+    }>;
+    /** Number of messages waiting in the offline queue */
+    get queueLength(): number;
+    /**
+     * Returns what the relay can and cannot see about this agent.
+     * Call this to understand your threat model. Total transparency.
+     */
+    threatModel(): {
+        relayCanSee: string[];
+        relayCannotSee: string[];
+        protections: string[];
+        gaps: string[];
+    };
+}
+/**
+ * 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 };