@ekodb/ekodb-client 0.22.0 → 0.23.1

package/dist/client.d.ts

@@ -31,6 +31,12 @@ export interface RateLimitInfo {
 /**
  * Client configuration options
  */
+/**
+ * Default per-request timeout (ms) for REST calls, matching the Rust and Go
+ * clients' 30s default. Applied to every non-streaming request; long-lived
+ * streaming/SSE calls are intentionally not bounded by it.
+ */
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
 export interface ClientConfig {
     /** Base URL of the ekoDB server */
     baseURL: string;
@@ -42,6 +48,13 @@ export interface ClientConfig {
     maxRetries?: number;
     /** Serialization format (default: MessagePack for best performance, use Json for debugging) */
     format?: SerializationFormat;
+    /**
+     * Per-request timeout in milliseconds for REST calls (default: 30000).
+     * A slow or unreachable server aborts with a timeout error instead of hanging
+     * the caller. Streaming/SSE calls are not bounded by it. Matches the Rust and
+     * Go clients.
+     */
+    timeout?: number;
 }
 /**
  * Rate limit error
@@ -342,6 +355,7 @@ export declare class EkoDBClient {
     private shouldRetry;
     private maxRetries;
     private format;
+    private requestTimeoutMs;
     private rateLimitInfo;
     constructor(config: string | ClientConfig, apiKey?: string);
     /**
@@ -508,16 +522,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

@@ -36,7 +36,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WebSocketClient = exports.SchemaCache = exports.EventStream = exports.EkoDBClient = exports.MergeStrategy = exports.RateLimitError = exports.SerializationFormat = void 0;
+exports.WebSocketClient = exports.SchemaCache = exports.EventStream = exports.EkoDBClient = exports.MergeStrategy = exports.RateLimitError = exports.DEFAULT_REQUEST_TIMEOUT_MS = exports.SerializationFormat = void 0;
 exports.extractRecordId = extractRecordId;
 const msgpack_1 = require("@msgpack/msgpack");
 const query_builder_1 = require("./query-builder");
@@ -51,6 +51,15 @@ var SerializationFormat;
     /** MessagePack format (binary, 2-3x faster) */
     SerializationFormat["MessagePack"] = "MessagePack";
 })(SerializationFormat || (exports.SerializationFormat = SerializationFormat = {}));
+/**
+ * Client configuration options
+ */
+/**
+ * Default per-request timeout (ms) for REST calls, matching the Rust and Go
+ * clients' 30s default. Applied to every non-streaming request; long-lived
+ * streaming/SSE calls are intentionally not bounded by it.
+ */
+exports.DEFAULT_REQUEST_TIMEOUT_MS = 30000;
 /**
  * Rate limit error
  */
