@dooor-ai/cortexdb 0.1.1 → 0.2.0

package/README.md

@@ -1,15 +1,29 @@
 # CortexDB TypeScript SDK
 
-Official TypeScript/JavaScript client for CortexDB - Multi-modal RAG Platform.
+Official TypeScript/JavaScript client for CortexDB.
+
+## What is CortexDB?
+
+CortexDB is a multi-modal RAG (Retrieval Augmented Generation) platform that combines traditional database capabilities with vector search and advanced document processing. It enables you to:
+
+- Store structured and unstructured data in a unified database
+- Automatically extract text from documents (PDF, DOCX, XLSX) using Docling
+- Generate embeddings for semantic search using various providers (OpenAI, Gemini, etc.)
+- Perform hybrid search combining filters with vector similarity
+- Build RAG applications with automatic chunking and vectorization
+
+CortexDB handles the complex infrastructure of vector databases (Qdrant), object storage (MinIO), and traditional databases (PostgreSQL) behind a simple API.
 
 ## Features
 
-- Full TypeScript support with type definitions
-- Async/await API using native fetch
-- Semantic search with vector embeddings
-- Collection and record management
-- Custom error types for better debugging
-- Works with Node.js 18+, Deno, and modern browsers
+- **Multi-modal document processing**: Upload PDFs, DOCX, XLSX files and automatically extract text with OCR fallback
+- **Semantic search**: Vector-based search using embeddings from OpenAI, Gemini, or custom providers
+- **Automatic chunking**: Smart text splitting optimized for RAG applications
+- **Flexible schema**: Define collections with typed fields (string, number, boolean, file, array)
+- **Hybrid queries**: Combine exact filters with semantic search
+- **Storage control**: Choose where each field is stored (PostgreSQL, Qdrant, MinIO)
+- **Type-safe**: Full TypeScript support with comprehensive type definitions
+- **Modern API**: Async/await using native fetch (Node.js 18+)
 
 ## Installation
 
@@ -39,28 +53,34 @@ async function main() {
     baseUrl: 'http://localhost:8000'
   });
 
-  // Create a collection
-  await client.collections.create('documents', [
-    { name: 'title', type: FieldType.STRING },
-    { name: 'content', type: FieldType.STRING, vectorize: true }
-  ]);
+  // Create a collection with vectorization enabled
+  await client.collections.create(
+    'documents',
+    [
+      { name: 'title', type: FieldType.STRING },
+      { name: 'content', type: FieldType.STRING, vectorize: true }
+    ],
+    'your-embedding-provider-id'  // Required when vectorize=true
+  );
 
   // Create a record
   const record = await client.records.create('documents', {
-    title: 'Hello World',
-    content: 'This is my first document'
+    title: 'Introduction to AI',
+    content: 'Artificial intelligence is transforming how we build software...'
   });
 
-  // Semantic search
+  // Semantic search - finds relevant content by meaning, not just keywords
   const results = await client.records.search(
     'documents',
-    'hello world',
+    'How is AI changing software development?',
     undefined,
     10
   );
 
   results.results.forEach(result => {
-    console.log(`Score: ${result.score.toFixed(4)} - ${result.record.data.title}`);
+    console.log(`Score: ${result.score.toFixed(4)}`);
+    console.log(`Title: ${result.record.data.title}`);
+    console.log(`Content: ${result.record.data.content}\n`);
   });
 
   await client.close();
@@ -76,64 +96,80 @@ main();
 ```typescript
 import { CortexClient } from '@dooor-ai/cortexdb';
 
-// Local development
-const client = new CortexClient({
-  baseUrl: 'http://localhost:8000'
-});
+// Using connection string (recommended)
+const client = new CortexClient('cortexdb://localhost:8000');
 
 // With API key
-const client = new CortexClient({
-  baseUrl: 'https://api.cortexdb.com',
-  apiKey: 'your-api-key'
-});
+const client = new CortexClient('cortexdb://my-api-key@localhost:8000');
 
-// Custom timeout
+// Production (HTTPS auto-detected)
+const client = new CortexClient('cortexdb://my-key@api.cortexdb.com');
+
+// Using options object (alternative)
 const client = new CortexClient({
   baseUrl: 'http://localhost:8000',
+  apiKey: 'your-api-key',
   timeout: 60000  // 60 seconds
 });
 ```
 
