@ekodb/ekodb-client 0.19.0 → 0.21.0

package/dist/client.test.js

@@ -250,6 +250,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 +300,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();
@@ -723,6 +736,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 +1411,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
@@ -1816,6 +1897,69 @@ function mockErrorResponse(status, message) {
         (0, vitest_1.expect)(dataCall[1]?.method).toBe("POST");
         (0, vitest_1.expect)(dataCall[1]?.headers?.Accept).toBe("text/event-stream");
     });
+    (0, vitest_1.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.mock.calls;
+        const auth = calls[1][1]?.headers
+            ?.Authorization;
+        (0, vitest_1.expect)(auth).toBe("Bearer test-jwt-token");
+        (0, vitest_1.expect)(auth).not.toContain("[object Promise]");
+    });
+    (0, vitest_1.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 = [];
+        const stream = client.chatMessageStream("chat_s", { message: "Hi" });
+        stream.on("event", (evt) => events.push(evt));
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        (0, vitest_1.expect)(events.filter((e) => e.type === "chunk").map((e) => e.content)).toEqual(["He", "llo"]);
+        (0, vitest_1.expect)(events[events.length - 1].type).toBe("end");
+        (0, vitest_1.expect)(events[events.length - 1].messageId).toBe("m1");
+    });
+});
+(0, vitest_1.describe)("EkoDBClient retry backoff", () => {
+    (0, vitest_1.it)("backoffSeconds grows, caps at 5s, and jitters within [d/2, d] (#126)", () => {
+        const client = createTestClient();
+        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);
+                (0, vitest_1.expect)(v).toBeGreaterThanOrEqual(d / 2);
+                (0, vitest_1.expect)(v).toBeLessThanOrEqual(d);
+            }
+        }
+    });
 });
 // ============================================================================
 // Schedule CRUD Tests
@@ -2259,3 +2403,146 @@ function mockErrorResponse(status, message) {
         (0, vitest_1.expect)(errors[0]).toContain("401");
     });
 });
