@ekodb/ekodb-client 0.21.0 → 0.23.0

package/dist/client.d.ts

@@ -508,16 +508,30 @@ export declare class EkoDBClient {
     batchInsert(collection: string, records: Record[], options?: BatchInsertOptions): Promise<BatchOperationResult>;
     /**
      * Batch update multiple documents
+     * @param collection - Collection name
+     * @param updates - Array of updates ({ id, data, bypassRipple? })
+     * @param options - Optional parameters (bypassRipple, transactionId). When
+     *   `transactionId` is set, the batch is staged into that MVCC transaction
+     *   (sent as the `transaction_id` query param) instead of committed
+     *   immediately — mirrors the single-record update.
      */
     batchUpdate(collection: string, updates: Array<{
         id: string;
         data: Record;
         bypassRipple?: boolean;
-    }>): Promise<BatchOperationResult>;
+    }>, options?: BatchUpdateOptions): Promise<BatchOperationResult>;
     /**
      * Batch delete multiple documents
+     * @param collection - Collection name
+     * @param ids - Document IDs to delete
+     * @param bypassRipple - Optional flag to bypass ripple propagation (legacy
+     *   positional form, kept for back-compat)
+     * @param options - Optional parameters (bypassRipple, transactionId). When
+     *   `transactionId` is set, the batch is staged into that MVCC transaction
+     *   (sent as the `transaction_id` query param) instead of committed
+     *   immediately — mirrors the single-record delete.
      */
-    batchDelete(collection: string, ids: string[], bypassRipple?: boolean): Promise<BatchOperationResult>;
+    batchDelete(collection: string, ids: string[], bypassRipple?: boolean, options?: BatchDeleteOptions): Promise<BatchOperationResult>;
     /**
      * Set a key-value pair with optional TTL
      * @param key - The key to set
@@ -895,6 +909,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

@@ -599,24 +599,61 @@ class EkoDBClient {
     }
     /**
      * Batch update multiple documents
+     * @param collection - Collection name
+     * @param updates - Array of updates ({ id, data, bypassRipple? })
+     * @param options - Optional parameters (bypassRipple, transactionId). When
+     *   `transactionId` is set, the batch is staged into that MVCC transaction
+     *   (sent as the `transaction_id` query param) instead of committed
+     *   immediately — mirrors the single-record update.
      */