@@ -96,6 +105,7 @@ class EkoDBClient {
             this.shouldRetry = true;
             this.maxRetries = 3;
             this.format = SerializationFormat.MessagePack; // Default to MessagePack for 2-3x performance
+            this.requestTimeoutMs = exports.DEFAULT_REQUEST_TIMEOUT_MS;
         }
         else {
             this.baseURL = stripTrailingSlashes(config.baseURL);
@@ -103,6 +113,7 @@ class EkoDBClient {
             this.shouldRetry = config.shouldRetry ?? true;
             this.maxRetries = config.maxRetries ?? 3;
             this.format = config.format ?? SerializationFormat.MessagePack; // Default to MessagePack for 2-3x performance
+            this.requestTimeoutMs = config.timeout ?? exports.DEFAULT_REQUEST_TIMEOUT_MS;
         }
     }
     /**
@@ -134,6 +145,7 @@ class EkoDBClient {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ api_key: this.apiKey }),
+            signal: AbortSignal.timeout(this.requestTimeoutMs),
         });
         if (!response.ok) {
             let errorMsg = `Auth failed with status: ${response.status}`;
@@ -317,6 +329,10 @@ class EkoDBClient {
                 "Content-Type": contentType,
                 Accept: contentType,
             },
+            // Bound every REST request so a slow/unreachable server aborts instead of
+            // hanging the caller. A fresh signal per attempt is correct here because
+            // makeRequest recurses on retry, rebuilding `options` each time.
+            signal: AbortSignal.timeout(this.requestTimeoutMs),
         };
         if (data) {
             options.body = isMessagePack
@@ -371,6 +387,16 @@ class EkoDBClient {
             throw new Error(`Request failed with status ${response.status}: ${text}`);
         }
         catch (error) {
+            // A fired request-timeout (AbortSignal.timeout) surfaces as a DOMException
+            // named "TimeoutError" (or "AbortError" in some runtimes). Convert it to a
+            // clear error and do NOT retry — retrying would multiply the wait beyond
+            // the configured bound.
+            const errName = error && typeof error === "object" && "name" in error
+                ? error.name
+                : undefined;
+            if (errName === "TimeoutError" || errName === "AbortError") {
+                throw new Error(`Request timed out after ${this.requestTimeoutMs}ms: ${method} ${path}`);
+            }
             // Handle network errors with retry
             if (error instanceof TypeError &&
                 this.shouldRetry &&
@@ -599,24 +625,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 +1596,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 +1647,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();
@@ -2582,3 +2645,29 @@ function mockErrorResponse(status, message) {
         (0, vitest_1.expect)(url).toContain("/api/chat/sess%231/messages");
     });
 });
+(0, vitest_1.describe)("request timeout", () => {
+    (0, vitest_1.it)("defaults to a 30s request timeout", () => {
+        (0, vitest_1.expect)(client_1.DEFAULT_REQUEST_TIMEOUT_MS).toBe(30000);
+    });
+    (0, vitest_1.it)("aborts a request that exceeds the configured timeout", async () => {
+        const client = new client_1.EkoDBClient({
+            baseURL: "http://localhost:8080",
+            apiKey: "test-api-key",
+            format: client_1.SerializationFormat.Json,
+            shouldRetry: false,
+            timeout: 20,
+        });
+        // Token fetch resolves immediately...
+        mockTokenResponse();
+        // ...but the actual request hangs until the request-timeout signal aborts
+        // it. The mock honors the AbortSignal the client attaches, rejecting with
+        // its reason (a "TimeoutError" DOMException) exactly like real fetch.
+        mockFetch.mockImplementationOnce((_url, opts) => new Promise((_resolve, reject) => {
+            const signal = opts.signal;
+            signal?.addEventListener("abort", () => {
+                reject(signal.reason ?? new DOMException("timed out", "TimeoutError"));
+            });
+        }));
+        await (0, vitest_1.expect)(client.find("users")).rejects.toThrow(/timed out after 20ms/);
+    });
+});

package/package.json

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

package/src/client.test.ts

@@ -6,7 +6,12 @@
  */
 
 import { describe, it, expect, beforeEach, vi, afterEach } from "vitest";
-import { EkoDBClient, SerializationFormat, extractRecordId } from "./client";
+import {
+  EkoDBClient,
+  SerializationFormat,
+  extractRecordId,
+  DEFAULT_REQUEST_TIMEOUT_MS,
+} from "./client";
 import { SearchQueryBuilder } from "./search";
 
 // Mock fetch globally
@@ -313,6 +318,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 +3352,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();
 
@@ -3395,3 +3483,38 @@ describe("EkoDBClient URL path segment encoding", () => {
     expect(url as string).toContain("/api/chat/sess%231/messages");
   });
 });
+
+describe("request timeout", () => {
+  it("defaults to a 30s request timeout", () => {
+    expect(DEFAULT_REQUEST_TIMEOUT_MS).toBe(30000);
+  });
+
+  it("aborts a request that exceeds the configured timeout", async () => {
+    const client = new EkoDBClient({
+      baseURL: "http://localhost:8080",
+      apiKey: "test-api-key",
+      format: SerializationFormat.Json,
+      shouldRetry: false,
+      timeout: 20,
+    });
+
+    // Token fetch resolves immediately...
+    mockTokenResponse();
+    // ...but the actual request hangs until the request-timeout signal aborts
+    // it. The mock honors the AbortSignal the client attaches, rejecting with
+    // its reason (a "TimeoutError" DOMException) exactly like real fetch.
+    mockFetch.mockImplementationOnce(
+      (_url: string, opts: RequestInit) =>
+        new Promise((_resolve, reject) => {
+          const signal = opts.signal as AbortSignal | undefined;
+          signal?.addEventListener("abort", () => {
+            reject(
+              signal.reason ?? new DOMException("timed out", "TimeoutError"),
+            );
+          });
+        }),
+    );
+
+    await expect(client.find("users")).rejects.toThrow(/timed out after 20ms/);
+  });
+});