+(0, vitest_1.describe)("baseURL normalization", () => {
+    (0, vitest_1.it)("strips a trailing slash so request URLs have no double slash", async () => {
+        mockTokenResponse();
+        const client = new client_1.EkoDBClient({
+            baseURL: "http://localhost:8080/",
+            apiKey: "test-api-key",
+            format: client_1.SerializationFormat.Json,
+            shouldRetry: false,
+        });
+        await client.init();
+        const url = mockFetch.mock.calls[0][0];
+        (0, vitest_1.expect)(url).toBe("http://localhost:8080/api/auth/token");
+        (0, vitest_1.expect)(url).not.toContain("//api");
+    });
+    (0, vitest_1.it)("leaves a URL without a trailing slash unchanged", async () => {
+        mockTokenResponse();
+        const client = new client_1.EkoDBClient({
+            baseURL: "http://localhost:8080",
+            apiKey: "test-api-key",
+            format: client_1.SerializationFormat.Json,
+            shouldRetry: false,
+        });
+        await client.init();
+        const url = mockFetch.mock.calls[0][0];
+        (0, vitest_1.expect)(url).toBe("http://localhost:8080/api/auth/token");
+    });
+});
+(0, vitest_1.describe)("extractRecordId", () => {
+    (0, vitest_1.it)("returns a plain string id", () => {
+        (0, vitest_1.expect)((0, client_1.extractRecordId)({ id: "abc" })).toBe("abc");
+    });
+    (0, vitest_1.it)("unwraps a genuine typed wrapper id", () => {
+        (0, vitest_1.expect)((0, client_1.extractRecordId)({ id: { type: "String", value: "abc" } })).toBe("abc");
+    });
+    (0, vitest_1.it)("stringifies a wrapped numeric id", () => {
+        (0, vitest_1.expect)((0, client_1.extractRecordId)({ id: { type: "Integer", value: 123 } })).toBe("123");
+    });
+    (0, vitest_1.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.
+        (0, vitest_1.expect)((0, client_1.extractRecordId)({ id: { value: 1, currency: "USD" } })).toBeUndefined();
+    });
+    (0, vitest_1.it)("prefers an alias candidate over id", () => {
+        (0, vitest_1.expect)((0, client_1.extractRecordId)({ users_id: "u1", id: "x" }, ["users_id"])).toBe("u1");
+    });
+    (0, vitest_1.it)("ignores a non-wrapper alias object and falls back to id", () => {
+        (0, vitest_1.expect)((0, client_1.extractRecordId)({ users_id: { value: 7, label: "lvl" }, id: "real" }, [
+            "users_id",
+        ])).toBe("real");
+    });
+    (0, vitest_1.it)("falls back to _id", () => {
+        (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/functions.test.d.ts

@@ -3,7 +3,6 @@
  *
  * These tests cover the pure-data construction helpers and the structural
  * parameter placeholder. They don't hit a running ekoDB — server-side
- * behavior is covered by the Rust integration tests in
- * `ekodb/ekodb_server/tests/function_parameters_tests.rs`.
+ * behavior is covered by the server-side integration tests.
  */
 export {};

package/dist/functions.test.js

@@ -4,8 +4,7 @@
  *
  * These tests cover the pure-data construction helpers and the structural
  * parameter placeholder. They don't hit a running ekoDB — server-side
- * behavior is covered by the Rust integration tests in
- * `ekodb/ekodb_server/tests/function_parameters_tests.rs`.
+ * behavior is covered by the server-side integration tests.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 const vitest_1 = require("vitest");

package/dist/query-builder.d.ts

@@ -86,10 +86,6 @@ export declare class QueryBuilder {
      * Add an ends-with filter
      */
     endsWith(field: string, suffix: string): this;
-    /**
-     * Add a regex filter
-     */
-    regex(field: string, pattern: string): this;
     /**
      * Combine filters with AND logic
      */

package/dist/query-builder.js

@@ -189,20 +189,8 @@ class QueryBuilder {
         });
         return this;
     }
-    /**
-     * Add a regex filter
-     */
-    regex(field, pattern) {
-        this.filters.push({
-            type: "Condition",
-            content: {
-                field,
-                operator: "Regex",
-                value: pattern,
-            },
-        });
-        return this;
-    }
+    // Note: regex filtering is pending server-side support. The server has no
+    // Regex filter operator; use contains/startsWith/endsWith instead.
     // ========================================================================
     // Logical Operators
     // ========================================================================

package/dist/query-builder.test.js

@@ -95,10 +95,6 @@ const query_builder_1 = require("./query-builder");
         const query = new query_builder_1.QueryBuilder().endsWith("filename", ".pdf").build();
         (0, vitest_1.expect)(query.filter.content.operator).toBe("EndsWith");
     });
-    (0, vitest_1.it)("builds regex filter", () => {
-        const query = new query_builder_1.QueryBuilder().regex("phone", "^\\+1").build();
-        (0, vitest_1.expect)(query.filter.content.operator).toBe("Regex");
-    });
 });
 // ============================================================================
 // Logical Operators Tests
@@ -368,7 +364,6 @@ const query_builder_1 = require("./query-builder");
         (0, vitest_1.expect)(qb.contains("i", "j")).toBe(qb);
         (0, vitest_1.expect)(qb.startsWith("k", "l")).toBe(qb);
         (0, vitest_1.expect)(qb.endsWith("m", "n")).toBe(qb);
-        (0, vitest_1.expect)(qb.regex("o", "p")).toBe(qb);
         (0, vitest_1.expect)(qb.sortAsc("q")).toBe(qb);
         (0, vitest_1.expect)(qb.sortDesc("r")).toBe(qb);
         (0, vitest_1.expect)(qb.limit(1)).toBe(qb);

package/dist/utils.js

@@ -33,7 +33,13 @@ exports.extractRecord = extractRecord;
  * ```
  */
 function getValue(field) {
-    if (field && typeof field === "object" && "value" in field) {
+    // Only unwrap a genuine typed wrapper — one carrying BOTH a "type"
+    // discriminator and a "value". A user object that merely has a "value" key
+    // (e.g. { value: 1, currency: "USD" }) must pass through untouched.
+    if (field &&
+        typeof field === "object" &&
+        "type" in field &&
+        "value" in field) {
         return field.value;
     }
     return field;

package/dist/utils.test.js

@@ -29,6 +29,10 @@ const utils_1 = require("./utils");
         const field = { type: "Null", value: null };
         (0, vitest_1.expect)((0, utils_1.getValue)(field)).toBeNull();
     });
+    (0, vitest_1.it)("passes through a user object that has a value key but no type (regression #134)", () => {
+        const field = { value: 1, currency: "USD" };
+        (0, vitest_1.expect)((0, utils_1.getValue)(field)).toEqual(field);
+    });
     (0, vitest_1.it)("returns plain string as-is", () => {
         (0, vitest_1.expect)((0, utils_1.getValue)("plain string")).toBe("plain string");
     });