+**Connection String Format:**  
+`cortexdb://[api_key@]host[:port]`
+
+Benefits:
+- Single string configuration
+- Easy to store in environment variables
+- Familiar pattern (like PostgreSQL, MongoDB, Redis)
+- Auto-detects HTTP vs HTTPS
+
 ### Collections
 
+Collections define the schema for your data. Each collection can have multiple fields with different types and storage options.
+
 ```typescript
 import { FieldType, StoreLocation } from '@dooor-ai/cortexdb';
 
-// Create collection
-const collection = await client.collections.create('articles', [
-  {
-    name: 'title',
-    type: FieldType.STRING
-  },
-  {
-    name: 'content',
-    type: FieldType.STRING,
-    vectorize: true  // Enable semantic search
-  },
-  {
-    name: 'year',
-    type: FieldType.NUMBER,
-    store_in: [StoreLocation.POSTGRES, StoreLocation.QDRANT_PAYLOAD]
-  }
-]);
+// Create collection with vectorization
+const collection = await client.collections.create(
+  'articles',
+  [
+    {
+      name: 'title',
+      type: FieldType.STRING
+    },
+    {
+      name: 'content',
+      type: FieldType.STRING,
+      vectorize: true  // Enable semantic search on this field
+    },
+    {
+      name: 'year',
+      type: FieldType.NUMBER,
+      store_in: [StoreLocation.POSTGRES, StoreLocation.QDRANT_PAYLOAD]
+    }
+  ],
+  'embedding-provider-id'  // Required when any field has vectorize=true
+);
 
 // List collections
 const collections = await client.collections.list();
 
-// Get collection
+// Get collection schema
 const schema = await client.collections.get('articles');
 
-// Delete collection
+// Delete collection and all its records
 await client.collections.delete('articles');
 ```
 
 ### Records
 
+Records are the actual data stored in collections. They must match the collection schema.
+
 ```typescript
 // Create record
 const record = await client.records.create('articles', {
   title: 'Machine Learning Basics',
-  content: 'Introduction to ML concepts...',
+  content: 'Machine learning is a subset of AI that focuses on learning from data...',
   year: 2024
 });
 
@@ -148,7 +184,7 @@ const updated = await client.records.update('articles', record.id, {
 // Delete record
 await client.records.delete('articles', record.id);
 
-// List records
+// List records with pagination
 const results = await client.records.list('articles', {
   limit: 10,
   offset: 0
@@ -157,8 +193,10 @@ const results = await client.records.list('articles', {
 
 ### Semantic Search
 
+Semantic search finds records by meaning, not just exact keyword matches. It uses vector embeddings to understand context.
+
 ```typescript
