@nebula-ai/sdk 0.0.19 → 0.0.21

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Nebula Cloud
+Copyright (c) 2025 Nebula AI Inc
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,6 +1,6 @@
 # @nebula-ai/sdk
 
-Official JavaScript/TypeScript SDK for Nebula Cloud - Memory, Search, and AI-powered conversations.
+Official JavaScript/TypeScript SDK for Nebula - Memory, Search, and AI-powered conversations.
 
 [![npm version](https://badge.fury.io/js/%40nebula-ai%2Fsdk.svg)](https://badge.fury.io/js/%40nebula-ai%2Fsdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -31,10 +31,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 +70,7 @@ console.log('Found memories:', results);
 ### Constructor
 
 ```typescript
-new NebulaSDK(config: NebulaSDKConfig)
+new NebulaClient(config: NebulaClientConfig)
 ```
 
 **Config Options:**
@@ -102,6 +102,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 +129,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 +141,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 +205,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
@@ -258,9 +284,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 +322,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');
@@ -322,15 +348,44 @@ async function trackConversation() {
   // Store conversation (returns conversation IDs)
   const conversationIds = await client.storeMemories(conversationMemories);
   console.log('Conversation IDs:', conversationIds);
+
+  // Retrieve conversation messages directly from conversations API
+  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');
@@ -380,9 +435,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
 });
@@ -391,9 +446,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
 });
