@ekodb/ekodb-client 0.21.0 → 0.22.0

package/dist/client.d.ts

@@ -895,6 +895,17 @@ export declare class EkoDBClient {
      * Unblocks ekoDB's tool loop so it can feed the result to the LLM.
      */
     submitChatToolResult(chatId: string, callId: string, success: boolean, result?: any, error?: string): Promise<void>;
+    /**
+     * Send a client tool keepalive (liveness ping) for an in-flight SSE chat stream.
+     *
+     * This is NOT a result: it does not unblock the tool loop or feed anything to the
+     * LLM. It simply resets the server's per-tool wait deadline (governed by
+     * `client_tool_timeout_secs`, default 60s) so that slow user confirmations or
+     * long-running client tools don't get the turn timed out before
+     * {@link submitChatToolResult} arrives. Send it periodically while a client tool
+     * is still working. See ekoDB#530.
+     */
+    submitChatToolKeepalive(chatId: string, callId: string): Promise<void>;
     /**
      * Send a message in an existing chat session via SSE streaming.
      *

package/dist/client.js

@@ -1249,6 +1249,22 @@ class EkoDBClient {
             ...(error !== undefined && { error }),
         }, 0, true);
     }
+    /**
+     * Send a client tool keepalive (liveness ping) for an in-flight SSE chat stream.
+     *
+     * This is NOT a result: it does not unblock the tool loop or feed anything to the
+     * LLM. It simply resets the server's per-tool wait deadline (governed by
+     * `client_tool_timeout_secs`, default 60s) so that slow user confirmations or
+     * long-running client tools don't get the turn timed out before
+     * {@link submitChatToolResult} arrives. Send it periodically while a client tool
+     * is still working. See ekoDB#530.
+     */
+    async submitChatToolKeepalive(chatId, callId) {
+        await this.makeRequest("POST", `/api/chat/${encodeURIComponent(chatId)}/tool-result`, {
+            call_id: callId,
+            keepalive: true,
+        }, 0, true);
+    }
     /**
      * Send a message in an existing chat session via SSE streaming.
      *

package/dist/client.test.js

@@ -8,6 +8,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const vitest_1 = require("vitest");
 const client_1 = require("./client");
+const search_1 = require("./search");
 // Mock fetch globally
 const mockFetch = vitest_1.vi.fn();
 global.fetch = mockFetch;
@@ -345,6 +346,22 @@ function mockErrorResponse(status, message) {
         (0, vitest_1.expect)(result.total).toBe(2);
     });
     // Note: textSearch and hybridSearch require specific mock setup - covered by integration tests
+    (0, vitest_1.it)("builds a vector search query with a metadata filter", () => {
+        const filter = {
+            type: "Condition",
+            content: { field: "category", operator: "Eq", value: "ml" },
+        };
+        const query = new search_1.SearchQueryBuilder("test")
+            .vector([0.1, 0.2, 0.3])
+            .filters(filter)
+            .build();
+        (0, vitest_1.expect)(query.filters).toEqual(filter);
+        (0, vitest_1.expect)(query.vector).toEqual([0.1, 0.2, 0.3]);
+    });
+    (0, vitest_1.it)("omits filters when not set", () => {
+        const query = new search_1.SearchQueryBuilder("test").build();
+        (0, vitest_1.expect)(query.filters).toBeUndefined();
+    });
 });
 // ============================================================================
 // KV Batch Operations Tests
@@ -2318,6 +2335,25 @@ function mockErrorResponse(status, message) {
     });
 });
 // ============================================================================
+// submitChatToolKeepalive Tests
+// ============================================================================
+(0, vitest_1.describe)("submitChatToolKeepalive", () => {
+    (0, vitest_1.it)("sends keepalive to correct endpoint", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({});
+        await client.submitChatToolKeepalive("chat-123", "call-456");
+        (0, vitest_1.expect)(mockFetch).toHaveBeenCalledTimes(2);
+        const call = mockFetch.mock.calls[1];
+        (0, vitest_1.expect)(call[0]).toContain("/api/chat/chat-123/tool-result");
+        const body = JSON.parse(call[1].body);
+        (0, vitest_1.expect)(body.call_id).toBe("call-456");
+        (0, vitest_1.expect)(body.keepalive).toBe(true);
+        (0, vitest_1.expect)(body.success).toBeUndefined();
+        (0, vitest_1.expect)(body.result).toBeUndefined();
+    });
+});
+// ============================================================================
 // subscribeSSE Tests
 // ============================================================================
 (0, vitest_1.describe)("subscribeSSE", () => {

package/dist/search.d.ts

@@ -52,6 +52,12 @@ export interface SearchQuery {
     select_fields?: string[];
     /** Exclude these fields from results */
     exclude_fields?: string[];
+    /**
+     * Metadata pre-filter for text/vector/hybrid search. A canonical QueryExpression
+     * (the same shape produced by `QueryBuilder.build().filter`); only records
+     * matching the filter are considered as candidates before ranking.
+     */
+    filters?: any;
 }
 /**
  * Search result with score and matched fields
@@ -177,6 +183,12 @@ export declare class SearchQueryBuilder {
      * Exclude specific fields from results
      */
     excludeFields(fields: string[]): this;
