commune-ai 0.2.5 → 0.2.61

package/README.md

@@ -132,6 +132,53 @@ const client = new CommuneClient({ apiKey: process.env.COMMUNE_API_KEY! });
 
 ---
 
+## Attachments
+Access email attachments with secure, temporary download URLs.
+
+Attachments are stored and available as `attachment_id`. These IDs are:
+- Available through email events in the incoming webhook
+- Available in metadata of semantic search results
+
+Use the `attachment_id` to directly access the attachment, download it or read it.
+
+```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 +277,75 @@ 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.
+
+### Automatic Spam Detection
+All incoming emails are automatically analyzed for spam patterns:
+- Content analysis (spam keywords, suspicious patterns)
+- URL validation (broken links, phishing detection)
+- Sender reputation tracking
+- Domain blacklist checking
+
+Spam emails are automatically rejected before reaching your webhook, protecting your agent from:
+- Phishing attempts
+- Malicious links
+- Mass spam campaigns
+- Fraudulent content
+
+### Outbound Protection
+Commune also protects your sending reputation:
+- Rate limiting per organization tier
+- Content validation for outbound emails
+- Burst detection for mass mailing
+- Automatic blocking of spam-like content
+
+This ensures your domain maintains high deliverability and isn't flagged by email providers.
+
+### Spam Reporting
+If a spam email gets through, you can report it:
+
+```ts
+import { CommuneClient } from "@commune/sdk";
+const client = new CommuneClient({ apiKey: process.env.COMMUNE_API_KEY! });
+
+// Report a message as spam
+await client.reportSpam({
+  message_id: "msg_123",
+  reason: "Unsolicited marketing email",
+  classification: "spam" // or "phishing", "malware", "other"
+});
+```
+
+The system learns from reports and automatically blocks repeat offenders.
+
 ## Context (conversation state)
 Commune stores conversation state so your agent can respond with context.
 
@@ -485,6 +597,7 @@ const handler = createWebhookHandler({
 ## Full example (single file)
 A complete copy‑paste example that:
 - receives webhook
+- handles attachments
 - replies by email
 - replies in Slack thread
 - fetches conversation history
@@ -497,7 +610,23 @@ const client = new CommuneClient({ apiKey: process.env.COMMUNE_API_KEY! });
 
 const handler = createWebhookHandler({
   onEvent: async (message, context) => {
-    // 1) Email reply (same thread)
+    // 1) Handle 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) Email reply (same thread)
     if (message.channel === "email") {
       const sender = message.participants.find(p => p.role === "sender")?.identity;
       if (!sender) return;
@@ -514,7 +643,7 @@ const handler = createWebhookHandler({
       return;
     }
 
-    // 2) Slack reply (same thread)
+    // 3) Slack reply (same thread)
     if (message.channel === "slack") {
       const channelId = message.metadata.slack_channel_id;
       if (!channelId) return;

package/dist/client.d.ts

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

package/dist/client.js

@@ -128,7 +128,11 @@ export class CommuneClient {
             },
         };
         this.attachments = {
-            get: async (attachmentId) => {
+            get: async (attachmentId, options) => {
+                if (options?.url) {
+                    const expiresIn = options.expiresIn || 3600;
+                    return this.request(`/api/attachments/${encodeURIComponent(attachmentId)}/url?expiresIn=${expiresIn}`);
+                }
                 return this.request(`/api/attachments/${encodeURIComponent(attachmentId)}`);
             },
         };

package/dist/types.d.ts

@@ -42,6 +42,22 @@ export interface AttachmentRecord {
     source: Channel;
     source_url?: string | null;
     download_error?: boolean;
+    storage_type?: 'cloudinary' | 'database';
+    cloudinary_url?: string | null;
+    cloudinary_public_id?: string | null;
+}
+export interface AttachmentMetadata {
+    attachment_id: string;
+    filename: string;
+    mime_type: string;
+    size: number;
+}
+export interface AttachmentUrl {
+    url: string;
+    expiresIn: number;
+    filename: string;
+    mimeType: string;
+    size: number;
 }
 export interface DomainWebhook {
     id?: string;
@@ -142,6 +158,7 @@ export interface InboundEmailWebhookPayload {
     email: unknown;
     message: UnifiedMessage;
     extractedData?: Record<string, any>;
+    attachments?: AttachmentMetadata[];
 }
 export interface ApiError {
     message?: string;
@@ -175,6 +192,9 @@ export interface SearchResult {
         participants: string[];
         threadId: string;
         timestamp: Date;
+        attachmentIds?: string[];
+        hasAttachments?: boolean;
+        attachmentCount?: number;
     };
 }
 export interface ConversationMetadata {
@@ -185,6 +205,9 @@ export interface ConversationMetadata {
     participants: string[];
     threadId: string;
     timestamp: Date;
+    attachmentIds?: string[];
+    hasAttachments?: boolean;
+    attachmentCount?: number;
 }
 export interface IndexConversationPayload {
     id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commune-ai",
-  "version": "0.2.5",
+  "version": "0.2.61",
   "description": "Our email infrastructure - webhooks, threads, history, and semantic search",
   "type": "module",
   "main": "dist/index.js",