@@ -435,7 +490,7 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 - 📧 Email: support@trynebula.ai
 - 🐛 Issues: [GitHub Issues](https://github.com/nebula-cloud/nebula-sdk-js/issues)
-- 📚 Documentation: [Nebula Cloud Docs](https://docs.trynebula.ai)
+- 📚 Documentation: [Nebula Docs](https://docs.trynebula.ai)
 
 ## Changelog
 

package/dist/index.d.mts

@@ -173,6 +173,10 @@ declare class NebulaSDK {
      * Delete a specific memory
      */
     delete(memoryId: string): Promise<boolean>;
+    /**
+     * Delete a conversation and all its messages
+     */
+    deleteConversation(conversationId: string): Promise<boolean>;
     /**
      * Get all memories from specific clusters
      */

package/dist/index.d.ts

@@ -173,6 +173,10 @@ declare class NebulaSDK {
      * Delete a specific memory
      */
     delete(memoryId: string): Promise<boolean>;
+    /**
+     * Delete a conversation and all its messages
+     */
+    deleteConversation(conversationId: string): Promise<boolean>;
     /**
      * Get all memories from specific clusters
      */

package/dist/index.js

@@ -1,7 +1,5 @@
 'use strict';
 
-Object.defineProperty(exports, '__esModule', { value: true });
-
 // src/types.ts
 var RetrievalType = /* @__PURE__ */ ((RetrievalType2) => {
   RetrievalType2["BASIC"] = "basic";
@@ -57,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) {
@@ -108,12 +106,23 @@ var NebulaSDK = class {
   async _makeRequest(method, endpoint, jsonData, params) {
     const url = new URL(endpoint, this.baseUrl);
     if (params) {
+      console.log("SDK: _makeRequest params before processing:", params);
       Object.entries(params).forEach(([key, value]) => {
         if (value !== void 0 && value !== null) {
-          url.searchParams.append(key, String(value));
+          if (Array.isArray(value)) {
+            console.log(`SDK: Adding array param ${key}:`, value);
+            value.forEach((item) => {
+              url.searchParams.append(key, String(item));
+              console.log(`SDK: Appended ${key}=${item} to URL`);
+            });
+          } else {
+            console.log(`SDK: Adding single param ${key}:`, value);
+            url.searchParams.append(key, String(value));
+          }
         }
       });
     }
+    console.log("SDK: Final URL being requested:", url.toString());
     const headers = this._buildAuthHeaders(true);
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
@@ -158,26 +167,26 @@ var NebulaSDK = class {
     const data = { name };
     if (description) data.description = description;
     if (metadata) data.metadata = metadata;
-    const response = await this._makeRequest("POST", "/v3/collections", data);
+    const response = await this._makeRequest("POST", "/v1/collections", data);
     const result = response.results || response;
     return this._clusterFromDict(result);
   }
   /** Get a specific cluster by ID */
   async getCluster(clusterId) {
-    const response = await this._makeRequest("GET", `/v3/collections/${clusterId}`);
+    const response = await this._makeRequest("GET", `/v1/collections/${clusterId}`);
     const result = response.results || response;
     return this._clusterFromDict(result);
   }
   /** Get a specific cluster by name */
   async getClusterByName(name) {
-    const response = await this._makeRequest("GET", `/v3/collections/name/${name}`);
+    const response = await this._makeRequest("GET", `/v1/collections/name/${name}`);
     const result = response.results || response;
     return this._clusterFromDict(result);
   }
   /** Get all clusters */
   async listClusters(limit = 100, offset = 0) {
     const params = { limit, offset };
-    const response = await this._makeRequest("GET", "/v3/collections", void 0, params);
+    const response = await this._makeRequest("GET", "/v1/collections", void 0, params);
     let clusters;
     if (response.results) {
       clusters = response.results;
@@ -190,9 +199,12 @@ var NebulaSDK = class {
   }
   // Conversations Methods
   /** List conversations for the authenticated user */
-  async listConversations(limit = 100, offset = 0) {
+  async listConversations(limit = 100, offset = 0, cluster_ids) {
     const params = { limit, offset };
-    const response = await this._makeRequest("GET", "/v3/conversations", void 0, params);
+    if (cluster_ids && cluster_ids.length > 0) {
+      params.collection_ids = cluster_ids;
+    }
+    const response = await this._makeRequest("GET", "/v1/conversations", void 0, params);
     let conversations;
     if (response && response.results) {
       conversations = response.results;
@@ -203,19 +215,91 @@ var NebulaSDK = class {
     }
     return conversations;
   }
+  async getConversationMessages(conversationIdOrIds) {
+    if (typeof conversationIdOrIds === "string") {
+      const response2 = await this._makeRequest("GET", `/v1/conversations/${conversationIdOrIds}`);
+      if (!response2 || !response2.results) {
+        return [];
+      }
+      return this._transformConversationMessages(response2.results);
+    }
+    if (!Array.isArray(conversationIdOrIds) || conversationIdOrIds.length === 0) {
+      return {};
+    }
+    const response = await this._makeRequest("POST", "/v1/conversations/batch", {
+      conversation_ids: conversationIdOrIds
+    });
+    console.log("\u{1F50D} SDK: Raw batch response:", response);
+    console.log("\u{1F50D} SDK: Response has results?", !!response?.results);
+    if (response?.results) {
+      console.log("\u{1F50D} SDK: Results keys:", Object.keys(response.results));
+      console.log("\u{1F50D} SDK: Sample result:", Object.keys(response.results)[0], ":", response.results[Object.keys(response.results)[0]]);
+    }
+    const results = {};
+    if (response && response.results) {
+      const batchResults = response.results.results || response.results;
+      console.log("\u{1F50D} SDK: Processing", Object.keys(batchResults).length, "conversations");
+      for (const [conversationId, messages] of Object.entries(batchResults)) {
+        if (Array.isArray(messages)) {
+          const transformed = this._transformConversationMessages(messages);
+          results[conversationId] = transformed;
+          console.log(`\u{1F50D} SDK: Conversation ${conversationId.slice(-8)}: ${messages.length} raw -> ${transformed.length} transformed`);
+        } else {
+          results[conversationId] = [];
+          console.log(`\u{1F50D} SDK: Conversation ${conversationId.slice(-8)}: not array, setting empty`);
+        }
+      }
+    }
+    for (const conversationId of conversationIdOrIds) {
+      if (!(conversationId in results)) {
+        results[conversationId] = [];
+      }
+    }
+    return results;
+  }
+  /** Helper method to transform conversation messages to MemoryResponse format */
+  _transformConversationMessages(messageResponses) {
+    return messageResponses.map((msgResp) => {
+      const msgId = String(msgResp.id || "");
+      const msg = msgResp.message || {};
+      const metadata = msgResp.metadata || {};
+      let text = "";
+      const rawContent = msg.content;
+      if (typeof rawContent === "string") {
+        text = rawContent;
+      } else if (rawContent && typeof rawContent === "object") {
+        text = String(rawContent.content || rawContent.text || JSON.stringify(rawContent));
+      } else if (rawContent != null) {
+        text = String(rawContent);
+      }
+      const role = msg.role || metadata.role || "user";
+      const combinedMetadata = {
+        ...metadata,
+        role
+        // Ensure role is in metadata for UI compatibility
+      };
+      return {
+        id: msgId,
+        content: text,
+        metadata: combinedMetadata,
+        created_at: msgResp.created_at,
+        cluster_ids: msgResp.collection_ids || []
+      };
+    });
+  }
   /** Update a cluster */
   async updateCluster(clusterId, name, description, metadata) {
     const data = {};
     if (name !== void 0) data.name = name;
     if (description !== void 0) data.description = description;
     if (metadata !== void 0) data.metadata = metadata;
-    const response = await this._makeRequest("POST", `/v3/collections/${clusterId}`, data);
+    const response = await this._makeRequest("POST", `/v1/collections/${clusterId}`, data);
     const result = response.results || response;
     return this._clusterFromDict(result);
   }
   /** Delete a cluster */
   async deleteCluster(clusterId) {
-    await this._makeRequest("DELETE", `/v3/collections/${clusterId}`);
+    await this._makeRequest("DELETE", `/v1/collections/${clusterId}`);
     return true;
   }
   // Memory Management Methods
@@ -234,7 +318,7 @@ var NebulaSDK = class {
       collection_ids: JSON.stringify([clusterId]),
       raw_text: String(content || "")
     };
-    const url = `${this.baseUrl}/v3/documents`;
+    const url = `${this.baseUrl}/v1/documents`;
     const headers = this._buildAuthHeaders(false);
     const response = await fetch(url, {
       method: "POST",
@@ -278,7 +362,7 @@ var NebulaSDK = class {
     if (mem.role) {
       let convId = mem.parent_id;
       if (!convId) {
-        const created = await this._makeRequest("POST", "/v3/conversations", {});
+        const created = await this._makeRequest("POST", "/v1/conversations", {});
         const conv = created.results || created;
         convId = conv.id;
         if (!convId) {
@@ -295,7 +379,7 @@ var NebulaSDK = class {
         ],
         collection_id: mem.cluster_id
       };
-      await this._makeRequest("POST", `/v3/conversations/${convId}/messages`, payload);
+      await this._makeRequest("POST", `/v1/conversations/${convId}/messages`, payload);
       return String(convId);
     }
     const contentText = String(mem.content || "");
@@ -309,7 +393,7 @@ var NebulaSDK = class {
       collection_ids: JSON.stringify([mem.cluster_id]),
       raw_text: contentText
     };
-    const url = `${this.baseUrl}/v3/documents`;
+    const url = `${this.baseUrl}/v1/documents`;
     const headers = this._buildAuthHeaders(false);
     const response = await fetch(url, {
       method: "POST",
@@ -349,7 +433,7 @@ var NebulaSDK = class {
       const clusterId = group[0].cluster_id;
       let convId;
       if (key.startsWith("__new__::")) {
-        const created = await this._makeRequest("POST", "/v3/conversations", {});
+        const created = await this._makeRequest("POST", "/v1/conversations", {});
         const conv = created.results || created;
         convId = conv.id;
         if (!convId) {
@@ -364,7 +448,7 @@ var NebulaSDK = class {
         metadata: m.metadata || {}
       }));
       const payload = { messages, collection_id: clusterId };
-      await this._makeRequest("POST", `/v3/conversations/${convId}/messages`, payload);
+      await this._makeRequest("POST", `/v1/conversations/${convId}/messages`, payload);
       results.push(...Array(group.length).fill(String(convId)));
     }
     for (const m of others) {
@@ -375,7 +459,19 @@ var NebulaSDK = class {
   /** Delete a specific memory */
   async delete(memoryId) {
     try {
-      await this._makeRequest("DELETE", `/v3/documents/${memoryId}`);
+      await this._makeRequest("DELETE", `/v1/documents/${memoryId}`);
+      return true;
+    } catch (error) {
+      if (error instanceof Error) {
+        throw error;
+      }
+      throw new NebulaClientException(`Unknown error: ${String(error)}`);
+    }
+  }
+  /** Delete a conversation and all its messages */
+  async deleteConversation(conversationId) {
+    try {
+      await this._makeRequest("DELETE", `/v1/conversations/${conversationId}`);
       return true;
     } catch (error) {
       if (error instanceof Error) {
@@ -391,7 +487,7 @@ var NebulaSDK = class {
       throw new NebulaClientException("cluster_ids must be provided to list_memories().");
     }
     const params = { limit, offset, collection_ids: ids };
-    const response = await this._makeRequest("GET", "/v3/documents", void 0, params);
+    const response = await this._makeRequest("GET", "/v1/documents", void 0, params);
     let documents;
     if (response.results) {
       documents = response.results;
@@ -404,7 +500,7 @@ var NebulaSDK = class {
   }
   /** Get a specific memory by ID */
   async getMemory(memoryId) {
-    const response = await this._makeRequest("GET", `/v3/documents/${memoryId}`);
+    const response = await this._makeRequest("GET", `/v1/documents/${memoryId}`);
     const content = response.text || response.content;
     const chunks = Array.isArray(response.chunks) ? response.chunks : void 0;
     const memoryData = {
@@ -462,7 +558,7 @@ var NebulaSDK = class {
       search_mode: "custom",
       search_settings: effectiveSettings
     };
-    const response = await this._makeRequest("POST", "/v3/retrieval/search", data);
+    const response = await this._makeRequest("POST", "/v1/retrieval/search", data);
     let chunkResults = [];
     let graphResults = [];
     if (response.results) {
@@ -647,18 +743,14 @@ Assistant: ${String(assistantMessage || "")}`;
   }
 };
 
-// src/index.ts
-var index_default = NebulaSDK;
-
 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;
-exports.default = index_default;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map