@ekodb/ekodb-client 0.14.0 → 0.15.0

package/dist/client.d.ts

@@ -170,6 +170,7 @@ export interface ChatMessageRequest {
     force_summarize?: boolean;
     max_iterations?: number;
     tool_config?: ToolConfig;
+    llm_model?: string;
 }
 export interface TokenUsage {
     prompt_tokens: number;
@@ -766,6 +767,20 @@ export declare class EkoDBClient {
      * Health check - verify the ekoDB server is responding
      */
     health(): Promise<boolean>;
+    /**
+     * Execute a tool via ekoDB's server-side tool pipeline.
+     *
+     * Calls POST /api/chat/tools/execute which goes through the same
+     * execute_tool function as the LLM tool-calling loop — with all
+     * collection filtering, permission enforcement, and internal collection
+     * blocking. No LLM round-trip.
+     *
+     * @returns The tool result if executed, or null if the server doesn't
+     * support the endpoint (older ekoDB versions).
+     */
+    executeTool(toolName: string, params: {
+        [key: string]: any;
+    }, chatId?: string): Promise<any | null>;
     /**
      * Create a new chat session
      */

package/dist/client.js

@@ -930,6 +930,43 @@ class EkoDBClient {
         }
     }
     // ========== Chat Methods ==========
+    /**
+     * Execute a tool via ekoDB's server-side tool pipeline.
+     *
+     * Calls POST /api/chat/tools/execute which goes through the same
+     * execute_tool function as the LLM tool-calling loop — with all
+     * collection filtering, permission enforcement, and internal collection
+     * blocking. No LLM round-trip.
+     *
+     * @returns The tool result if executed, or null if the server doesn't
+     * support the endpoint (older ekoDB versions).
+     */
+    async executeTool(toolName, params, chatId) {
+        const body = { tool: toolName, params };
+        if (chatId) {
+            body.chat_id = chatId;
+        }
+        try {
+            const result = await this.makeRequest("POST", "/api/chat/tools/execute", body, 0, true);
+            if (result.success) {
+                return result.result;
+            }
+            else {
+                throw new Error(result.error || "tool execution failed");
+            }
+        }
+        catch (err) {
+            // Server doesn't have the endpoint (404) or route mismatch (405)
+            // Parse status from makeRequest error format: "Request failed with status NNN: ..."
+            const message = String(err?.message ?? "");
+            const match = message.match(/Request failed with status (\d+):/);
+            const status = match ? parseInt(match[1], 10) : undefined;
+            if (status === 404 || status === 405) {
+                return null;
+            }
+            throw err;
+        }
+    }
     /**
      * Create a new chat session
      */

package/dist/client.test.js

@@ -805,6 +805,57 @@ function mockErrorResponse(status, message) {
     });
 });
 // ============================================================================
+// executeTool Tests
+// ============================================================================
+(0, vitest_1.describe)("EkoDBClient executeTool", () => {
+    (0, vitest_1.it)("executes tool successfully", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({
+            success: true,
+            result: { count: 42 },
+        });
+        const result = await client.executeTool("count_records", {
+            collection: "users",
+        });
+        (0, vitest_1.expect)(result).toEqual({ count: 42 });
+    });
+    (0, vitest_1.it)("passes chat_id when provided", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({
+            success: true,
+            result: { value: "hello" },
+        });
+        const result = await client.executeTool("kv_get", { key: "greeting" }, "chat_456");
+        (0, vitest_1.expect)(result).toEqual({ value: "hello" });
+        // Verify the request body included chat_id
+        const lastCall = mockFetch.mock.calls[1];
+        const body = JSON.parse(lastCall[1].body);
+        (0, vitest_1.expect)(body.chat_id).toBe("chat_456");
+        (0, vitest_1.expect)(body.tool).toBe("kv_get");
+        (0, vitest_1.expect)(body.params).toEqual({ key: "greeting" });
+    });
+    (0, vitest_1.it)("throws on tool execution failure", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({
+            success: false,
+            error: "permission denied",
+        });
+        await (0, vitest_1.expect)(client.executeTool("delete_collection", { collection: "system" })).rejects.toThrow("permission denied");
+    });
+    (0, vitest_1.it)("returns null when server does not support endpoint", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockErrorResponse(404, "Not Found");
+        const result = await client.executeTool("count_records", {
+            collection: "users",
+        });
+        (0, vitest_1.expect)(result).toBeNull();
+    });
+});
+// ============================================================================
 // Chat Models Tests
 // ============================================================================
 (0, vitest_1.describe)("EkoDBClient chat models", () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekodb/ekodb-client",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Official TypeScript/JavaScript client for ekoDB",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/client.test.ts

@@ -1105,6 +1105,80 @@ describe("Convenience methods", () => {
   });
 });
 
