@voidly/agent-sdk 1.0.0 → 1.1.0

package/dist/index.d.mts

@@ -140,6 +140,35 @@ declare class VoidlyAgent {
      * Get relay network statistics.
      */
     stats(): Promise<Record<string, unknown>>;
+    /**
+     * Register a webhook for real-time message delivery.
+     * Instead of polling receive(), messages are POSTed to your URL with HMAC signatures.
+     */
+    registerWebhook(webhookUrl: string, options?: {
+        events?: string[];
+    }): Promise<{
+        id: string;
+        secret: string;
+        webhook_url: string;
+    }>;
+    /**
+     * List registered webhooks.
+     */
+    listWebhooks(): Promise<Array<{
+        id: string;
+        webhook_url: string;
+        events: string[];
+        enabled: boolean;
+    }>>;
+    /**
+     * Delete a webhook.
+     */
+    deleteWebhook(webhookId: string): Promise<void>;
+    /**
+     * Verify a webhook payload signature (for use in your webhook handler).
+     * Returns true if the HMAC-SHA256 signature matches.
+     */
+    static verifyWebhookSignature(payload: string, signature: string, secret: string): Promise<boolean>;
     /**
      * Rotate this agent's keypairs. Old messages encrypted with old keys cannot be re-decrypted.
      */

package/dist/index.d.ts

@@ -140,6 +140,35 @@ declare class VoidlyAgent {
      * Get relay network statistics.
      */
     stats(): Promise<Record<string, unknown>>;
+    /**
+     * Register a webhook for real-time message delivery.
+     * Instead of polling receive(), messages are POSTed to your URL with HMAC signatures.
+     */
+    registerWebhook(webhookUrl: string, options?: {
+        events?: string[];
+    }): Promise<{
+        id: string;
+        secret: string;
+        webhook_url: string;
+    }>;
+    /**
+     * List registered webhooks.
+     */
+    listWebhooks(): Promise<Array<{
+        id: string;
+        webhook_url: string;
+        events: string[];
+        enabled: boolean;
+    }>>;
+    /**
+     * Delete a webhook.
+     */
+    deleteWebhook(webhookId: string): Promise<void>;
+    /**
+     * Verify a webhook payload signature (for use in your webhook handler).
+     * Returns true if the HMAC-SHA256 signature matches.
+     */
+    static verifyWebhookSignature(payload: string, signature: string, secret: string): Promise<boolean>;
     /**
      * Rotate this agent's keypairs. Old messages encrypted with old keys cannot be re-decrypted.
      */

package/dist/index.js

@@ -2555,6 +2555,72 @@ var VoidlyAgent = class _VoidlyAgent {
     const res = await fetch(`${this.baseUrl}/v1/agent/stats`);
     return await res.json();
   }
+  // ─── Webhooks ──────────────────────────────────────────────────────────────
+  /**
+   * Register a webhook for real-time message delivery.
+   * Instead of polling receive(), messages are POSTed to your URL with HMAC signatures.
+   */
+  async registerWebhook(webhookUrl, options = {}) {
+    const res = await fetch(`${this.baseUrl}/v1/agent/webhooks`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Agent-Key": this.apiKey
+      },
+      body: JSON.stringify({
+        webhook_url: webhookUrl,
+        events: options.events
+      })
+    });
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({}));
+      throw new Error(`Webhook registration failed: ${err.error?.message || err.error || res.statusText}`);
+    }
+    return await res.json();
+  }
+  /**
+   * List registered webhooks.
+   */
+  async listWebhooks() {
+    const res = await fetch(`${this.baseUrl}/v1/agent/webhooks`, {
+      headers: { "X-Agent-Key": this.apiKey }
+    });
+    if (!res.ok) return [];
+    const data = await res.json();
+    return data.webhooks;
+  }
+  /**
+   * Delete a webhook.
+   */
+  async deleteWebhook(webhookId) {
+    await fetch(`${this.baseUrl}/v1/agent/webhooks/${webhookId}`, {
+      method: "DELETE",
+      headers: { "X-Agent-Key": this.apiKey }
+    });
+  }
+  /**
+   * Verify a webhook payload signature (for use in your webhook handler).
+   * Returns true if the HMAC-SHA256 signature matches.
+   */
+  static async verifyWebhookSignature(payload, signature, secret) {
+    const encoder = new TextEncoder();
+    if (typeof globalThis.crypto?.subtle !== "undefined") {
+      const key = await globalThis.crypto.subtle.importKey(
+        "raw",
+        encoder.encode(secret),
+        { name: "HMAC", hash: "SHA-256" },
+        false,
+        ["sign"]
+      );
+      const sig = await globalThis.crypto.subtle.sign("HMAC", key, encoder.encode(payload));
+      const expectedSig2 = `sha256=${Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("")}`;
+      return signature === expectedSig2;
+    }
+    const { createHmac } = await import("crypto");
+    const expectedSig = `sha256=${createHmac("sha256", secret).update(payload).digest("hex")}`;
+    return signature === expectedSig;
+  }
+  // ─── Key Management ───────────────────────────────────────────────────────
   /**
    * Rotate this agent's keypairs. Old messages encrypted with old keys cannot be re-decrypted.
    */

