@nebula-ai/sdk 0.0.21 → 0.0.27

package/README.md

@@ -6,18 +6,6 @@ Official JavaScript/TypeScript SDK for Nebula - Memory, Search, and AI-powered c
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 
-## Features
-
-- 🚀 **Full API Parity** - Mirrors the exact Nebula Python SDK client.py implementation
-- 🔐 **Flexible Authentication** - Supports both API keys and Bearer tokens
-- 🌐 **Browser & Node.js Ready** - Works in browsers and Node.js environments
-- 📱 **TypeScript First** - Full type safety with comprehensive interfaces
-- 🎯 **Unified Memory Model** - Store text, conversations, and structured data
-- 🔍 **Advanced Search** - Vector search with graph results (entities, relationships, communities)
-- 💬 **Conversation Support** - Built-in conversation tracking and management
-- ⚡ **Performance Optimized** - Configurable timeouts and error handling
-- 🧠 **Graph Intelligence** - Leverage knowledge graphs for enhanced search
-
 ## Installation
 
 ```bash
@@ -41,10 +29,10 @@ const client = new NebulaClient({
 });
 
 // Create a cluster
-const cluster = await client.createCluster(
-  'My Project', 
-  'A collection of project memories'
-);
+const cluster = await client.createCluster({
+  name: 'My Project',
+  description: 'A collection of project memories'
+});
 
 // Store a memory using the unified Memory model
 const memoryId = await client.storeMemory({
@@ -54,13 +42,13 @@ const memoryId = await client.storeMemory({
 });
 
 // Search for memories with advanced options
-const results = await client.search(
-  'project information',
-  [cluster.id],
-  5,
-  RetrievalType.ADVANCED,
-  { 'metadata.category': 'project' }
-);
+const results = await client.search({
+  query: 'project information',
+  cluster_ids: [cluster.id],
+  limit: 5,
+  retrieval_type: RetrievalType.ADVANCED,
+  filters: { 'metadata.category': 'project' }
+});
 
 console.log('Found memories:', results);
 ```
@@ -84,7 +72,7 @@ new NebulaClient(config: NebulaClientConfig)
 
 ```typescript
 // Create a new cluster
-await client.createCluster(name: string, description?: string, metadata?: Record<string, any>)
+await client.createCluster(options: { name: string, description?: string, metadata?: Record<string, any> })
 
 // Get a cluster by ID
 await client.getCluster(clusterId: string)
@@ -93,10 +81,10 @@ await client.getCluster(clusterId: string)
 await client.getClusterByName(name: string)
 
 // List all clusters
-await client.listClusters(limit?: number, offset?: number)
+await client.listClusters(options?: { limit?: number, offset?: number })
 
 // Update a cluster
-await client.updateCluster(clusterId: string, name?: string, description?: string, metadata?: Record<string, any>)
+await client.updateCluster(options: { clusterId: string, name?: string, description?: string, metadata?: Record<string, any> })
 
 // Delete a cluster
 await client.deleteCluster(clusterId: string)
@@ -106,7 +94,7 @@ await client.deleteCluster(clusterId: string)
 
 ```typescript
 // List conversations for the authenticated user
-await client.listConversations(limit?: number, offset?: number, cluster_ids?: string[])
+await client.listConversations(options?: { limit?: number, offset?: number, cluster_ids?: string[] })
 
 // Get conversation messages
 await client.getConversationMessages(conversationId: string): Promise<MemoryResponse[]>
@@ -129,24 +117,28 @@ await client.storeMemories(memories: Memory[])
 await client.getMemory(memoryId: string)
 
 // List memories from clusters
-await client.listMemories(clusterIds: string | string[], limit?: number, offset?: number)
+await client.listMemories(options: { cluster_ids: string | string[], limit?: number, offset?: number })
 
-// Delete a memory
-await client.delete(memoryId: string)
+// Delete one or more memories
+// Single deletion:
+await client.delete('memory-id') // Returns: boolean
+
+// Batch deletion:
+await client.delete(['id1', 'id2', 'id3']) // Returns: detailed results object
 ```
 
 #### Search
 
 ```typescript
 // Search within clusters
