@nebula-ai/sdk 0.0.19

package/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2024 Nebula Cloud
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+
+
+

package/README.md

@@ -0,0 +1,448 @@
+# @nebula-ai/sdk
+
+Official JavaScript/TypeScript SDK for Nebula Cloud - Memory, Search, and AI-powered conversations.
+
+[![npm version](https://badge.fury.io/js/%40nebula-ai%2Fsdk.svg)](https://badge.fury.io/js/%40nebula-ai%2Fsdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+
+## Features
+
+- 🚀 **Full API Parity** - Mirrors the exact Nebula Python SDK client.py implementation
+- 🔐 **Flexible Authentication** - Supports both API keys and Bearer tokens
+- 🌐 **Browser & Node.js Ready** - Works in browsers and Node.js environments
+- 📱 **TypeScript First** - Full type safety with comprehensive interfaces
+- 🎯 **Unified Memory Model** - Store text, conversations, and structured data
+- 🔍 **Advanced Search** - Vector search with graph results (entities, relationships, communities)
+- 💬 **Conversation Support** - Built-in conversation tracking and management
+- ⚡ **Performance Optimized** - Configurable timeouts and error handling
+- 🧠 **Graph Intelligence** - Leverage knowledge graphs for enhanced search
+
+## Installation
+
+```bash
+npm install @nebula-ai/sdk
+# or
+yarn add @nebula-ai/sdk
+# or
+pnpm add @nebula-ai/sdk
+```
+
+## Quick Start
+
+```typescript
+import { NebulaSDK, RetrievalType } from '@nebula-ai/sdk';
+
+// Initialize the SDK
+const client = new NebulaSDK({
+  apiKey: 'your-nebula-api-key',
+  baseUrl: 'https://api.nebulacloud.app', // optional, defaults to this
+  timeout: 30000 // optional, defaults to 30 seconds
+});
+
+// Create a cluster
+const cluster = await client.createCluster(
+  'My Project', 
+  'A collection of project memories'
+);
+
+// Store a memory using the unified Memory model
+const memoryId = await client.storeMemory({
+  cluster_id: cluster.id,
+  content: 'This is an important piece of information about my project.',
+  metadata: { category: 'project', priority: 'high' }
+});
+
+// Search for memories with advanced options
+const results = await client.search(
+  'project information',
+  [cluster.id],
+  5,
+  RetrievalType.ADVANCED,
+  { 'metadata.category': 'project' }
+);
+
+console.log('Found memories:', results);
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+new NebulaSDK(config: NebulaSDKConfig)
+```
+
+**Config Options:**
+- `apiKey` (required): Your Nebula API key
+- `baseUrl` (optional): Custom API base URL, defaults to `https://api.nebulacloud.app`
+- `timeout` (optional): Request timeout in milliseconds, defaults to 30000
+
+### Core Methods
+
+#### Clusters
+
+```typescript
+// Create a new cluster
+await client.createCluster(name: string, description?: string, metadata?: Record<string, any>)
+
+// Get a cluster by ID
+await client.getCluster(clusterId: string)
+
+// Get a cluster by name
+await client.getClusterByName(name: string)
+
+// List all clusters
+await client.listClusters(limit?: number, offset?: number)
+
+// Update a cluster
+await client.updateCluster(clusterId: string, name?: string, description?: string, metadata?: Record<string, any>)
+
+// Delete a cluster
+await client.deleteCluster(clusterId: string)
+```
+
+#### Memories
+
+```typescript
+// Store a single memory
+await client.storeMemory(memory: Memory | Record<string, any>)
+
+// Store multiple memories
+await client.storeMemories(memories: Memory[])
+
+// Get a specific memory
+await client.getMemory(memoryId: string)
+
+// List memories from clusters
+await client.listMemories(clusterIds: string[], limit?: number, offset?: number)
+
+// Delete a memory
+await client.delete(memoryId: string)
+```
+
+#### Search
+
+```typescript
+// Search within clusters
+await client.search(
+  query: string,
+  clusterIds: string[],
+  limit?: number,
+  retrievalType?: RetrievalType | string,
+  filters?: Record<string, any>,
+  searchSettings?: Record<string, any>
+)
+```
+
+#### Health Check
+
+```typescript
+// Check API health
+await client.healthCheck()
+```
+
+### Data Models
+
+#### Memory (for writing)
+
+```typescript
+interface Memory {
+  cluster_id: string;        // Required: cluster to store in
+  content: string;           // Required: text content
+  role?: string;             // Optional: 'user', 'assistant', or custom (for conversations)
+  parent_id?: string;        // Optional: conversation ID (for conversations)
+  metadata?: Record<string, any>; // Optional: additional metadata
+}
+```
+
+#### MemoryResponse (for reading)
+
+```typescript
+interface MemoryResponse {
+  id: string;
+  content?: string;
+  chunks?: string[];
+  metadata: Record<string, any>;
+  cluster_ids: string[];
+  created_at?: string;
+  updated_at?: string;
+}
+```
+
+#### SearchResult
+
+```typescript
+interface SearchResult {
+  id: string;
+  score: number;
+  metadata: Record<string, any>;
+  source?: string;
+
+  // Chunk fields
+  content?: string;
+
+  // Graph fields
+  graph_result_type?: GraphSearchResultType;
+  graph_entity?: GraphEntityResult;
+  graph_relationship?: GraphRelationshipResult;
+  graph_community?: GraphCommunityResult;
+  chunk_ids?: string[];
+}
+```
+
+#### RetrievalType
+
+```typescript
+enum RetrievalType {
+  BASIC = "basic",
+  ADVANCED = "advanced",
+  CUSTOM = "custom"
+}
+```
+
+### Search Options
+
+The search method supports advanced configuration:
+
+```typescript
+const results = await client.search(
+  'query',
+  [clusterId],
+  10,
+  RetrievalType.ADVANCED,
+  { 'metadata.category': 'science' },
+  {
+    graph_settings: {
+      enabled: true,
+      bfs_enabled: true,
+      bfs_max_depth: 2
+    },
+    search_strategy: 'rag_fusion',
+    num_sub_queries: 3
+  }
+);
+```
+
+### Error Handling
+
+The SDK provides custom error classes matching the Python SDK:
+
+```typescript
+import { 
+  NebulaException, 
+  NebulaClientException, 
+  NebulaAuthenticationException,
+  NebulaRateLimitException,
+  NebulaValidationException,
+  NebulaClusterNotFoundException
+} from '@nebula-ai/sdk';
+
+try {
+  await client.search('query', [clusterId]);
+} catch (error) {
+  if (error instanceof NebulaAuthenticationException) {
+    console.log('Invalid API key');
+  } else if (error instanceof NebulaRateLimitException) {
+    console.log('Rate limit exceeded');
+  } else if (error instanceof NebulaValidationException) {
+    console.log('Validation error:', error.details);
+  } else if (error instanceof NebulaException) {
+    console.log('API error:', error.statusCode, error.details);
+  }
+}
+```
+
+## Examples
+
+### Basic Memory Management
+
+```typescript
+import { NebulaSDK } from '@nebula-ai/sdk';
+
+const client = new NebulaSDK({ apiKey: 'your-key' });
+
+async function manageMemories() {
+  // Create a cluster
+  const cluster = await client.createCluster(
+    'Knowledge Base',
+    'My personal knowledge repository'
+  );
+
+  // Store memories using the unified model
+  const memories = [
+    {
+      cluster_id: cluster.id,
+      content: 'JavaScript is a programming language',
+      metadata: { category: 'programming', difficulty: 'beginner' }
+    },
+    {
+      cluster_id: cluster.id,
+      content: 'TypeScript adds static typing to JavaScript',
+      metadata: { category: 'programming', difficulty: 'beginner' }
+    }
+  ];
+
+  // Store all memories at once
+  const memoryIds = await client.storeMemories(memories);
+  console.log('Stored memories:', memoryIds);
+
+  // Search for memories
+  const results = await client.search('JavaScript', [cluster.id]);
+  console.log('Search results:', results);
+}
+```
+
+### Conversation Tracking
+
+```typescript
+import { NebulaSDK } from '@nebula-ai/sdk';
+
+const client = new NebulaSDK({ apiKey: 'your-key' });
+
+async function trackConversation() {
+  const cluster = await client.createCluster('Conversations', 'AI chat history');
+
+  // Store conversation turns
+  const conversationMemories = [
+    {
+      cluster_id: cluster.id,
+      content: 'What is machine learning?',
+      role: 'user',
+      metadata: { topic: 'AI' }
+    },
+    {
+      cluster_id: cluster.id,
+      content: 'Machine learning is a subset of AI...',
+      role: 'assistant',
+      metadata: { topic: 'AI' }
+    }
+  ];
+
+  // Store conversation (returns conversation IDs)
+  const conversationIds = await client.storeMemories(conversationMemories);
+  console.log('Conversation IDs:', conversationIds);
+}
+```
+
+### Advanced Search with Graph Results
+
+```typescript
+import { NebulaSDK, RetrievalType } from '@nebula-ai/sdk';
+
+const client = new NebulaSDK({ apiKey: 'your-key' });
+
+async function advancedSearch() {
+  const cluster = await client.createCluster('Knowledge Graph', 'Entity relationships');
+
+  // Store knowledge graph data
+  await client.storeMemory({
+    cluster_id: cluster.id,
+    content: 'Einstein developed the theory of relativity',
+    metadata: { entity: 'Einstein', concept: 'relativity', field: 'physics' }
+  });
+
+  // Search with graph settings
+  const results = await client.search(
+    'Einstein relativity',
+    [cluster.id],
+    10,
+    RetrievalType.ADVANCED,
+    undefined,
+    {
+      graph_settings: {
+        enabled: true,
+        bfs_enabled: true,
+        bfs_max_depth: 2
+      }
+    }
+  );
+
+  // Handle both chunk and graph results
+  results.forEach(result => {
+    if (result.content) {
+      console.log('Chunk result:', result.content);
+    }
+    if (result.graph_entity) {
+      console.log('Entity:', result.graph_entity.name);
+    }
+    if (result.graph_relationship) {
+      console.log('Relationship:', result.graph_relationship.subject, 
+                  result.graph_relationship.predicate, 
+                  result.graph_relationship.object);
+    }
+  });
+}
+```
+
+## Browser vs Node.js
+
+### Browser Usage
+
+```typescript
+import { NebulaSDK } from '@nebula-ai/sdk';
+
+const client = new NebulaSDK({
+  apiKey: 'your-api-key'
+  // Note: CORS handling is now built into the SDK
+});
+```
+
+### Node.js Usage
+
+```typescript
+import { NebulaSDK } from '@nebula-ai/sdk';
+
+const client = new NebulaSDK({
+  apiKey: 'your-api-key'
+  // No additional configuration needed
+});
+```
+
+## Development
+
+### Building
+
+```bash
+npm run build
+```
+
+### Testing
+
+```bash
+npm test
+```
+
+### Type Checking
+
+```bash
+npm run type-check
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Submit a pull request
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Support
+
+- 📧 Email: support@trynebula.ai
+- 🐛 Issues: [GitHub Issues](https://github.com/nebula-cloud/nebula-sdk-js/issues)
+- 📚 Documentation: [Nebula Cloud Docs](https://docs.trynebula.ai)
+
+## Changelog
+
+### v0.0.19
+- Complete rewrite to match Python SDK client.py exactly
+- Unified Memory model for text and conversations
+- Advanced search with graph results support
+- Proper error handling matching Python SDK
+- Full TypeScript support with comprehensive interfaces
+- Browser and Node.js compatibility

package/dist/index.d.mts

@@ -0,0 +1,218 @@
+declare enum RetrievalType {
+    BASIC = "basic",
+    ADVANCED = "advanced",
+    CUSTOM = "custom"
+}
+declare enum GraphSearchResultType {
+    ENTITY = "entity",
+    RELATIONSHIP = "relationship",
+    COMMUNITY = "community"
+}
+interface MemoryResponse {
+    id: string;
+    content?: string;
+    chunks?: string[];
+    metadata: Record<string, any>;
+    cluster_ids: string[];
+    created_at?: string;
+    updated_at?: string;
+}
+interface Memory {
+    cluster_id: string;
+    content: string;
+    role?: string;
+    parent_id?: string;
+    metadata: Record<string, any>;
+}
+interface Cluster {
+    id: string;
+    name: string;
+    description?: string;
+    metadata: Record<string, any>;
+    created_at?: string;
+    updated_at?: string;
+    memory_count: number;
+    owner_id?: string;
+}
+interface SearchResult {
+    id: string;
+    score: number;
+    metadata: Record<string, any>;
+    source?: string;
+    content?: string;
+    graph_result_type?: GraphSearchResultType;
+    graph_entity?: GraphEntityResult;
+    graph_relationship?: GraphRelationshipResult;
+    graph_community?: GraphCommunityResult;
+    chunk_ids?: string[];
+}
+interface GraphEntityResult {
+    id?: string;
+    name: string;
+    description: string;
+    metadata: Record<string, any>;
+}
+interface GraphRelationshipResult {
+    id?: string;
+    subject: string;
+    predicate: string;
+    object: string;
+    subject_id?: string;
+    object_id?: string;
+    description?: string;
+    metadata: Record<string, any>;
+}
+interface GraphCommunityResult {
+    id?: string;
+    name: string;
+    summary: string;
+    metadata: Record<string, any>;
+}
+interface AgentResponse {
+    content: string;
+    agent_id: string;
+    conversation_id?: string;
+    metadata: Record<string, any>;
+    citations: Record<string, any>[];
+}
+interface SearchOptions {
+    limit: number;
+    filters?: Record<string, any>;
+    retrieval_type: RetrievalType;
+}
+interface NebulaSDKConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+}
+declare class NebulaException extends Error {
+    statusCode?: number | undefined;
+    details?: any;
+    constructor(message: string, statusCode?: number | undefined, details?: any);
+}
+declare class NebulaClientException extends NebulaException {
+    cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+declare class NebulaAuthenticationException extends NebulaException {
+    constructor(message?: string);
+}
+declare class NebulaRateLimitException extends NebulaException {
+    constructor(message?: string);
+}
+declare class NebulaValidationException extends NebulaException {
+    details?: any;
+    constructor(message?: string, details?: any);
+}
+declare class NebulaClusterNotFoundException extends NebulaException {
+    constructor(message?: string);
+}
+
+/**
+ * Official Nebula Cloud JavaScript/TypeScript SDK
+ * Mirrors the exact Nebula Python SDK client.py implementation
+ */
+declare class NebulaSDK {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    constructor(config: NebulaSDKConfig);
+    /**
+     * Check if API key is set
+     */
+    isApiKeySet(): boolean;
+    /**
+     * Detect if a token looks like a Nebula API key (public.raw)
+     */
+    private _isNebulaApiKey;
+    /**
+     * Build authentication headers
+     */
+    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): Promise<any[]>;
+    /**
+     * Update a cluster
+     */
+    updateCluster(clusterId: string, name?: string, description?: string, metadata?: Record<string, any>): Promise<Cluster>;
+    /**
+     * Delete a cluster
+     */
+    deleteCluster(clusterId: string): Promise<boolean>;
+    /**
+     * Store a single memory
+     */
+    storeMemory(memory: Memory | Record<string, any>): Promise<string>;
+    /**
+     * Store multiple memories
+     */
+    storeMemories(memories: Memory[]): Promise<string[]>;
+    /**
+     * Delete a specific memory
+     */
+    delete(memoryId: string): Promise<boolean>;
+    /**
+     * Get all memories from specific clusters
+     */
+    listMemories(clusterIds: string[], limit?: number, offset?: number): Promise<MemoryResponse[]>;
+    /**
+     * Get a specific memory by ID
+     */
+    getMemory(memoryId: string): Promise<MemoryResponse>;
+    /**
+     * Search within specific clusters
+     */
+    search(query: string, clusterIds: string[], limit?: number, retrievalType?: RetrievalType | string, filters?: Record<string, any>, searchSettings?: Record<string, any>): Promise<SearchResult[]>;
+    /**
+     * Check the health of the Nebula API
+     */
+    healthCheck(): Promise<Record<string, any>>;
+    /**
+     * Convert cluster dict to Cluster object
+     */
+    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 };