commune-ai 0.2.6 → 0.2.62

package/README.md

@@ -1,22 +1,22 @@
 # @commune/sdk
 
 Commune is the **communication infrastructure for agents**. It gives your agent a **unified inbox**
-for **email + Slack**, so your agent can talk to humans where they already work. Most teams
+for **email**, so your agent can talk to humans where they already work. Most teams
 get a working integration in **~15 minutes**.
 
 ## Why Commune exists (what it enables)
-Agents are powerful, but users already live in **email and Slack**. Commune bridges that gap so:
+Agents are powerful, but users already live in **email**. Commune bridges that gap so:
 - your agent is reachable where humans already work
-- you don’t have to build deliverability, threading, or Slack plumbing
+- you don’t have to build deliverability, threading, or email plumbing
 - you can ship an agent‑first experience in minutes, not weeks
 
 In practice, Commune lets you:
 - give an agent a real inbox on your domain
-- respond in the correct email or Slack thread every time
+- respond in the correct email thread every time
 - use **conversation state** to make smarter, context‑aware replies
 
 ## How it works (mental model)
-1) Commune receives inbound email/Slack events.
+1) Commune receives inbound email events.
 2) Commune normalizes them into a **UnifiedMessage**.
 3) Commune sends the UnifiedMessage to your webhook.
 4) Your agent replies using one API call.
@@ -48,7 +48,7 @@ const handler = createWebhookHandler({
     });
   },
   onEvent: async (message, context) => {
-    // Example inbound payload (unified across email + Slack):
+    // Example inbound payload:
     // message = {
     //   channel: "email",
     //   conversation_id: "thread_id",
@@ -61,32 +61,17 @@ const handler = createWebhookHandler({
     const agentReply = await llm.complete(prompt); // replace with your LLM client
 
     // Email reply (same thread)
-    if (message.channel === "email") {
-      const sender = message.participants.find(p => p.role === "sender")?.identity;
-      if (!sender) return;
-
-      await client.messages.send({
-        channel: "email",
-        to: sender,
-        text: agentReply,
-        conversation_id: message.conversation_id,
-        domainId: context.payload.domainId,
-        inboxId: context.payload.inboxId,
-      });
-    }
-
-    // Slack reply (same thread)
-    if (message.channel === "slack") {
-      const channelId = message.metadata.slack_channel_id;
-      if (!channelId) return;
-
-      await client.messages.send({
-        channel: "slack",
-        to: channelId,
-        text: agentReply,
-        conversation_id: message.conversation_id, // thread_ts
-      });
-    }
+    const sender = message.participants.find(p => p.role === "sender")?.identity;
+    if (!sender) return;
+
+    await client.messages.send({
+      channel: "email",
+      to: sender,
+      text: agentReply,
+      conversation_id: message.conversation_id,
+      domainId: context.payload.domainId,
+      inboxId: context.payload.inboxId,
+    });
   },
 });
 
@@ -103,16 +88,16 @@ npm install @commune/sdk
 ---
 
 ## Unified inbox (what your webhook receives)
-Every inbound email or Slack message arrives in this shape:
+Every inbound email arrives in this shape:
 
 ```ts
 export interface UnifiedMessage {
-  channel: "email" | "slack";
+  channel: "email";
   message_id: string;
-  conversation_id: string; // email thread or Slack thread_ts
+  conversation_id: string; // email thread
   participants: { role: string; identity: string }[];
   content: string;
-  metadata: { slack_channel_id?: string; ... };
+  metadata: { ... };
 }
 ```
 
@@ -132,6 +117,81 @@ const client = new CommuneClient({ apiKey: process.env.COMMUNE_API_KEY! });
 
 ---
 
