commune-ai 0.1.6 → 0.1.8

package/README.md

@@ -29,6 +29,7 @@ Build agents that receive emails, reply in threads, access conversation history,
 - [Reply in email threads](#reply-in-email-threads)
 - [Access conversation history](#access-conversation-history)
 - [Manage Inboxes Programmatically](#manage-inboxes-programmatically)
+- [How Webhooks Work](#how-webhooks-work)
 - [Listen for Specific Inbox Events](#listen-for-specific-inbox-events)
 - [Semantic Search (Coming Soon)](#semantic-search-coming-soon)
 - [Complete agent example](#complete-agent-example)
@@ -90,9 +91,24 @@ COMMUNE_BASE_URL=https://your-self-hosted-api.com
 
 ---
 
-## Receive emails instantly
+## Receive emails at your webhook endpoint
 
-Get emails delivered to your agent as structured webhook data.
+Configure your inbox to send emails to your server, then mount the webhook handler at that endpoint.
+
+### Step 1: Configure webhook URL for your inbox
+
+First, set the webhook URL in your inbox settings (via dashboard or SDK):
+
+```ts
+await client.inboxes.setWebhook(domainId, inboxId, {
+  endpoint: "https://your-server.com/api/emails",  // Your endpoint URL
+  events: ["email.received"],
+});
+```
+
+### Step 2: Mount webhook handler at that URL
+
+Your server must listen at the **exact same URL** you configured:
 
 ```ts
 import "dotenv/config";
@@ -104,8 +120,8 @@ const client = new CommuneClient({
   apiKey: process.env.COMMUNE_API_KEY, // ← From Step 3 above
 });
 
-// Handle incoming emails
-const handler = createWebhookHandler({
+// Create webhook handler to process incoming emails
+const emailHandler = createWebhookHandler({
   onEvent: async (message, context) => {
     console.log(`📧 New email: ${message.content}`);
 
@@ -129,9 +145,11 @@ const handler = createWebhookHandler({
   },
 });
 
-// Set up webhook endpoint
+// Set up your server
 const app = express();
-app.post("/webhook", express.raw({ type: "*/*" }), handler);
+
+// This URL must match what you configured in Step 1
+app.post("/api/emails", express.raw({ type: "*/*" }), emailHandler);
 
 // Health check
 app.get("/health", (req, res) => res.json({ status: "ok" }));
@@ -142,6 +160,12 @@ app.listen(3000, () => {
 });
 ```
 
+**Complete flow:**
+1. Email arrives at your inbox
+2. Resend sends webhook to Commune backend
+3. Commune backend sends email to your configured endpoint (`/api/emails`)
+4. Your `emailHandler` processes the email and replies
+
 **Email structure:**
 ```ts
 interface UnifiedMessage {
@@ -176,7 +200,8 @@ const client = new CommuneClient({
   apiKey: process.env.COMMUNE_API_KEY,
 });
 
-const handler = createWebhookHandler({
+// Create webhook handler
+const emailHandler = createWebhookHandler({
   onEvent: async (message, context) => {
     const sender = message.participants.find(p => p.role === "sender")?.identity;
     if (!sender) return;
@@ -193,9 +218,15 @@ const handler = createWebhookHandler({
   },
 });
 
+// Set up your server
 const app = express();
-app.post("/webhook", express.raw({ type: "*/*" }), handler);
-app.listen(3000);
+
+// Mount handler at your webhook endpoint
+app.post("/api/emails", express.raw({ type: "*/*" }), emailHandler);
+
+app.listen(3000, () => {
+  console.log("Agent running on port 3000");
+});
 ```
 
 ---
@@ -323,14 +354,33 @@ await client.inboxes.remove(domainId, inboxId);
 
 ---
 
-## Listen for Specific Inbox Events
+## How Webhooks Work
+
+**Understanding the webhook flow:**
+
+1. **Resend Webhooks** → When you verify a domain, the backend creates a webhook at Resend (email service) that points to the Commune backend
+2. **Commune Backend** → Processes the webhook from Resend and looks up inbox configurations
+3. **Your Webhook Endpoint** → If an inbox has a webhook URL set, Commune sends an HTTP POST to your endpoint
 
-Route incoming emails based on which inbox received them:
+```typescript
+// Webhook flow: Resend → Commune Backend → Your Server
+// Your server uses createWebhookHandler to process webhooks from Commune
+```
+
+## Listen for specific inbox events
+
+Route incoming emails based on which inbox received them. Set up different webhook endpoints for different inboxes.
 
 ```ts
-import { createWebhookHandler } from "commune-ai";
+import express from "express";
+import { CommuneClient, createWebhookHandler } from "commune-ai";
+
+const client = new CommuneClient({
+  apiKey: process.env.COMMUNE_API_KEY,
+});
 
-const handler = createWebhookHandler({
+// Create webhook handler for routing
+const emailRouter = createWebhookHandler({
   onEvent: async (message, context) => {
     const { inboxId, inboxAddress } = context.payload;
 
@@ -348,6 +398,18 @@ const handler = createWebhookHandler({
   },
 });
 
+// Set up your server
+const app = express();
+
+// Mount the same handler at different endpoints for different inboxes
+app.post("/api/support", express.raw({ type: "*/*" }), emailRouter);    // For support inbox
+app.post("/api/sales", express.raw({ type: "*/*" }), emailRouter);      // For sales inbox
+app.post("/api/general", express.raw({ type: "*/*" }), emailRouter);    // For general inbox
+
+app.listen(3000, () => {
+  console.log("Agent running with multiple inbox endpoints");
+});
+
 // Example handlers
 async function handleSupportEmail(message: any, context: any) {
   const sender = message.participants.find(p => p.role === "sender")?.identity;
@@ -427,7 +489,7 @@ const client = new CommuneClient({
   apiKey: process.env.COMMUNE_API_KEY,
 });
 
-const handler = createWebhookHandler({
+const emailProcessor = createWebhookHandler({
   onEvent: async (message, context) => {
     const sender = message.participants.find(p => p.role === "sender")?.identity;
     if (!sender) return;
@@ -471,8 +533,11 @@ const handler = createWebhookHandler({
   },
 });
 
+// Set up your server
 const app = express();
-app.post("/webhook", express.raw({ type: "*/*" }), handler);
+
+// Mount webhook handler at your endpoint
+app.post("/api/emails", express.raw({ type: "*/*" }), emailProcessor);
 
 // Health check endpoint
 app.get("/health", (req, res) => res.json({ status: "ok" }));

package/package.json

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