@ekodb/ekodb-client 0.20.0 → 0.22.0

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;
@@ -250,6 +251,12 @@ function mockErrorResponse(status, message) {
         mockJsonResponse({ deleted: true });
         await (0, vitest_1.expect)(client.kvDelete("my_key")).resolves.not.toThrow();
     });
+    (0, vitest_1.it)("clears KV store", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({ message: "success" });
+        await (0, vitest_1.expect)(client.kvClear()).resolves.not.toThrow();
+    });
     (0, vitest_1.it)("checks KV exists", async () => {
         const client = createTestClient();
         mockTokenResponse();
@@ -294,6 +301,13 @@ function mockErrorResponse(status, message) {
         (0, vitest_1.expect)(result).toContain("users");
         (0, vitest_1.expect)(result).toHaveLength(3);
     });
+    (0, vitest_1.it)("lists user collections (excludes internal)", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({ collections: ["users", "posts"] });
+        const result = await client.listUserCollections();
+        (0, vitest_1.expect)(result).toEqual(["users", "posts"]);
+    });
     (0, vitest_1.it)("deletes collection", async () => {
         const client = createTestClient();
         mockTokenResponse();
@@ -332,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
@@ -723,6 +753,64 @@ function mockErrorResponse(status, message) {
         (0, vitest_1.expect)(result).toBeDefined();
     });
 });
+(0, vitest_1.describe)("bypass_ripple on the transactional read path", () => {
+    (0, vitest_1.it)("findById sends bypass_ripple AND transaction_id together (query params)", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({ id: "user_123", name: "Alice" });
+        await client.findById("users", "user_123", {
+            bypassRipple: true,
+            transactionId: "tx_123",
+        });
+        const [url, init] = mockFetch.mock.calls[1];
+        (0, vitest_1.expect)(init.method).toBe("GET");
+        const parsed = new URL(url);
+        (0, vitest_1.expect)(parsed.searchParams.get("bypass_ripple")).toBe("true");
+        (0, vitest_1.expect)(parsed.searchParams.get("transaction_id")).toBe("tx_123");
+    });
+    (0, vitest_1.it)("findById sends bypass_ripple=false explicitly alongside transaction_id", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({ id: "user_123", name: "Alice" });
+        await client.findById("users", "user_123", {
+            bypassRipple: false,
+            transactionId: "tx_123",
+        });
+        const [url] = mockFetch.mock.calls[1];
+        const parsed = new URL(url);
+        (0, vitest_1.expect)(parsed.searchParams.get("bypass_ripple")).toBe("false");
+        (0, vitest_1.expect)(parsed.searchParams.get("transaction_id")).toBe("tx_123");
+    });
+    (0, vitest_1.it)("find sends bypass_ripple AND transaction_id together as query params", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse([{ id: "user_1", name: "Alice" }]);
+        await client.find("users", { limit: 10 }, { bypassRipple: true, transactionId: "tx_123" });
+        const [url, init] = mockFetch.mock.calls[1];
+        (0, vitest_1.expect)(init.method).toBe("POST");
+        const parsed = new URL(url);
+        // bypass_ripple is a query param (like every other method), not in the body.
+        (0, vitest_1.expect)(parsed.searchParams.get("transaction_id")).toBe("tx_123");
+        (0, vitest_1.expect)(parsed.searchParams.get("bypass_ripple")).toBe("true");
+        const body = JSON.parse(init.body);
+        (0, vitest_1.expect)(body.bypass_ripple).toBeUndefined();
+        (0, vitest_1.expect)(body.limit).toBe(10);
+    });
+    (0, vitest_1.it)("find hoists bypass_ripple from the query object into the query string", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse([]);
+        // A query object carrying bypass_ripple, as QueryBuilder.bypassRipple() builds.
+        await client.find("users", { limit: 5, bypass_ripple: true });
+        const [url, init] = mockFetch.mock.calls[1];
+        const parsed = new URL(url);
+        // Hoisted to the query string, removed from the body.
+        (0, vitest_1.expect)(parsed.searchParams.get("bypass_ripple")).toBe("true");
+        const body = JSON.parse(init.body);
+        (0, vitest_1.expect)(body.bypass_ripple).toBeUndefined();
+        (0, vitest_1.expect)(body.limit).toBe(5);
+    });
+});
 // ============================================================================
 // Convenience Methods Tests
 // ============================================================================
@@ -1340,6 +1428,16 @@ function mockErrorResponse(status, message) {
         const dataCall = calls[1];
         (0, vitest_1.expect)(dataCall[0]).toBe("http://localhost:8080/api/find/users/123");
     });
