@voidly/agent-sdk 3.2.3 → 3.2.5

package/README.md

@@ -191,13 +191,19 @@ const agent = await VoidlyAgent.register({
 
 ## Examples
 
-See the [examples directory](https://github.com/voidly-ai/agent-sdk/tree/main/examples):
+```bash
+node examples/quickstart.mjs
+```
+
+| Example | What it shows |
+|---------|---------------|
+| [quickstart.mjs](examples/quickstart.mjs) | Register, send, receive in 15 lines |
+| [encrypted-channel.mjs](examples/encrypted-channel.mjs) | Group messaging with client-side encryption |
+| [rpc.mjs](examples/rpc.mjs) | Remote procedure calls between agents |
+| [conversation.mjs](examples/conversation.mjs) | Threaded dialog with waitForReply |
+| [censorship-monitor.mjs](examples/censorship-monitor.mjs) | Real-world: censorship data + encrypted alerts |
 
-- **quickstart.mjs** — Register, send, receive in 15 lines
-- **encrypted-channel.mjs** — Group messaging with client-side encryption
-- **rpc.mjs** — Remote procedure calls between agents
-- **conversation.mjs** — Threaded dialog with waitForReply
-- **censorship-monitor.mjs** — Combine censorship data + agent messaging
+All examples are self-contained and run against the public relay. No API key needed.
 
 ## Protocol
 

package/dist/index.js

@@ -1,4 +1,3 @@
-import { createRequire as __createRequire } from 'module'; const require = __createRequire(import.meta.url);
 "use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;

package/examples/censorship-monitor.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * Censorship Monitor — Real-world use case combining Voidly data + agent messaging.
+ *
+ * Run:  node examples/censorship-monitor.mjs
+ *
+ * Fetches live censorship data from the Voidly API, checks for high block
+ * rates, and sends an encrypted alert to a subscriber agent.
+ */
+import { VoidlyAgent } from '@voidly/agent-sdk';
+
+const ALERT_THRESHOLD = 50; // Alert if censorship score > 50 (out of 100)
+
+// Register a monitor agent and a subscriber agent
+const monitor    = await VoidlyAgent.register({ name: 'censorship-monitor' });
+const subscriber = await VoidlyAgent.register({ name: 'alert-subscriber' });
+
+console.log(`Monitor:    ${monitor.did}`);
+console.log(`Subscriber: ${subscriber.did}\n`);
+
+// Fetch live censorship index from Voidly public API
+console.log('Fetching live censorship data...');
+const res = await fetch('https://api.voidly.ai/data/censorship-index.json');
+const index = await res.json();
+const countries = index.countries;
+console.log(`Loaded data for ${countries.length} countries.\n`);
+
+// Find countries above the alert threshold
+const alerts = countries
+  .filter((c) => c.score > ALERT_THRESHOLD)
+  .sort((a, b) => b.score - a.score)
+  .slice(0, 5);
+
+if (alerts.length === 0) {
+  console.log('No countries above alert threshold.');
+} else {
+  console.log(`${alerts.length} countries with censorship score > ${ALERT_THRESHOLD}:\n`);
+
+  for (const country of alerts) {
+    const alertMsg = JSON.stringify({
+      type: 'censorship_alert',
+      country: country.country,
+      code: country.code,
+      score: country.score,
+      level: country.level,
+      samples: country.samples,
+    });
+
+    // Send encrypted alert
+    await monitor.send(subscriber.did, alertMsg, {
+      contentType: 'application/json',
+      messageType: 'alert',
+    });
+
+    console.log(`  ⚠ ${country.country} (${country.code}): score ${country.score}/100 [${country.level}]`);
+  }
+
+  // Subscriber receives encrypted alerts
+  console.log('\nSubscriber receiving alerts...');
+  const messages = await subscriber.receive({ limit: 10 });
+  console.log(`Received ${messages.length} encrypted alerts.`);
+
+  for (const msg of messages) {
+    const data = JSON.parse(msg.content);
+    console.log(`  ✓ ${data.country}: score ${data.score}/100 — signature valid: ${msg.signatureValid}`);
+  }
+}
+
+console.log('\n✓ Done — censorship monitoring with E2E encrypted alerts.');

package/examples/conversation.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * Conversations — Threaded dialog between agents.
+ *
+ * Run:  node examples/conversation.mjs
+ *
+ * Uses conversation() to auto-thread messages and waitForReply()
+ * for synchronous back-and-forth. Great for LLM agent dialogs.
+ */
+import { VoidlyAgent } from '@voidly/agent-sdk';
+
+const researcher = await VoidlyAgent.register({ name: 'conv-researcher' });
+const analyst    = await VoidlyAgent.register({ name: 'conv-analyst' });
+
+console.log(`Researcher: ${researcher.did}`);
+console.log(`Analyst:    ${analyst.did}\n`);
+
+// Start a threaded conversation
+const conv = researcher.conversation(analyst.did);
+
+// Researcher sends first message
+await conv.say('Is twitter.com currently blocked in Iran?');
+console.log('Researcher: "Is twitter.com currently blocked in Iran?"');
+
+// Simulate the analyst responding (in a real app, the analyst's
+// listener would process the question and reply automatically)
+const analystConv = analyst.conversation(researcher.did, conv.threadId);
+await analystConv.say('Yes — DNS poisoning detected across 3 major ISPs. Block rate: 94%.');
+console.log('Analyst:    "Yes — DNS poisoning detected across 3 major ISPs."');
+
+// Researcher waits for the reply
+const reply = await conv.waitForReply(10000);
+console.log(`\nResearcher received reply: "${reply.content}"`);
+console.log(`  Thread:          ${reply.threadId}`);
+console.log(`  Signature valid: ${reply.signatureValid}`);
+
+// View full conversation history
+const history = await conv.history();
+console.log(`\nConversation history: ${history.length} messages`);
+for (const msg of history) {
+  const who = msg.from === researcher.did ? 'Researcher' : 'Analyst';
+  console.log(`  ${who}: "${msg.content}"`);
+}
+
+console.log('\n✓ Done — threaded conversation with E2E encryption.');

package/examples/encrypted-channel.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+/**
+ * Encrypted Channels — Group messaging with client-side encryption.
+ *
+ * Run:  node examples/encrypted-channel.mjs
+ *
+ * Channel key is generated locally. The relay stores opaque ciphertext
+ * and cannot read channel messages.
+ */
+import { VoidlyAgent } from '@voidly/agent-sdk';
+
+// Register two agents
+const alice = await VoidlyAgent.register({ name: 'chan-alice' });
+const bob   = await VoidlyAgent.register({ name: 'chan-bob' });
+
+// Alice creates an encrypted channel (key generated client-side)
+const { id: channelId, channelKey } = await alice.createEncryptedChannel({
+  name: 'research-team',
+  description: 'Private research coordination',
+});
+console.log(`Channel created: ${channelId}\n`);
+
+// Bob joins
+await bob.joinChannel(channelId);
+console.log('Bob joined the channel.\n');
+
+// Alice posts an encrypted message
+await alice.postEncrypted(channelId, 'New censorship incident detected in IR', channelKey);
+console.log('Alice posted: "New censorship incident detected in IR"\n');
+
+// Bob reads and decrypts with the shared channel key
+const { messages } = await bob.readEncrypted(channelId, channelKey);
+for (const msg of messages) {
+  console.log(`Bob read: "${msg.content}"`);
+  console.log(`  From:            ${msg.from}`);
+  console.log(`  Signature valid: ${msg.signatureValid}`);
+}
+
+console.log('\n✓ Done — group messages encrypted with NaCl secretbox.');

package/examples/quickstart.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * Quickstart — Register two agents, send an encrypted message, receive it.
+ *
+ * Run:  node examples/quickstart.mjs
+ *
+ * All encryption happens client-side. The relay never sees plaintext.
+ */
+import { VoidlyAgent } from '@voidly/agent-sdk';
+
+const alice = await VoidlyAgent.register({ name: 'example-alice' });
+const bob   = await VoidlyAgent.register({ name: 'example-bob' });
+
+console.log(`Alice: ${alice.did}`);
+console.log(`Bob:   ${bob.did}\n`);
+
+// Alice sends an encrypted message to Bob
+await alice.send(bob.did, 'Hello from Alice!');
+console.log('Alice → Bob: "Hello from Alice!" (encrypted + signed)\n');
+
+// Bob receives and decrypts
+const messages = await bob.receive();
+for (const msg of messages) {
+  console.log(`Bob received: "${msg.content}"`);
+  console.log(`  From:            ${msg.from}`);
+  console.log(`  Signature valid: ${msg.signatureValid}`);
+  console.log(`  Encrypted:       client-side (relay never saw plaintext)`);
+}
+
+console.log('\n✓ Done — two agents communicated with E2E encryption.');

package/examples/rpc.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/**
+ * Agent RPC — Call functions on remote agents.
+ *
+ * Run:  node examples/rpc.mjs
+ *
+ * Agent A exposes a "translate" method. Agent B invokes it remotely.
+ * The RPC payload is E2E encrypted — the relay never sees the request or response.
+ */
+import { VoidlyAgent } from '@voidly/agent-sdk';
+
+// Register a "translator" agent and a "client" agent
+const translator = await VoidlyAgent.register({
+  name: 'rpc-translator',
+  capabilities: ['translate'],
+});
+const client = await VoidlyAgent.register({ name: 'rpc-client' });
+
+console.log(`Translator: ${translator.did}`);
+console.log(`Client:     ${client.did}\n`);
+
+// Translator registers an RPC handler
+translator.onInvoke('translate', async (params) => {
+  console.log(`Translator received RPC: translate("${params.text}" → ${params.to})`);
+  // Simulate translation (real agent would call an LLM or translation API)
+  const translations = { es: 'Hola', fr: 'Bonjour', de: 'Hallo', ja: 'こんにちは' };
+  return { translated: translations[params.to] || params.text, lang: params.to };
+});
+
+// Start the translator's listener so it can receive RPC calls
+const stop = translator.listen(() => {});
+
+// Client invokes the translator's "translate" method
+console.log('Client calling translate("Hello" → "es")...');
+const result = await client.invoke(translator.did, 'translate', {
+  text: 'Hello',
+  to: 'es',
+});
+console.log(`Result: ${JSON.stringify(result)}`);
+
+stop(); // Stop listening
+console.log('\n✓ Done — remote procedure call over E2E encrypted channel.');

package/package.json

@@ -1,12 +1,20 @@
 {
   "name": "@voidly/agent-sdk",
-  "version": "3.2.3",
+  "version": "3.2.5",
   "description": "E2E encrypted agent-to-agent communication SDK — Double Ratchet, X3DH, deniable auth, ML-KEM-768 post-quantum, SSE streaming, ratchet persistence, multi-relay federation",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
   "files": [
-    "dist"
+    "dist",
+    "examples"
   ],
   "scripts": {
     "build": "tsup",
@@ -24,13 +32,20 @@
   },
   "keywords": [
     "agent",
+    "ai-agent",
+    "multi-agent",
     "encryption",
     "e2e",
+    "double-ratchet",
+    "post-quantum",
     "nacl",
     "did",
+    "privacy",
     "voidly",
     "mcp",
-    "a2a"
+    "a2a",
+    "langchain",
+    "crewai"
   ],
   "license": "MIT",
   "repository": {