@ekodb/ekodb-client 0.1.0

package/dist/client.js

@@ -0,0 +1,553 @@
+"use strict";
+/**
+ * ekoDB TypeScript Client
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebSocketClient = exports.EkoDBClient = exports.MergeStrategy = exports.RateLimitError = void 0;
+const query_builder_1 = require("./query-builder");
+const search_1 = require("./search");
+const schema_1 = require("./schema");
+/**
+ * Rate limit error
+ */
+class RateLimitError extends Error {
+    constructor(retryAfterSecs, message) {
+        super(message || `Rate limit exceeded. Retry after ${retryAfterSecs} seconds`);
+        this.retryAfterSecs = retryAfterSecs;
+        this.name = 'RateLimitError';
+    }
+}
+exports.RateLimitError = RateLimitError;
+var MergeStrategy;
+(function (MergeStrategy) {
+    MergeStrategy["Chronological"] = "Chronological";
+    MergeStrategy["Summarized"] = "Summarized";
+    MergeStrategy["LatestOnly"] = "LatestOnly";
+})(MergeStrategy || (exports.MergeStrategy = MergeStrategy = {}));
+class EkoDBClient {
+    constructor(config, apiKey) {
+        this.token = null;
+        this.rateLimitInfo = null;
+        // Support both old (baseURL, apiKey) and new (config object) signatures
+        if (typeof config === 'string') {
+            this.baseURL = config;
+            this.apiKey = apiKey;
+            this.shouldRetry = true;
+            this.maxRetries = 3;
+            this.timeout = 30000;
+        }
+        else {
+            this.baseURL = config.baseURL;
+            this.apiKey = config.apiKey;
+            this.shouldRetry = config.shouldRetry ?? true;
+            this.maxRetries = config.maxRetries ?? 3;
+            this.timeout = config.timeout ?? 30000;
+        }
+    }
+    /**
+     * Initialize the client by getting an auth token
+     */
+    async init() {
+        await this.refreshToken();
+    }
+    /**
+     * Get the current rate limit information
+     */
+    getRateLimitInfo() {
+        return this.rateLimitInfo;
+    }
+    /**
+     * Check if approaching rate limit (less than 10% remaining)
+     */
+    isNearRateLimit() {
+        if (!this.rateLimitInfo)
+            return false;
+        const threshold = this.rateLimitInfo.limit * 0.1;
+        return this.rateLimitInfo.remaining <= threshold;
+    }
+    /**
+     * Refresh the authentication token
+     */
+    async refreshToken() {
+        const response = await fetch(`${this.baseURL}/api/auth/token`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ api_key: this.apiKey }),
+        });
+        if (!response.ok) {
+            throw new Error(`Auth failed with status: ${response.status}`);
+        }
+        const result = await response.json();
+        this.token = result.token;
+    }
+    /**
+     * Extract rate limit information from response headers
+     */
+    extractRateLimitInfo(response) {
+        const limit = response.headers.get('x-ratelimit-limit');
+        const remaining = response.headers.get('x-ratelimit-remaining');
+        const reset = response.headers.get('x-ratelimit-reset');
+        if (limit && remaining && reset) {
+            this.rateLimitInfo = {
+                limit: parseInt(limit, 10),
+                remaining: parseInt(remaining, 10),
+                reset: parseInt(reset, 10),
+            };
+            // Log warning if approaching rate limit
+            if (this.isNearRateLimit()) {
+                console.warn(`Approaching rate limit: ${this.rateLimitInfo.remaining}/${this.rateLimitInfo.limit} remaining`);
+            }
+        }
+    }
+    /**
+     * Sleep for a specified number of seconds
+     */
+    sleep(seconds) {
+        return new Promise(resolve => setTimeout(resolve, seconds * 1000));
+    }
+    /**
+     * Make an HTTP request to the ekoDB API with retry logic
+     */
+    async makeRequest(method, path, data, attempt = 0) {
+        if (!this.token) {
+            await this.refreshToken();
+        }
+        const options = {
+            method,
+            headers: {
+                'Authorization': `Bearer ${this.token}`,
+                'Content-Type': 'application/json',
+            },
+        };
+        if (data) {
+            options.body = JSON.stringify(data);
+        }
+        try {
+            const response = await fetch(`${this.baseURL}${path}`, options);
+            // Extract rate limit info from successful responses
+            if (response.ok) {
+                this.extractRateLimitInfo(response);
+                return response.json();
+            }
+            // Handle rate limiting (429)
+            if (response.status === 429) {
+                const retryAfter = parseInt(response.headers.get('retry-after') || '60', 10);
+                if (this.shouldRetry && attempt < this.maxRetries) {
+                    console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
+                    await this.sleep(retryAfter);
+                    return this.makeRequest(method, path, data, attempt + 1);
+                }
+                throw new RateLimitError(retryAfter);
+            }
+            // Handle service unavailable (503)
+            if (response.status === 503 && this.shouldRetry && attempt < this.maxRetries) {
+                const retryDelay = 10;
+                console.log(`Service unavailable. Retrying after ${retryDelay} seconds...`);
+                await this.sleep(retryDelay);
+                return this.makeRequest(method, path, data, attempt + 1);
+            }
+            // Handle other errors
+            const text = await response.text();
+            throw new Error(`Request failed with status ${response.status}: ${text}`);
+        }
+        catch (error) {
+            // Handle network errors with retry
+            if (error instanceof TypeError && this.shouldRetry && attempt < this.maxRetries) {
+                const retryDelay = 3;
+                console.log(`Network error. Retrying after ${retryDelay} seconds...`);
+                await this.sleep(retryDelay);
+                return this.makeRequest(method, path, data, attempt + 1);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Insert a document into a collection
+     */
+    async insert(collection, record, ttl) {
+        const data = { ...record };
+        if (ttl) {
+            data.ttl_duration = ttl;
+        }
+        return this.makeRequest('POST', `/api/insert/${collection}`, data);
+    }
+    /**
+     * Find documents in a collection
+     *
+     * @param collection - Collection name
+     * @param query - Query object or QueryBuilder instance
+     * @returns Array of matching records
+     *
+     * @example
+     * ```typescript
+     * // Using QueryBuilder
+     * const results = await client.find("users",
+     *   new QueryBuilder()
+     *     .eq("status", "active")
+     *     .gt("age", 18)
+     *     .sortDesc("created_at")
+     *     .limit(10)
+     * );
+     *
+     * // Using plain Query object
+     * const results = await client.find("users", { limit: 10 });
+     * ```
+     */
+    async find(collection, query = {}) {
+        const queryObj = query instanceof query_builder_1.QueryBuilder ? query.build() : query;
+        return this.makeRequest('POST', `/api/find/${collection}`, queryObj);
+    }
+    /**
+     * Find a document by ID
+     */
+    async findByID(collection, id) {
+        return this.makeRequest('GET', `/api/find/${collection}/${id}`);
+    }
+    /**
+     * Update a document
+     */
+    async update(collection, id, record) {
+        return this.makeRequest('PUT', `/api/update/${collection}/${id}`, record);
+    }
+    /**
+     * Delete a document
+     */
+    async delete(collection, id) {
+        await this.makeRequest('DELETE', `/api/delete/${collection}/${id}`);
+    }
+    /**
+     * Batch insert multiple documents
+     */
+    async batchInsert(collection, records) {
+        const inserts = records.map(data => ({ data }));
+        const result = await this.makeRequest('POST', `/api/batch/insert/${collection}`, { inserts });
+        return result.successful.map(id => ({ id }));
+    }
+    /**
+     * Batch update multiple documents
+     */
+    async batchUpdate(collection, updates) {
+        const result = await this.makeRequest('PUT', `/api/batch/update/${collection}`, { updates });
+        return result.successful.map(id => ({ id }));
+    }
+    /**
+     * Batch delete multiple documents
+     */
+    async batchDelete(collection, ids) {
+        const deletes = ids.map(id => ({ id }));
+        const result = await this.makeRequest('DELETE', `/api/batch/delete/${collection}`, { deletes });
+        return result.successful.length;
+    }
+    /**
+     * Set a key-value pair
+     */
+    async kvSet(key, value) {
+        await this.makeRequest('POST', `/api/kv/set/${encodeURIComponent(key)}`, { value });
+    }
+    /**
+     * Get a value by key
+     */
+    async kvGet(key) {
+        const result = await this.makeRequest('GET', `/api/kv/get/${encodeURIComponent(key)}`);
+        return result.value;
+    }
+    /**
+     * Delete a key
+     */
+    async kvDelete(key) {
+        await this.makeRequest('DELETE', `/api/kv/delete/${encodeURIComponent(key)}`);
+    }
+    /**
+     * List all collections
+     */
+    async listCollections() {
+        const result = await this.makeRequest('GET', '/api/collections');
+        return result.collections;
+    }
+    /**
+     * Delete a collection
+     */
+    async deleteCollection(collection) {
+        await this.makeRequest('DELETE', `/api/collections/${collection}`);
+    }
+    /**
+     * Create a collection with schema
+     *
+     * @param collection - Collection name
+     * @param schema - Schema definition or SchemaBuilder instance
+     *
+     * @example
+     * ```typescript
+     * const schema = new SchemaBuilder()
+     *   .addField("name", new FieldTypeSchemaBuilder("string").required())
+     *   .addField("email", new FieldTypeSchemaBuilder("string").unique())
+     *   .addField("age", new FieldTypeSchemaBuilder("number").range(0, 150));
+     *
+     * await client.createCollection("users", schema);
+     * ```
+     */
+    async createCollection(collection, schema) {
+        const schemaObj = schema instanceof schema_1.SchemaBuilder ? schema.build() : schema;
+        await this.makeRequest('POST', `/api/collections/${collection}`, schemaObj);
+    }
+    /**
+     * Get collection metadata and schema
+     *
+     * @param collection - Collection name
+     * @returns Collection metadata including schema and analytics
+     */
+    async getCollection(collection) {
+        return this.makeRequest('GET', `/api/collections/${collection}`);
+    }
+    /**
+     * Get collection schema
+     *
+     * @param collection - Collection name
+     * @returns The collection schema
+     */
+    async getSchema(collection) {
+        const metadata = await this.getCollection(collection);
+        return metadata.collection;
+    }
+    /**
+     * Search documents in a collection using full-text, vector, or hybrid search
+     *
+     * @param collection - Collection name
+     * @param searchQuery - Search query object or SearchQueryBuilder instance
+     * @returns Search response with results and metadata
+     *
+     * @example
+     * ```typescript
+     * // Full-text search
+     * const results = await client.search("users",
+     *   new SearchQueryBuilder("john")
+     *     .fields(["name", "email"])
+     *     .fuzzy(true)
+     *     .limit(10)
+     * );
+     *
+     * // Vector search
+     * const results = await client.search("documents",
+     *   new SearchQueryBuilder("")
+     *     .vector([0.1, 0.2, 0.3, ...])
+     *     .vectorK(5)
+     * );
+     *
+     * // Hybrid search
+     * const results = await client.search("products",
+     *   new SearchQueryBuilder("laptop")
+     *     .vector([0.1, 0.2, ...])
+     *     .textWeight(0.7)
+     *     .vectorWeight(0.3)
+     * );
+     * ```
+     */
+    async search(collection, searchQuery) {
+        const queryObj = searchQuery instanceof search_1.SearchQueryBuilder ? searchQuery.build() : searchQuery;
+        return this.makeRequest('POST', `/api/search/${collection}`, queryObj);
+    }
+    // ========== Chat Methods ==========
+    /**
+     * Create a new chat session
+     */
+    async createChatSession(request) {
+        return this.makeRequest('POST', '/api/chat', request);
+    }
+    /**
+     * Send a message in an existing chat session
+     */
+    async chatMessage(sessionId, request) {
+        return this.makeRequest('POST', `/api/chat/${sessionId}/messages`, request);
+    }
+    /**
+     * Get a chat session by ID
+     */
+    async getChatSession(sessionId) {
+        return this.makeRequest('GET', `/api/chat/${sessionId}`);
+    }
+    /**
+     * List all chat sessions
+     */
+    async listChatSessions(query) {
+        const params = new URLSearchParams();
+        if (query?.limit)
+            params.append('limit', query.limit.toString());
+        if (query?.skip)
+            params.append('skip', query.skip.toString());
+        if (query?.sort)
+            params.append('sort', query.sort);
+        const queryString = params.toString();
+        const path = queryString ? `/api/chat?${queryString}` : '/api/chat';
+        return this.makeRequest('GET', path);
+    }
+    /**
+     * Get messages from a chat session
+     */
+    async getChatSessionMessages(sessionId, query) {
+        const params = new URLSearchParams();
+        if (query?.limit)
+            params.append('limit', query.limit.toString());
+        if (query?.skip)
+            params.append('skip', query.skip.toString());
+        if (query?.sort)
+            params.append('sort', query.sort);
+        const queryString = params.toString();
+        const path = queryString ? `/api/chat/${sessionId}/messages?${queryString}` : `/api/chat/${sessionId}/messages`;
+        return this.makeRequest('GET', path);
+    }
+    /**
+     * Update a chat session
+     */
+    async updateChatSession(sessionId, request) {
+        return this.makeRequest('PUT', `/api/chat/${sessionId}`, request);
+    }
+    /**
+     * Branch a chat session
+     */
+    async branchChatSession(request) {
+        return this.makeRequest('POST', '/api/chat/branch', request);
+    }
+    /**
+     * Delete a chat session
+     */
+    async deleteChatSession(sessionId) {
+        await this.makeRequest('DELETE', `/api/chat/${sessionId}`);
+    }
+    /**
+     * Regenerate an AI response message
+     */
+    async regenerateMessage(sessionId, messageId) {
+        return this.makeRequest('POST', `/api/chat/${sessionId}/messages/${messageId}/regenerate`);
+    }
+    /**
+     * Update a specific message
+     */
+    async updateChatMessage(sessionId, messageId, content) {
+        await this.makeRequest('PUT', `/api/chat/${sessionId}/messages/${messageId}`, { content });
+    }
+    /**
+     * Delete a specific message
+     */
+    async deleteChatMessage(sessionId, messageId) {
+        await this.makeRequest('DELETE', `/api/chat/${sessionId}/messages/${messageId}`);
+    }
+    /**
+     * Toggle the "forgotten" status of a message
+     */
+    async toggleForgottenMessage(sessionId, messageId, forgotten) {
+        await this.makeRequest('PATCH', `/api/chat/${sessionId}/messages/${messageId}/forgotten`, { forgotten });
+    }
+    /**
+     * Merge multiple chat sessions into one
+     */
+    async mergeChatSessions(request) {
+        return this.makeRequest('POST', '/api/chat/merge', request);
+    }
+    /**
+     * Create a WebSocket client
+     */
+    websocket(wsURL) {
+        return new WebSocketClient(wsURL, this.token);
+    }
+}
+exports.EkoDBClient = EkoDBClient;
+/**
+ * WebSocket client for real-time queries
+ */
+class WebSocketClient {
+    constructor(wsURL, token) {
+        this.ws = null;
+        this.wsURL = wsURL;
+        this.token = token;
+    }
+    /**
+     * Connect to WebSocket
+     */
+    async connect() {
+        if (this.ws)
+            return;
+        // Dynamic import for Node.js WebSocket
+        const WebSocket = (await Promise.resolve().then(() => __importStar(require('ws')))).default;
+        let url = this.wsURL;
+        if (!url.endsWith('/api/ws')) {
+            url += '/api/ws';
+        }
+        this.ws = new WebSocket(url, {
+            headers: {
+                'Authorization': `Bearer ${this.token}`,
+            },
+        });
+        return new Promise((resolve, reject) => {
+            this.ws.on('open', () => resolve());
+            this.ws.on('error', (err) => reject(err));
+        });
+    }
+    /**
+     * Find all records in a collection via WebSocket
+     */
+    async findAll(collection) {
+        await this.connect();
+        const messageId = Date.now().toString();
+        const request = {
+            type: 'FindAll',
+            messageId,
+            payload: { collection },
+        };
+        return new Promise((resolve, reject) => {
+            this.ws.send(JSON.stringify(request));
+            this.ws.once('message', (data) => {
+                const response = JSON.parse(data.toString());
+                if (response.type === 'Error') {
+                    reject(new Error(response.message));
+                }
+                else {
+                    resolve(response.payload?.data || []);
+                }
+            });
+            this.ws.once('error', reject);
+        });
+    }
+    /**
+     * Close the WebSocket connection
+     */
+    close() {
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+    }
+}
+exports.WebSocketClient = WebSocketClient;

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { EkoDBClient, WebSocketClient, MergeStrategy, RateLimitError } from './client';
+export { QueryBuilder, SortOrder } from './query-builder';
+export { SearchQueryBuilder } from './search';
+export { SchemaBuilder, FieldTypeSchemaBuilder, VectorIndexAlgorithm, DistanceMetric } from './schema';
+export { JoinBuilder } from './join';
+export type { SearchQuery, SearchResult, SearchResponse } from './search';
+export type { Schema, FieldTypeSchema, IndexConfig, CollectionMetadata } from './schema';
+export type { JoinConfig } from './join';
+export type { Record, Query, BatchOperationResult, ClientConfig, RateLimitInfo, CollectionConfig, ChatRequest, CreateChatSessionRequest, ChatMessageRequest, TokenUsage, ChatResponse, ChatSession, ChatSessionResponse, ListSessionsQuery, ListSessionsResponse, GetMessagesQuery, GetMessagesResponse, UpdateSessionRequest, MergeSessionsRequest } from './client';

package/dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JoinBuilder = exports.DistanceMetric = exports.VectorIndexAlgorithm = exports.FieldTypeSchemaBuilder = exports.SchemaBuilder = exports.SearchQueryBuilder = exports.SortOrder = exports.QueryBuilder = exports.RateLimitError = exports.MergeStrategy = exports.WebSocketClient = exports.EkoDBClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "EkoDBClient", { enumerable: true, get: function () { return client_1.EkoDBClient; } });
+Object.defineProperty(exports, "WebSocketClient", { enumerable: true, get: function () { return client_1.WebSocketClient; } });
+Object.defineProperty(exports, "MergeStrategy", { enumerable: true, get: function () { return client_1.MergeStrategy; } });
+Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return client_1.RateLimitError; } });
+var query_builder_1 = require("./query-builder");
+Object.defineProperty(exports, "QueryBuilder", { enumerable: true, get: function () { return query_builder_1.QueryBuilder; } });
+Object.defineProperty(exports, "SortOrder", { enumerable: true, get: function () { return query_builder_1.SortOrder; } });
+var search_1 = require("./search");
+Object.defineProperty(exports, "SearchQueryBuilder", { enumerable: true, get: function () { return search_1.SearchQueryBuilder; } });
+var schema_1 = require("./schema");
+Object.defineProperty(exports, "SchemaBuilder", { enumerable: true, get: function () { return schema_1.SchemaBuilder; } });
+Object.defineProperty(exports, "FieldTypeSchemaBuilder", { enumerable: true, get: function () { return schema_1.FieldTypeSchemaBuilder; } });
+Object.defineProperty(exports, "VectorIndexAlgorithm", { enumerable: true, get: function () { return schema_1.VectorIndexAlgorithm; } });
+Object.defineProperty(exports, "DistanceMetric", { enumerable: true, get: function () { return schema_1.DistanceMetric; } });
+var join_1 = require("./join");
+Object.defineProperty(exports, "JoinBuilder", { enumerable: true, get: function () { return join_1.JoinBuilder; } });

