commune-ai 0.2.4 → 0.2.6

package/README.md

@@ -132,6 +132,150 @@ const client = new CommuneClient({ apiKey: process.env.COMMUNE_API_KEY! });
 
 ---
 
+## 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.
+
+### Basic Search
+```ts
+import { CommuneClient } from "@commune/sdk";
+const client = new CommuneClient({ apiKey: process.env.COMMUNE_API_KEY! });
+
+// Search across all conversations in an organization
+const results = await client.searchConversations(
+  "customer asking about refund policy",
+  { organizationId: "org_123" }
+);
+
+// Search with inbox filter
+const inboxResults = await client.searchConversations(
+  "shipping delays",
+  { 
+    organizationId: "org_123",
+    inboxIds: ["inbox_1", "inbox_2"]
+  }
+);
+
+// Search by participant
+const userResults = await client.searchConversations(
+  "account upgrade request",
+  {
+    organizationId: "org_123",
+    participants: ["user@example.com"]
+  }
+);
+
+// Search with date range
+const dateResults = await client.searchConversations(
+  "feature request",
+  {
+    organizationId: "org_123",
+    startDate: "2026-01-01",
+    endDate: "2026-02-01"
+  }
+);
+```
+
+### Manual Indexing
+By default, all conversations are automatically indexed. You can also manually index conversations:
+
+```ts
+// Index a single conversation
+await client.indexConversation("org_123", {
+  id: "conv_123",
+  subject: "Product Inquiry",
+  content: "Customer asking about product features",
+  metadata: {
+    subject: "Product Inquiry",
+    organizationId: "org_123",
+    inboxId: "inbox_1",
+    domainId: "domain_1",
+    participants: ["customer@example.com"],
+    threadId: "thread_1",
+    timestamp: new Date()
+  }
+});
+
+// Batch index multiple conversations
+await client.indexConversationBatch("org_123", [
+  {
+    id: "conv_1",
+    subject: "Support Request",
+    content: "Customer needs help with login",
+    metadata: {
+      subject: "Support Request",
+      organizationId: "org_123",
+      inboxId: "support_inbox",
+      domainId: "domain_1",
+      participants: ["customer@example.com"],
+      threadId: "thread_1",
+      timestamp: new Date()
+    }
+  },
+  // ... more conversations
+]);
+```
+
+### Search Results
+Search results include relevance scores and metadata:
+
+```ts
+interface SearchResult {
+  id: string;          // Conversation ID
+  score: number;       // Similarity score (0-1)
+  metadata: {
+    subject: string;       // Email subject
+    organizationId: string;
+    inboxId: string;
+    domainId: string;
+    participants: string[];
+    threadId: string;
+    timestamp: Date;
+  };
+}
+```
+
+## 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.
 

package/dist/client/search.d.ts