+<!--  -->
+## Attachments
+Send and receive email attachments with secure storage and temporary download URLs.
+
+### Sending attachments
+Upload attachments first, then use the attachment ID when sending emails.
+
+```ts
+import fs from 'fs';
+
+// 1. Upload attachment (base64 encoded)
+const fileBuffer = fs.readFileSync('invoice.pdf');
+const base64Content = fileBuffer.toString('base64');
+
+const { attachment_id } = await client.attachments.upload(
+  base64Content,
+  'invoice.pdf',
+  'application/pdf'
+);
+
+// 2. Send email with attachment
+await client.messages.send({
+  to: 'customer@example.com',
+  subject: 'Your invoice',
+  text: 'Please find your invoice attached.',
+  attachments: [attachment_id],
+  domainId: 'your-domain-id',
+});
+```
+
+### Receiving attachments
+Attachments are available through:
+- Email events in the incoming webhook
+- Metadata of semantic search results
+
+Use the `attachment_id` to access the attachment.
+
+```ts
+// Get attachment metadata
+const attachment = await client.attachments.get("att_123");
+console.log(attachment.filename, attachment.size);
+
+// Get download URL (expires in 1 hour)
+const { url } = await client.attachments.get("att_123", { url: true });
+// Use the URL to download or display the file
+
+// Custom expiration (2 hours)
+const { url } = await client.attachments.get("att_123", { url: true, expiresIn: 7200 });
+```
+
+### Handling attachments in webhook
+```ts
+const handler = createWebhookHandler({
+  onEvent: async (message, context) => {
+    const { attachments } = context.payload;
+    
+    if (attachments && attachments.length > 0) {
+      for (const att of attachments) {
+        console.log(`Attachment: ${att.filename} (${att.size} bytes)`);
+        
+        // Get download URL
+        const { url } = await client.attachments.get(att.attachment_id, { url: true });
+        
+        // Download the file
+        const response = await fetch(url);
+        const buffer = await response.arrayBuffer();
+        // Process the file...
+      }
+    }
+  },
+});
+```
+
+---
+
 ## Semantic Search
 Commune provides powerful semantic search capabilities to help your agent find relevant conversations and context. The search is powered by embeddings and vector similarity, allowing natural language queries.
 
@@ -230,10 +290,33 @@ interface SearchResult {
     participants: string[];
     threadId: string;
     timestamp: Date;
+    attachmentIds?: string[];      // Attachment IDs in this conversation
+    hasAttachments?: boolean;      // Whether conversation has attachments
+    attachmentCount?: number;      // Number of attachments
   };
 }
 ```
 
+### Search with attachments
+```ts
+// Search for conversations with attachments
+const results = await client.searchConversations(
+  "invoice with receipt",
+  { organizationId: "org_123" }
+);
+
+// Filter results that have attachments
+const withAttachments = results.filter(r => r.metadata.hasAttachments);
+
+// Access attachments from search results
+for (const result of withAttachments) {
+  for (const attachmentId of result.metadata.attachmentIds || []) {
+    const { url, filename } = await client.attachments.get(attachmentId, { url: true });
+    console.log(`Download: ${filename} - ${url}`);
+  }
+}
+```
+
 ## Spam Protection
 Commune includes built-in spam detection and protection to keep your agent safe from malicious emails and prevent abuse.
 
@@ -283,7 +366,7 @@ Commune stores conversation state so your agent can respond with context.
 import { CommuneClient } from "@commune/sdk";
 const client = new CommuneClient({ apiKey: process.env.COMMUNE_API_KEY! });
 
-// Thread history (email thread or Slack thread)
+// Thread history (email thread)
 const thread = await client.messages.listByConversation(message.conversation_id, {
   order: "asc",
   limit: 50,
@@ -305,8 +388,8 @@ const inboxMessages = await client.messages.list({
 
 ---
 
-## Cross‑channel behavior (email + Slack in one handler)
-The same `UnifiedMessage` shape works for both channels. You only branch on `channel`.
+## Email handling
+The `UnifiedMessage` shape works for email messages.
 
 ```ts
 import express from "express";
@@ -317,31 +400,17 @@ const client = new CommuneClient({ apiKey: process.env.COMMUNE_API_KEY! });
 
 const handler = createWebhookHandler({
   onEvent: async (message, context) => {
-    if (message.channel === "email") {
-      const sender = message.participants.find(p => p.role === "sender")?.identity;
-      if (!sender) return;
-
-      await client.messages.send({
-        channel: "email",
-        to: sender,
-        text: "Got it — thanks for the message.",
-        conversation_id: message.conversation_id,
-        domainId: context.payload.domainId,
-        inboxId: context.payload.inboxId,
-      });
-    }
-
-    if (message.channel === "slack") {
-      const channelId = message.metadata.slack_channel_id;
-      if (!channelId) return;
-
-      await client.messages.send({
-        channel: "slack",
-        to: channelId,
-        text: "Replying in thread ✅",
-        conversation_id: message.conversation_id,
-      });
-    }
+    const sender = message.participants.find(p => p.role === "sender")?.identity;
+    if (!sender) return;
+
+    await client.messages.send({
+      channel: "email",
+      to: sender,
+      text: "Got it — thanks for the message.",
+      conversation_id: message.conversation_id,
+      domainId: context.payload.domainId,
+      inboxId: context.payload.inboxId,
+    });
   },
 });
 
