@nebula-ai/sdk 0.0.21 → 0.0.27

package/dist/index.d.ts

@@ -1,8 +1,3 @@
-declare enum RetrievalType {
-    BASIC = "basic",
-    ADVANCED = "advanced",
-    CUSTOM = "custom"
-}
 declare enum GraphSearchResultType {
     ENTITY = "entity",
     RELATIONSHIP = "relationship",
@@ -39,6 +34,11 @@ interface SearchResult {
     score: number;
     metadata: Record<string, any>;
     source?: string;
+    timestamp?: string;
+    display_name?: string;
+    source_role?: string;
+    document_id?: string;
+    owner_id?: string;
     content?: string;
     graph_result_type?: GraphSearchResultType;
     graph_entity?: GraphEntityResult;
@@ -78,17 +78,17 @@ interface AgentResponse {
 interface SearchOptions {
     limit: number;
     filters?: Record<string, any>;
-    retrieval_type: RetrievalType;
+    search_mode?: 'fast' | 'super';
 }
-interface NebulaSDKConfig {
+interface NebulaClientConfig {
     apiKey: string;
     baseUrl?: string;
     timeout?: number;
 }
 declare class NebulaException extends Error {
     statusCode?: number | undefined;
-    details?: any;
-    constructor(message: string, statusCode?: number | undefined, details?: any);
+    details?: any | undefined;
+    constructor(message: string, statusCode?: number | undefined, details?: any | undefined);
 }
 declare class NebulaClientException extends NebulaException {
     cause?: Error | undefined;
@@ -101,122 +101,221 @@ declare class NebulaRateLimitException extends NebulaException {
     constructor(message?: string);
 }
 declare class NebulaValidationException extends NebulaException {
-    details?: any;
-    constructor(message?: string, details?: any);
+    details?: any | undefined;
+    constructor(message?: string, details?: any | undefined);
 }
 declare class NebulaClusterNotFoundException extends NebulaException {
     constructor(message?: string);
 }
 
 /**
- * Official Nebula Cloud JavaScript/TypeScript SDK
+ * Official Nebula JavaScript/TypeScript SDK
  * Mirrors the exact Nebula Python SDK client.py implementation
  */
-declare class NebulaSDK {
+declare class NebulaClient {
     private apiKey;
     private baseUrl;
     private timeout;
-    constructor(config: NebulaSDKConfig);
-    /**
-     * Check if API key is set
-     */
+    constructor(config: NebulaClientConfig);
+    setApiKey(next: string): void;
+    setBaseUrl(next: string): void;
+    setCorsProxy(_next: string): void;
+    /** Check if API key is set */
     isApiKeySet(): boolean;
-    /**
-     * Detect if a token looks like a Nebula API key (public.raw)
-     */
+    /** Detect if a token looks like a Nebula API key (public.raw) */
     private _isNebulaApiKey;
-    /**
-     * Build authentication headers
-     */
+    /** Build authentication headers */
     private _buildAuthHeaders;
-    /**
-     * Make an HTTP request to the Nebula API
-     */
+    /** 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
-     */
+    /** Create a new cluster */
+    createCluster(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
-     */
+    /** 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): Promise<any[]>;
-    /**
-     * Update a cluster
-     */
-    updateCluster(clusterId: string, name?: string, description?: string, metadata?: Record<string, any>): Promise<Cluster>;
-    /**
-     * Delete a cluster
-     */
+    /** Get all clusters */
+    listClusters(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<Cluster[]>;
+    /** List conversations for the authenticated user */
+    listConversations(options?: {
+        limit?: number;
+        offset?: number;
+        cluster_ids?: string[];
+    }): 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;
+        name?: string;
+        description?: string;
+        metadata?: Record<string, any>;
+    }): Promise<Cluster>;
+    /** Delete a cluster */
     deleteCluster(clusterId: string): Promise<boolean>;
     /**
-     * Store a single memory
+     * Legacy convenience: store raw text content into a cluster as 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
-     */
+    /** Store multiple memories */
     storeMemories(memories: Memory[]): Promise<string[]>;
-    /**
-     * Delete a specific memory
-     */
-    delete(memoryId: string): Promise<boolean>;
-    /**
-     * Delete a conversation and all its messages
-     */
+    /** 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 conversation and all its messages */
     deleteConversation(conversationId: string): Promise<boolean>;
-    /**
-     * Get all memories from specific clusters
-     */
-    listMemories(clusterIds: string[], limit?: number, offset?: number): Promise<MemoryResponse[]>;
-    /**
-     * Get a specific memory by ID
-     */
+    /** Get all memories from specific clusters */
+    listMemories(options: {
+        cluster_ids: string | string[];
+        limit?: number;
+        offset?: number;
+    }): Promise<MemoryResponse[]>;
+    /** Get a specific memory by ID */
     getMemory(memoryId: string): Promise<MemoryResponse>;
     /**
-     * Search within specific 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
      */
-    search(query: string, clusterIds: string[], limit?: number, retrievalType?: RetrievalType | string, filters?: Record<string, any>, searchSettings?: Record<string, any>): Promise<SearchResult[]>;
+    search(options: {
+        query: string;
+        cluster_ids: string | string[];
+        limit?: number;
+        filters?: Record<string, any>;
+        search_mode?: 'fast' | 'super';
+        searchSettings?: Record<string, any>;
+    }): Promise<SearchResult[]>;
     /**
-     * Check the health of the Nebula API
+     * Legacy wrapper: store a two-message conversation turn as a document
      */
-    healthCheck(): Promise<Record<string, any>>;
+    storeConversation(userMessage: string, assistantMessage: string, clusterId: string, sessionId: string): Promise<MemoryResponse>;
     /**
-     * Convert cluster dict to Cluster object
+     * Legacy wrapper: search conversations optionally scoped by session
      */
+    searchConversations(query: string, clusterId: string, sessionId?: string, includeAllSessions?: boolean): Promise<SearchResult[]>;
+    healthCheck(): Promise<Record<string, any>>;
     private _clusterFromDict;
-    /**
-     * Convert memory dict to MemoryResponse object
-     */
     private _memoryResponseFromDict;
-    /**
-     * Convert search result dict to SearchResult object
-     */
     private _searchResultFromDict;
-    /**
-     * Convert graph search result dict to SearchResult object
-     */
     private _searchResultFromGraphDict;
-    /**
-     * SHA-256 hash function
-     */
     private _sha256;
-    /**
-     * Convert object to FormData
-     */
     private _formDataFromObject;
 }
 
-export { type AgentResponse, type Cluster, type GraphCommunityResult, type GraphEntityResult, type GraphRelationshipResult, GraphSearchResultType, type Memory, type MemoryResponse, NebulaAuthenticationException, NebulaClientException, NebulaClusterNotFoundException, NebulaException, NebulaRateLimitException, NebulaSDK, type NebulaSDKConfig, NebulaValidationException, RetrievalType, type SearchOptions, type SearchResult, NebulaSDK as default };
+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 };