-// Basic search
+// Basic semantic search
 const results = await client.records.search(
   'articles',
   'machine learning fundamentals',
@@ -166,7 +204,7 @@ const results = await client.records.search(
   10
 );
 
-// Search with filters
+// Search with filters - combine semantic search with exact matches
 const filteredResults = await client.records.search(
   'articles',
   'neural networks',
@@ -177,30 +215,55 @@ const filteredResults = await client.records.search(
   5
 );
 
-// Process results
+// Process results - ordered by relevance score
 filteredResults.results.forEach(result => {
-  console.log(`Score: ${result.score.toFixed(4)}`);
+  console.log(`Score: ${result.score.toFixed(4)}`);  // Higher = more relevant
   console.log(`Title: ${result.record.data.title}`);
   console.log(`Year: ${result.record.data.year}`);
 });
 ```
 
+### Working with Files
+
+CortexDB can process documents and automatically extract text for vectorization.
+
+```typescript
+// Create collection with file field
+await client.collections.create(
+  'documents',
+  [
+    { name: 'title', type: FieldType.STRING },
+    {
+      name: 'document',
+      type: FieldType.FILE,
+      vectorize: true  // Extract text and create embeddings
+    }
+  ],
+  'embedding-provider-id'
+);
+
+// Note: File upload support is currently available in the REST API
+// TypeScript SDK file upload will be added in a future version
+```
+
 ### Filter Operators
 
 ```typescript
-// Exact match
+// Exact match filters
 const results = await client.records.list('articles', {
   filters: {
     category: 'technology',
-    published: true
+    published: true,
+    year: 2024
   }
 });
 
-// Combine filters
+// Combine multiple filters
 const filtered = await client.records.list('articles', {
   filters: {
     year: 2024,
-    category: 'AI'
+    category: 'AI',
+    author: 'John Doe'
   },
   limit: 20
 });
@@ -208,12 +271,15 @@ const filtered = await client.records.list('articles', {
 
 ## Error Handling
 
+The SDK provides specific error types for different failure scenarios.
+
 ```typescript
 import {
   CortexDBError,
   CortexDBNotFoundError,
   CortexDBValidationError,
-  CortexDBConnectionError
+  CortexDBConnectionError,
+  CortexDBTimeoutError
 } from '@dooor-ai/cortexdb';
 
 try {
@@ -222,9 +288,11 @@ try {
   if (error instanceof CortexDBNotFoundError) {
     console.log('Record not found');
   } else if (error instanceof CortexDBValidationError) {
-    console.log('Validation error:', error.message);
+    console.log('Invalid data:', error.message);
   } else if (error instanceof CortexDBConnectionError) {
     console.log('Connection failed:', error.message);
+  } else if (error instanceof CortexDBTimeoutError) {
+    console.log('Request timed out:', error.message);
   } else if (error instanceof CortexDBError) {
     console.log('General error:', error.message);
   }
@@ -233,11 +301,11 @@ try {
 
 ## Examples
 
-Check the [`examples/`](./examples) directory for more usage examples:
+Check the [`examples/`](./examples) directory for complete working examples:
 
-- [`quickstart.ts`](./examples/quickstart.ts) - Walkthrough of SDK features
-- [`search.ts`](./examples/search.ts) - Semantic search with filters
-- [`basic.ts`](./examples/basic.ts) - Basic operations
+- [`quickstart.ts`](./examples/quickstart.ts) - Complete walkthrough of SDK features
+- [`search.ts`](./examples/search.ts) - Semantic search with filters and providers
+- [`basic.ts`](./examples/basic.ts) - Basic CRUD operations
 
 Run examples:
 
@@ -264,27 +332,44 @@ npm run build
 ### Scripts
 
 ```bash
-# Build
+# Build TypeScript
 npm run build
 
-# Watch mode
+# Build in watch mode
 npm run build:watch
 
-# Clean
+# Clean build artifacts
 npm run clean
 
-# Lint
+# Lint code
 npm run lint
 
-# Format
+# Format code
 npm run format
 ```
 
 ## Requirements
 
-- Node.js >= 18.0.0
-- CortexDB gateway running (local or remote)
+- Node.js >= 18.0.0 (for native fetch support)
+- CortexDB gateway running locally or remotely
+- Embedding provider configured (OpenAI, Gemini, etc.) if using vectorization
+
+## Architecture
+
+CortexDB integrates multiple technologies:
+
+- **PostgreSQL**: Stores structured data and metadata
+- **Qdrant**: Vector database for semantic search
+- **MinIO**: Object storage for files
+- **Docling**: Advanced document processing and text extraction
+
+The SDK abstracts this complexity into a simple, unified API.
 
 ## License
 
 MIT License - see [LICENSE](./LICENSE) for details.
+
+## Related
+
+- [CortexDB Python SDK](../python) - Python client for CortexDB
+- [CortexDB Documentation](../../docs) - Complete platform documentation

package/dist/client/index.d.ts

@@ -10,7 +10,24 @@ export declare class CortexClient {
     private http;
     collections: CollectionsAPI;
     records: RecordsAPI;
-    constructor(options?: CortexClientOptions);
+    /**
+     * Create a new CortexDB client
+     *
+     * @param options - Configuration options or connection string
+     *
+     * @example
+     * ```typescript
+     * // Using options object
+     * const client = new CortexClient({
+     *   baseUrl: 'http://localhost:8000',
+     *   apiKey: 'my-key'
+     * });
+     *
+     * // Using connection string
+     * const client = new CortexClient('cortexdb://my-key@localhost:8000');
+     * ```
+     */
+    constructor(options?: CortexClientOptions | string);
     /**
      * Check if the connection to CortexDB is working
      */

package/dist/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAG3B,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE5C,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,IAAI,CAAa;IAClB,WAAW,EAAE,cAAc,CAAC;IAC5B,OAAO,EAAE,UAAU,CAAC;gBAEf,OAAO,GAAE,mBAAwB;IAY7C;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAI3C;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IASrC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAG3B,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAG5C,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,IAAI,CAAa;IAClB,WAAW,EAAE,cAAc,CAAC;IAC5B,OAAO,EAAE,UAAU,CAAC;IAE3B;;;;;;;;;;;;;;;;OAgBG;gBACS,OAAO,GAAE,mBAAmB,GAAG,MAAW;IAuBtD;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAI3C;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IASrC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/client/index.js

@@ -5,9 +5,42 @@ exports.CortexClient = void 0;
 const client_1 = require("../http/client");
 const api_1 = require("../collections/api");
 const api_2 = require("../records/api");
+const connection_string_1 = require("../utils/connection-string");
 class CortexClient {
+    /**
+     * Create a new CortexDB client
+     *
+     * @param options - Configuration options or connection string
+     *
+     * @example
+     * ```typescript
+     * // Using options object
+     * const client = new CortexClient({
+     *   baseUrl: 'http://localhost:8000',
+     *   apiKey: 'my-key'
+     * });
+     *
+     * // Using connection string
+     * const client = new CortexClient('cortexdb://my-key@localhost:8000');
+     * ```
+     */
     constructor(options = {}) {
-        const { baseUrl = "http://localhost:8000", apiKey, timeout = 30000, } = options;
+        let baseUrl;
+        let apiKey;
+        let timeout;
+        // Handle connection string
+        if (typeof options === 'string') {
+            const parsed = (0, connection_string_1.parseConnectionString)(options);
+            baseUrl = parsed.baseUrl;
+            apiKey = parsed.apiKey;
+            timeout = 30000;
+        }
+        else {
+            // Handle options object
+            baseUrl = options.baseUrl || "http://localhost:8000";
+            apiKey = options.apiKey;
+            timeout = options.timeout || 30000;
+        }
         this.http = new client_1.HTTPClient(baseUrl, apiKey, timeout);
         this.collections = new api_1.CollectionsAPI(this.http);
         this.records = new api_2.RecordsAPI(this.http);

package/dist/client/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":";AAAA,2BAA2B;;;AAE3B,2CAA4C;AAC5C,4CAAoD;AACpD,wCAA4C;AAQ5C,MAAa,YAAY;IAKvB,YAAY,UAA+B,EAAE;QAC3C,MAAM,EACJ,OAAO,GAAG,uBAAuB,EACjC,MAAM,EACN,OAAO,GAAG,KAAK,GAChB,GAAG,OAAO,CAAC;QAEZ,IAAI,CAAC,IAAI,GAAG,IAAI,mBAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;QACrD,IAAI,CAAC,WAAW,GAAG,IAAI,oBAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjD,IAAI,CAAC,OAAO,GAAG,IAAI,gBAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,MAAM;QACV,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAClC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,WAAW;QACf,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;YACrC,OAAO,QAAQ,CAAC,MAAM,KAAK,IAAI,CAAC;QAClC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK;QACT,6DAA6D;IAC/D,CAAC;CACF;AA1CD,oCA0CC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":";AAAA,2BAA2B;;;AAE3B,2CAA4C;AAC5C,4CAAoD;AACpD,wCAA4C;AAC5C,kEAAmE;AAQnE,MAAa,YAAY;IAKvB;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,UAAwC,EAAE;QACpD,IAAI,OAAe,CAAC;QACpB,IAAI,MAA0B,CAAC;QAC/B,IAAI,OAAe,CAAC;QAEpB,2BAA2B;QAC3B,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAChC,MAAM,MAAM,GAAG,IAAA,yCAAqB,EAAC,OAAO,CAAC,CAAC;YAC9C,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;YACzB,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;YACvB,OAAO,GAAG,KAAK,CAAC;QAClB,CAAC;aAAM,CAAC;YACN,wBAAwB;YACxB,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,uBAAuB,CAAC;YACrD,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;YACxB,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,KAAK,CAAC;QACrC,CAAC;QAED,IAAI,CAAC,IAAI,GAAG,IAAI,mBAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;QACrD,IAAI,CAAC,WAAW,GAAG,IAAI,oBAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjD,IAAI,CAAC,OAAO,GAAG,IAAI,gBAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,MAAM;QACV,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAClC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,WAAW;QACf,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;YACrC,OAAO,QAAQ,CAAC,MAAM,KAAK,IAAI,CAAC;QAClC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK;QACT,6DAA6D;IAC/D,CAAC;CACF;AAtED,oCAsEC"}

package/dist/utils/connection-string.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Parse CortexDB connection strings
+ *
+ * Format: cortexdb://[api_key@]host[:port]
+ *
+ * Examples:
+ * - cortexdb://localhost:8000
+ * - cortexdb://my_key@localhost:8000
+ * - cortexdb://my_key@api.cortexdb.com
+ */
+export interface ParsedConnection {
+    baseUrl: string;
+    apiKey?: string;
+}
+/**
+ * Parse a CortexDB connection string
+ *
+ * @param connectionString - Connection string in format cortexdb://[api_key@]host[:port]
+ * @returns Parsed connection options
+ * @throws Error if connection string is invalid
+ *
+ * @example
+ * ```typescript
+ * parseConnectionString('cortexdb://localhost:8000')
+ * // { baseUrl: 'http://localhost:8000' }
+ *
+ * parseConnectionString('cortexdb://my_key@localhost:8000')
+ * // { baseUrl: 'http://localhost:8000', apiKey: 'my_key' }
+ *
+ * parseConnectionString('cortexdb://key@api.cortexdb.com:443')
+ * // { baseUrl: 'https://api.cortexdb.com:443', apiKey: 'key' }
+ * ```
+ */
+export declare function parseConnectionString(connectionString: string): ParsedConnection;
+//# sourceMappingURL=connection-string.d.ts.map

package/dist/utils/connection-string.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-string.d.ts","sourceRoot":"","sources":["../../src/utils/connection-string.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CAAC,gBAAgB,EAAE,MAAM,GAAG,gBAAgB,CAoDhF"}

package/dist/utils/connection-string.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Parse CortexDB connection strings
+ *
+ * Format: cortexdb://[api_key@]host[:port]
+ *
+ * Examples:
+ * - cortexdb://localhost:8000
+ * - cortexdb://my_key@localhost:8000
+ * - cortexdb://my_key@api.cortexdb.com
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseConnectionString = parseConnectionString;
+/**
+ * Parse a CortexDB connection string
+ *
+ * @param connectionString - Connection string in format cortexdb://[api_key@]host[:port]
+ * @returns Parsed connection options
+ * @throws Error if connection string is invalid
+ *
+ * @example
+ * ```typescript
+ * parseConnectionString('cortexdb://localhost:8000')
+ * // { baseUrl: 'http://localhost:8000' }
+ *
+ * parseConnectionString('cortexdb://my_key@localhost:8000')
+ * // { baseUrl: 'http://localhost:8000', apiKey: 'my_key' }
+ *
+ * parseConnectionString('cortexdb://key@api.cortexdb.com:443')
+ * // { baseUrl: 'https://api.cortexdb.com:443', apiKey: 'key' }
+ * ```
+ */
+function parseConnectionString(connectionString) {
+    // Remove cortexdb:// prefix
+    if (!connectionString.startsWith('cortexdb://')) {
+        throw new Error('Connection string must start with "cortexdb://"');
+    }
+    const withoutProtocol = connectionString.slice('cortexdb://'.length);
+    // Split by @ to separate api_key from host
+    let apiKey;
+    let hostPart;
+    if (withoutProtocol.includes('@')) {
+        const parts = withoutProtocol.split('@');
+        if (parts.length !== 2) {
+            throw new Error('Invalid connection string format');
+        }
+        apiKey = parts[0];
+        hostPart = parts[1];
+    }
+    else {
+        hostPart = withoutProtocol;
+    }
+    // Parse host and port
+    let host;
+    let port;
+    if (hostPart.includes(':')) {
+        const hostPortParts = hostPart.split(':');
+        host = hostPortParts[0];
+        port = hostPortParts[1];
+    }
+    else {
+        host = hostPart;
+    }
+    // Determine protocol (https for port 443 or production domains, http otherwise)
+    const isSecure = port === '443' ||
+        host.includes('cortexdb.com') ||
+        (!host.includes('localhost') && !host.startsWith('127.'));
+    const protocol = isSecure ? 'https' : 'http';
+    // Build base URL
+    let baseUrl = `${protocol}://${host}`;
+    if (port && !(port === '443' && isSecure) && !(port === '80' && !isSecure)) {
+        baseUrl += `:${port}`;
+    }
+    return {
+        baseUrl,
+        apiKey
+    };
+}
+//# sourceMappingURL=connection-string.js.map

package/dist/utils/connection-string.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-string.js","sourceRoot":"","sources":["../../src/utils/connection-string.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;AA0BH,sDAoDC;AAvED;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,qBAAqB,CAAC,gBAAwB;IAC5D,4BAA4B;IAC5B,IAAI,CAAC,gBAAgB,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACrE,CAAC;IAED,MAAM,eAAe,GAAG,gBAAgB,CAAC,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IAErE,2CAA2C;IAC3C,IAAI,MAA0B,CAAC;IAC/B,IAAI,QAAgB,CAAC;IAErB,IAAI,eAAe,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAClC,MAAM,KAAK,GAAG,eAAe,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACzC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;QACtD,CAAC;QACD,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QAClB,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACtB,CAAC;SAAM,CAAC;QACN,QAAQ,GAAG,eAAe,CAAC;IAC7B,CAAC;IAED,sBAAsB;IACtB,IAAI,IAAY,CAAC;IACjB,IAAI,IAAwB,CAAC;IAE7B,IAAI,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,aAAa,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC1C,IAAI,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;QACxB,IAAI,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;IAC1B,CAAC;SAAM,CAAC;QACN,IAAI,GAAG,QAAQ,CAAC;IAClB,CAAC;IAED,gFAAgF;IAChF,MAAM,QAAQ,GAAG,IAAI,KAAK,KAAK;QACd,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC;QAC7B,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;IAE3E,MAAM,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;IAE7C,iBAAiB;IACjB,IAAI,OAAO,GAAG,GAAG,QAAQ,MAAM,IAAI,EAAE,CAAC;IACtC,IAAI,IAAI,IAAI,CAAC,CAAC,IAAI,KAAK,KAAK,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3E,OAAO,IAAI,IAAI,IAAI,EAAE,CAAC;IACxB,CAAC;IAED,OAAO;QACL,OAAO;QACP,MAAM;KACP,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dooor-ai/cortexdb",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Official TypeScript/JavaScript SDK for CortexDB - Multi-modal RAG Platform with advanced document processing",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",