-await client.search(
+await client.search(options: {
   query: string,
-  clusters: string | string[],
-  limitOrOptions?: number | { limit?: number },
-  retrievalType?: RetrievalType | string,
+  cluster_ids: string | string[],
+  limit?: number,
+  retrieval_type?: RetrievalType | string,
   filters?: Record<string, any>,
   searchSettings?: Record<string, any>
-)
+})
 ```
 
 #### Health Check
@@ -232,22 +224,21 @@ enum RetrievalType {
 The search method supports advanced configuration:
 
 ```typescript
-const results = await client.search(
-  'query',
-  [clusterId],
-  10,
-  RetrievalType.ADVANCED,
-  { 'metadata.category': 'science' },
-  {
+const results = await client.search({
+  query: 'query',
+  cluster_ids: [clusterId],
+  limit: 10,
+  retrieval_type: RetrievalType.ADVANCED,
+  filters: { 'metadata.category': 'science' },
+  searchSettings: {
     graph_settings: {
       enabled: true,
       bfs_enabled: true,
       bfs_max_depth: 2
     },
-    search_strategy: 'rag_fusion',
     num_sub_queries: 3
   }
-);
+});
 ```
 
 ### Error Handling
@@ -265,7 +256,7 @@ import {
 } from '@nebula-ai/sdk';
 
 try {
-  await client.search('query', [clusterId]);
+  await client.search({ query: 'query', cluster_ids: [clusterId] });
 } catch (error) {
   if (error instanceof NebulaAuthenticationException) {
     console.log('Invalid API key');
@@ -290,10 +281,10 @@ const client = new NebulaClient({ apiKey: 'your-key' });
 
 async function manageMemories() {
   // Create a cluster
-  const cluster = await client.createCluster(
-    'Knowledge Base',
-    'My personal knowledge repository'
-  );
+  const cluster = await client.createCluster({
+    name: 'Knowledge Base',
+    description: 'My personal knowledge repository'
+  });
 
   // Store memories using the unified model
   const memories = [
@@ -314,8 +305,24 @@ async function manageMemories() {
   console.log('Stored memories:', memoryIds);
 
   // Search for memories
-  const results = await client.search('JavaScript', [cluster.id]);
+  const results = await client.search({ query: 'JavaScript', cluster_ids: [cluster.id] });
   console.log('Search results:', results);
+
+  // Delete a single memory
+  const deleted = await client.delete(memoryIds[0]);
+  console.log('Deleted single memory:', deleted); // true
+
+  // Delete multiple memories at once
+  const batchResult = await client.delete([memoryIds[1], memoryIds[2]]);
+  console.log('Batch deletion results:', batchResult);
+  // {
+  //   message: "Deleted 2 of 2 documents",
+  //   results: {
+  //     successful: ["id1", "id2"],
+  //     failed: [],
+  //     summary: { total: 2, succeeded: 2, failed: 0 }
+  //   }
+  // }
 }
 ```
 
@@ -327,7 +334,10 @@ import { NebulaClient } from '@nebula-ai/sdk';
 const client = new NebulaClient({ apiKey: 'your-key' });
 
 async function trackConversation() {
-  const cluster = await client.createCluster('Conversations', 'AI chat history');
+  const cluster = await client.createCluster({
+    name: 'Conversations',
+    description: 'AI chat history'
+  });
 
   // Store conversation turns
   const conversationMemories = [
@@ -363,7 +373,7 @@ const client = new NebulaClient({ apiKey: 'your-key' });
 
 async function manageConversations() {
   // List all conversations
-  const conversations = await client.listConversations(10, 0);
+  const conversations = await client.listConversations({ limit: 10, offset: 0 });
   console.log('All conversations:', conversations);
 
   // Get messages from a specific conversation
@@ -388,7 +398,10 @@ import { NebulaClient, RetrievalType } from '@nebula-ai/sdk';
 const client = new NebulaClient({ apiKey: 'your-key' });
 
 async function advancedSearch() {
-  const cluster = await client.createCluster('Knowledge Graph', 'Entity relationships');
+  const cluster = await client.createCluster({
+    name: 'Knowledge Graph',
+    description: 'Entity relationships'
+  });
 
   // Store knowledge graph data
   await client.storeMemory({
@@ -398,20 +411,19 @@ async function advancedSearch() {
   });
 
   // Search with graph settings
-  const results = await client.search(
-    'Einstein relativity',
-    [cluster.id],
-    10,
-    RetrievalType.ADVANCED,
-    undefined,
-    {
+  const results = await client.search({
+    query: 'Einstein relativity',
+    cluster_ids: [cluster.id],
+    limit: 10,
+    retrieval_type: RetrievalType.ADVANCED,
+    searchSettings: {
       graph_settings: {
         enabled: true,
         bfs_enabled: true,
         bfs_max_depth: 2
       }
     }
-  );
+  });
 
   // Handle both chunk and graph results
   results.forEach(result => {

package/dist/index.d.mts

@@ -1,8 +1,3 @@
-declare enum RetrievalType {
-    BASIC = "basic",
-    ADVANCED = "advanced",
-    CUSTOM = "custom"
-}
 declare enum GraphSearchResultType {
     ENTITY = "entity",
     RELATIONSHIP = "relationship",
@@ -39,6 +34,11 @@ interface SearchResult {
     score: number;
     metadata: Record<string, any>;
     source?: string;
+    timestamp?: string;
+    display_name?: string;
+    source_role?: string;
+    document_id?: string;
+    owner_id?: string;
     content?: string;
     graph_result_type?: GraphSearchResultType;
     graph_entity?: GraphEntityResult;
@@ -78,17 +78,17 @@ interface AgentResponse {
 interface SearchOptions {
     limit: number;
     filters?: Record<string, any>;
-    retrieval_type: RetrievalType;
+    search_mode?: 'fast' | 'super';
 }
-interface NebulaSDKConfig {
+interface NebulaClientConfig {
     apiKey: string;
     baseUrl?: string;
     timeout?: number;
 }
 declare class NebulaException extends Error {
     statusCode?: number | undefined;
-    details?: any;
-    constructor(message: string, statusCode?: number | undefined, details?: any);
+    details?: any | undefined;
+    constructor(message: string, statusCode?: number | undefined, details?: any | undefined);
 }
 declare class NebulaClientException extends NebulaException {
     cause?: Error | undefined;
@@ -101,122 +101,221 @@ declare class NebulaRateLimitException extends NebulaException {
     constructor(message?: string);
 }
 declare class NebulaValidationException extends NebulaException {
-    details?: any;
-    constructor(message?: string, details?: any);
+    details?: any | undefined;
+    constructor(message?: string, details?: any | undefined);
 }
 declare class NebulaClusterNotFoundException extends NebulaException {
     constructor(message?: string);
 }
 
 /**
- * Official Nebula Cloud JavaScript/TypeScript SDK
+ * Official Nebula JavaScript/TypeScript SDK
  * Mirrors the exact Nebula Python SDK client.py implementation
  */
-declare class NebulaSDK {
+declare class NebulaClient {
     private apiKey;
     private baseUrl;
     private timeout;
-    constructor(config: NebulaSDKConfig);
-    /**
-     * Check if API key is set
-     */
+    constructor(config: NebulaClientConfig);
+    setApiKey(next: string): void;
+    setBaseUrl(next: string): void;
+    setCorsProxy(_next: string): void;
+    /** Check if API key is set */
     isApiKeySet(): boolean;
-    /**
-     * Detect if a token looks like a Nebula API key (public.raw)
-     */
+    /** Detect if a token looks like a Nebula API key (public.raw) */
     private _isNebulaApiKey;
-    /**
-     * Build authentication headers
-     */
+    /** Build authentication headers */
     private _buildAuthHeaders;
-    /**
-     * Make an HTTP request to the Nebula API
-     */
+    /** Make an HTTP request to the Nebula API */
     private _makeRequest;
-    /**
-     * Create a new cluster
-     */
-    createCluster(name: string, description?: string, metadata?: Record<string, any>): Promise<Cluster>;
-    /**
-     * Get a specific cluster by ID
-     */
+    /** Create a new cluster */
+    createCluster(options: {
+        name: string;
+        description?: string;
+        metadata?: Record<string, any>;
+    }): Promise<Cluster>;
+    /** Get a specific cluster by ID */
     getCluster(clusterId: string): Promise<Cluster>;
-    /**
-     * Get a specific cluster by name
-     */
+    /** Get a specific cluster by name */
     getClusterByName(name: string): Promise<Cluster>;
-    /**
-     * Get all clusters
-     */
-    listClusters(limit?: number, offset?: number): Promise<Cluster[]>;
-    /**
-     * List conversations for the authenticated user
-     */
-    listConversations(limit?: number, offset?: number): Promise<any[]>;
-    /**
-     * Update a cluster
-     */
-    updateCluster(clusterId: string, name?: string, description?: string, metadata?: Record<string, any>): Promise<Cluster>;
-    /**
-     * Delete a cluster
-     */
+    /** Get all clusters */
+    listClusters(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<Cluster[]>;
+    /** List conversations for the authenticated user */
+    listConversations(options?: {
+        limit?: number;
+        offset?: number;
+        cluster_ids?: string[];
+    }): Promise<any[]>;
+    /** Get conversation messages directly from the conversations API */
+    getConversationMessages(conversationId: string): Promise<MemoryResponse[]>;
+    getConversationMessages(conversationIds: string[]): Promise<Record<string, MemoryResponse[]>>;
+    /** Helper method to transform conversation messages to MemoryResponse format */
+    private _transformConversationMessages;
+    /** Update a cluster */
+    updateCluster(options: {
+        clusterId: string;
+        name?: string;
+        description?: string;
+        metadata?: Record<string, any>;
+    }): Promise<Cluster>;
+    /** Delete a cluster */
     deleteCluster(clusterId: string): Promise<boolean>;
     /**
-     * Store a single memory
+     * Legacy convenience: store raw text content into a cluster as a document
      */
+    store(content: string, clusterId: string, metadata?: Record<string, any>): Promise<MemoryResponse>;
+    /** Store a single memory */
     storeMemory(memory: Memory | Record<string, any>): Promise<string>;
-    /**
-     * Store multiple memories
-     */
+    /** Store multiple memories */
     storeMemories(memories: Memory[]): Promise<string[]>;
-    /**
-     * Delete a specific memory
-     */
-    delete(memoryId: string): Promise<boolean>;
-    /**
-     * Delete a conversation and all its messages
-     */
+    /** Delete one or more memories */
+    delete(memoryIds: string | string[]): Promise<boolean | {
+        message: string;
+        results: {
+            successful: string[];
+            failed: Array<{
+                id: string;
+                error: string;
+            }>;
+            summary: {
+                total: number;
+                succeeded: number;
+                failed: number;
+            };
+        };
+    }>;
+    /** Delete a conversation and all its messages */
     deleteConversation(conversationId: string): Promise<boolean>;
-    /**
-     * Get all memories from specific clusters
-     */
-    listMemories(clusterIds: string[], limit?: number, offset?: number): Promise<MemoryResponse[]>;
-    /**
-     * Get a specific memory by ID
-     */
+    /** Get all memories from specific clusters */
+    listMemories(options: {
+        cluster_ids: string | string[];
+        limit?: number;
+        offset?: number;
+    }): Promise<MemoryResponse[]>;
+    /** Get a specific memory by ID */
     getMemory(memoryId: string): Promise<MemoryResponse>;
     /**
-     * Search within specific clusters
+     * Search within specific clusters with optional metadata filtering.
+     *
+     * @param options - Search configuration
+     * @param options.query - Search query string
+     * @param options.cluster_ids - One or more cluster IDs to search within
+     * @param options.limit - Maximum number of results to return (default: 10)
+     * @param options.retrieval_type - Retrieval strategy (default: ADVANCED)
+     * @param options.filters - Optional filters to apply to the search. Supports comprehensive metadata filtering
+     *                          with MongoDB-like operators for both vector/chunk search and graph search.
+     * @param options.searchSettings - Optional search configuration
+     *
+     * @returns Promise resolving to array of SearchResult objects containing both vector/chunk and graph search results
+     *
+     * @example
+     * // Basic equality filter
+     * await client.search({
+     *   query: "machine learning",
+     *   cluster_ids: ["research-cluster"],
+     *   filters: {
+     *     "metadata.category": { $eq: "research" },
+     *     "metadata.verified": true  // Shorthand for $eq
+     *   }
+     * });
+     *
+     * @example
+     * // Numeric comparisons
+     * await client.search({
+     *   query: "high priority",
+     *   cluster_ids: ["tasks"],
+     *   filters: {
+     *     "metadata.priority": { $gte: 8 },
+     *     "metadata.score": { $lt: 100 }
+     *   }
+     * });
+     *
+     * @example
+     * // String matching
+     * await client.search({
+     *   query: "employees",
+     *   cluster_ids: ["team"],
+     *   filters: {
+     *     "metadata.email": { $ilike: "%@company.com" }  // Case-insensitive
+     *   }
+     * });
+     *
+     * @example
+     * // Array operations
+     * await client.search({
+     *   query: "developers",
+     *   cluster_ids: ["team"],
+     *   filters: {
+     *     "metadata.skills": { $overlap: ["python", "typescript"] }  // Has any
+     *   }
+     * });
+     *
+     * @example
+     * // Nested paths
+     * await client.search({
+     *   query: "users",
+     *   cluster_ids: ["profiles"],
+     *   filters: {
+     *     "metadata.user.preferences.theme": { $eq: "dark" }
+     *   }
+     * });
+     *
+     * @example
+     * // Complex logical combinations
+     * await client.search({
+     *   query: "candidates",
+     *   cluster_ids: ["hiring"],
+     *   filters: {
+     *     $and: [
+     *       { "metadata.verified": true },
+     *       { "metadata.level": { $gte: 5 } },
+     *       {
+     *         $or: [
+     *           { "metadata.skills": { $overlap: ["python", "go"] } },
+     *           { "metadata.years_experience": { $gte: 8 } }
+     *         ]
+     *       }
+     *     ]
+     *   }
+     * });
+     *
+     * @remarks
+     * Supported Operators:
+     * - Comparison: $eq, $ne, $lt, $lte, $gt, $gte
+     * - String: $like (case-sensitive), $ilike (case-insensitive)
+     * - Array: $in, $nin, $overlap, $contains
+     * - JSONB: $json_contains
+     * - Logical: $and, $or
+     *
+     * For comprehensive filtering documentation, see the Metadata Filtering Guide:
+     * https://docs.nebulacloud.app/guides/metadata-filtering
      */
-    search(query: string, clusterIds: string[], limit?: number, retrievalType?: RetrievalType | string, filters?: Record<string, any>, searchSettings?: Record<string, any>): Promise<SearchResult[]>;
+    search(options: {
+        query: string;
+        cluster_ids: string | string[];
+        limit?: number;
+        filters?: Record<string, any>;
+        search_mode?: 'fast' | 'super';
+        searchSettings?: Record<string, any>;
+    }): Promise<SearchResult[]>;
     /**
-     * Check the health of the Nebula API
+     * Legacy wrapper: store a two-message conversation turn as a document
      */
-    healthCheck(): Promise<Record<string, any>>;
+    storeConversation(userMessage: string, assistantMessage: string, clusterId: string, sessionId: string): Promise<MemoryResponse>;
     /**
-     * Convert cluster dict to Cluster object
+     * Legacy wrapper: search conversations optionally scoped by session
      */
+    searchConversations(query: string, clusterId: string, sessionId?: string, includeAllSessions?: boolean): Promise<SearchResult[]>;
+    healthCheck(): Promise<Record<string, any>>;
     private _clusterFromDict;
-    /**
-     * Convert memory dict to MemoryResponse object
-     */
     private _memoryResponseFromDict;
-    /**
-     * Convert search result dict to SearchResult object
-     */
     private _searchResultFromDict;
-    /**
-     * Convert graph search result dict to SearchResult object
-     */
     private _searchResultFromGraphDict;
-    /**
-     * SHA-256 hash function
-     */
     private _sha256;
-    /**
-     * Convert object to FormData
-     */
     private _formDataFromObject;
 }
 
-export { type AgentResponse, type Cluster, type GraphCommunityResult, type GraphEntityResult, type GraphRelationshipResult, GraphSearchResultType, type Memory, type MemoryResponse, NebulaAuthenticationException, NebulaClientException, NebulaClusterNotFoundException, NebulaException, NebulaRateLimitException, NebulaSDK, type NebulaSDKConfig, NebulaValidationException, RetrievalType, type SearchOptions, type SearchResult, NebulaSDK as default };
+export { type AgentResponse, type Cluster, type GraphCommunityResult, type GraphEntityResult, type GraphRelationshipResult, GraphSearchResultType, type Memory, type MemoryResponse, NebulaAuthenticationException, NebulaClient, type NebulaClientConfig, NebulaClientException, NebulaClusterNotFoundException, NebulaException, NebulaRateLimitException, NebulaValidationException, type SearchOptions, type SearchResult };