@nebula-ai/sdk 0.0.21 → 0.0.27

package/dist/index.js

@@ -1,12 +1,6 @@
 'use strict';
 
 // 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";
@@ -163,10 +157,10 @@ var NebulaClient = class {
   }
   // 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;
+  async createCluster(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);
@@ -184,8 +178,11 @@ var NebulaClient = class {
     return this._clusterFromDict(result);
   }
   /** Get all clusters */
-  async listClusters(limit = 100, offset = 0) {
-    const params = { limit, offset };
+  async listClusters(options) {
+    const params = {
+      limit: options?.limit ?? 100,
+      offset: options?.offset ?? 0
+    };
     const response = await this._makeRequest("GET", "/v1/collections", void 0, params);
     let clusters;
     if (response.results) {
@@ -199,10 +196,13 @@ var NebulaClient = class {
   }
   // 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;
+  async listConversations(options) {
+    const params = {
+      limit: options?.limit ?? 100,
+      offset: options?.offset ?? 0
+    };
+    if (options?.cluster_ids && options.cluster_ids.length > 0) {
+      params.collection_ids = options.cluster_ids;
     }
     const response = await this._makeRequest("GET", "/v1/conversations", void 0, params);
     let conversations;
@@ -288,12 +288,12 @@ var NebulaClient = class {
     });
   }
   /** Update a cluster */
-  async updateCluster(clusterId, name, description, metadata) {
+  async updateCluster(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.clusterId}`, data);
     const result = response.results || response;
     return this._clusterFromDict(result);
   }
@@ -456,11 +456,29 @@ 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;
+      if (typeof memoryIds === "string") {
+        try {
+          await this._makeRequest("DELETE", `/v1/documents/${memoryIds}`);
+          return true;
+        } catch {
+          try {
+            const response = await this._makeRequest("POST", "/v1/documents/delete", {
+              ids: memoryIds
+            });
+            return typeof response === "object" && response.success !== void 0 ? response.success : true;
+          } catch (error) {
+            throw error;
+          }
+        }
+      } else {
+        const response = await this._makeRequest("POST", "/v1/documents/delete", {
+          ids: memoryIds
+        });
+        return response;
+      }
     } catch (error) {
       if (error instanceof Error) {
         throw error;
@@ -481,12 +499,16 @@ var NebulaClient = class {
     }
   }
   /** Get all memories from specific clusters */
-  async listMemories(clusterIds, limit = 100, offset = 0) {
-    const ids = Array.isArray(clusterIds) ? clusterIds : [clusterIds];
+  async listMemories(options) {
+    const ids = Array.isArray(options.cluster_ids) ? options.cluster_ids : [options.cluster_ids];
     if (!ids.length) {
       throw new NebulaClientException("cluster_ids must be provided to list_memories().");
     }
-    const params = { limit, offset, collection_ids: ids };
+    const params = {
+      limit: options.limit ?? 100,
+      offset: options.offset ?? 0,
+      collection_ids: ids
+    };
     const response = await this._makeRequest("GET", "/v1/documents", void 0, params);
     let documents;
     if (response.results) {
@@ -513,49 +535,122 @@ 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];
+  /**
+   * 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
+   */
+  async search(options) {
+    const clusterIds = Array.isArray(options.cluster_ids) ? options.cluster_ids : [options.cluster_ids];
     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 };
-    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
+    const limit = options.limit ?? 10;
+    const searchMode = options.search_mode ?? "super";
+    const effectiveSettings = {
+      ...options.searchSettings
     };
-    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;
-    }
+    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 };
     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);
@@ -589,7 +684,12 @@ Assistant: ${String(assistantMessage || "")}`;
     if (sessionId && !includeAllSessions) {
       filters["metadata.session_id"] = sessionId;
     }
-    return this.search(query, [clusterId], { limit: 10 }, "advanced" /* ADVANCED */, filters);
+    return this.search({
+      query,
+      cluster_ids: [clusterId],
+      limit: 10,
+      filters
+    });
   }
   // Health Check
   async healthCheck() {
@@ -685,6 +785,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 documentId = data.document_id ? String(data.document_id) : void 0;
+    const ownerId = data.owner_id ? String(data.owner_id) : void 0;
     let entity;
     let rel;
     let comm;
@@ -724,7 +841,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,
+      document_id: documentId,
+      owner_id: ownerId
     };
   }
   async _sha256(message) {
@@ -751,6 +873,5 @@ exports.NebulaClusterNotFoundException = NebulaClusterNotFoundException;
 exports.NebulaException = NebulaException;
 exports.NebulaRateLimitException = NebulaRateLimitException;
 exports.NebulaValidationException = NebulaValidationException;
-exports.RetrievalType = RetrievalType;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map