@ekodb/ekodb-client 0.22.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
-     */
-    batchDelete(collection: string, ids: string[], bypassRipple?: boolean): Promise<BatchOperationResult>;
+     * @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, options?: BatchDeleteOptions): Promise<BatchOperationResult>;
     /**
      * Set a key-value pair with optional TTL
      * @param key - The key to set

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
@@ -1533,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}`);
     }
     /**
@@ -1580,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

@@ -227,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
@@ -2503,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekodb/ekodb-client",
-  "version": "0.22.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

@@ -313,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("");
+  });
 });
 
 // ============================================================================
@@ -3281,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 });
   }
 
   /**
@@ -2449,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}`);
   }
 
@@ -2529,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}`,