package/dist/join.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Join support for multi-collection queries
+ *
+ * This module provides support for joining data across multiple collections,
+ * similar to SQL joins but with document-oriented semantics.
+ */
+/**
+ * Configuration for joining collections
+ */
+export interface JoinConfig {
+    /** Target collections to join with */
+    collections: string[];
+    /** Field in the current collection */
+    local_field: string;
+    /** Field in the target collection(s) */
+    foreign_field: string;
+    /** Name of the field to store joined data */
+    as_field: string;
+}
+/**
+ * Builder for constructing join configurations
+ *
+ * @example
+ * ```typescript
+ * // Single collection join
+ * const join = JoinBuilder.single("users", "user_id", "id", "user");
+ *
+ * // Multi-collection join
+ * const join = JoinBuilder.multi(
+ *   ["users", "profiles", "settings"],
+ *   "user_id",
+ *   "id",
+ *   "user_info"
+ * );
+ *
+ * // Use in query
+ * const query = new QueryBuilder()
+ *   .eq("status", "active")
+ *   .join(join)
+ *   .build();
+ * ```
+ */
+export declare class JoinBuilder {
+    private config;
+    private constructor();
+    /**
+     * Create a join with a single collection
+     *
+     * @param collection - Target collection name
+     * @param localField - Field in the current collection
+     * @param foreignField - Field in the target collection
+     * @param asField - Name of the field to store joined data
+     */
+    static single(collection: string, localField: string, foreignField: string, asField: string): JoinConfig;
+    /**
+     * Create a join with multiple collections
+     *
+     * @param collections - Array of target collection names
+     * @param localField - Field in the current collection
+     * @param foreignField - Field in the target collections
+     * @param asField - Name of the field to store joined data
+     */
+    static multi(collections: string[], localField: string, foreignField: string, asField: string): JoinConfig;
+    /**
+     * Build the final JoinConfig
+     */
+    build(): JoinConfig;
+}