@ekodb/ekodb-client 0.19.0 → 0.21.0

package/src/client.test.ts

@@ -6,7 +6,7 @@
  */
 
 import { describe, it, expect, beforeEach, vi, afterEach } from "vitest";
-import { EkoDBClient, SerializationFormat } from "./client";
+import { EkoDBClient, SerializationFormat, extractRecordId } from "./client";
 
 // Mock fetch globally
 const mockFetch = vi.fn();
@@ -350,6 +350,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 +423,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();
 
@@ -994,6 +1014,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 +1919,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");
+  });
 });
 
 // ============================================================================
@@ -2432,6 +2550,80 @@ describe("EkoDBClient chatMessageStream", () => {
     expect(dataCall[1]?.method).toBe("POST");
     expect(dataCall[1]?.headers?.Accept).toBe("text/event-stream");
   });
+
+  it("sends a resolved Bearer token, not a Promise (regression #124)", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      text: async () => 'data: {"token":"ok"}\n',
+      headers: new Headers({ "content-type": "text/event-stream" }),
+    });
+
+    client.chatMessageStream("chat_789", { message: "Test" });
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    const calls = (global.fetch as ReturnType<typeof vi.fn>).mock.calls;
+    const auth = (calls[1][1]?.headers as Record<string, string>)
+      ?.Authorization;
+    expect(auth).toBe("Bearer test-jwt-token");
+    expect(auth).not.toContain("[object Promise]");
+  });
+
+  it("streams SSE events incrementally from response.body, reassembling split lines (regression #125)", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+
+    // A data line is deliberately split across chunk boundaries to exercise the
+    // incremental buffer (the old code buffered the whole body via text()).
+    const enc = new TextEncoder();
+    const chunks = [
+      'data: {"token":"He"}\nda',
+      'ta: {"token":"llo"}\n',
+      'data: {"content":"Hello","message_id":"m1","execution_time_ms":1}\n',
+    ];
+    const body = new ReadableStream({
+      start(controller) {
+        for (const c of chunks) controller.enqueue(enc.encode(c));
+        controller.close();
+      },
+    });
+
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      body,
+      text: async () => chunks.join(""),
+      headers: new Headers({ "content-type": "text/event-stream" }),
+    });
+
+    const events: any[] = [];
+    const stream = client.chatMessageStream("chat_s", { message: "Hi" });
+    stream.on("event", (evt: any) => events.push(evt));
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(
+      events.filter((e) => e.type === "chunk").map((e) => e.content),
+    ).toEqual(["He", "llo"]);
+    expect(events[events.length - 1].type).toBe("end");
+    expect(events[events.length - 1].messageId).toBe("m1");
+  });
+});
+
+describe("EkoDBClient retry backoff", () => {
+  it("backoffSeconds grows, caps at 5s, and jitters within [d/2, d] (#126)", () => {
+    const client = createTestClient() as any;
+    for (let attempt = 0; attempt < 10; attempt++) {
+      const d = Math.min(0.2 * 2 ** attempt, 5);
+      for (let i = 0; i < 50; i++) {
+        const v = client.backoffSeconds(attempt);
+        expect(v).toBeGreaterThanOrEqual(d / 2);
+        expect(v).toBeLessThanOrEqual(d);
+      }
+    }
+  });
 });
 
 // ============================================================================
@@ -2959,3 +3151,204 @@ describe("subscribeSSE", () => {
     expect(errors[0]).toContain("401");
   });
 });
+
+describe("baseURL normalization", () => {
+  it("strips a trailing slash so request URLs have no double slash", async () => {
+    mockTokenResponse();
+    const client = new EkoDBClient({
+      baseURL: "http://localhost:8080/",
+      apiKey: "test-api-key",
+      format: SerializationFormat.Json,
+      shouldRetry: false,
+    });
+    await client.init();
+
+    const url = mockFetch.mock.calls[0][0] as string;
+    expect(url).toBe("http://localhost:8080/api/auth/token");
+    expect(url).not.toContain("//api");
+  });
+
+  it("leaves a URL without a trailing slash unchanged", async () => {
+    mockTokenResponse();
+    const client = new EkoDBClient({
+      baseURL: "http://localhost:8080",
+      apiKey: "test-api-key",
+      format: SerializationFormat.Json,
+      shouldRetry: false,
+    });
+    await client.init();
+
+    const url = mockFetch.mock.calls[0][0] as string;
+    expect(url).toBe("http://localhost:8080/api/auth/token");
+  });
+});
+
+describe("extractRecordId", () => {
+  it("returns a plain string id", () => {
+    expect(extractRecordId({ id: "abc" })).toBe("abc");
+  });
+
+  it("unwraps a genuine typed wrapper id", () => {
+    expect(extractRecordId({ id: { type: "String", value: "abc" } })).toBe(
+      "abc",
+    );
+  });
+
+  it("stringifies a wrapped numeric id", () => {
+    expect(extractRecordId({ id: { type: "Integer", value: 123 } })).toBe(
+      "123",
+    );
+  });
+
+  it("does not treat a user object with a value key (no type) as the id", () => {
+    // Regression for #134: { value: 1, currency: "USD" } is a user object,
+    // not a typed wrapper, so it must not be unwrapped into the id.
+    expect(
+      extractRecordId({ id: { value: 1, currency: "USD" } }),
+    ).toBeUndefined();
+  });
+
+  it("prefers an alias candidate over id", () => {
+    expect(extractRecordId({ users_id: "u1", id: "x" }, ["users_id"])).toBe(
+      "u1",
+    );
+  });
+
+  it("ignores a non-wrapper alias object and falls back to id", () => {
+    expect(
+      extractRecordId({ users_id: { value: 7, label: "lvl" }, id: "real" }, [
+        "users_id",
+      ]),
+    ).toBe("real");
+  });
+
+  it("falls back to _id", () => {
+    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");
+  });
+});