+    /**
+     * Set a metadata pre-filter for text/vector/hybrid search. Accepts a canonical
+     * QueryExpression (the same shape produced by `QueryBuilder.build().filter`);
+     * only records matching the filter are considered before ranking.
+     */
+    filters(filter: any): this;
     /**
      * Build the final SearchQuery object
      */

package/dist/search.js

@@ -176,6 +176,15 @@ class SearchQueryBuilder {
         this.query.exclude_fields = fields;
         return this;
     }
+    /**
+     * Set a metadata pre-filter for text/vector/hybrid search. Accepts a canonical
+     * QueryExpression (the same shape produced by `QueryBuilder.build().filter`);
+     * only records matching the filter are considered before ranking.
+     */
+    filters(filter) {
+        this.query.filters = filter;
+        return this;
+    }
     /**
      * Build the final SearchQuery object
      */

package/package.json

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

package/src/client.test.ts

@@ -7,6 +7,7 @@
 
 import { describe, it, expect, beforeEach, vi, afterEach } from "vitest";
 import { EkoDBClient, SerializationFormat, extractRecordId } from "./client";
+import { SearchQueryBuilder } from "./search";
 
 // Mock fetch globally
 const mockFetch = vi.fn();
@@ -489,6 +490,25 @@ describe("EkoDBClient search", () => {
   });
 
   // Note: textSearch and hybridSearch require specific mock setup - covered by integration tests
+
+  it("builds a vector search query with a metadata filter", () => {
+    const filter = {
+      type: "Condition",
+      content: { field: "category", operator: "Eq", value: "ml" },
+    };
+    const query = new SearchQueryBuilder("test")
+      .vector([0.1, 0.2, 0.3])
+      .filters(filter)
+      .build();
+
+    expect(query.filters).toEqual(filter);
+    expect(query.vector).toEqual([0.1, 0.2, 0.3]);
+  });
+
+  it("omits filters when not set", () => {
+    const query = new SearchQueryBuilder("test").build();
+    expect(query.filters).toBeUndefined();
+  });
 });
 
 // ============================================================================
@@ -3049,6 +3069,29 @@ describe("submitChatToolResult", () => {
   });
 });
 
+// ============================================================================
+// submitChatToolKeepalive Tests
+// ============================================================================
+
+describe("submitChatToolKeepalive", () => {
+  it("sends keepalive to correct endpoint", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({});
+
+    await client.submitChatToolKeepalive("chat-123", "call-456");
+
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+    const call = mockFetch.mock.calls[1];
+    expect(call[0]).toContain("/api/chat/chat-123/tool-result");
+    const body = JSON.parse(call[1].body);
+    expect(body.call_id).toBe("call-456");
+    expect(body.keepalive).toBe(true);
+    expect(body.success).toBeUndefined();
+    expect(body.result).toBeUndefined();
+  });
+});
+
 // ============================================================================
 // subscribeSSE Tests
 // ============================================================================

package/src/client.ts

@@ -2014,6 +2014,29 @@ export class EkoDBClient {
     );
   }
 
+  /**
+   * Send a client tool keepalive (liveness ping) for an in-flight SSE chat stream.
+   *
+   * This is NOT a result: it does not unblock the tool loop or feed anything to the
+   * LLM. It simply resets the server's per-tool wait deadline (governed by
+   * `client_tool_timeout_secs`, default 60s) so that slow user confirmations or
+   * long-running client tools don't get the turn timed out before
+   * {@link submitChatToolResult} arrives. Send it periodically while a client tool
+   * is still working. See ekoDB#530.
+   */
+  async submitChatToolKeepalive(chatId: string, callId: string): Promise<void> {
+    await this.makeRequest(
+      "POST",
+      `/api/chat/${encodeURIComponent(chatId)}/tool-result`,
+      {
+        call_id: callId,
+        keepalive: true,
+      },
+      0,
+      true,
+    );
+  }
+
   /**
    * Send a message in an existing chat session via SSE streaming.
    *

package/src/search.ts

@@ -59,6 +59,14 @@ export interface SearchQuery {
   select_fields?: string[];
   /** Exclude these fields from results */
   exclude_fields?: string[];
+
+  // Metadata pre-filter
+  /**
+   * Metadata pre-filter for text/vector/hybrid search. A canonical QueryExpression
+   * (the same shape produced by `QueryBuilder.build().filter`); only records
+   * matching the filter are considered as candidates before ranking.
+   */
+  filters?: any;
 }
 
 /**
@@ -275,6 +283,16 @@ export class SearchQueryBuilder {
     return this;
   }
 
+  /**
+   * Set a metadata pre-filter for text/vector/hybrid search. Accepts a canonical
+   * QueryExpression (the same shape produced by `QueryBuilder.build().filter`);
+   * only records matching the filter are considered before ranking.
+   */
+  filters(filter: any): this {
+    this.query.filters = filter;
+    return this;
+  }
+
   /**
    * Build the final SearchQuery object
    */