commune-ai 0.1.2 → 0.1.4

package/README.md

@@ -27,51 +27,100 @@ pnpm add commune-ai
 
 ---
 
+## How to Setup (Dashboard Steps)
+
+**Before you can receive emails, you need to set up your domain, inbox, and API key in the Commune dashboard.**
+
+### 1. Create and Verify Domain
+1. Go to your [Commune dashboard](https://your-dashboard.com)
+2. Sign up and create an organization
+3. Go to **Domains** → Click **"Add Domain"**
+4. Enter a subdomain (e.g., `agent.yourcompany.com`)
+5. Click **"Create"** - The dashboard will show DNS records to add
+6. Add the DNS records shown in the dashboard to your DNS provider
+7. Click **"Verify"** in the dashboard (wait 5-10 minutes for DNS propagation)
+
+### 2. Create Inbox
+1. In the dashboard, go to **Inboxes**
+2. Click **"Create Inbox"**
+3. Enter a local part (e.g., `support`, `help`, `agent`)
+4. This creates an email address like `support@agent.yourcompany.com`
+5. **Copy the Domain ID and Inbox ID** - you'll need these for your webhook
+
+### 3. Create API Key
+1. Go to **API Keys** in the dashboard
+2. Click **"Create Key"**
+3. Enter a name (e.g., "production-agent")
+4. **Copy the API key immediately** (it only shows once!)
+5. Store it securely as an environment variable
+
+### 4. Configure Webhook
+1. In your domain settings, go to **Webhooks**
+2. Set the webhook endpoint URL to your server's webhook handler
+3. Configure webhook events (usually "email.received")
+4. **Optional:** Set a webhook secret for verification
+
+### 5. Environment Variables
+```bash
+# Required
+COMMUNE_API_KEY=cmk_your_api_key_from_dashboard
+
+# Optional (for self-hosting)
+COMMUNE_BASE_URL=https://your-self-hosted-api.com
+```
+
+---
+
 ## Receive emails instantly
 
 Get emails delivered to your agent as structured webhook data.
 
 ```ts
+import "dotenv/config";
 import express from "express";
 import { CommuneClient, createWebhookHandler } from "commune-ai";
 
+// Initialize with your API key from dashboard
 const client = new CommuneClient({
-  apiKey: process.env.COMMUNE_API_KEY,
+  apiKey: process.env.COMMUNE_API_KEY, // ← From Step 3 above
 });
 
+// Handle incoming emails
 const handler = createWebhookHandler({
   onEvent: async (message, context) => {
-    // Every email arrives as structured data:
-    // message = {
-    //   channel: "email",
-    //   conversation_id: "thread_id",
-    //   participants: [{ role: "sender", identity: "user@example.com" }],
-    //   content: "Can you help with pricing?",
-    //   metadata: { subject: "Pricing Question", ... }
-    // }
+    console.log(`📧 New email: ${message.content}`);
 
-    console.log(`New email: ${message.content}`);
+    // Find sender's email address
+    const sender = message.participants.find(p => p.role === "sender")?.identity;
+    if (!sender) return;
 
     // Your agent logic here
     const reply = `Thanks for your email! I'll help with that.`;
 
     // Reply in the same email thread
-    const sender = message.participants.find(p => p.role === "sender")?.identity;
-    if (sender) {
-      await client.messages.send({
-        to: sender,
-        text: reply,
-        conversation_id: message.conversation_id,
-        domainId: context.payload.domainId,
-        inboxId: context.payload.inboxId,
-      });
-    }
+    await client.messages.send({
+      to: sender,
+      text: reply,
+      conversation_id: message.conversation_id,
+      domainId: context.payload.domainId,  // ← From Step 2 above
+      inboxId: context.payload.inboxId,    // ← From Step 2 above
+    });
+
+    console.log(`✅ Replied to: ${sender}`);
   },
 });
 
+// Set up webhook endpoint
 const app = express();
 app.post("/webhook", express.raw({ type: "*/*" }), handler);
-app.listen(3000, () => console.log("Agent listening on :3000"));
+
+// Health check
+app.get("/health", (req, res) => res.json({ status: "ok" }));
+
+app.listen(3000, () => {
+  console.log("🤖 Agent listening on port 3000");
+  console.log("📧 Send emails to your inbox address to test!");
+});
 ```
 
 **Email structure:**
@@ -171,11 +220,44 @@ const searchResults = await client.search({
 });
 
 console.log(`Found ${searchResults.length} relevant emails`);
-for (const result of searchResults) {
+```
+
+---
+
+## Semantic Search (Coming Soon)
+
+Search across all emails in your organization using natural language queries.
+
+```ts
+import { CommuneClient } from "commune-ai";
+
+const client = new CommuneClient({
+  apiKey: process.env.COMMUNE_API_KEY,
+});
+
+// Find emails similar to a query
+const results = await client.search({
+  query: "What were the pricing questions from last week?",
+  limit: 10,
+  threshold: 0.7, // Similarity threshold 0-1
+  before: "2024-12-31", // Only search recent emails
+  sender: "customer@example.com", // Filter by sender (optional)
+});
+
+console.log(`Found ${results.length} relevant emails:`);
+for (const result of results) {
   console.log(`Match (${result.similarity.toFixed(2)}): ${result.message.content}`);
+  console.log(`Highlights: ${result.highlights.join(", ")}`);
 }
 ```
 
+**What you get:**
+- **Natural language queries** - Search like "pricing issues from enterprise customers"
+- **Similarity scores** - Ranked results by relevance (0-1)
+- **Highlighted matches** - Text snippets showing why the email matched
+- **Filtering options** - By date range, sender, or other criteria
+- **Fast results** - AI-powered semantic matching
+
 ---
 
 ## Complete agent example

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commune-ai",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Email infrastructure for AI agents - webhooks, threads, history, and semantic search",
   "type": "module",
   "main": "dist/index.js",