@nebula-ai/sdk 0.0.24 → 0.0.29

package/dist/index.mjs

@@ -1,10 +1,4 @@
 // src/types.ts
-var RetrievalType = /* @__PURE__ */ ((RetrievalType2) => {
-  RetrievalType2["BASIC"] = "basic";
-  RetrievalType2["ADVANCED"] = "advanced";
-  RetrievalType2["CUSTOM"] = "custom";
-  return RetrievalType2;
-})(RetrievalType || {});
 var GraphSearchResultType = /* @__PURE__ */ ((GraphSearchResultType2) => {
   GraphSearchResultType2["ENTITY"] = "entity";
   GraphSearchResultType2["RELATIONSHIP"] = "relationship";
@@ -45,10 +39,16 @@ var NebulaValidationException = class extends NebulaException {
     this.name = "NebulaValidationException";
   }
 };
-var NebulaClusterNotFoundException = class extends NebulaException {
-  constructor(message = "Cluster not found") {
+var NebulaCollectionNotFoundException = class extends NebulaException {
+  constructor(message = "Collection not found") {
     super(message, 404);
-    this.name = "NebulaClusterNotFoundException";
+    this.name = "NebulaCollectionNotFoundException";
+  }
+};
+var NebulaNotFoundException = class extends NebulaException {
+  constructor(resourceId, resourceType = "Resource") {
+    super(`${resourceType} not found: ${resourceId}`, 404);
+    this.name = "NebulaNotFoundException";
   }
 };
 
@@ -141,6 +141,17 @@ var NebulaClient = class {
       } else if (response.status === 400) {
         const errorData = await response.json().catch(() => ({}));
         throw new NebulaValidationException(errorData.message || "Validation error", errorData.details);
+      } else if (response.status === 422) {
+        const errorData = await response.json().catch(() => ({}));
+        console.error("[SDK] 422 Validation error - Full details:");
+        console.error("  Status:", response.status);
+        console.error("  Error data:", JSON.stringify(errorData, null, 2));
+        console.error("  Message:", errorData.message);
+        console.error("  Detail:", errorData.detail);
+        throw new NebulaValidationException(
+          errorData.message || (typeof errorData.detail === "string" ? errorData.detail : JSON.stringify(errorData.detail)) || "Validation error",
+          errorData
+        );
       } else {
         const errorData = await response.json().catch(() => ({}));
         throw new NebulaException(errorData.message || `API error: ${response.status}`, response.status, errorData);
@@ -159,48 +170,85 @@ var NebulaClient = class {
       throw new NebulaClientException(`Request failed: ${String(error)}`);
     }
   }
-  // Cluster Management Methods
-  /** Create a new cluster */
-  async createCluster(name, description, metadata) {
-    const data = { name };
-    if (description) data.description = description;
-    if (metadata) data.metadata = metadata;
+  // Collection Management Methods
+  /** Create a new collection */
+  async createCollection(options) {
+    const data = { name: options.name };
+    if (options.description) data.description = options.description;
+    if (options.metadata) data.metadata = options.metadata;
     const response = await this._makeRequest("POST", "/v1/collections", data);
     const result = response.results || response;
-    return this._clusterFromDict(result);
+    return this._collectionFromDict(result);
   }
-  /** Get a specific cluster by ID */
-  async getCluster(clusterId) {
-    const response = await this._makeRequest("GET", `/v1/collections/${clusterId}`);
+  /** Get a specific collection by ID */
+  async getCollection(collectionId) {
+    const response = await this._makeRequest("GET", `/v1/collections/${collectionId}`);
     const result = response.results || response;
-    return this._clusterFromDict(result);
+    return this._collectionFromDict(result);
   }
-  /** Get a specific cluster by name */
-  async getClusterByName(name) {
+  /** Get a specific collection by name */
+  async getCollectionByName(name) {
     const response = await this._makeRequest("GET", `/v1/collections/name/${name}`);
     const result = response.results || response;
-    return this._clusterFromDict(result);
+    return this._collectionFromDict(result);
   }
-  /** Get all clusters */
-  async listClusters(limit = 100, offset = 0) {
-    const params = { limit, offset };
+  /** Get all collections */
+  async listCollections(options) {
+    const params = {
+      limit: options?.limit ?? 100,
+      offset: options?.offset ?? 0
+    };
     const response = await this._makeRequest("GET", "/v1/collections", void 0, params);
-    let clusters;
+    let collections;
     if (response.results) {
-      clusters = response.results;
+      collections = response.results;
     } else if (Array.isArray(response)) {
-      clusters = response;
+      collections = response;
     } else {
-      clusters = [response];
+      collections = [response];
     }
-    return clusters.map((cluster) => this._clusterFromDict(cluster));
+    return collections.map((collection) => this._collectionFromDict(collection));
   }
   // Conversations Methods
-  /** List conversations for the authenticated user */
-  async listConversations(limit = 100, offset = 0, cluster_ids) {
-    const params = { limit, offset };
-    if (cluster_ids && cluster_ids.length > 0) {
-      params.collection_ids = cluster_ids;
+  /**
+   * List conversations for the authenticated user with optional metadata filtering
+   *
+   * @param options - Configuration for listing conversations
+   * @param options.limit - Maximum number of conversations to return (default: 100)
+   * @param options.offset - Number of conversations to skip for pagination (default: 0)
+   * @param options.collection_ids - Optional list of collection IDs to filter conversations by
+   * @param options.metadata_filters - Optional metadata filters using MongoDB-like operators.
+   *   Supported operators: $eq, $ne, $in, $nin, $exists, $and, $or
+   *
+   * @returns Promise resolving to array of conversation objects with fields: id, created_at, user_id, name, collection_ids
+   *
+   * @example
+   * // Get all playground conversations
+   * const conversations = await client.listConversations({
+   *   collection_ids: ['collection-id'],
+   *   metadata_filters: {
+   *     'metadata.playground': { $eq: true }
+   *   }
+   * });
+   *
+   * @example
+   * // Filter by session ID
+   * const conversations = await client.listConversations({
+   *   metadata_filters: {
+   *     'metadata.session_id': { $eq: 'session-123' }
+   *   }
+   * });
+   */
+  async listConversations(options) {
+    const params = {
+      limit: options?.limit ?? 100,
+      offset: options?.offset ?? 0
+    };
+    if (options?.collection_ids && options.collection_ids.length > 0) {
+      params.collection_ids = options.collection_ids;
+    }
+    if (options?.metadata_filters) {
+      params.metadata_filters = JSON.stringify(options.metadata_filters);
     }
     const response = await this._makeRequest("GET", "/v1/conversations", void 0, params);
     let conversations;
@@ -281,30 +329,30 @@ var NebulaClient = class {
         content: text,
         metadata: combinedMetadata,
         created_at: msgResp.created_at,
-        cluster_ids: msgResp.collection_ids || []
+        collection_ids: msgResp.collection_ids || []
       };
     });
   }
-  /** Update a cluster */
-  async updateCluster(clusterId, name, description, metadata) {
+  /** Update a collection */
+  async updateCollection(options) {
     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", `/v1/collections/${clusterId}`, data);
+    if (options.name !== void 0) data.name = options.name;
+    if (options.description !== void 0) data.description = options.description;
+    if (options.metadata !== void 0) data.metadata = options.metadata;
+    const response = await this._makeRequest("POST", `/v1/collections/${options.collectionId}`, data);
     const result = response.results || response;
-    return this._clusterFromDict(result);
+    return this._collectionFromDict(result);
   }
-  /** Delete a cluster */
-  async deleteCluster(clusterId) {
-    await this._makeRequest("DELETE", `/v1/collections/${clusterId}`);
+  /** Delete a collection */
+  async deleteCollection(collectionId) {
+    await this._makeRequest("DELETE", `/v1/collections/${collectionId}`);
     return true;
   }
   // Memory Management Methods
   /**
-   * Legacy convenience: store raw text content into a cluster as a document
+   * Legacy convenience: store raw text content into a collection as a document
    */
-  async store(content, clusterId, metadata = {}) {
+  async store(content, collectionId, metadata = {}) {
     const docMetadata = {
       ...metadata,
       memory_type: "memory",
@@ -313,10 +361,10 @@ var NebulaClient = class {
     const data = {
       metadata: JSON.stringify(docMetadata),
       ingestion_mode: "fast",
-      collection_ids: JSON.stringify([clusterId]),
+      collection_ids: JSON.stringify([collectionId]),
       raw_text: String(content || "")
     };
-    const url = `${this.baseUrl}/v1/documents`;
+    const url = `${this.baseUrl}/v1/memories`;
     const headers = this._buildAuthHeaders(false);
     const response = await fetch(url, {
       method: "POST",
@@ -326,72 +374,117 @@ var NebulaClient = class {
     if (!response.ok) {
       const errorData = await response.json().catch(() => ({}));
       throw new NebulaException(
-        errorData.message || `Failed to create document: ${response.status}`,
+        errorData.message || `Failed to create engram: ${response.status}`,
         response.status,
         errorData
       );
     }
     const respData = await response.json();
-    const id = respData?.results?.document_id || respData?.results?.id || respData?.id || "";
+    const id = respData?.results?.engram_id || respData?.results?.id || respData?.id || "";
     const result = {
       id: String(id),
       content: String(content || ""),
       metadata: docMetadata,
-      cluster_ids: [clusterId],
+      collection_ids: [collectionId],
       created_at: docMetadata.timestamp,
       updated_at: docMetadata.timestamp
     };
     return result;
   }
-  /** Store a single memory */
-  async storeMemory(memory) {
+  /**
+   * Store a single memory using the unified engrams API.
+   *
+   * Automatically infers memory type:
+   * - If role is present, creates a conversation
+   * - Otherwise, creates a document
+   */
+  async storeMemory(memory, name) {
     let mem;
-    if ("cluster_id" in memory) {
+    if ("collection_id" in memory) {
       mem = memory;
     } else {
       mem = {
-        cluster_id: memory.cluster_id,
-        content: memory.content,
+        collection_id: memory.collection_id,
+        content: memory.content || "",
         role: memory.role,
-        parent_id: memory.parent_id,
+        memory_id: memory.memory_id,
         metadata: memory.metadata || {}
       };
     }
-    if (mem.role) {
-      let convId = mem.parent_id;
-      if (!convId) {
-        const created = await this._makeRequest("POST", "/v1/conversations", {});
-        const conv = created.results || created;
-        convId = conv.id;
+    if (mem.memory_id) {
+      return await this._appendToMemory(mem.memory_id, mem);
+    }
+    const memoryType = mem.role ? "conversation" : "document";
+    if (memoryType === "conversation") {
+      const docMetadata2 = { ...mem.metadata };
+      const data2 = {
+        engram_type: "conversation",
+        name: name || "Conversation",
+        metadata: JSON.stringify(docMetadata2),
+        collection_ids: JSON.stringify([mem.collection_id])
+      };
+      const url2 = `${this.baseUrl}/v1/memories`;
+      const headers2 = this._buildAuthHeaders(false);
+      const response2 = await fetch(url2, {
+        method: "POST",
+        headers: headers2,
+        body: this._formDataFromObject(data2)
+      });
+      if (!response2.ok) {
+        const errorData = await response2.json().catch(() => ({}));
+        throw new NebulaException(
+          errorData.message || `Failed to create conversation: ${response2.status}`,
+          response2.status,
+          errorData
+        );
+      }
+      const respData2 = await response2.json();
+      if (respData2.results) {
+        const convId = respData2.results.engram_id || respData2.results.id;
         if (!convId) {
           throw new NebulaClientException("Failed to create conversation: no id returned");
         }
+        if (mem.content && mem.role) {
+          const appendMem = {
+            collection_id: mem.collection_id,
+            content: [
+              {
+                content: String(mem.content),
+                role: mem.role,
+                metadata: mem.metadata,
+                ...typeof mem.authority === "number" ? { authority: Number(mem.authority) } : {}
+              }
+            ],
+            memory_id: convId,
+            metadata: {}
+          };
+          await this._appendToMemory(convId, appendMem);
+        }
+        return String(convId);
       }
-      const payload = {
-        messages: [
-          {
-            content: String(mem.content),
-            role: mem.role,
-            metadata: mem.metadata
-          }
-        ],
-        collection_id: mem.cluster_id
-      };
-      await this._makeRequest("POST", `/v1/conversations/${convId}/messages`, payload);
-      return String(convId);
+      throw new NebulaClientException("Failed to create conversation: invalid response format");
     }
     const contentText = String(mem.content || "");
+    if (!contentText) {
+      throw new NebulaClientException("Content is required for document memories");
+    }
     const contentHash = await this._sha256(contentText);
     const docMetadata = { ...mem.metadata };
     docMetadata.memory_type = "memory";
     docMetadata.content_hash = contentHash;
+    if (typeof mem.authority === "number") {
+      const v = Number(mem.authority);
+      if (!Number.isNaN(v) && v >= 0 && v <= 1) {
+        docMetadata.authority = v;
+      }
+    }
     const data = {
       metadata: JSON.stringify(docMetadata),
       ingestion_mode: "fast",
-      collection_ids: JSON.stringify([mem.cluster_id]),
+      collection_ids: JSON.stringify([mem.collection_id]),
       raw_text: contentText
     };
-    const url = `${this.baseUrl}/v1/documents`;
+    const url = `${this.baseUrl}/v1/memories`;
     const headers = this._buildAuthHeaders(false);
     const response = await fetch(url, {
       method: "POST",
@@ -401,26 +494,67 @@ var NebulaClient = class {
     if (!response.ok) {
       const errorData = await response.json().catch(() => ({}));
       throw new NebulaException(
-        errorData.message || `Failed to create document: ${response.status}`,
+        errorData.message || `Failed to create engram: ${response.status}`,
         response.status,
         errorData
       );
     }
     const respData = await response.json();
     if (respData.results) {
-      if (respData.results.document_id) return String(respData.results.document_id);
+      if (respData.results.engram_id) return String(respData.results.engram_id);
       if (respData.results.id) return String(respData.results.id);
     }
     return "";
   }
-  /** Store multiple memories */
+  /**
+   * Internal method to append content to an existing engram
+   *
+   * @throws NebulaNotFoundException if engram_id doesn't exist
+   */
+  async _appendToMemory(memoryId, memory) {
+    const collectionId = memory.collection_id;
+    const content = memory.content;
+    const metadata = memory.metadata;
+    if (!collectionId) {
+      throw new NebulaClientException("collection_id is required");
+    }
+    const payload = {
+      collection_id: collectionId
+    };
+    if (Array.isArray(content)) {
+      if (content.length > 0 && typeof content[0] === "object" && "content" in content[0]) {
+        payload.messages = content;
+      } else {
+        payload.chunks = content;
+      }
+    } else if (typeof content === "string") {
+      payload.raw_text = content;
+    } else {
+      throw new NebulaClientException(
+        "content must be a string, array of strings, or array of message objects"
+      );
+    }
+    if (metadata) {
+      payload.metadata = metadata;
+    }
+    try {
+      await this._makeRequest("POST", `/v1/memories/${memoryId}/append`, payload);
+      return memoryId;
+    } catch (error) {
+      if (error instanceof NebulaException && error.statusCode === 404) {
+        throw new NebulaNotFoundException(memoryId, "Memory");
+      }
+      throw error;
+    }
+  }
+  /** Store multiple memories using the unified engrams API */
   async storeMemories(memories) {
     const results = [];
     const convGroups = {};
     const others = [];
     for (const m of memories) {
       if (m.role) {
-        const key = m.parent_id || `__new__::${m.cluster_id}`;
+        const key = m.memory_id || `__new__::${m.collection_id}`;
         if (!convGroups[key]) convGroups[key] = [];
         convGroups[key].push(m);
       } else {
@@ -428,15 +562,19 @@ var NebulaClient = class {
       }
     }
     for (const [key, group] of Object.entries(convGroups)) {
-      const clusterId = group[0].cluster_id;
+      const collectionId = group[0].collection_id;
       let convId;
       if (key.startsWith("__new__::")) {
-        const created = await this._makeRequest("POST", "/v1/conversations", {});
-        const conv = created.results || created;
-        convId = conv.id;
-        if (!convId) {
-          throw new NebulaClientException("Failed to create conversation: no id returned");
-        }
+        convId = await this.storeMemory(
+          {
+            collection_id: collectionId,
+            content: "",
+            role: "assistant",
+            // Placeholder role to infer conversation type
+            metadata: {}
+          },
+          "Conversation"
+        );
       } else {
         convId = key;
       }
@@ -445,8 +583,13 @@ var NebulaClient = class {
         role: m.role,
         metadata: m.metadata || {}
       }));
-      const payload = { messages, collection_id: clusterId };
-      await this._makeRequest("POST", `/v1/conversations/${convId}/messages`, payload);
+      const appendMem = {
+        collection_id: collectionId,
+        content: messages,
+        memory_id: convId,
+        metadata: {}
+      };
+      await this._appendToMemory(convId, appendMem);
       results.push(...Array(group.length).fill(String(convId)));
     }
     for (const m of others) {
@@ -454,18 +597,116 @@ var NebulaClient = class {
     }
     return results;
   }
-  /** Delete a specific memory */
-  async delete(memoryId) {
+  /** Delete one or more memories */
+  async delete(memoryIds) {
     try {
-      await this._makeRequest("DELETE", `/v1/documents/${memoryId}`);
-      return true;
+      console.log("[SDK] delete() called with:", { memoryIds, type: typeof memoryIds, isArray: Array.isArray(memoryIds) });
+      if (typeof memoryIds === "string") {
+        console.log("[SDK] Single deletion path for ID:", memoryIds);
+        try {
+          await this._makeRequest("DELETE", `/v1/memories/${memoryIds}`);
+          return true;
+        } catch {
+          try {
+            console.log("[SDK] Falling back to POST /v1/memories/delete with single ID");
+            const response = await this._makeRequest("POST", "/v1/memories/delete", memoryIds);
+            return typeof response === "object" && response.success !== void 0 ? response.success : true;
+          } catch (error) {
+            throw error;
+          }
+        }
+      } else {
+        console.log("[SDK] Batch deletion path for IDs:", memoryIds);
+        console.log("[SDK] Sending POST request with body:", memoryIds);
+        const response = await this._makeRequest("POST", "/v1/memories/delete", memoryIds);
+        console.log("[SDK] Batch deletion response:", response);
+        return response;
+      }
     } catch (error) {
+      console.error("[SDK] Delete error:", error);
       if (error instanceof Error) {
         throw error;
       }
       throw new NebulaClientException(`Unknown error: ${String(error)}`);
     }
   }
+  /** Delete a specific chunk or message within a memory */
+  async deleteChunk(chunkId) {
+    try {
+      await this._makeRequest("DELETE", `/v1/chunks/${chunkId}`);
+      return true;
+    } catch (error) {
+      if (error instanceof NebulaException && error.statusCode === 404) {
+        throw new NebulaNotFoundException(chunkId, "Chunk");
+      }
+      throw error;
+    }
+  }
+  /** Update a specific chunk or message within a memory */
+  async updateChunk(chunkId, content, metadata) {
+    const payload = { content };
+    if (metadata !== void 0) {
+      payload.metadata = metadata;
+    }
+    try {
+      await this._makeRequest("PATCH", `/v1/chunks/${chunkId}`, payload);
+      return true;
+    } catch (error) {
+      if (error instanceof NebulaException && error.statusCode === 404) {
+        throw new NebulaNotFoundException(chunkId, "Chunk");
+      }
+      throw error;
+    }
+  }
+  /**
+   * Update memory-level properties including name, metadata, and collection associations.
+   *
+   * This method allows updating properties of an entire memory (document or conversation)
+   * without modifying its content. For updating individual chunks or messages within a memory,
+   * use updateChunk(). For updating content, use storeMemory() to append.
+   *
+   * @param options - Update configuration
+   * @param options.memoryId - The ID of the memory to update
+   * @param options.name - New name for the memory (useful for conversations and documents)
+   * @param options.metadata - Metadata to set. By default, replaces existing metadata.
+   *                           Set mergeMetadata=true to merge with existing metadata instead.
+   * @param options.collectionIds - New collection associations. Must specify at least one valid collection.
+   * @param options.mergeMetadata - If true, merges provided metadata with existing metadata.
+   *                                If false (default), replaces existing metadata entirely.
+   *
+   * @returns Promise resolving to true if successful
+   *
+   * @throws NebulaNotFoundException if memory_id doesn't exist
+   * @throws NebulaValidationException if validation fails (e.g., no fields provided)
+   * @throws NebulaAuthenticationException if user doesn't have permission to update this memory
+   */
+  async updateMemory(options) {
+    const payload = {};
+    if (options.name !== void 0) {
+      payload.name = options.name;
+    }
+    if (options.metadata !== void 0) {
+      payload.metadata = options.metadata;
+      payload.merge_metadata = options.mergeMetadata ?? false;
+    }
+    if (options.collectionIds !== void 0) {
+      payload.collection_ids = options.collectionIds;
+    }
+    if (Object.keys(payload).length === 0) {
+      throw new NebulaValidationException(
+        "At least one field (name, metadata, or collectionIds) must be provided to update"
+      );
+    }
+    try {
+      await this._makeRequest("PATCH", `/v1/memories/${options.memoryId}`, payload);
+      return true;
+    } catch (error) {
+      if (error instanceof NebulaException && error.statusCode === 404) {
+        throw new NebulaNotFoundException(options.memoryId, "Memory");
+      }
+      throw error;
+    }
+  }
   /** Delete a conversation and all its messages */
   async deleteConversation(conversationId) {
     try {
@@ -478,14 +719,53 @@ var NebulaClient = class {
       throw new NebulaClientException(`Unknown error: ${String(error)}`);
     }
   }
-  /** Get all memories from specific clusters */
-  async listMemories(clusterIds, limit = 100, offset = 0) {
-    const ids = Array.isArray(clusterIds) ? clusterIds : [clusterIds];
+  /**
+   * Get all memories from specific collections with optional metadata filtering
+   *
+   * @param options - Configuration for listing memories
+   * @param options.collection_ids - One or more collection IDs to retrieve memories from
+   * @param options.limit - Maximum number of memories to return (default: 100)
+   * @param options.offset - Number of memories to skip for pagination (default: 0)
+   * @param options.metadata_filters - Optional metadata filters using MongoDB-like operators.
+   *   Supported operators: $eq, $ne, $in, $nin, $exists, $and, $or
+   *
+   * @returns Promise resolving to array of MemoryResponse objects
+   *
+   * @example
+   * // Get all playground memories excluding conversations
+   * const memories = await client.listMemories({
+   *   collection_ids: ['collection-id'],
+   *   metadata_filters: {
+   *     'metadata.content_type': { $ne: 'conversation' }
+   *   }
+   * });
+   *
+   * @example
+   * // Complex filter with multiple conditions
+   * const memories = await client.listMemories({
+   *   collection_ids: ['collection-id'],
+   *   metadata_filters: {
+   *     $and: [
+   *       { 'metadata.playground': { $eq: true } },
+   *       { 'metadata.session_id': { $exists: true } }
+   *     ]
+   *   }
+   * });
+   */
+  async listMemories(options) {
+    const ids = Array.isArray(options.collection_ids) ? options.collection_ids : [options.collection_ids];
     if (!ids.length) {
-      throw new NebulaClientException("cluster_ids must be provided to list_memories().");
+      throw new NebulaClientException("collection_ids must be provided to list_memories().");
+    }
+    const params = {
+      limit: options.limit ?? 100,
+      offset: options.offset ?? 0,
+      collection_ids: ids
+    };
+    if (options.metadata_filters) {
+      params.metadata_filters = JSON.stringify(options.metadata_filters);
     }
-    const params = { limit, offset, collection_ids: ids };
-    const response = await this._makeRequest("GET", "/v1/documents", void 0, params);
+    const response = await this._makeRequest("GET", "/v1/memories", void 0, params);
     let documents;
     if (response.results) {
       documents = response.results;
@@ -496,9 +776,9 @@ var NebulaClient = class {
     }
     return documents.map((doc) => this._memoryResponseFromDict(doc, ids));
   }
-  /** Get a specific memory by ID */
+  /** Get a specific memory by engram ID */
   async getMemory(memoryId) {
-    const response = await this._makeRequest("GET", `/v1/documents/${memoryId}`);
+    const response = await this._makeRequest("GET", `/v1/memories/${memoryId}`);
     const content = response.text || response.content;
     const chunks = Array.isArray(response.chunks) ? response.chunks : void 0;
     const memoryData = {
@@ -511,32 +791,123 @@ var NebulaClient = class {
     return this._memoryResponseFromDict(memoryData, []);
   }
   // Search Methods
-  /** Search within specific clusters */
-  async search(query, clusters, limitOrOptions, retrievalType = "advanced" /* ADVANCED */, filters, searchSettings) {
-    const clusterIds = Array.isArray(clusters) ? clusters : [clusters];
-    if (!clusterIds.length) {
-      throw new NebulaClientException("cluster_ids must be provided to search().");
-    }
-    let limit = 10;
-    if (typeof limitOrOptions === "number") {
-      limit = limitOrOptions;
-    } else if (typeof limitOrOptions === "object" && limitOrOptions) {
-      if (typeof limitOrOptions.limit === "number") limit = limitOrOptions.limit;
-    }
-    if (typeof retrievalType === "string") {
-      retrievalType = RetrievalType[retrievalType.toUpperCase()] || "advanced" /* ADVANCED */;
-    }
-    const effectiveSettings = { ...searchSettings };
+  /**
+   * Search within specific collections with optional metadata filtering.
+   *
+   * @param options - Search configuration
+   * @param options.query - Search query string
+   * @param options.collection_ids - One or more collection 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",
+   *   collection_ids: ["research-collection"],
+   *   filters: {
+   *     "metadata.category": { $eq: "research" },
+   *     "metadata.verified": true  // Shorthand for $eq
+   *   }
+   * });
+   *
+   * @example
+   * // Numeric comparisons
+   * await client.search({
+   *   query: "high priority",
+   *   collection_ids: ["tasks"],
+   *   filters: {
+   *     "metadata.priority": { $gte: 8 },
+   *     "metadata.score": { $lt: 100 }
+   *   }
+   * });
+   *
+   * @example
+   * // String matching
+   * await client.search({
+   *   query: "employees",
+   *   collection_ids: ["team"],
+   *   filters: {
+   *     "metadata.email": { $ilike: "%@company.com" }  // Case-insensitive
+   *   }
+   * });
+   *
+   * @example
+   * // Array operations
+   * await client.search({
+   *   query: "developers",
+   *   collection_ids: ["team"],
+   *   filters: {
+   *     "metadata.skills": { $overlap: ["python", "typescript"] }  // Has any
+   *   }
+   * });
+   *
+   * @example
+   * // Nested paths
+   * await client.search({
+   *   query: "users",
+   *   collection_ids: ["profiles"],
+   *   filters: {
+   *     "metadata.user.preferences.theme": { $eq: "dark" }
+   *   }
+   * });
+   *
+   * @example
+   * // Complex logical combinations
+   * await client.search({
+   *   query: "candidates",
+   *   collection_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
+   */
+  async search(options) {
+    const collectionIds = Array.isArray(options.collection_ids) ? options.collection_ids : [options.collection_ids];
+    const validCollectionIds = collectionIds.filter((id) => id && id.trim() !== "");
+    if (!validCollectionIds.length) {
+      throw new NebulaClientException("collection_ids must be provided to search().");
+    }
+    const limit = options.limit ?? 10;
+    const searchMode = options.search_mode ?? "super";
+    const effectiveSettings = {
+      ...options.searchSettings
+    };
     effectiveSettings.limit = limit;
     const userFilters = { ...effectiveSettings.filters };
-    if (filters) {
-      Object.assign(userFilters, filters);
+    if (options.filters) {
+      Object.assign(userFilters, options.filters);
     }
-    userFilters.collection_ids = { $overlap: clusterIds };
+    userFilters.collection_ids = { $overlap: validCollectionIds };
     effectiveSettings.filters = userFilters;
     const data = {
-      query,
-      search_mode: "custom",
+      query: options.query,
+      search_mode: searchMode,
       search_settings: effectiveSettings
     };
     const response = await this._makeRequest("POST", "/v1/retrieval/search", data);
@@ -556,28 +927,33 @@ var NebulaClient = class {
   /**
    * Legacy wrapper: store a two-message conversation turn as a document
    */
-  async storeConversation(userMessage, assistantMessage, clusterId, sessionId) {
+  async storeConversation(userMessage, assistantMessage, collectionId, sessionId) {
     const content = `User: ${String(userMessage || "")}
 Assistant: ${String(assistantMessage || "")}`;
     const metadata = { session_id: sessionId, content_type: "conversation" };
-    return this.store(content, clusterId, metadata);
+    return this.store(content, collectionId, metadata);
   }
   /**
    * Legacy wrapper: search conversations optionally scoped by session
    */
-  async searchConversations(query, clusterId, sessionId, includeAllSessions = true) {
+  async searchConversations(query, collectionId, sessionId, includeAllSessions = true) {
     const filters = { "metadata.content_type": "conversation" };
     if (sessionId && !includeAllSessions) {
       filters["metadata.session_id"] = sessionId;
     }
-    return this.search(query, [clusterId], { limit: 10 }, "advanced" /* ADVANCED */, filters);
+    return this.search({
+      query,
+      collection_ids: [collectionId],
+      limit: 10,
+      filters
+    });
   }
   // Health Check
   async healthCheck() {
     return this._makeRequest("GET", "/health");
   }
   // Helpers
-  _clusterFromDict(data) {
+  _collectionFromDict(data) {
     let createdAt;
     if (data.created_at) {
       createdAt = typeof data.created_at === "string" ? data.created_at : data.created_at.toISOString();
@@ -586,29 +962,29 @@ Assistant: ${String(assistantMessage || "")}`;
     if (data.updated_at) {
       updatedAt = typeof data.updated_at === "string" ? data.updated_at : data.updated_at.toISOString();
     }
-    const clusterId = String(data.id || "");
-    const clusterName = data.name || "";
-    const clusterDescription = data.description;
-    const clusterOwnerId = data.owner_id ? String(data.owner_id) : void 0;
+    const collectionId = String(data.id || "");
+    const collectionName = data.name || "";
+    const collectionDescription = data.description;
+    const collectionOwnerId = data.owner_id ? String(data.owner_id) : void 0;
     const memoryCount = data.document_count || 0;
     const metadata = {
-      graph_cluster_status: data.graph_cluster_status || "",
+      graph_collection_status: data.graph_collection_status || "",
       graph_sync_status: data.graph_sync_status || "",
       user_count: data.user_count || 0,
       document_count: data.document_count || 0
     };
     return {
-      id: clusterId,
-      name: clusterName,
-      description: clusterDescription,
+      id: collectionId,
+      name: collectionName,
+      description: collectionDescription,
       metadata,
       created_at: createdAt,
       updated_at: updatedAt,
       memory_count: memoryCount,
-      owner_id: clusterOwnerId
+      owner_id: collectionOwnerId
     };
   }
-  _memoryResponseFromDict(data, clusterIds) {
+  _memoryResponseFromDict(data, collectionIds) {
     let createdAt;
     if (data.created_at) {
       createdAt = typeof data.created_at === "string" ? data.created_at : data.created_at.toISOString();
@@ -617,7 +993,7 @@ Assistant: ${String(assistantMessage || "")}`;
     if (data.updated_at) {
       updatedAt = typeof data.updated_at === "string" ? data.updated_at : data.updated_at.toISOString();
     }
-    const memoryId = String(data.id || "");
+    const engramId = String(data.id || "");
     const content = data.content || data.text;
     let chunks;
     if (data.chunks && Array.isArray(data.chunks)) {
@@ -628,12 +1004,12 @@ Assistant: ${String(assistantMessage || "")}`;
       }
     }
     const metadata = { ...data.metadata };
-    if (data.document_id) {
-      metadata.document_id = data.document_id;
+    if (data.engram_id) {
+      metadata.engram_id = data.engram_id;
     }
-    let finalId = memoryId;
-    if (data.document_id && !memoryId) {
-      finalId = data.document_id;
+    let finalId = engramId;
+    if (data.engram_id && !engramId) {
+      finalId = data.engram_id;
     }
     if (data.document_metadata) {
       Object.assign(metadata, data.document_metadata);
@@ -643,7 +1019,7 @@ Assistant: ${String(assistantMessage || "")}`;
       content,
       chunks,
       metadata,
-      cluster_ids: data.collection_ids || clusterIds,
+      collection_ids: data.collection_ids || collectionIds,
       created_at: createdAt,
       updated_at: updatedAt
     };
@@ -666,6 +1042,23 @@ Assistant: ${String(assistantMessage || "")}`;
     const score = data.score !== void 0 ? Number(data.score) : 0;
     const metadata = data.metadata || {};
     const chunkIds = Array.isArray(data.chunk_ids) ? data.chunk_ids : void 0;
+    let timestamp;
+    if (data.timestamp) {
+      if (typeof data.timestamp === "string") {
+        timestamp = data.timestamp;
+      } else if (data.timestamp instanceof Date) {
+        timestamp = data.timestamp.toISOString();
+      } else {
+        const parsed = new Date(data.timestamp);
+        if (!Number.isNaN(parsed.valueOf())) {
+          timestamp = parsed.toISOString();
+        }
+      }
+    }
+    const displayName = typeof data.display_name === "string" ? data.display_name : void 0;
+    const sourceRole = typeof data.source_role === "string" ? data.source_role : void 0;
+    const engramId = data.engram_id ? String(data.engram_id) : void 0;
+    const ownerId = data.owner_id ? String(data.owner_id) : void 0;
     let entity;
     let rel;
     let comm;
@@ -705,7 +1098,12 @@ Assistant: ${String(assistantMessage || "")}`;
       graph_entity: entity,
       graph_relationship: rel,
       graph_community: comm,
-      chunk_ids: chunkIds
+      chunk_ids: chunkIds,
+      timestamp,
+      display_name: displayName,
+      source_role: sourceRole,
+      engram_id: engramId,
+      owner_id: ownerId
     };
   }
   async _sha256(message) {
@@ -724,6 +1122,6 @@ Assistant: ${String(assistantMessage || "")}`;
   }
 };
 
-export { GraphSearchResultType, NebulaAuthenticationException, NebulaClient, NebulaClientException, NebulaClusterNotFoundException, NebulaException, NebulaRateLimitException, NebulaValidationException, RetrievalType };
+export { GraphSearchResultType, NebulaAuthenticationException, NebulaClient, NebulaClientException, NebulaCollectionNotFoundException, NebulaException, NebulaNotFoundException, NebulaRateLimitException, NebulaValidationException };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map