+// ============================================================================
+// executeTool Tests
+// ============================================================================
+
+describe("EkoDBClient executeTool", () => {
+  it("executes tool successfully", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({
+      success: true,
+      result: { count: 42 },
+    });
+
+    const result = await client.executeTool("count_records", {
+      collection: "users",
+    });
+
+    expect(result).toEqual({ count: 42 });
+  });
+
+  it("passes chat_id when provided", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({
+      success: true,
+      result: { value: "hello" },
+    });
+
+    const result = await client.executeTool(
+      "kv_get",
+      { key: "greeting" },
+      "chat_456",
+    );
+
+    expect(result).toEqual({ value: "hello" });
+
+    // Verify the request body included chat_id
+    const lastCall = mockFetch.mock.calls[1];
+    const body = JSON.parse(lastCall[1].body);
+    expect(body.chat_id).toBe("chat_456");
+    expect(body.tool).toBe("kv_get");
+    expect(body.params).toEqual({ key: "greeting" });
+  });
+
+  it("throws on tool execution failure", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({
+      success: false,
+      error: "permission denied",
+    });
+
+    await expect(
+      client.executeTool("delete_collection", { collection: "system" }),
+    ).rejects.toThrow("permission denied");
+  });
+
+  it("returns null when server does not support endpoint", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockErrorResponse(404, "Not Found");
+
+    const result = await client.executeTool("count_records", {
+      collection: "users",
+    });
+
+    expect(result).toBeNull();
+  });
+});
+
 // ============================================================================
 // Chat Models Tests
 // ============================================================================

package/src/client.ts

@@ -203,6 +203,7 @@ export interface ChatMessageRequest {
   force_summarize?: boolean;
   max_iterations?: number;
   tool_config?: ToolConfig;
+  llm_model?: string;
 }
 
 export interface TokenUsage {
@@ -1552,6 +1553,54 @@ export class EkoDBClient {
 
   // ========== Chat Methods ==========
 
+  /**
+   * Execute a tool via ekoDB's server-side tool pipeline.
+   *
+   * Calls POST /api/chat/tools/execute which goes through the same
+   * execute_tool function as the LLM tool-calling loop — with all
+   * collection filtering, permission enforcement, and internal collection
+   * blocking. No LLM round-trip.
+   *
+   * @returns The tool result if executed, or null if the server doesn't
+   * support the endpoint (older ekoDB versions).
+   */
+  async executeTool(
+    toolName: string,
+    params: { [key: string]: any },
+    chatId?: string,
+  ): Promise<any | null> {
+    const body: { [key: string]: any } = { tool: toolName, params };
+    if (chatId) {
+      body.chat_id = chatId;
+    }
+
+    try {
+      const result = await this.makeRequest<{ [key: string]: any }>(
+        "POST",
+        "/api/chat/tools/execute",
+        body,
+        0,
+        true, // Force JSON for chat operations
+      );
+
+      if (result.success) {
+        return result.result;
+      } else {
+        throw new Error(result.error || "tool execution failed");
+      }
+    } catch (err: any) {
+      // Server doesn't have the endpoint (404) or route mismatch (405)
+      // Parse status from makeRequest error format: "Request failed with status NNN: ..."
+      const message = String(err?.message ?? "");
+      const match = message.match(/Request failed with status (\d+):/);
+      const status = match ? parseInt(match[1], 10) : undefined;
+      if (status === 404 || status === 405) {
+        return null;
+      }
+      throw err;
+    }
+  }
+
   /**
    * Create a new chat session
    */