@nebula-ai/sdk 0.0.27 → 0.0.29

package/dist/index.d.ts

@@ -3,23 +3,35 @@ declare enum GraphSearchResultType {
     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;
@@ -37,7 +49,7 @@ interface SearchResult {
     timestamp?: string;
     display_name?: string;
     source_role?: string;
-    document_id?: string;
+    memory_id?: string;
     owner_id?: string;
     content?: string;
     graph_result_type?: GraphSearchResultType;
@@ -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,48 +143,89 @@ declare class NebulaClient {
     private _buildAuthHeaders;
     /** Make an HTTP request to the Nebula API */
     private _makeRequest;
-    /** Create a new cluster */
-    createCluster(options: {
+    /** Create a new collection */
+    createCollection(options: {
         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(options?: {
+    }): 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<Cluster[]>;
-    /** List conversations for the authenticated user */
+    }): 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;
-        cluster_ids?: string[];
+        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(options: {
-        clusterId: string;
+    /** Update a collection */
+    updateCollection(options: {
+        collectionId: string;
         name?: string;
         description?: string;
         metadata?: Record<string, any>;
-    }): Promise<Cluster>;
-    /** Delete a cluster */
-    deleteCluster(clusterId: string): Promise<boolean>;
+    }): 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 one or more memories */
     delete(memoryIds: string | string[]): Promise<boolean | {
@@ -187,22 +243,88 @@ declare class NebulaClient {
             };
         };
     }>;
+    /** 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 */
+    /**
+     * 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: {
-        cluster_ids: string | string[];
+        collection_ids: string | string[];
         limit?: number;
         offset?: number;
+        metadata_filters?: Record<string, any>;
     }): Promise<MemoryResponse[]>;
-    /** Get a specific memory by ID */
+    /** Get a specific memory by engram ID */
     getMemory(memoryId: string): Promise<MemoryResponse>;
     /**
-     * Search within specific clusters with optional metadata filtering.
+     * Search within specific collections 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.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
@@ -215,7 +337,7 @@ declare class NebulaClient {
      * // Basic equality filter
      * await client.search({
      *   query: "machine learning",
-     *   cluster_ids: ["research-cluster"],
+     *   collection_ids: ["research-collection"],
      *   filters: {
      *     "metadata.category": { $eq: "research" },
      *     "metadata.verified": true  // Shorthand for $eq
@@ -226,7 +348,7 @@ declare class NebulaClient {
      * // Numeric comparisons
      * await client.search({
      *   query: "high priority",
-     *   cluster_ids: ["tasks"],
+     *   collection_ids: ["tasks"],
      *   filters: {
      *     "metadata.priority": { $gte: 8 },
      *     "metadata.score": { $lt: 100 }
@@ -237,7 +359,7 @@ declare class NebulaClient {
      * // String matching
      * await client.search({
      *   query: "employees",
-     *   cluster_ids: ["team"],
+     *   collection_ids: ["team"],
      *   filters: {
      *     "metadata.email": { $ilike: "%@company.com" }  // Case-insensitive
      *   }
@@ -247,7 +369,7 @@ declare class NebulaClient {
      * // Array operations
      * await client.search({
      *   query: "developers",
-     *   cluster_ids: ["team"],
+     *   collection_ids: ["team"],
      *   filters: {
      *     "metadata.skills": { $overlap: ["python", "typescript"] }  // Has any
      *   }
@@ -257,7 +379,7 @@ declare class NebulaClient {
      * // Nested paths
      * await client.search({
      *   query: "users",
-     *   cluster_ids: ["profiles"],
+     *   collection_ids: ["profiles"],
      *   filters: {
      *     "metadata.user.preferences.theme": { $eq: "dark" }
      *   }
@@ -267,7 +389,7 @@ declare class NebulaClient {
      * // Complex logical combinations
      * await client.search({
      *   query: "candidates",
-     *   cluster_ids: ["hiring"],
+     *   collection_ids: ["hiring"],
      *   filters: {
      *     $and: [
      *       { "metadata.verified": true },
@@ -295,7 +417,7 @@ declare class NebulaClient {
      */
     search(options: {
         query: string;
-        cluster_ids: string | string[];
+        collection_ids: string | string[];
         limit?: number;
         filters?: Record<string, any>;
         search_mode?: 'fast' | 'super';
@@ -304,13 +426,13 @@ declare class NebulaClient {
     /**
      * 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;
@@ -318,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, 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 };