package/dist/index.mjs

@@ -2545,6 +2545,72 @@ var VoidlyAgent = class _VoidlyAgent {
     const res = await fetch(`${this.baseUrl}/v1/agent/stats`);
     return await res.json();
   }
+  // ─── Webhooks ──────────────────────────────────────────────────────────────
+  /**
+   * Register a webhook for real-time message delivery.
+   * Instead of polling receive(), messages are POSTed to your URL with HMAC signatures.
+   */
+  async registerWebhook(webhookUrl, options = {}) {
+    const res = await fetch(`${this.baseUrl}/v1/agent/webhooks`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Agent-Key": this.apiKey
+      },
+      body: JSON.stringify({
+        webhook_url: webhookUrl,
+        events: options.events
+      })
+    });
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({}));
+      throw new Error(`Webhook registration failed: ${err.error?.message || err.error || res.statusText}`);
+    }
+    return await res.json();
+  }
+  /**
+   * List registered webhooks.
+   */
+  async listWebhooks() {
+    const res = await fetch(`${this.baseUrl}/v1/agent/webhooks`, {
+      headers: { "X-Agent-Key": this.apiKey }
+    });
+    if (!res.ok) return [];
+    const data = await res.json();
+    return data.webhooks;
+  }
+  /**
+   * Delete a webhook.
+   */
+  async deleteWebhook(webhookId) {
+    await fetch(`${this.baseUrl}/v1/agent/webhooks/${webhookId}`, {
+      method: "DELETE",
+      headers: { "X-Agent-Key": this.apiKey }
+    });
+  }
+  /**
+   * Verify a webhook payload signature (for use in your webhook handler).
+   * Returns true if the HMAC-SHA256 signature matches.
+   */
+  static async verifyWebhookSignature(payload, signature, secret) {
+    const encoder = new TextEncoder();
+    if (typeof globalThis.crypto?.subtle !== "undefined") {
+      const key = await globalThis.crypto.subtle.importKey(
+        "raw",
+        encoder.encode(secret),
+        { name: "HMAC", hash: "SHA-256" },
+        false,
+        ["sign"]
+      );
+      const sig = await globalThis.crypto.subtle.sign("HMAC", key, encoder.encode(payload));
+      const expectedSig2 = `sha256=${Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("")}`;
+      return signature === expectedSig2;
+    }
+    const { createHmac } = await import("crypto");
+    const expectedSig = `sha256=${createHmac("sha256", secret).update(payload).digest("hex")}`;
+    return signature === expectedSig;
+  }
+  // ─── Key Management ───────────────────────────────────────────────────────
   /**
    * Rotate this agent's keypairs. Old messages encrypted with old keys cannot be re-decrypted.
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voidly/agent-sdk",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "E2E encrypted agent-to-agent communication SDK — true client-side encryption",
   "main": "dist/index.js",
   "module": "dist/index.mjs",