@@ -0,0 +1,91 @@
+import { SearchFilter, SearchOptions, SearchResult, IndexConversationPayload } from '../types.js';
+export declare class SearchClient {
+    private baseUrl;
+    private headers;
+    constructor(baseUrl: string, headers: Record<string, string>);
+    /**
+     * Search conversations using semantic search
+     * @param query - The search query in natural language
+     * @param filter - Filter criteria for the search
+     * @param options - Additional search options
+     * @returns Promise<SearchResult[]>
+     * @example
+     * ```typescript
+     * // Search across organization
+     * const results = await client.conversations.search(
+     *   "customer asking about refund policy",
+     *   { organizationId: "org_123" }
+     * );
+     *
+     * // Search in specific inboxes
+     * const results = await client.conversations.search(
+     *   "shipping delays",
+     *   {
+     *     organizationId: "org_123",
+     *     inboxIds: ["inbox_1", "inbox_2"]
+     *   }
+     * );
+     *
+     * // Search with participant filter
+     * const results = await client.conversations.search(
+     *   "account upgrade request",
+     *   {
+     *     organizationId: "org_123",
+     *     participants: ["user@example.com"]
+     *   }
+     * );
+     * ```
+     */
+    search(query: string, filter: SearchFilter, options?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * Index a conversation for semantic search
+     * @param organizationId - The organization ID
+     * @param conversation - The conversation to index
+     * @returns Promise<void>
+     * @example
+     * ```typescript
+     * await client.conversations.index("org_123", {
+     *   id: "conv_123",
+     *   subject: "Product Inquiry",
+     *   content: "Customer asking about product features",
+     *   metadata: {
+     *     subject: "Product Inquiry",
+     *     organizationId: "org_123",
+     *     inboxId: "inbox_1",
+     *     domainId: "domain_1",
+     *     participants: ["customer@example.com"],
+     *     threadId: "thread_1",
+     *     timestamp: new Date()
+     *   }
+     * });
+     * ```
+     */
+    index(organizationId: string, conversation: IndexConversationPayload): Promise<void>;
+    /**
+     * Index multiple conversations in batch
+     * @param organizationId - The organization ID
+     * @param conversations - Array of conversations to index
+     * @returns Promise<void>
+     * @example
+     * ```typescript
+     * await client.conversations.indexBatch("org_123", [
+     *   {
+     *     id: "conv_1",
+     *     subject: "Support Request",
+     *     content: "Customer needs help with login",
+     *     metadata: {
+     *       subject: "Support Request",
+     *       organizationId: "org_123",
+     *       inboxId: "support_inbox",
+     *       domainId: "domain_1",
+     *       participants: ["customer@example.com"],
+     *       threadId: "thread_1",
+     *       timestamp: new Date()
+     *     }
+     *   },
+     *   // ... more conversations
+     * ]);
+     * ```
+     */
+    indexBatch(organizationId: string, conversations: IndexConversationPayload[]): Promise<void>;
+}

package/dist/client/search.js

@@ -0,0 +1,131 @@
+export class SearchClient {
+    constructor(baseUrl, headers) {
+        this.baseUrl = baseUrl;
+        this.headers = headers;
+    }
+    /**
+     * Search conversations using semantic search
+     * @param query - The search query in natural language
+     * @param filter - Filter criteria for the search
+     * @param options - Additional search options
+     * @returns Promise<SearchResult[]>
+     * @example
+     * ```typescript
+     * // Search across organization
+     * const results = await client.conversations.search(
+     *   "customer asking about refund policy",
+     *   { organizationId: "org_123" }
+     * );
+     *
+     * // Search in specific inboxes
+     * const results = await client.conversations.search(
+     *   "shipping delays",
+     *   {
+     *     organizationId: "org_123",
+     *     inboxIds: ["inbox_1", "inbox_2"]
+     *   }
+     * );
+     *
+     * // Search with participant filter
+     * const results = await client.conversations.search(
+     *   "account upgrade request",
+     *   {
+     *     organizationId: "org_123",
+     *     participants: ["user@example.com"]
+     *   }
+     * );
+     * ```
+     */
+    async search(query, filter, options) {
+        const response = await fetch(`${this.baseUrl}/search`, {
+            method: 'POST',
+            headers: {
+                ...this.headers,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ query, filter, options }),
+        });
+        const data = await response.json();
+        if (data.error) {
+            throw new Error(data.error.message || 'Search failed');
+        }
+        return data.data.results;
+    }
+    /**
+     * Index a conversation for semantic search
+     * @param organizationId - The organization ID
+     * @param conversation - The conversation to index
+     * @returns Promise<void>
+     * @example
+     * ```typescript
+     * await client.conversations.index("org_123", {
+     *   id: "conv_123",
+     *   subject: "Product Inquiry",
+     *   content: "Customer asking about product features",
+     *   metadata: {
+     *     subject: "Product Inquiry",
+     *     organizationId: "org_123",
+     *     inboxId: "inbox_1",
+     *     domainId: "domain_1",
+     *     participants: ["customer@example.com"],
+     *     threadId: "thread_1",
+     *     timestamp: new Date()
+     *   }
+     * });
+     * ```
+     */
+    async index(organizationId, conversation) {
+        const response = await fetch(`${this.baseUrl}/search/index`, {
+            method: 'POST',
+            headers: {
+                ...this.headers,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ organizationId, conversation }),
+        });
+        const data = await response.json();
+        if (data.error || !data.data.success) {
+            throw new Error(data.error?.message || 'Failed to index conversation');
+        }
+    }
+    /**
+     * Index multiple conversations in batch
+     * @param organizationId - The organization ID
+     * @param conversations - Array of conversations to index
+     * @returns Promise<void>
+     * @example
+     * ```typescript
+     * await client.conversations.indexBatch("org_123", [
+     *   {
+     *     id: "conv_1",
+     *     subject: "Support Request",
+     *     content: "Customer needs help with login",
+     *     metadata: {
+     *       subject: "Support Request",
+     *       organizationId: "org_123",
+     *       inboxId: "support_inbox",
+     *       domainId: "domain_1",
+     *       participants: ["customer@example.com"],
+     *       threadId: "thread_1",
+     *       timestamp: new Date()
+     *     }
+     *   },
+     *   // ... more conversations
+     * ]);
+     * ```
+     */
+    async indexBatch(organizationId, conversations) {
+        const response = await fetch(`${this.baseUrl}/search/index/batch`, {
+            method: 'POST',
+            headers: {
+                ...this.headers,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ organizationId, conversations }),
+        });
+        const data = await response.json();
+        if (data.error || !data.data.success) {
+            throw new Error(data.error?.message || 'Failed to index conversations');
+        }
+    }
+}

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { AttachmentRecord, ConversationListParams, CreateDomainPayload, DomainEntry, InboxEntry, MessageListParams, SemanticSearchParams, SemanticSearchResult, SendMessagePayload, UnifiedMessage } 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;
@@ -6,6 +6,7 @@ export type ClientOptions = {
     fetcher?: typeof fetch;
 };
 export declare class CommuneClient {
+    private searchClient;
     private baseUrl;
     private apiKey;
     private headers?;
@@ -59,10 +60,21 @@ export declare class CommuneClient {
     messages: {
         send: (payload: SendMessagePayload) => Promise<Record<string, unknown>>;
         list: (params: MessageListParams) => Promise<UnifiedMessage[]>;
-        listByConversation: (conversationId: string, params?: ConversationListParams) => Promise<UnifiedMessage[]>;
+        listByConversation: (conversationId: string, params?: MessageListParams) => Promise<UnifiedMessage[]>;
+    };
+    conversations: {
+        search: (query: string, filter: SearchFilter, options?: SearchOptions) => Promise<SearchResult[]>;
+        index: (organizationId: string, conversation: IndexConversationPayload) => Promise<{
+            success: boolean;
+        }>;
+        indexBatch: (organizationId: string, conversations: IndexConversationPayload[]) => Promise<{
+            success: boolean;
+        }>;
     };
-    search: (params: SemanticSearchParams) => Promise<SemanticSearchResult[]>;
     attachments: {
-        get: (attachmentId: string) => Promise<AttachmentRecord>;
+        get: (attachmentId: string, options?: {
+            url?: boolean;
+            expiresIn?: number;
+        }) => Promise<AttachmentRecord | AttachmentUrl>;
     };
 }

package/dist/client.js

@@ -1,3 +1,4 @@
+import { SearchClient } from './client/search.js';
 const DEFAULT_BASE_URL = 'https://web-production-3f46f.up.railway.app';
 const buildQuery = (params) => {
     const query = new URLSearchParams();
@@ -89,26 +90,49 @@ export class CommuneClient {
                     inbox_id: params.inbox_id,
                 })}`);
             },
-            listByConversation: async (conversationId, params = {}) => {
+            listByConversation: async (conversationId, params) => {
                 return this.request(`/api/conversations/${encodeURIComponent(conversationId)}/messages${buildQuery({
-                    limit: params.limit,
-                    order: params.order,
+                    limit: params?.limit,
+                    order: params?.order,
                 })}`);
             },
         };
-        // Semantic search across all organizational emails
-        this.search = async (params) => {
-            return this.request(`/api/search${buildQuery({
-                q: params.query,
-                limit: params.limit || 10,
-                threshold: params.threshold || 0.7,
-                before: params.before,
-                after: params.after,
-                sender: params.sender,
-            })}`);
+        this.conversations = {
+            search: async (query, filter, options) => {
+                return this.request('/api/search', {
+                    method: 'POST',
+                    json: {
+                        query,
+                        filter,
+                        options,
+                    },
+                });
+            },
+            index: async (organizationId, conversation) => {
+                return this.request('/api/search/index', {
+                    method: 'POST',
+                    json: {
+                        organizationId,
+                        conversation,
+                    },
+                });
+            },
+            indexBatch: async (organizationId, conversations) => {
+                return this.request('/api/search/index/batch', {
+                    method: 'POST',
+                    json: {
+                        organizationId,
+                        conversations,
+                    },
+                });
+            },
         };
         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)}`);
             },
         };