@@ -527,47 +596,58 @@ const handler = createWebhookHandler({
 ## Full example (single file)
 A complete copy‑paste example that:
 - receives webhook
+- handles incoming attachments
+- sends email with attachments
 - replies by email
-- replies in Slack thread
-- fetches conversation history
 
 ```ts
 import express from "express";
 import { CommuneClient, createWebhookHandler } from "@commune/sdk";
+import fs from "fs";
 
 const client = new CommuneClient({ apiKey: process.env.COMMUNE_API_KEY! });
 
 const handler = createWebhookHandler({
   onEvent: async (message, context) => {
-    // 1) Email reply (same thread)
-    if (message.channel === "email") {
-      const sender = message.participants.find(p => p.role === "sender")?.identity;
-      if (!sender) return;
-
-      await client.messages.send({
-        channel: "email",
-        to: sender,
-        text: "Thanks! We received your email.",
-        conversation_id: message.conversation_id,
-        domainId: context.payload.domainId,
-        inboxId: context.payload.inboxId,
-      });
-
-      return;
+    // 1) Handle incoming attachments
+    const { attachments } = context.payload;
+    if (attachments && attachments.length > 0) {
+      console.log(`Received ${attachments.length} attachments`);
+      
+      for (const att of attachments) {
+        // Get download URL
+        const { url, filename } = await client.attachments.get(att.attachment_id, { url: true });
+        console.log(`Attachment: ${filename} - ${url}`);
+        
+        // Download if needed
+        // const response = await fetch(url);
+        // const buffer = await response.arrayBuffer();
+      }
     }
 
-    // 2) Slack reply (same thread)
-    if (message.channel === "slack") {
-      const channelId = message.metadata.slack_channel_id;
-      if (!channelId) return;
-
-      await client.messages.send({
-        channel: "slack",
-        to: channelId,
-        text: "Thanks! Replying in thread.",
-        conversation_id: message.conversation_id,
-      });
-    }
+    // 2) Email reply with attachment (same thread)
+    const sender = message.participants.find(p => p.role === "sender")?.identity;
+    if (!sender) return;
+
+    // Upload attachment for sending
+    const fileBuffer = fs.readFileSync('receipt.pdf');
+    const base64Content = fileBuffer.toString('base64');
+    const { attachment_id } = await client.attachments.upload(
+      base64Content,
+      'receipt.pdf',
+      'application/pdf'
+    );
+
+    await client.messages.send({
+      channel: "email",
+      to: sender,
+      subject: "Your receipt",
+      text: "Thanks! Here's your receipt.",
+      attachments: [attachment_id],
+      conversation_id: message.conversation_id,
+      domainId: context.payload.domainId,
+      inboxId: context.payload.inboxId,
+    });
   },
 });
 

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { AttachmentRecord, AttachmentUrl, CreateDomainPayload, DomainEntry, InboxEntry, MessageListParams, SendMessagePayload, UnifiedMessage, SearchFilter, SearchOptions, SearchResult, IndexConversationPayload } from './types.js';
+import type { AttachmentRecord, AttachmentUrl, AttachmentUploadResponse, CreateDomainPayload, DomainEntry, InboxEntry, MessageListParams, SendMessagePayload, UnifiedMessage, SearchFilter, SearchOptions, SearchResult, IndexConversationPayload } from './types.js';
 export type ClientOptions = {
     baseUrl?: string;
     apiKey: string;
@@ -72,6 +72,7 @@ export declare class CommuneClient {
         }>;
     };
     attachments: {
+        upload: (content: string, filename: string, mimeType: string) => Promise<AttachmentUploadResponse>;
         get: (attachmentId: string, options?: {
             url?: boolean;
             expiresIn?: number;

package/dist/client.js

@@ -128,6 +128,12 @@ export class CommuneClient {
             },
         };
         this.attachments = {
+            upload: async (content, filename, mimeType) => {
+                return this.request('/api/attachments/upload', {
+                    method: 'POST',
+                    body: JSON.stringify({ content, filename, mimeType }),
+                });
+            },
             get: async (attachmentId, options) => {
                 if (options?.url) {
                     const expiresIn = options.expiresIn || 3600;

package/dist/types.d.ts

@@ -59,6 +59,13 @@ export interface AttachmentUrl {
     mimeType: string;
     size: number;
 }
+export interface AttachmentUploadResponse {
+    attachment_id: string;
+    filename: string;
+    mime_type: string;
+    size: number;
+    storage_type: 'cloudinary' | 'database';
+}
 export interface DomainWebhook {
     id?: string;
     endpoint?: string;
@@ -104,10 +111,7 @@ export interface SendMessagePayload {
     to: string | string[];
     text?: string;
     html?: string;
-    attachments?: {
-        id?: string;
-        attachment_id?: string;
-    }[];
+    attachments?: string[];
     subject?: string;
     cc?: string[];
     bcc?: string[];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "commune-ai",
-  "version": "0.2.6",
-  "description": "Our email infrastructure - webhooks, threads, history, and semantic search",
+  "version": "0.2.62",
+  "description": "SDK-first email infrastructure for agents - threads, history, semantic search, structured data output and attachments.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",