@ekodb/ekodb-client 0.20.0 → 0.22.0

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();
@@ -350,6 +351,15 @@ describe("EkoDBClient KV store", () => {
     await expect(client.kvDelete("my_key")).resolves.not.toThrow();
   });
 
+  it("clears KV store", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({ message: "success" });
+
+    await expect(client.kvClear()).resolves.not.toThrow();
+  });
+
   it("checks KV exists", async () => {
     const client = createTestClient();
 
@@ -414,6 +424,17 @@ describe("EkoDBClient collections", () => {
     expect(result).toHaveLength(3);
   });
 
+  it("lists user collections (excludes internal)", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({ collections: ["users", "posts"] });
+
+    const result = await client.listUserCollections();
+
+    expect(result).toEqual(["users", "posts"]);
+  });
+
   it("deletes collection", async () => {
     const client = createTestClient();
 
@@ -469,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();
+  });
 });
 
 // ============================================================================
@@ -994,6 +1034,84 @@ describe("EkoDBClient transaction status", () => {
   });
 });
 
+describe("bypass_ripple on the transactional read path", () => {
+  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];
+    expect(init.method).toBe("GET");
+    const parsed = new URL(url as string);
+    expect(parsed.searchParams.get("bypass_ripple")).toBe("true");
+    expect(parsed.searchParams.get("transaction_id")).toBe("tx_123");
+  });
+
+  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 as string);
+    expect(parsed.searchParams.get("bypass_ripple")).toBe("false");
+    expect(parsed.searchParams.get("transaction_id")).toBe("tx_123");
+  });
+
+  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];
+    expect(init.method).toBe("POST");
+    const parsed = new URL(url as string);
+    // bypass_ripple is a query param (like every other method), not in the body.
+    expect(parsed.searchParams.get("transaction_id")).toBe("tx_123");
+    expect(parsed.searchParams.get("bypass_ripple")).toBe("true");
+    const body = JSON.parse(init.body as string);
+    expect(body.bypass_ripple).toBeUndefined();
+    expect(body.limit).toBe(10);
+  });
+
+  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 } as any);
+
+    const [url, init] = mockFetch.mock.calls[1];
+    const parsed = new URL(url as string);
+    // Hoisted to the query string, removed from the body.
+    expect(parsed.searchParams.get("bypass_ripple")).toBe("true");
+    const body = JSON.parse(init.body as string);
+    expect(body.bypass_ripple).toBeUndefined();
+    expect(body.limit).toBe(5);
+  });
+});
+
 // ============================================================================
 // Convenience Methods Tests
 // ============================================================================
@@ -1821,6 +1939,26 @@ describe("findByIdWithProjection", () => {
     const dataCall = calls[1];
     expect(dataCall[0]).toBe("http://localhost:8080/api/find/users/123");
   });
+
+  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 as ReturnType<typeof vi.fn>).mock.calls;
+    const dataCall = calls[1];
+    expect(dataCall[0]).toContain("transaction_id=txn-abc");
+    expect(dataCall[0]).toContain("select_fields=name");
+  });
 });
 
 // ============================================================================
@@ -2931,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
 // ============================================================================
@@ -3108,3 +3269,129 @@ describe("extractRecordId", () => {
     expect(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.
+// ============================================================================
+
+describe("EkoDBClient URL path segment encoding", () => {
+  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];
+    expect(url as string).toContain("/api/find/users/a%2Fb");
+    expect(url as string).not.toContain("/api/find/users/a/b");
+  });
+
+  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];
+    expect(url as string).toContain("/api/find/my%20coll/user_123");
+  });
+
+  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];
+    expect(url as string).toContain("/api/find/users/123");
+    expect(url as string).not.toContain("%2F");
+    expect(url as string).not.toContain("%20");
+  });
+
+  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];
+    expect(url as string).toContain("/api/functions/anthropic%2Fclaude");
+    expect(url as string).not.toContain("/api/functions/anthropic/claude");
+  });
+
+  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];
+    expect(url as string).toContain("/api/functions/items%20get%2Fby%20id");
+  });
+
+  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];
+    expect(url as string).toContain("/api/chat_models/anthropic%2Fclaude");
+    expect(url as string).not.toContain("/api/chat_models/anthropic/claude");
+  });
+
+  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];
+    expect(url as string).toContain("/api/collections/a%2Fb");
+  });
+
+  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];
+    expect(url as string).toContain("/api/chat/sess%2F1/messages");
+    expect(url as string).not.toContain("/api/chat/sess/1/messages");
+  });
+
+  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];
+    expect(url as string).toContain("/api/chat/sess%231/messages");
+  });
+});