@nebula-ai/sdk 0.0.20 → 0.0.24

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
@@ -31,10 +19,10 @@ pnpm add @nebula-ai/sdk
 ## Quick Start
 
 ```typescript
-import { NebulaSDK, RetrievalType } from '@nebula-ai/sdk';
+import { NebulaClient, RetrievalType } from '@nebula-ai/sdk';
 
 // Initialize the SDK
-const client = new NebulaSDK({
+const client = new NebulaClient({
   apiKey: 'your-nebula-api-key',
   baseUrl: 'https://api.nebulacloud.app', // optional, defaults to this
   timeout: 30000 // optional, defaults to 30 seconds
@@ -70,7 +58,7 @@ console.log('Found memories:', results);
 ### Constructor
 
 ```typescript
-new NebulaSDK(config: NebulaSDKConfig)
+new NebulaClient(config: NebulaClientConfig)
 ```
 
 **Config Options:**
@@ -102,6 +90,20 @@ await client.updateCluster(clusterId: string, name?: string, description?: strin
 await client.deleteCluster(clusterId: string)
 ```
 
+#### Conversations
+
+```typescript
+// List conversations for the authenticated user
+await client.listConversations(limit?: number, offset?: number, cluster_ids?: string[])
+
+// Get conversation messages
+await client.getConversationMessages(conversationId: string): Promise<MemoryResponse[]>
+await client.getConversationMessages(conversationIds: string[]): Promise<Record<string, MemoryResponse[]>>
+
+// Delete a conversation and all its messages
+await client.deleteConversation(conversationId: string)
+```
+
 #### Memories
 
 ```typescript
@@ -115,7 +117,7 @@ await client.storeMemories(memories: Memory[])
 await client.getMemory(memoryId: string)
 
 // List memories from clusters
-await client.listMemories(clusterIds: string[], limit?: number, offset?: number)
+await client.listMemories(clusterIds: string | string[], limit?: number, offset?: number)
 
 // Delete a memory
 await client.delete(memoryId: string)
@@ -127,8 +129,8 @@ await client.delete(memoryId: string)
 // Search within clusters
 await client.search(
   query: string,
-  clusterIds: string[],
-  limit?: number,
+  clusters: string | string[],
+  limitOrOptions?: number | { limit?: number },
   retrievalType?: RetrievalType | string,
   filters?: Record<string, any>,
   searchSettings?: Record<string, any>
@@ -191,6 +193,18 @@ interface SearchResult {
 }
 ```
 
+#### AgentResponse
+
+```typescript
+interface AgentResponse {
+  content: string;
+  agent_id: string;
+  conversation_id?: string;
+  metadata: Record<string, any>;
+  citations: Record<string, any>[];
+}
+```
+
 #### RetrievalType
 
 ```typescript
@@ -218,7 +232,6 @@ const results = await client.search(
       bfs_enabled: true,
       bfs_max_depth: 2
     },
-    search_strategy: 'rag_fusion',
     num_sub_queries: 3
   }
 );
@@ -258,9 +271,9 @@ try {
 ### Basic Memory Management
 
 ```typescript
-import { NebulaSDK } from '@nebula-ai/sdk';
+import { NebulaClient } from '@nebula-ai/sdk';
 
