commune-ai 0.2.4 → 0.2.5

package/README.md

@@ -132,6 +132,108 @@ 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;
+  };
+}
+```
+
 ## 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, 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,9 +60,17 @@ 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>;
     };

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,23 +90,42 @@ 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) => {
@@ -116,6 +136,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

@@ -126,6 +126,8 @@ export interface MessageListParams {
 export interface ConversationListParams {
     limit?: number;
     order?: 'asc' | 'desc';
+    before?: string;
+    after?: string;
 }
 export interface SvixHeaders {
     id: string;
@@ -149,16 +151,45 @@ 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;
+    };
+}
+export interface ConversationMetadata {
+    subject: string;
+    organizationId: string;
+    inboxId: string;
+    domainId: string;
+    participants: string[];
+    threadId: string;
+    timestamp: Date;
+}
+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.5",
   "description": "Our email infrastructure - webhooks, threads, history, and semantic search",
   "type": "module",
   "main": "dist/index.js",