package/src/client.ts

@@ -37,6 +37,13 @@ export interface RateLimitInfo {
 /**
  * Client configuration options
  */
+/**
+ * Default per-request timeout (ms) for REST calls, matching the Rust and Go
+ * clients' 30s default. Applied to every non-streaming request; long-lived
+ * streaming/SSE calls are intentionally not bounded by it.
+ */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+
 export interface ClientConfig {
   /** Base URL of the ekoDB server */
   baseURL: string;
@@ -48,6 +55,13 @@ export interface ClientConfig {
   maxRetries?: number;
   /** Serialization format (default: MessagePack for best performance, use Json for debugging) */
   format?: SerializationFormat;
+  /**
+   * Per-request timeout in milliseconds for REST calls (default: 30000).
+   * A slow or unreachable server aborts with a timeout error instead of hanging
+   * the caller. Streaming/SSE calls are not bounded by it. Matches the Rust and
+   * Go clients.
+   */
+  timeout?: number;
 }
 
 /**
@@ -419,6 +433,7 @@ export class EkoDBClient {
   private shouldRetry: boolean;
   private maxRetries: number;
   private format: SerializationFormat;
+  private requestTimeoutMs: number;
   private rateLimitInfo: RateLimitInfo | null = null;
 
   constructor(config: string | ClientConfig, apiKey?: string) {
@@ -431,12 +446,14 @@ export class EkoDBClient {
       this.shouldRetry = true;
       this.maxRetries = 3;
       this.format = SerializationFormat.MessagePack; // Default to MessagePack for 2-3x performance
+      this.requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS;
     } else {
       this.baseURL = stripTrailingSlashes(config.baseURL);
       this.apiKey = config.apiKey;
       this.shouldRetry = config.shouldRetry ?? true;
       this.maxRetries = config.maxRetries ?? 3;
       this.format = config.format ?? SerializationFormat.MessagePack; // Default to MessagePack for 2-3x performance
+      this.requestTimeoutMs = config.timeout ?? DEFAULT_REQUEST_TIMEOUT_MS;
     }
   }
 
@@ -471,6 +488,7 @@ export class EkoDBClient {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({ api_key: this.apiKey }),
+      signal: AbortSignal.timeout(this.requestTimeoutMs),
     });
 
     if (!response.ok) {
@@ -683,6 +701,10 @@ export class EkoDBClient {
         "Content-Type": contentType,
         Accept: contentType,
       },
+      // Bound every REST request so a slow/unreachable server aborts instead of
+      // hanging the caller. A fresh signal per attempt is correct here because
+      // makeRequest recurses on retry, rebuilding `options` each time.
+      signal: AbortSignal.timeout(this.requestTimeoutMs),
     };
 
     if (data) {
@@ -757,6 +779,20 @@ export class EkoDBClient {
       const text = await response.text();
       throw new Error(`Request failed with status ${response.status}: ${text}`);
     } catch (error) {
+      // A fired request-timeout (AbortSignal.timeout) surfaces as a DOMException
+      // named "TimeoutError" (or "AbortError" in some runtimes). Convert it to a
+      // clear error and do NOT retry — retrying would multiply the wait beyond
+      // the configured bound.
+      const errName =
+        error && typeof error === "object" && "name" in error
+          ? (error as { name?: string }).name
+          : undefined;
+      if (errName === "TimeoutError" || errName === "AbortError") {
+        throw new Error(
+          `Request timed out after ${this.requestTimeoutMs}ms: ${method} ${path}`,
+        );
+      }
+
       // Handle network errors with retry
       if (
         error instanceof TypeError &&
@@ -1051,40 +1087,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 +2522,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 +2606,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}`,