-const client = new NebulaSDK({ apiKey: 'your-key' });
+const client = new NebulaClient({ apiKey: 'your-key' });
 
 async function manageMemories() {
   // Create a cluster
@@ -296,9 +309,9 @@ async function manageMemories() {
 ### Conversation Tracking
 
 ```typescript
-import { NebulaSDK } from '@nebula-ai/sdk';
+import { NebulaClient } from '@nebula-ai/sdk';
 
-const client = new NebulaSDK({ apiKey: 'your-key' });
+const client = new NebulaClient({ apiKey: 'your-key' });
 
 async function trackConversation() {
   const cluster = await client.createCluster('Conversations', 'AI chat history');
@@ -327,14 +340,39 @@ async function trackConversation() {
   const messages = await client.getConversationMessages(conversationIds[0]);
   console.log('Conversation messages:', messages);
 }
+
+### Managing Conversations
+
+```typescript
+import { NebulaClient } from '@nebula-ai/sdk';
+
+const client = new NebulaClient({ apiKey: 'your-key' });
+
+async function manageConversations() {
+  // List all conversations
+  const conversations = await client.listConversations(10, 0);
+  console.log('All conversations:', conversations);
+
+  // Get messages from a specific conversation
+  const messages = await client.getConversationMessages('conversation-id');
+  console.log('Conversation messages:', messages);
+
+  // Get messages from multiple conversations at once
+  const multipleMessages = await client.getConversationMessages(['conv1', 'conv2']);
+  console.log('Multiple conversations:', multipleMessages);
+
+  // Delete a conversation
+  await client.deleteConversation('conversation-id');
+  console.log('Conversation deleted');
+}
 ```
 
 ### Advanced Search with Graph Results
 
 ```typescript
-import { NebulaSDK, RetrievalType } from '@nebula-ai/sdk';
+import { NebulaClient, RetrievalType } from '@nebula-ai/sdk';
 
-const client = new NebulaSDK({ apiKey: 'your-key' });
+const client = new NebulaClient({ apiKey: 'your-key' });
 
 async function advancedSearch() {
   const cluster = await client.createCluster('Knowledge Graph', 'Entity relationships');
@@ -384,9 +422,9 @@ async function advancedSearch() {
 ### Browser Usage
 
 ```typescript
-import { NebulaSDK } from '@nebula-ai/sdk';
+import { NebulaClient } from '@nebula-ai/sdk';
 
-const client = new NebulaSDK({
+const client = new NebulaClient({
   apiKey: 'your-api-key'
   // Note: CORS handling is now built into the SDK
 });
@@ -395,9 +433,9 @@ const client = new NebulaSDK({
 ### Node.js Usage
 
 ```typescript
-import { NebulaSDK } from '@nebula-ai/sdk';
+import { NebulaClient } from '@nebula-ai/sdk';
 
-const client = new NebulaSDK({
+const client = new NebulaClient({
   apiKey: 'your-api-key'
   // No additional configuration needed
 });

package/dist/index.d.mts

@@ -80,15 +80,15 @@ interface SearchOptions {
     filters?: Record<string, any>;
     retrieval_type: RetrievalType;
 }
-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,87 @@ 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
-     */
+    /** Create a new cluster */
     createCluster(name: string, description?: string, metadata?: Record<string, any>): Promise<Cluster>;
-    /**
-     * Get a specific cluster by ID
-     */
+    /** 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
-     */
+    /** 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
-     */
+    /** List conversations for the authenticated user */
+    listConversations(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(clusterId: string, name?: string, description?: string, metadata?: Record<string, any>): Promise<Cluster>;
-    /**
-     * Delete a 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 a specific memory */
     delete(memoryId: string): Promise<boolean>;
-    /**
-     * Delete a conversation and all its messages
-     */
+    /** 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(clusterIds: string | string[], limit?: number, offset?: number): Promise<MemoryResponse[]>;
+    /** Get a specific memory by ID */
     getMemory(memoryId: string): Promise<MemoryResponse>;
+    /** Search within specific clusters */
+    search(query: string, clusters: string | string[], limitOrOptions?: number | {
+        limit?: number;
+    }, retrievalType?: RetrievalType | string, filters?: Record<string, any>, searchSettings?: Record<string, any>): Promise<SearchResult[]>;
     /**
-     * Search within specific clusters
+     * Legacy wrapper: store a two-message conversation turn as a document
      */
-    search(query: string, clusterIds: string[], limit?: number, retrievalType?: RetrievalType | string, filters?: Record<string, any>, searchSettings?: Record<string, any>): Promise<SearchResult[]>;
+    storeConversation(userMessage: string, assistantMessage: string, clusterId: string, sessionId: string): Promise<MemoryResponse>;
     /**
-     * Check the health of the Nebula API
+     * Legacy wrapper: search conversations optionally scoped by session
      */
+    searchConversations(query: string, clusterId: string, sessionId?: string, includeAllSessions?: boolean): Promise<SearchResult[]>;
     healthCheck(): Promise<Record<string, any>>;
-    /**
-     * Convert cluster dict to Cluster object
-     */
     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, RetrievalType, type SearchOptions, type SearchResult };

package/dist/index.d.ts

@@ -80,15 +80,15 @@ interface SearchOptions {
     filters?: Record<string, any>;
     retrieval_type: RetrievalType;
 }
-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,87 @@ 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
-     */
+    /** Create a new cluster */
     createCluster(name: string, description?: string, metadata?: Record<string, any>): Promise<Cluster>;
-    /**
-     * Get a specific cluster by ID
-     */
+    /** 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
-     */
+    /** 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
-     */
+    /** List conversations for the authenticated user */
+    listConversations(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(clusterId: string, name?: string, description?: string, metadata?: Record<string, any>): Promise<Cluster>;
-    /**
-     * Delete a 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 a specific memory */
     delete(memoryId: string): Promise<boolean>;
-    /**
-     * Delete a conversation and all its messages
-     */
+    /** 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(clusterIds: string | string[], limit?: number, offset?: number): Promise<MemoryResponse[]>;
+    /** Get a specific memory by ID */
     getMemory(memoryId: string): Promise<MemoryResponse>;
+    /** Search within specific clusters */
+    search(query: string, clusters: string | string[], limitOrOptions?: number | {
+        limit?: number;
+    }, retrievalType?: RetrievalType | string, filters?: Record<string, any>, searchSettings?: Record<string, any>): Promise<SearchResult[]>;
     /**
-     * Search within specific clusters
+     * Legacy wrapper: store a two-message conversation turn as a document
      */
-    search(query: string, clusterIds: string[], limit?: number, retrievalType?: RetrievalType | string, filters?: Record<string, any>, searchSettings?: Record<string, any>): Promise<SearchResult[]>;
+    storeConversation(userMessage: string, assistantMessage: string, clusterId: string, sessionId: string): Promise<MemoryResponse>;
     /**
-     * Check the health of the Nebula API
+     * Legacy wrapper: search conversations optionally scoped by session
      */
+    searchConversations(query: string, clusterId: string, sessionId?: string, includeAllSessions?: boolean): Promise<SearchResult[]>;
     healthCheck(): Promise<Record<string, any>>;
-    /**
-     * Convert cluster dict to Cluster object
-     */
     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, RetrievalType, type SearchOptions, type SearchResult };

package/dist/index.js

@@ -55,7 +55,7 @@ var NebulaClusterNotFoundException = class extends NebulaException {
 };
 
 // src/client.ts
-var NebulaSDK = class {
+var NebulaClient = class {
   constructor(config) {
     this.apiKey = config.apiKey;
     if (!this.apiKey) {
@@ -530,23 +530,6 @@ var NebulaSDK = class {
     }
     const effectiveSettings = { ...searchSettings };
     effectiveSettings.limit = limit;
-    effectiveSettings.use_semantic_search = false;
-    effectiveSettings.use_fulltext_search = false;
-    effectiveSettings.use_hybrid_search = false;
-    effectiveSettings.chunk_settings = {
-      ...effectiveSettings.chunk_settings || {},
-      enabled: false
-    };
-    effectiveSettings.search_strategy = "rag_fusion";
-    effectiveSettings.num_sub_queries = 3;
-    const gs = { ...effectiveSettings.graph_settings };
-    gs.enabled = true;
-    gs.bfs_enabled = true;
-    gs.bfs_max_depth = 2;
-    effectiveSettings.graph_settings = gs;
-    if (retrievalType !== "advanced" /* ADVANCED */) {
-      effectiveSettings.retrieval_type = retrievalType;
-    }
     const userFilters = { ...effectiveSettings.filters };
     if (filters) {
       Object.assign(userFilters, filters);
@@ -745,11 +728,11 @@ Assistant: ${String(assistantMessage || "")}`;
 
 exports.GraphSearchResultType = GraphSearchResultType;
 exports.NebulaAuthenticationException = NebulaAuthenticationException;
+exports.NebulaClient = NebulaClient;
 exports.NebulaClientException = NebulaClientException;
 exports.NebulaClusterNotFoundException = NebulaClusterNotFoundException;
 exports.NebulaException = NebulaException;
 exports.NebulaRateLimitException = NebulaRateLimitException;
-exports.NebulaSDK = NebulaSDK;
 exports.NebulaValidationException = NebulaValidationException;
 exports.RetrievalType = RetrievalType;
 //# sourceMappingURL=index.js.map