@ekodb/ekodb-client 0.11.0 → 0.13.0

package/dist/client.js

@@ -36,7 +36,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WebSocketClient = exports.EkoDBClient = exports.MergeStrategy = exports.RateLimitError = exports.SerializationFormat = void 0;
+exports.WebSocketClient = exports.EventStream = exports.EkoDBClient = exports.MergeStrategy = exports.RateLimitError = exports.SerializationFormat = void 0;
 const msgpack_1 = require("@msgpack/msgpack");
 const query_builder_1 = require("./query-builder");
 const schema_1 = require("./schema");
@@ -66,6 +66,7 @@ var MergeStrategy;
     MergeStrategy["Chronological"] = "Chronological";
     MergeStrategy["Summarized"] = "Summarized";
     MergeStrategy["LatestOnly"] = "LatestOnly";
+    MergeStrategy["Interleaved"] = "Interleaved";
 })(MergeStrategy || (exports.MergeStrategy = MergeStrategy = {}));
 class EkoDBClient {
     constructor(config, apiKey) {
@@ -77,7 +78,6 @@ class EkoDBClient {
             this.apiKey = apiKey;
             this.shouldRetry = true;
             this.maxRetries = 3;
-            this.timeout = 30000;
             this.format = SerializationFormat.MessagePack; // Default to MessagePack for 2-3x performance
         }
         else {
@@ -85,7 +85,6 @@ class EkoDBClient {
             this.apiKey = config.apiKey;
             this.shouldRetry = config.shouldRetry ?? true;
             this.maxRetries = config.maxRetries ?? 3;
-            this.timeout = config.timeout ?? 30000;
             this.format = config.format ?? SerializationFormat.MessagePack; // Default to MessagePack for 2-3x performance
         }
     }
@@ -135,6 +134,20 @@ class EkoDBClient {
         const result = (await response.json());
         this.token = result.token;
     }
+    /**
+     * Get the current authentication token.
+     * Returns null if not yet authenticated. Call refreshToken() first.
+     */
+    getToken() {
+        return this.token;
+    }
+    /**
+     * Clear the cached authentication token.
+     * The next request will trigger a fresh token exchange.
+     */
+    clearTokenCache() {
+        this.token = null;
+    }
     /**
      * Extract rate limit information from response headers
      */
@@ -325,6 +338,26 @@ class EkoDBClient {
     async findById(collection, id) {
         return this.makeRequest("GET", `/api/find/${collection}/${id}`);
     }
+    /**
+     * Find a document by ID with field projection
+     * @param collection - Collection name
+     * @param id - Document ID
+     * @param selectFields - Fields to include in the result
+     * @param excludeFields - Fields to exclude from the result
+     */
+    async findByIdWithProjection(collection, id, selectFields, excludeFields) {
+        const params = new URLSearchParams();
+        if (selectFields?.length) {
+            params.append("select_fields", selectFields.join(","));
+        }
+        if (excludeFields?.length) {
+            params.append("exclude_fields", excludeFields.join(","));
+        }
+        const url = params.toString()
+            ? `/api/find/${collection}/${id}?${params.toString()}`
+            : `/api/find/${collection}/${id}`;
+        return this.makeRequest("GET", url);
+    }
     /**
      * Update a document
      * @param collection - Collection name
@@ -345,6 +378,40 @@ class EkoDBClient {
             : `/api/update/${collection}/${id}`;
         return this.makeRequest("PUT", url, record);
     }
+    /**
+     * Apply an atomic field action to a single field of a record.
+     *
+     * Use this instead of `update()` for safe concurrent modifications like
+     * incrementing counters, pushing to arrays, or arithmetic operations.
+     *
+     * @param collection - Collection name
+     * @param id - Record ID
+     * @param action - The atomic action: increment, decrement, multiply, divide, modulo,
+     *                 push, pop, shift, unshift, remove, append, clear
+     * @param field - The field name to apply the action to
+     * @param value - The value for the action (omit for pop/shift/clear)
+     */
+    async updateWithAction(collection, id, action, field, value) {
+        const url = `/api/update/${collection}/${id}/action/${action}`;
+        return this.makeRequest("PUT", url, {
+            field,
+            value: value ?? null,
+        });
+    }
+    /**
+     * Apply a sequence of atomic field actions to a record in a single request.
+     *
+     * All actions are applied atomically — the record is fetched once, all actions
+     * run in order, and the result is persisted in a single update.
+     *
+     * @param collection - Collection name
+     * @param id - Record ID
+     * @param actions - Array of [action, field, value] tuples
+     */
+    async updateWithActionSequence(collection, id, actions) {
+        const url = `/api/update/sequence/${collection}/${id}`;
+        return this.makeRequest("PUT", url, actions);
+    }
     /**
      * Delete a document
      * @param collection - Collection name
@@ -771,6 +838,36 @@ class EkoDBClient {
         // Ensure all parameters from SearchQuery are sent to server
         return this.makeRequest("POST", `/api/search/${collection}`, query, 0, true);
     }
+    /**
+     * Get distinct (unique) values for a field across all records in a collection.
+     *
+     * Results are deduplicated and sorted alphabetically. Supports an optional filter
+     * to restrict which records are examined.
+     *
+     * @param collection - Collection name
+     * @param field - Field to get distinct values for
+     * @param options - Optional filter and bypass flags
+     *
+     * @example
+     * // All distinct statuses
+     * const resp = await client.distinctValues("orders", "status");
+     * console.log(resp.values); // ["active", "cancelled", "shipped"]
+     *
+     * // Only statuses for US orders
+     * const resp = await client.distinctValues("orders", "status", {
+     *   filter: { type: "Condition", content: { field: "region", operator: "Eq", value: "us" } }
+     * });
+     */
+    async distinctValues(collection, field, options = {}) {
+        const body = {};
+        if (options.filter !== undefined)
+            body.filter = options.filter;
+        if (options.bypassRipple !== undefined)
+            body.bypass_ripple = options.bypassRipple;
+        if (options.bypassCache !== undefined)
+            body.bypass_cache = options.bypassCache;
+        return this.makeRequest("POST", `/api/distinct/${collection}/${field}`, body, 0, true);
+    }
     /**
      * Health check - verify the ekoDB server is responding
      */
@@ -790,6 +887,25 @@ class EkoDBClient {
     async createChatSession(request) {
         return this.makeRequest("POST", "/api/chat", request, 0, true);
     }
+    /**
+     * Stateless raw LLM completion — no session, no history, no RAG.
+     *
+     * Sends a system prompt and user message directly to the LLM via ekoDB
+     * and returns the raw text response without any context injection or
+     * conversation management. Use this for structured-output tasks such as
+     * planning where the response must be parsed programmatically.
+     *
+     * @example
+     * const resp = await client.rawCompletion({
+     *   system_prompt: "You are a helpful assistant.",
+     *   message: "Summarize this in JSON.",
+     *   max_tokens: 2048,
+     * });
+     * console.log(resp.content);
+     */
+    async rawCompletion(request) {
+        return this.makeRequest("POST", "/api/chat/complete", request, 0, true);
+    }
     /**
      * Send a message in an existing chat session
      */
@@ -889,6 +1005,14 @@ class EkoDBClient {
     async getChatModels() {
         return this.makeRequest("GET", "/api/chat_models", undefined, 0, true);
     }
+    /**
+     * Get all built-in server-side chat tool definitions.
+     * Returns a list of tool objects with name, description, and parameters fields.
+     * Used by planning agents to discover available tools dynamically.
+     */
+    async getChatTools() {
+        return this.makeRequest("GET", "/api/chat/tools", undefined, 0, true);
+    }
     /**
      * Get available models for a specific provider
      * @param provider - Provider name (e.g., "openai", "anthropic", "perplexity")
@@ -1026,13 +1150,7 @@ class EkoDBClient {
     }
     // ========== RAG Helper Methods ==========
     /**
-     * Generate embeddings for text using ekoDB's native Functions
-     *
-     * This helper simplifies embedding generation by:
-     * 1. Creating a temporary collection with the text
-     * 2. Running a Script with FindAll + Embed Functions
-     * 3. Extracting and returning the embedding vector
-     * 4. Cleaning up temporary resources
+     * Generate embeddings for a single text
      *
      * @param text - The text to generate embeddings for
      * @param model - The embedding model to use (e.g., "text-embedding-3-small")
@@ -1048,52 +1166,28 @@ class EkoDBClient {
      * ```
      */
     async embed(text, model) {
-        const tempCollection = `embed_temp_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
-        try {
-            // Insert temporary record with the text
-            await this.insert(tempCollection, { text }, undefined);
-            // Create Script with FindAll + Embed Functions
-            const tempLabel = `embed_script_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
-            const script = {
-                label: tempLabel,
-                name: "Generate Embedding",
-                description: "Temporary script for embedding generation",
-                version: "1.0",
-                parameters: {},
-                functions: [
-                    {
-                        type: "FindAll",
-                        collection: tempCollection,
-                    },
-                    {
-                        type: "Embed",
-                        input_field: "text",
-                        output_field: "embedding",
-                        model: model,
-                    },
-                ],
-                tags: [],
-            };
-            // Save and execute the script
-            const scriptId = await this.saveScript(script);
-            const result = await this.callScript(scriptId, undefined);
-            // Clean up
-            await this.deleteScript(scriptId).catch(() => { });
-            await this.deleteCollection(tempCollection).catch(() => { });
-            // Extract embedding from result
-            if (result.records && result.records.length > 0) {
-                const record = result.records[0];
-                if (record.embedding && Array.isArray(record.embedding)) {
-                    return record.embedding;
-                }
-            }
-            throw new Error("Failed to extract embedding from result");
-        }
-        catch (error) {
-            // Ensure cleanup even on error
-            await this.deleteCollection(tempCollection).catch(() => { });
-            throw error;
+        const response = await this.embedRequest({ text, model });
+        if (response.embeddings.length === 0) {
+            throw new Error("No embedding returned");
         }
+        return response.embeddings[0];
+    }
+    /**
+     * Generate embeddings for multiple texts in a single batch request
+     *
+     * @param texts - Array of texts to generate embeddings for
+     * @param model - The embedding model to use
+     * @returns Array of embedding vectors
+     */
+    async embedBatch(texts, model) {
+        const response = await this.embedRequest({ texts, model });
+        return response.embeddings;
+    }
+    /**
+     * Internal: make embed API request
+     */
+    async embedRequest(request) {
+        return this.makeRequest("POST", "/api/embed", request, 0, true);
     }
     /**
      * Perform text search without embeddings
@@ -1179,22 +1273,64 @@ class EkoDBClient {
     }
 }
 exports.EkoDBClient = EkoDBClient;
+/** EventEmitter-like interface for subscriptions and chat streams. */
+class EventStream {
+    constructor() {
+        this.listeners = new Map();
+        this._closed = false;
+    }
+    on(event, listener) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, []);
+        }
+        this.listeners.get(event).push(listener);
+        return this;
+    }
+    /** @internal */
+    emit(event, data) {
+        const handlers = this.listeners.get(event);
+        if (handlers) {
+            for (const handler of handlers) {
+                handler(data);
+            }
+        }
+    }
+    get closed() {
+        return this._closed;
+    }
+    /** @internal */
+    close() {
+        this._closed = true;
+        this.emit("close");
+    }
+}
+exports.EventStream = EventStream;
 /**
- * WebSocket client for real-time queries
+ * WebSocket client for real-time queries, subscriptions, and chat streaming.
  */
 class WebSocketClient {
     constructor(wsURL, token) {
         this.ws = null;
+        this.dispatcherRunning = false;
+        // Dispatcher state
+        this.pendingRequests = new Map();
+        this.subscriptions = new Map();
+        this.chatStreams = new Map();
+        this.registerToolsAck = null;
+        this.messageCounter = 0;
         this.wsURL = wsURL;
         this.token = token;
     }
+    genMessageId() {
+        const counter = this.messageCounter++;
+        return `${Date.now()}-${counter}-${Math.random().toString(36).slice(2, 8)}`;
+    }
     /**
-     * Connect to WebSocket
+     * Connect and start the dispatcher.
      */
-    async connect() {
-        if (this.ws)
+    async ensureConnected() {
+        if (this.ws && this.dispatcherRunning)
             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")) {
@@ -1205,43 +1341,277 @@ class WebSocketClient {
                 Authorization: `Bearer ${this.token}`,
             },
         });
-        return new Promise((resolve, reject) => {
+        await new Promise((resolve, reject) => {
             this.ws.on("open", () => resolve());
             this.ws.on("error", (err) => reject(err));
         });
+        this.spawnDispatcher();
+    }
+    spawnDispatcher() {
+        if (this.dispatcherRunning)
+            return;
+        this.dispatcherRunning = true;
+        this.ws.on("message", (data) => {
+            try {
+                const msg = JSON.parse(data.toString());
+                this.routeMessage(msg);
+            }
+            catch {
+                // Ignore malformed messages
+            }
+        });
+        this.ws.on("close", () => {
+            this.dispatcherRunning = false;
+            // Notify all pending requests
+            for (const [, pending] of this.pendingRequests) {
+                pending.reject(new Error("WebSocket connection closed"));
+            }
+            this.pendingRequests.clear();
+            // Close all chat streams
+            for (const [, stream] of this.chatStreams) {
+                stream.emit("event", { type: "error", error: "Connection closed" });
+                stream.close();
+            }
+            this.chatStreams.clear();
+            // Close all subscriptions
+            for (const [, stream] of this.subscriptions) {
+                stream.close();
+            }
+            this.subscriptions.clear();
+            this.ws = null;
+        });
+    }
+    routeMessage(msg) {
+        switch (msg.type) {
+            case "Success":
+            case "Error": {
+                const messageId = msg.payload?.message_id || msg.payload?.messageId;
+                if (messageId && this.pendingRequests.has(messageId)) {
+                    const pending = this.pendingRequests.get(messageId);
+                    this.pendingRequests.delete(messageId);
+                    if (msg.type === "Error") {
+                        pending.reject(new Error(msg.message || "Unknown error"));
+                    }
+                    else {
+                        pending.resolve(msg.payload);
+                    }
+                }
+                else if (this.registerToolsAck) {
+                    const ack = this.registerToolsAck;
+                    this.registerToolsAck = null;
+                    if (msg.type === "Error") {
+                        ack.reject(new Error(msg.message || "Tool registration failed"));
+                    }
+                    else {
+                        ack.resolve(msg.payload);
+                    }
+                }
+                break;
+            }
+            case "MutationNotification": {
+                const payload = msg.payload;
+                const notification = {
+                    collection: payload.collection,
+                    event: payload.event,
+                    recordIds: payload.record_ids || payload.recordIds || [],
+                    records: payload.records,
+                    timestamp: payload.timestamp,
+                };
+                for (const [collection, stream] of this.subscriptions) {
+                    if (collection === notification.collection) {
+                        stream.emit("mutation", notification);
+                    }
+                }
+                break;
+            }
+            case "ChatStreamChunk": {
+                const chatId = msg.payload?.chat_id || msg.payload?.chatId;
+                const stream = this.chatStreams.get(chatId);
+                if (stream) {
+                    stream.emit("event", {
+                        type: "chunk",
+                        content: msg.payload.content,
+                    });
+                }
+                break;
+            }
+            case "ChatStreamEnd": {
+                const chatId = msg.payload?.chat_id || msg.payload?.chatId;
+                const stream = this.chatStreams.get(chatId);
+                if (stream) {
+                    stream.emit("event", {
+                        type: "end",
+                        messageId: msg.payload.message_id || msg.payload.messageId || "",
+                        tokenUsage: msg.payload.token_usage || msg.payload.tokenUsage,
+                        toolCallHistory: msg.payload.tool_call_history || msg.payload.toolCallHistory,
+                        executionTimeMs: msg.payload.execution_time_ms || msg.payload.executionTimeMs || 0,
+                    });
+                    this.chatStreams.delete(chatId);
+                    stream.close();
+                }
+                break;
+            }
+            case "ChatStreamError": {
+                const chatId = msg.payload?.chat_id || msg.payload?.chatId;
+                const stream = this.chatStreams.get(chatId);
+                if (stream) {
+                    stream.emit("event", {
+                        type: "error",
+                        error: msg.payload.error || msg.payload.message || "Unknown error",
+                    });
+                    this.chatStreams.delete(chatId);
+                    stream.close();
+                }
+                break;
+            }
+            case "ClientToolCall": {
+                const chatId = msg.payload?.chat_id || msg.payload?.chatId;
+                const stream = this.chatStreams.get(chatId);
+                if (stream) {
+                    stream.emit("event", {
+                        type: "toolCall",
+                        chatId,
+                        callId: msg.payload.call_id || msg.payload.callId,
+                        toolName: msg.payload.tool_name || msg.payload.toolName,
+                        arguments: msg.payload.arguments,
+                    });
+                }
+                break;
+            }
+        }
+    }
+    async sendRequest(request) {
+        await this.ensureConnected();
+        const messageId = request.messageId || request.message_id;
+        return new Promise((resolve, reject) => {
+            this.pendingRequests.set(messageId, { resolve, reject });
+            try {
+                this.ws.send(JSON.stringify(request));
+            }
+            catch (err) {
+                this.pendingRequests.delete(messageId);
+                reject(err);
+            }
+        });
     }
     /**
-     * Find all records in a collection via WebSocket
+     * Find all records in a collection via WebSocket.
      */
     async findAll(collection) {
-        await this.connect();
-        const messageId = Date.now().toString();
-        const request = {
+        const messageId = this.genMessageId();
+        const payload = await this.sendRequest({
             type: "FindAll",
             messageId,
             payload: { collection },
+        });
+        return payload?.data || [];
+    }
+    /**
+     * Subscribe to mutation notifications on a collection.
+     * Returns an EventStream that emits "mutation" events.
+     */
+    async subscribe(collection, options) {
+        await this.ensureConnected();
+        if (this.subscriptions.has(collection)) {
+            throw new Error(`Already subscribed to collection "${collection}"`);
+        }
+        const messageId = this.genMessageId();
+        const stream = new EventStream();
+        this.subscriptions.set(collection, stream);
+        const request = {
+            type: "Subscribe",
+            messageId,
+            payload: {
+                collection,
+                ...(options?.filterField && { filter_field: options.filterField }),
+                ...(options?.filterValue && { filter_value: options.filterValue }),
+            },
         };
-        return new Promise((resolve, reject) => {
+        // Send subscribe request and wait for ack
+        try {
+            await this.sendRequest(request);
+        }
+        catch (err) {
+            this.subscriptions.delete(collection);
+            throw err;
+        }
+        return stream;
+    }
+    /**
+     * Send a chat message and receive a streaming response.
+     * Returns an EventStream that emits "event" with ChatStreamEvent objects.
+     */
+    async chatSend(chatId, message, options) {
+        await this.ensureConnected();
+        if (this.chatStreams.has(chatId)) {
+            throw new Error(`Chat stream already active for chatId "${chatId}"`);
+        }
+        const stream = new EventStream();
+        this.chatStreams.set(chatId, stream);
+        const request = {
+            type: "ChatSend",
+            payload: {
+                chat_id: chatId,
+                message,
+                ...(options?.bypassRipple != null && {
+                    bypass_ripple: options.bypassRipple,
+                }),
+                ...(options?.clientTools && { client_tools: options.clientTools }),
+                ...(options?.maxIterations != null && {
+                    max_iterations: options.maxIterations,
+                }),
+                ...(options?.confirmTools && { confirm_tools: options.confirmTools }),
+                ...(options?.excludeTools && { exclude_tools: options.excludeTools }),
+            },
+        };
+        this.ws.send(JSON.stringify(request));
+        return stream;
+    }
+    /**
+     * Register client-side tools for a chat session.
+     */
+    async registerClientTools(chatId, tools) {
+        await this.ensureConnected();
+        const request = {
+            type: "RegisterClientTools",
+            payload: {
+                chat_id: chatId,
+                tools,
+            },
+        };
+        await new Promise((resolve, reject) => {
+            this.registerToolsAck = {
+                resolve: () => resolve(),
+                reject: (err) => reject(err),
+            };
             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
+     * Send a tool result back to the server during a chat stream.
+     */
+    async sendToolResult(chatId, callId, success, result, error) {
+        await this.ensureConnected();
+        const request = {
+            type: "ClientToolResult",
+            payload: {
+                chat_id: chatId,
+                call_id: callId,
+                success,
+                ...(result !== undefined && { result }),
+                ...(error !== undefined && { error }),
+            },
+        };
+        this.ws.send(JSON.stringify(request));
+    }
+    /**
+     * Close the WebSocket connection.
      */
     close() {
         if (this.ws) {
             this.ws.close();
             this.ws = null;
+            this.dispatcherRunning = false;
         }
     }
 }