-    async batchUpdate(collection, updates) {
+    async batchUpdate(collection, updates, options) {
+        const params = new URLSearchParams();
+        if (options?.bypassRipple !== undefined) {
+            params.append("bypass_ripple", String(options.bypassRipple));
+        }
+        if (options?.transactionId) {
+            params.append("transaction_id", options.transactionId);
+        }
         const formattedUpdates = updates.map((u) => ({
             id: u.id,
             data: u.data,
             bypass_ripple: u.bypassRipple,
         }));
-        return this.makeRequest("PUT", `/api/batch/update/${encodeURIComponent(collection)}`, { updates: formattedUpdates });
+        const url = params.toString()
+            ? `/api/batch/update/${encodeURIComponent(collection)}?${params.toString()}`
+            : `/api/batch/update/${encodeURIComponent(collection)}`;
+        return this.makeRequest("PUT", url, {
+            updates: formattedUpdates,
+        });
     }
     /**
      * Batch delete multiple documents
-     */
-    async batchDelete(collection, ids, bypassRipple) {
+     * @param collection - Collection name
+     * @param ids - Document IDs to delete
+     * @param bypassRipple - Optional flag to bypass ripple propagation (legacy
+     *   positional form, kept for back-compat)
+     * @param options - Optional parameters (bypassRipple, transactionId). When
+     *   `transactionId` is set, the batch is staged into that MVCC transaction
+     *   (sent as the `transaction_id` query param) instead of committed
+     *   immediately — mirrors the single-record delete.
+     */
+    async batchDelete(collection, ids, bypassRipple, options) {
+        // bypass_ripple is sent per-item in the body (existing behavior). The
+        // effective value prefers the explicit positional arg, falling back to the
+        // options object so callers can use either form.
+        const effectiveBypassRipple = bypassRipple !== undefined ? bypassRipple : options?.bypassRipple;
+        const params = new URLSearchParams();
+        if (options?.transactionId) {
+            params.append("transaction_id", options.transactionId);
+        }
         const deletes = ids.map((id) => ({
             id: id,
-            bypass_ripple: bypassRipple,
+            bypass_ripple: effectiveBypassRipple,
         }));
-        return this.makeRequest("DELETE", `/api/batch/delete/${encodeURIComponent(collection)}`, { deletes });
+        const url = params.toString()
+            ? `/api/batch/delete/${encodeURIComponent(collection)}?${params.toString()}`
+            : `/api/batch/delete/${encodeURIComponent(collection)}`;
+        return this.makeRequest("DELETE", url, { deletes });
     }
     /**
      * Set a key-value pair with optional TTL
@@ -1249,6 +1286,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.
      *
@@ -1517,7 +1570,11 @@ class EkoDBClient {
      * List all functions, optionally filtered by tags
      */
     async listFunctions(tags) {
-        const params = tags ? `?tags=${tags.join(",")}` : "";
+        // URLSearchParams percent-encodes the value (`&`/`=`/`,`), so a tag
+        // containing query-reserved characters can't smuggle extra params.
+        const params = tags
+            ? `?${new URLSearchParams({ tags: tags.join(",") }).toString()}`
+            : "";
         return this.makeRequest("GET", `/api/functions${params}`);
     }
     /**
@@ -1564,7 +1621,11 @@ class EkoDBClient {
      * @returns Array of user functions
      */
     async listUserFunctions(tags) {
-        const params = tags ? `?tags=${tags.join(",")}` : "";
+        // URLSearchParams percent-encodes the value (`&`/`=`/`,`), so a tag
+        // containing query-reserved characters can't smuggle extra params.
+        const params = tags
+            ? `?${new URLSearchParams({ tags: tags.join(",") }).toString()}`
+            : "";
         return this.makeRequest("GET", `/api/functions${params}`, undefined, 0, true);
     }
     /**

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;
@@ -226,6 +227,56 @@ function mockErrorResponse(status, message) {
         const result = await client.batchDelete("users", ["id_1", "id_2"]);
         (0, vitest_1.expect)(result.successful).toHaveLength(2);
     });
+    (0, vitest_1.it)("batchInsert sends transaction_id as a query param", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({ successful: ["id_1"], failed: [] });
+        await client.batchInsert("users", [{ name: "A" }], {
+            transactionId: "tx_123",
+        });
+        const [url, init] = mockFetch.mock.calls[1];
+        (0, vitest_1.expect)(init.method).toBe("POST");
+        const parsed = new URL(url);
+        (0, vitest_1.expect)(parsed.pathname).toBe("/api/batch/insert/users");
+        (0, vitest_1.expect)(parsed.searchParams.get("transaction_id")).toBe("tx_123");
+    });
+    (0, vitest_1.it)("batchUpdate sends transaction_id as a query param", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({ successful: ["id_1"], failed: [] });
+        await client.batchUpdate("users", [{ id: "id_1", data: { name: "B" } }], {
+            transactionId: "tx_123",
+        });
+        const [url, init] = mockFetch.mock.calls[1];
+        (0, vitest_1.expect)(init.method).toBe("PUT");
+        const parsed = new URL(url);
+        (0, vitest_1.expect)(parsed.pathname).toBe("/api/batch/update/users");
+        (0, vitest_1.expect)(parsed.searchParams.get("transaction_id")).toBe("tx_123");
+    });
+    (0, vitest_1.it)("batchDelete sends transaction_id as a query param", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({ successful: ["id_1", "id_2"], failed: [] });
+        await client.batchDelete("users", ["id_1", "id_2"], undefined, {
+            transactionId: "tx_123",
+        });
+        const [url, init] = mockFetch.mock.calls[1];
+        (0, vitest_1.expect)(init.method).toBe("DELETE");
+        const parsed = new URL(url);
+        (0, vitest_1.expect)(parsed.pathname).toBe("/api/batch/delete/users");
+        (0, vitest_1.expect)(parsed.searchParams.get("transaction_id")).toBe("tx_123");
+    });
+    (0, vitest_1.it)("batch ops without transaction_id send no such query param (additive)", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({ successful: ["id_1"], failed: [] });
+        // Legacy call sites: no options object at all.
+        await client.batchUpdate("users", [{ id: "id_1", data: { name: "B" } }]);
+        const [url] = mockFetch.mock.calls[1];
+        const parsed = new URL(url);
+        (0, vitest_1.expect)(parsed.searchParams.get("transaction_id")).toBeNull();
+        (0, vitest_1.expect)(parsed.search).toBe("");
+    });
 });
 // ============================================================================
 // KV Store Tests
@@ -345,6 +396,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 +2385,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", () => {
@@ -2467,6 +2553,19 @@ function mockErrorResponse(status, message) {
 // URLSearchParams, so they are out of scope here.
 // ============================================================================
 (0, vitest_1.describe)("EkoDBClient URL path segment encoding", () => {
+    (0, vitest_1.it)("listUserFunctions percent-encodes reserved chars in the tags query param", async () => {
+        // A tag with query-reserved characters must be percent-encoded, not
+        // concatenated raw into `?tags=...`. Without encoding, `a&injected=1`
+        // splits into tags="a" plus a smuggled `injected=1` query param.
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse([]);
+        await client.listUserFunctions(["a&injected=1", "b"]);
+        const [url] = mockFetch.mock.calls[1];
+        const parsed = new URL(url);
+        (0, vitest_1.expect)(parsed.searchParams.get("tags")).toBe("a&injected=1,b");
+        (0, vitest_1.expect)(parsed.searchParams.has("injected")).toBe(false);
+    });
     (0, vitest_1.it)("findById encodes a reserved-char id (a/b -> a%2Fb)", async () => {
         const client = createTestClient();
         mockTokenResponse();

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.23.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();
@@ -312,6 +313,72 @@ describe("EkoDBClient batch operations", () => {
 
     expect(result.successful).toHaveLength(2);
   });
+
+  it("batchInsert sends transaction_id as a query param", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({ successful: ["id_1"], failed: [] });
+
+    await client.batchInsert("users", [{ name: "A" }], {
+      transactionId: "tx_123",
+    });
+
+    const [url, init] = mockFetch.mock.calls[1];
+    expect(init.method).toBe("POST");
+    const parsed = new URL(url as string);
+    expect(parsed.pathname).toBe("/api/batch/insert/users");
+    expect(parsed.searchParams.get("transaction_id")).toBe("tx_123");
+  });
+
+  it("batchUpdate sends transaction_id as a query param", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({ successful: ["id_1"], failed: [] });
+
+    await client.batchUpdate("users", [{ id: "id_1", data: { name: "B" } }], {
+      transactionId: "tx_123",
+    });
+
+    const [url, init] = mockFetch.mock.calls[1];
+    expect(init.method).toBe("PUT");
+    const parsed = new URL(url as string);
+    expect(parsed.pathname).toBe("/api/batch/update/users");
+    expect(parsed.searchParams.get("transaction_id")).toBe("tx_123");
+  });
+
+  it("batchDelete sends transaction_id as a query param", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({ successful: ["id_1", "id_2"], failed: [] });
+
+    await client.batchDelete("users", ["id_1", "id_2"], undefined, {
+      transactionId: "tx_123",
+    });
+
+    const [url, init] = mockFetch.mock.calls[1];
+    expect(init.method).toBe("DELETE");
+    const parsed = new URL(url as string);
+    expect(parsed.pathname).toBe("/api/batch/delete/users");
+    expect(parsed.searchParams.get("transaction_id")).toBe("tx_123");
+  });
+
+  it("batch ops without transaction_id send no such query param (additive)", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({ successful: ["id_1"], failed: [] });
+
+    // Legacy call sites: no options object at all.
+    await client.batchUpdate("users", [{ id: "id_1", data: { name: "B" } }]);
+
+    const [url] = mockFetch.mock.calls[1];
+    const parsed = new URL(url as string);
+    expect(parsed.searchParams.get("transaction_id")).toBeNull();
+    expect(parsed.search).toBe("");
+  });
 });
 
 // ============================================================================
@@ -489,6 +556,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 +3135,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
 // ============================================================================
@@ -3238,6 +3347,23 @@ describe("extractRecordId", () => {
 // ============================================================================
 
 describe("EkoDBClient URL path segment encoding", () => {
+  it("listUserFunctions percent-encodes reserved chars in the tags query param", async () => {
+    // A tag with query-reserved characters must be percent-encoded, not
+    // concatenated raw into `?tags=...`. Without encoding, `a&injected=1`
+    // splits into tags="a" plus a smuggled `injected=1` query param.
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse([]);
+
+    await client.listUserFunctions(["a&injected=1", "b"]);
+
+    const [url] = mockFetch.mock.calls[1];
+    const parsed = new URL(url as string);
+    expect(parsed.searchParams.get("tags")).toBe("a&injected=1,b");
+    expect(parsed.searchParams.has("injected")).toBe(false);
+  });
+
   it("findById encodes a reserved-char id (a/b -> a%2Fb)", async () => {
     const client = createTestClient();
 

package/src/client.ts

@@ -1051,40 +1051,77 @@ export class EkoDBClient {
 
   /**
    * Batch update multiple documents
+   * @param collection - Collection name
+   * @param updates - Array of updates ({ id, data, bypassRipple? })
+   * @param options - Optional parameters (bypassRipple, transactionId). When
+   *   `transactionId` is set, the batch is staged into that MVCC transaction
+   *   (sent as the `transaction_id` query param) instead of committed
+   *   immediately — mirrors the single-record update.
    */
   async batchUpdate(
     collection: string,
     updates: Array<{ id: string; data: Record; bypassRipple?: boolean }>,
+    options?: BatchUpdateOptions,
   ): Promise<BatchOperationResult> {
+    const params = new URLSearchParams();
+    if (options?.bypassRipple !== undefined) {
+      params.append("bypass_ripple", String(options.bypassRipple));
+    }
+    if (options?.transactionId) {
+      params.append("transaction_id", options.transactionId);
+    }
+
     const formattedUpdates = updates.map((u) => ({
       id: u.id,
       data: u.data,
       bypass_ripple: u.bypassRipple,
     }));
-    return this.makeRequest<BatchOperationResult>(
-      "PUT",
-      `/api/batch/update/${encodeURIComponent(collection)}`,
-      { updates: formattedUpdates },
-    );
+    const url = params.toString()
+      ? `/api/batch/update/${encodeURIComponent(collection)}?${params.toString()}`
+      : `/api/batch/update/${encodeURIComponent(collection)}`;
+
+    return this.makeRequest<BatchOperationResult>("PUT", url, {
+      updates: formattedUpdates,
+    });
   }
 
   /**
    * Batch delete multiple documents
+   * @param collection - Collection name
+   * @param ids - Document IDs to delete
+   * @param bypassRipple - Optional flag to bypass ripple propagation (legacy
+   *   positional form, kept for back-compat)
+   * @param options - Optional parameters (bypassRipple, transactionId). When
+   *   `transactionId` is set, the batch is staged into that MVCC transaction
+   *   (sent as the `transaction_id` query param) instead of committed
+   *   immediately — mirrors the single-record delete.
    */
   async batchDelete(
     collection: string,
     ids: string[],
     bypassRipple?: boolean,
+    options?: BatchDeleteOptions,
   ): Promise<BatchOperationResult> {
+    // bypass_ripple is sent per-item in the body (existing behavior). The
+    // effective value prefers the explicit positional arg, falling back to the
+    // options object so callers can use either form.
+    const effectiveBypassRipple =
+      bypassRipple !== undefined ? bypassRipple : options?.bypassRipple;
+
+    const params = new URLSearchParams();
+    if (options?.transactionId) {
+      params.append("transaction_id", options.transactionId);
+    }
+
     const deletes = ids.map((id) => ({
       id: id,
-      bypass_ripple: bypassRipple,
+      bypass_ripple: effectiveBypassRipple,
     }));
-    return this.makeRequest<BatchOperationResult>(
-      "DELETE",
-      `/api/batch/delete/${encodeURIComponent(collection)}`,
-      { deletes },
-    );
+    const url = params.toString()
+      ? `/api/batch/delete/${encodeURIComponent(collection)}?${params.toString()}`
+      : `/api/batch/delete/${encodeURIComponent(collection)}`;
+
+    return this.makeRequest<BatchOperationResult>("DELETE", url, { deletes });
   }
 
   /**
@@ -2014,6 +2051,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.
    *
@@ -2426,7 +2486,11 @@ export class EkoDBClient {
    * List all functions, optionally filtered by tags
    */
   async listFunctions(tags?: string[]): Promise<UserFunction[]> {
-    const params = tags ? `?tags=${tags.join(",")}` : "";
+    // URLSearchParams percent-encodes the value (`&`/`=`/`,`), so a tag
+    // containing query-reserved characters can't smuggle extra params.
+    const params = tags
+      ? `?${new URLSearchParams({ tags: tags.join(",") }).toString()}`
+      : "";
     return this.makeRequest<UserFunction[]>("GET", `/api/functions${params}`);
   }
 
@@ -2506,7 +2570,11 @@ export class EkoDBClient {
    * @returns Array of user functions
    */
   async listUserFunctions(tags?: string[]): Promise<UserFunction[]> {
-    const params = tags ? `?tags=${tags.join(",")}` : "";
+    // URLSearchParams percent-encodes the value (`&`/`=`/`,`), so a tag
+    // containing query-reserved characters can't smuggle extra params.
+    const params = tags
+      ? `?${new URLSearchParams({ tags: tags.join(",") }).toString()}`
+      : "";
     return this.makeRequest<UserFunction[]>(
       "GET",
       `/api/functions${params}`,

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
    */