@@ -116,6 +140,7 @@ export class CommuneClient {
         this.apiKey = options.apiKey;
         this.headers = options.headers;
         this.fetcher = options.fetcher || fetch;
+        this.searchClient = new SearchClient(this.baseUrl, { Authorization: `Bearer ${this.apiKey}` });
     }
     async request(path, options = {}) {
         const { json, headers, ...rest } = options;

package/dist/types/search.d.ts

@@ -0,0 +1,35 @@
+export interface SearchFilter {
+    organizationId: string;
+    inboxIds?: string[];
+    participants?: string[];
+    domainId?: string;
+    startDate?: string;
+    endDate?: string;
+}
+export interface SearchOptions {
+    limit?: number;
+    offset?: number;
+    minScore?: number;
+}
+export interface SearchResult {
+    id: string;
+    score: number;
+    metadata: {
+        subject: string;
+        organizationId: string;
+        inboxId: string;
+        domainId: string;
+        participants: string[];
+        threadId: string;
+        timestamp: Date;
+    };
+}
+export interface ConversationMetadata {
+    subject: string;
+    organizationId: string;
+    inboxId: string;
+    domainId: string;
+    participants: string[];
+    threadId: string;
+    timestamp: Date;
+}

package/dist/types/search.js

@@ -0,0 +1 @@
+export {};

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;
@@ -126,6 +142,8 @@ export interface MessageListParams {
 export interface ConversationListParams {
     limit?: number;
     order?: 'asc' | 'desc';
+    before?: string;
+    after?: string;
 }
 export interface SvixHeaders {
     id: string;
@@ -140,6 +158,7 @@ export interface InboundEmailWebhookPayload {
     email: unknown;
     message: UnifiedMessage;
     extractedData?: Record<string, any>;
+    attachments?: AttachmentMetadata[];
 }
 export interface ApiError {
     message?: string;
@@ -149,16 +168,51 @@ export interface ApiResponse<T> {
     data: T;
     error?: ApiError;
 }
-export interface SemanticSearchParams {
-    query: string;
+export interface SearchFilter {
+    organizationId: string;
+    inboxIds?: string[];
+    participants?: string[];
+    domainId?: string;
+    startDate?: string;
+    endDate?: string;
+}
+export interface SearchOptions {
     limit?: number;
-    threshold?: number;
-    before?: string;
-    after?: string;
-    sender?: string;
+    offset?: number;
+    minScore?: number;
 }
-export interface SemanticSearchResult {
-    message: UnifiedMessage;
-    similarity: number;
-    highlights: string[];
+export interface SearchResult {
+    id: string;
+    score: number;
+    metadata: {
+        subject: string;
+        organizationId: string;
+        inboxId: string;
+        domainId: string;
+        participants: string[];
+        threadId: string;
+        timestamp: Date;
+        attachmentIds?: string[];
+        hasAttachments?: boolean;
+        attachmentCount?: number;
+    };
+}
+export interface ConversationMetadata {
+    subject: string;
+    organizationId: string;
+    inboxId: string;
+    domainId: string;
+    participants: string[];
+    threadId: string;
+    timestamp: Date;
+    attachmentIds?: string[];
+    hasAttachments?: boolean;
+    attachmentCount?: number;
+}
+export interface IndexConversationPayload {
+    id: string;
+    subject: string;
+    content: string;
+    metadata: ConversationMetadata;
 }
+export type SearchType = 'vector' | 'agent';

package/package.json

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