+    (0, vitest_1.it)("appends transaction_id when a transactionId is given", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({ id: "123", name: "Alice" });
+        await client.findByIdWithProjection("users", "123", ["name"], undefined, "txn-abc");
+        const calls = global.fetch.mock.calls;
+        const dataCall = calls[1];
+        (0, vitest_1.expect)(dataCall[0]).toContain("transaction_id=txn-abc");
+        (0, vitest_1.expect)(dataCall[0]).toContain("select_fields=name");
+    });
 });
 // ============================================================================
 // Goal CRUD Tests
@@ -2237,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", () => {
@@ -2376,3 +2493,92 @@ function mockErrorResponse(status, message) {
         (0, vitest_1.expect)((0, client_1.extractRecordId)({ _id: "underscore" })).toBe("underscore");
     });
 });
+// ============================================================================
+// URL Path Segment Encoding Tests
+//
+// Every caller-supplied path segment (collection, id, function label, chat
+// model/provider, session/message ids, etc.) must be percent-encoded so a
+// reserved char (`/`, space, `#`, `?`) can't break the URL. This matches the
+// Rust and Go clients. Query parameters are NOT path segments and go through
+// URLSearchParams, so they are out of scope here.
+// ============================================================================
+(0, vitest_1.describe)("EkoDBClient URL path segment encoding", () => {
+    (0, vitest_1.it)("findById encodes a reserved-char id (a/b -> a%2Fb)", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({ id: "a/b", name: "Alice" });
+        await client.findById("users", "a/b");
+        const [url] = mockFetch.mock.calls[1];
+        (0, vitest_1.expect)(url).toContain("/api/find/users/a%2Fb");
+        (0, vitest_1.expect)(url).not.toContain("/api/find/users/a/b");
+    });
+    (0, vitest_1.it)("findById encodes a reserved-char collection", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({ id: "user_123" });
+        await client.findById("my coll", "user_123");
+        const [url] = mockFetch.mock.calls[1];
+        (0, vitest_1.expect)(url).toContain("/api/find/my%20coll/user_123");
+    });
+    (0, vitest_1.it)("findById leaves a normal id unchanged (/api/find/users/123)", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({ id: "123", name: "Alice" });
+        await client.findById("users", "123");
+        const [url] = mockFetch.mock.calls[1];
+        (0, vitest_1.expect)(url).toContain("/api/find/users/123");
+        (0, vitest_1.expect)(url).not.toContain("%2F");
+        (0, vitest_1.expect)(url).not.toContain("%20");
+    });
+    (0, vitest_1.it)("callFunction encodes a label containing a slash (anthropic/claude)", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({ result: { ok: true } });
+        await client.callFunction("anthropic/claude", {});
+        const [url] = mockFetch.mock.calls[1];
+        (0, vitest_1.expect)(url).toContain("/api/functions/anthropic%2Fclaude");
+        (0, vitest_1.expect)(url).not.toContain("/api/functions/anthropic/claude");
+    });
+    (0, vitest_1.it)("getUserFunction encodes a label containing reserved chars", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({ label: "items get/by id" });
+        await client.getUserFunction("items get/by id");
+        const [url] = mockFetch.mock.calls[1];
+        (0, vitest_1.expect)(url).toContain("/api/functions/items%20get%2Fby%20id");
+    });
+    (0, vitest_1.it)("getChatModel encodes a provider containing a slash (anthropic/claude)", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse(["claude-3"]);
+        await client.getChatModel("anthropic/claude");
+        const [url] = mockFetch.mock.calls[1];
+        (0, vitest_1.expect)(url).toContain("/api/chat_models/anthropic%2Fclaude");
+        (0, vitest_1.expect)(url).not.toContain("/api/chat_models/anthropic/claude");
+    });
+    (0, vitest_1.it)("deleteCollection encodes a reserved-char collection", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({ status: "deleted" });
+        await client.deleteCollection("a/b");
+        const [url] = mockFetch.mock.calls[1];
+        (0, vitest_1.expect)(url).toContain("/api/collections/a%2Fb");
+    });
+    (0, vitest_1.it)("getChatSessionMessages encodes the session id path segment", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({ messages: [], total: 0 });
+        await client.getChatSessionMessages("sess/1");
+        const [url] = mockFetch.mock.calls[1];
+        (0, vitest_1.expect)(url).toContain("/api/chat/sess%2F1/messages");
+        (0, vitest_1.expect)(url).not.toContain("/api/chat/sess/1/messages");
+    });
+    (0, vitest_1.it)("chatMessage encodes the session id and leaves a normal one unchanged", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({ message_id: "m1", content: "hi" });
+        await client.chatMessage("sess#1", { message: "hi" });
+        const [url] = mockFetch.mock.calls[1];
+        (0, vitest_1.expect)(url).toContain("/api/chat/sess%231/messages");
+    });
+});

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/dist/websocket.test.js

