@nebula-ai/sdk 0.0.24 → 0.0.29

package/dist/index.d.ts

@@ -1,30 +1,37 @@
-declare enum RetrievalType {
-    BASIC = "basic",
-    ADVANCED = "advanced",
-    CUSTOM = "custom"
-}
 declare enum GraphSearchResultType {
     ENTITY = "entity",
     RELATIONSHIP = "relationship",
     COMMUNITY = "community"
 }
+interface Chunk {
+    id: string;
+    content: string;
+    metadata: Record<string, any>;
+    role?: string;
+}
 interface MemoryResponse {
     id: string;
     content?: string;
-    chunks?: string[];
+    chunks?: Chunk[];
     metadata: Record<string, any>;
-    cluster_ids: string[];
+    collection_ids: string[];
     created_at?: string;
     updated_at?: string;
 }
 interface Memory {
-    cluster_id: string;
-    content: string;
+    collection_id: string;
+    content: string | string[] | Array<{
+        content: string;
+        role: string;
+        metadata?: Record<string, any>;
+        authority?: number;
+    }>;
     role?: string;
-    parent_id?: string;
+    memory_id?: string;
     metadata: Record<string, any>;
+    authority?: number;
 }
-interface Cluster {
+interface Collection {
     id: string;
     name: string;
     description?: string;
@@ -39,6 +46,11 @@ interface SearchResult {
     score: number;
     metadata: Record<string, any>;
     source?: string;
+    timestamp?: string;
+    display_name?: string;
+    source_role?: string;
+    memory_id?: string;
+    owner_id?: string;
     content?: string;
     graph_result_type?: GraphSearchResultType;
     graph_entity?: GraphEntityResult;
@@ -78,7 +90,7 @@ interface AgentResponse {
 interface SearchOptions {
     limit: number;
     filters?: Record<string, any>;
-    retrieval_type: RetrievalType;
+    search_mode?: 'fast' | 'super';
 }
 interface NebulaClientConfig {
     apiKey: string;
@@ -104,9 +116,12 @@ declare class NebulaValidationException extends NebulaException {
     details?: any | undefined;
     constructor(message?: string, details?: any | undefined);
 }
-declare class NebulaClusterNotFoundException extends NebulaException {
+declare class NebulaCollectionNotFoundException extends NebulaException {
     constructor(message?: string);
 }
+declare class NebulaNotFoundException extends NebulaException {
+    constructor(resourceId: string, resourceType?: string);
+}
 
 /**
  * Official Nebula JavaScript/TypeScript SDK
@@ -128,55 +143,296 @@ declare class NebulaClient {
     private _buildAuthHeaders;
     /** Make an HTTP request to the Nebula API */
     private _makeRequest;
-    /** Create a new cluster */
-    createCluster(name: string, description?: string, metadata?: Record<string, any>): Promise<Cluster>;
-    /** Get a specific cluster by ID */
-    getCluster(clusterId: string): Promise<Cluster>;
-    /** Get a specific cluster by name */
-    getClusterByName(name: string): Promise<Cluster>;
-    /** Get all clusters */
-    listClusters(limit?: number, offset?: number): Promise<Cluster[]>;
-    /** List conversations for the authenticated user */
-    listConversations(limit?: number, offset?: number, cluster_ids?: string[]): Promise<any[]>;
+    /** Create a new collection */
+    createCollection(options: {
+        name: string;
+        description?: string;
+        metadata?: Record<string, any>;
+    }): Promise<Collection>;
+    /** Get a specific collection by ID */
+    getCollection(collectionId: string): Promise<Collection>;
+    /** Get a specific collection by name */
+    getCollectionByName(name: string): Promise<Collection>;
+    /** Get all collections */
+    listCollections(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<Collection[]>;
+    /**
+     * 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' }
+     *   }
+     * });
+     */
+    listConversations(options?: {
+        limit?: number;
+        offset?: number;
+        collection_ids?: string[];
+        metadata_filters?: Record<string, any>;
+    }): 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 */
-    deleteCluster(clusterId: string): Promise<boolean>;
+    /** Update a collection */
+    updateCollection(options: {
+        collectionId: string;
+        name?: string;
+        description?: string;
+        metadata?: Record<string, any>;
+    }): Promise<Collection>;
+    /** Delete a collection */
+    deleteCollection(collectionId: string): Promise<boolean>;
+    /**
+     * Legacy convenience: store raw text content into a collection as a document
+     */
+    store(content: string, collectionId: string, metadata?: Record<string, any>): Promise<MemoryResponse>;
     /**
-     * Legacy convenience: store raw text content into a cluster as a document
+     * Store a single memory using the unified engrams API.
+     *
+     * Automatically infers memory type:
+     * - If role is present, creates a conversation
+     * - Otherwise, creates 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 */
+    storeMemory(memory: Memory | Record<string, any>, name?: string): Promise<string>;
+    /**
+     * Internal method to append content to an existing engram
+     *
+     * @throws NebulaNotFoundException if engram_id doesn't exist
+     */
+    private _appendToMemory;
+    /** Store multiple memories using the unified engrams API */
     storeMemories(memories: Memory[]): Promise<string[]>;
-    /** Delete a specific memory */
-    delete(memoryId: string): Promise<boolean>;
+    /** Delete one or more memories */
+    delete(memoryIds: string | string[]): Promise<boolean | {
+        message: string;
+        results: {
+            successful: string[];
+            failed: Array<{
+                id: string;
+                error: string;
+            }>;
+            summary: {
+                total: number;
+                succeeded: number;
+                failed: number;
+            };
+        };
+    }>;
+    /** Delete a specific chunk or message within a memory */
+    deleteChunk(chunkId: string): Promise<boolean>;
+    /** Update a specific chunk or message within a memory */
+    updateChunk(chunkId: string, content: string, metadata?: Record<string, any>): Promise<boolean>;
+    /**
+     * 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
+     */
+    updateMemory(options: {
+        memoryId: string;
+        name?: string;
+        metadata?: Record<string, any>;
+        collectionIds?: string[];
+        mergeMetadata?: boolean;
+    }): Promise<boolean>;
     /** Delete a conversation and all its messages */
     deleteConversation(conversationId: string): Promise<boolean>;
-    /** Get all memories from specific clusters */
-    listMemories(clusterIds: string | string[], limit?: number, offset?: number): Promise<MemoryResponse[]>;
-    /** Get a specific memory by ID */
+    /**
+     * 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 } }
+     *     ]
+     *   }
+     * });
+     */
+    listMemories(options: {
+        collection_ids: string | string[];
+        limit?: number;
+        offset?: number;
+        metadata_filters?: Record<string, any>;
+    }): Promise<MemoryResponse[]>;
+    /** Get a specific memory by engram ID */
     getMemory(memoryId: string): Promise<MemoryResponse>;
-    /** Search within specific clusters */
-    search(query: string, clusters: string | string[], limitOrOptions?: number | {
+    /**
+     * 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
+     */
+    search(options: {
+        query: string;
+        collection_ids: string | string[];
         limit?: number;
-    }, retrievalType?: RetrievalType | string, filters?: Record<string, any>, searchSettings?: Record<string, any>): Promise<SearchResult[]>;
+        filters?: Record<string, any>;
+        search_mode?: 'fast' | 'super';
+        searchSettings?: Record<string, any>;
+    }): Promise<SearchResult[]>;
     /**
      * Legacy wrapper: store a two-message conversation turn as a document
      */
-    storeConversation(userMessage: string, assistantMessage: string, clusterId: string, sessionId: string): Promise<MemoryResponse>;
+    storeConversation(userMessage: string, assistantMessage: string, collectionId: string, sessionId: string): Promise<MemoryResponse>;
     /**
      * Legacy wrapper: search conversations optionally scoped by session
      */
-    searchConversations(query: string, clusterId: string, sessionId?: string, includeAllSessions?: boolean): Promise<SearchResult[]>;
+    searchConversations(query: string, collectionId: string, sessionId?: string, includeAllSessions?: boolean): Promise<SearchResult[]>;
     healthCheck(): Promise<Record<string, any>>;
-    private _clusterFromDict;
+    private _collectionFromDict;
     private _memoryResponseFromDict;
     private _searchResultFromDict;
     private _searchResultFromGraphDict;
@@ -184,4 +440,4 @@ declare class NebulaClient {
     private _formDataFromObject;
 }
 
-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 };
+export { type AgentResponse, type Chunk, type Collection, type GraphCommunityResult, type GraphEntityResult, type GraphRelationshipResult, GraphSearchResultType, type Memory, type MemoryResponse, NebulaAuthenticationException, NebulaClient, type NebulaClientConfig, NebulaClientException, NebulaCollectionNotFoundException, NebulaException, NebulaNotFoundException, NebulaRateLimitException, NebulaValidationException, type SearchOptions, type SearchResult };