@@ -7,6 +7,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const vitest_1 = require("vitest");
 const ws_1 = require("ws");
+const msgpack_1 = require("@msgpack/msgpack");
 const client_1 = require("./client");
 // ============================================================================
 // Test Helpers
@@ -14,11 +15,48 @@ const client_1 = require("./client");
 let wss;
 let port;
 let serverConnections = [];
+// Format the mock server Welcomes during the handshake. Default "json" keeps
+// the existing tests on the text transport they assert against; the binary
+// negotiation test sets "msgpack" before connecting.
+let welcomeFormat = "json";
+const recvState = new Map();
 function startServer() {
     return new Promise((resolve) => {
         wss = new ws_1.WebSocketServer({ port: 0 });
         wss.on("connection", (ws) => {
             serverConnections.push(ws);
+            const state = {
+                queue: [],
+                waiters: [],
+                handshakeDone: false,
+                lastBinary: false,
+            };
+            recvState.set(ws, state);
+            ws.on("message", (data, isBinary) => {
+                let msg;
+                try {
+                    msg = isBinary ? (0, msgpack_1.decode)(data) : JSON.parse(data.toString());
+                }
+                catch {
+                    return;
+                }
+                // Answer the additive Hello handshake exactly like the real server, and
+                // never surface it to the test. The Hello is always text.
+                if (!state.handshakeDone && msg?.type === "Hello") {
+                    state.handshakeDone = true;
+                    ws.send(JSON.stringify({
+                        type: "Welcome",
+                        payload: { format: welcomeFormat },
+                    }));
+                    return;
+                }
+                state.lastBinary = isBinary;
+                const waiter = state.waiters.shift();
+                if (waiter)
+                    waiter(msg);
+                else
+                    state.queue.push(msg);
+            });
         });
         wss.on("listening", () => {
             const addr = wss.address();
@@ -29,12 +67,15 @@ function startServer() {
 function getLastConnection() {
     return serverConnections[serverConnections.length - 1];
 }
+// Resolve with the next real (post-handshake) frame, draining any already
+// buffered. Decoded per the negotiated frame type, so it works for both JSON
+// and msgpack connections without the caller caring which.
 function waitForMessage(ws) {
-    return new Promise((resolve) => {
-        ws.once("message", (data) => {
-            resolve(JSON.parse(data.toString()));
-        });
-    });
+    const state = recvState.get(ws);
+    const queued = state.queue.shift();
+    if (queued !== undefined)
+        return Promise.resolve(queued);
+    return new Promise((resolve) => state.waiters.push(resolve));
 }
 // ============================================================================
 // Tests
@@ -42,6 +83,8 @@ function waitForMessage(ws) {
 (0, vitest_1.describe)("WebSocketClient", () => {
     (0, vitest_1.beforeEach)(async () => {
         serverConnections = [];
+        recvState.clear();
+        welcomeFormat = "json";
         port = await startServer();
     });
     (0, vitest_1.afterEach)(() => {
@@ -317,6 +360,70 @@ function waitForMessage(ws) {
         });
     });
     // --------------------------------------------------------------------------
+    // unsubscribe
+    // --------------------------------------------------------------------------
+    (0, vitest_1.describe)("unsubscribe", () => {
+        (0, vitest_1.it)("sends an Unsubscribe frame to the server", async () => {
+            const client = new client_1.WebSocketClient(`ws://localhost:${port}/api/ws`, "test-token");
+            const streamPromise = client.subscribe("orders");
+            await new Promise((r) => wss.once("connection", r));
+            const ws = getLastConnection();
+            const subMsg = await waitForMessage(ws);
+            (0, vitest_1.expect)(subMsg.type).toBe("Subscribe");
+            ws.send(JSON.stringify({
+                type: "Success",
+                payload: { message_id: subMsg.messageId, status: "subscribed" },
+            }));
+            await streamPromise;
+            const unsubMsg = waitForMessage(ws);
+            client.unsubscribe("orders");
+            const sent = await unsubMsg;
+            (0, vitest_1.expect)(sent.type).toBe("Unsubscribe");
+            (0, vitest_1.expect)(sent.payload.collection).toBe("orders");
+            client.close();
+        });
+    });
+    // cancelChat
+    // --------------------------------------------------------------------------
+    (0, vitest_1.describe)("cancelChat", () => {
+        (0, vitest_1.it)("sends CancelChat frame", async () => {
+            const client = new client_1.WebSocketClient(`ws://localhost:${port}/api/ws`, "test-token");
+            // Open the connection via a chat stream first.
+            const streamPromise = client.chatSend("chat-1", "test");
+            await new Promise((r) => wss.once("connection", r));
+            const ws = getLastConnection();
+            await waitForMessage(ws); // ChatSend
+            await streamPromise;
+            const cancelMsg = waitForMessage(ws);
+            await client.cancelChat("chat-1");
+            const sent = await cancelMsg;
+            (0, vitest_1.expect)(sent.type).toBe("CancelChat");
+            (0, vitest_1.expect)(sent.payload.chat_id).toBe("chat-1");
+            // A correlation id must be attached so a Success ack can't be misrouted by
+            // the dispatcher's single-pending fallback.
+            (0, vitest_1.expect)(typeof sent.messageId).toBe("string");
+            (0, vitest_1.expect)(sent.messageId.length).toBeGreaterThan(0);
+            client.close();
+        });
+        (0, vitest_1.it)("attaches a unique messageId on each CancelChat frame", async () => {
+            const client = new client_1.WebSocketClient(`ws://localhost:${port}/api/ws`, "test-token");
+            const streamPromise = client.chatSend("chat-1", "test");
+            await new Promise((r) => wss.once("connection", r));
+            const ws = getLastConnection();
+            await waitForMessage(ws); // ChatSend
+            await streamPromise;
+            const first = waitForMessage(ws);
+            await client.cancelChat("chat-1");
+            const firstSent = await first;
+            const second = waitForMessage(ws);
+            await client.cancelChat("chat-1");
+            const secondSent = await second;
+            (0, vitest_1.expect)(firstSent.messageId).toBeTruthy();
+            (0, vitest_1.expect)(secondSent.messageId).toBeTruthy();
+            (0, vitest_1.expect)(firstSent.messageId).not.toBe(secondSent.messageId);
+            client.close();
+        });
+    });
     // sendToolResult
     // --------------------------------------------------------------------------
     (0, vitest_1.describe)("sendToolResult", () => {
@@ -673,4 +780,51 @@ function waitForMessage(ws) {
             client.close();
         });
     });
+    // --------------------------------------------------------------------------
+    // Binary (msgpack) negotiation
+    // --------------------------------------------------------------------------
+    (0, vitest_1.describe)("msgpack negotiation", () => {
+        (0, vitest_1.it)("negotiates msgpack and round-trips a binary request/response", async () => {
+            welcomeFormat = "msgpack";
+            const client = new client_1.WebSocketClient(`ws://localhost:${port}/api/ws`, "test-token");
+            const resultPromise = client.findAll("users");
+            await new Promise((r) => wss.once("connection", r));
+            const ws = getLastConnection();
+            const msg = await waitForMessage(ws);
+            // The request arrived as a binary msgpack frame, decoded to the same
+            // object shape as JSON would produce.
+            (0, vitest_1.expect)(recvState.get(ws).lastBinary).toBe(true);
+            (0, vitest_1.expect)(msg.type).toBe("FindAll");
+            (0, vitest_1.expect)(msg.payload.collection).toBe("users");
+            // Respond with a binary msgpack frame; the client must decode it
+            // transparently.
+            ws.send((0, msgpack_1.encode)({
+                type: "Success",
+                payload: {
+                    message_id: msg.messageId,
+                    data: [{ id: "1", name: "Alice" }],
+                },
+            }));
+            const result = await resultPromise;
+            (0, vitest_1.expect)(result).toEqual([{ id: "1", name: "Alice" }]);
+            client.close();
+        });
+        (0, vitest_1.it)("stays on JSON text when the server welcomes only json", async () => {
+            welcomeFormat = "json";
+            const client = new client_1.WebSocketClient(`ws://localhost:${port}/api/ws`, "test-token");
+            const resultPromise = client.findAll("users");
+            await new Promise((r) => wss.once("connection", r));
+            const ws = getLastConnection();
+            const msg = await waitForMessage(ws);
+            // The request is a JSON text frame, not binary.
+            (0, vitest_1.expect)(recvState.get(ws).lastBinary).toBe(false);
+            (0, vitest_1.expect)(msg.type).toBe("FindAll");
+            ws.send(JSON.stringify({
+                type: "Success",
+                payload: { message_id: msg.messageId, data: [] },
+            }));
+            await resultPromise;
+            client.close();
+        });
+    });
 });

package/package.json

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