@ekodb/ekodb-client 0.20.0 → 0.22.0

package/README.md

@@ -254,6 +254,7 @@ const joinResults = await client.find("users", multiQuery);
 - `kvSet(key: string, value: any): Promise<void>`
 - `kvGet(key: string): Promise<any>`
 - `kvDelete(key: string): Promise<void>`
+- `kvClear(): Promise<void>` - Clear the entire KV store
 
 #### Query Builder
 
@@ -297,6 +298,8 @@ const joinResults = await client.find("users", multiQuery);
 #### Collection Management
 
 - `listCollections(): Promise<string[]>`
+- `listUserCollections(): Promise<string[]>` - List collections excluding
+  internal chat/system collections
 - `deleteCollection(collection: string): Promise<void>`
 - `collectionExists(collection: string): Promise<boolean>` - Check if collection
   exists
@@ -346,6 +349,14 @@ const joinResults = await client.find("users", multiQuery);
 - `deleteCollection(name): Promise<void>`
 - `close(): void`
 
+**Subscriptions & chat:**
+
+- `subscribe(collection, options?): Promise<EventStream<MutationNotification>>`
+  - Subscribe to a collection's mutation notifications
+- `unsubscribe(collection): void` - Tear down a subscription (not replayed on
+  reconnect)
+- `cancelChat(chatId): Promise<void>` - Cancel an in-flight streaming chat
+
 **Schema Cache:**
 
 ```typescript
@@ -359,6 +370,23 @@ const id = extractRecordId(record); // tries "id", "_id"
 const id2 = ws.extractId("users", record); // uses cache
 ```
 
+### Transactions
+
+Buffered, read-your-writes transactions. Statements issued with a
+`transactionId` are staged and applied atomically at commit.
+
+- `beginTransaction(isolationLevel?): Promise<string>` - Start a transaction and
+  return its id
+- `commitTransaction(transactionId): Promise<void>` - Apply staged writes. May
+  reject with a retryable conflict (HTTP 409)
+- `rollbackTransaction(transactionId): Promise<void>` - Discard staged writes
+- `createSavepoint(transactionId, name): Promise<void>`
+- `rollbackToSavepoint(transactionId, name): Promise<void>`
+- `releaseSavepoint(transactionId, name): Promise<void>`
+
+Pass `transactionId` in the options of `insert` / `update` / `delete` / `find` /
+`findById` to read and write within the transaction (read-your-writes).
+
 ## Examples
 
 See the

package/dist/client.d.ts

@@ -1,7 +1,7 @@
 /**
  * ekoDB TypeScript Client
  */
-import { QueryBuilder } from "./query-builder";
+import { QueryBuilder, Query } from "./query-builder";
 import { SearchQuery, SearchResponse } from "./search";
 import { Schema, SchemaBuilder, CollectionMetadata } from "./schema";
 import { UserFunction, FunctionResult } from "./functions";
@@ -50,11 +50,7 @@ export declare class RateLimitError extends Error {
     retryAfterSecs: number;
     constructor(retryAfterSecs: number, message?: string);
 }
-export interface Query {
-    limit?: number;
-    offset?: number;
-    filter?: Record;
-}
+export type { Query };
 export interface BatchOperationResult {
     successful: string[];
     failed: Array<{
@@ -95,6 +91,23 @@ export interface FindOptions {
     bypassCache?: boolean;
     selectFields?: string[];
     excludeFields?: string[];
+    /**
+     * Read within a transaction (read-your-writes). When set, the read is served
+     * from the transaction's own view — its uncommitted staged writes, else the
+     * committed store — and recorded in the transaction's read set for
+     * commit-time conflict detection. Omit for an ordinary committed read.
+     */
+    transactionId?: string;
+}
+/**
+ * Options for a point read by id. `transactionId` enables read-your-writes
+ * within a transaction (see {@link FindOptions.transactionId}).
+ */
+export interface FindByIdOptions {
+    selectFields?: string[];
+    excludeFields?: string[];
+    bypassRipple?: boolean;
+    transactionId?: string;
 }
 export interface BatchInsertOptions {
     bypassRipple?: boolean;
@@ -427,19 +440,25 @@ export declare class EkoDBClient {
      * const results = await client.find("users", { limit: 10 });
      * ```
      */
-    find(collection: string, query?: Query | QueryBuilder): Promise<Record[]>;
+    find(collection: string, query?: Query | QueryBuilder, options?: {
+        bypassRipple?: boolean;
+        transactionId?: string;
+    }): Promise<Record[]>;
     /**
-     * Find a document by ID
+     * Find a document by ID.
+     * @param options - Optional read options. `transactionId` reads within a
+     *   transaction (read-your-writes); see {@link FindByIdOptions}.
      */
-    findById(collection: string, id: string): Promise<Record>;
+    findById(collection: string, id: string, options?: FindByIdOptions): Promise<Record>;
     /**
      * Find a document by ID with field projection
      * @param collection - Collection name
      * @param id - Document ID
      * @param selectFields - Fields to include in the result
      * @param excludeFields - Fields to exclude from the result
+     * @param transactionId - Read within a transaction (read-your-writes)
      */
-    findByIdWithProjection(collection: string, id: string, selectFields?: string[], excludeFields?: string[]): Promise<Record>;
+    findByIdWithProjection(collection: string, id: string, selectFields?: string[], excludeFields?: string[], transactionId?: string): Promise<Record>;
     /**
      * Update a document
      * @param collection - Collection name
@@ -514,6 +533,10 @@ export declare class EkoDBClient {
      * Delete a key
      */
     kvDelete(key: string): Promise<void>;
+    /**
+     * Clear the entire KV store (all keys in the namespace).
+     */
+    kvClear(): Promise<void>;
     /**
      * Batch get multiple keys
      * @param keys - Array of keys to retrieve
@@ -560,7 +583,18 @@ export declare class EkoDBClient {
         include_expired?: boolean;
     }): Promise<any[]>;
     /**
-     * Begin a new transaction
+     * Begin a new transaction.
+     *
+     * Transactions are buffered: statements issued with this `transactionId`
+     * (passed via the `transactionId` option on insert/update/delete/find/…) are
+     * staged and applied atomically only at {@link commitTransaction}. They are
+     * invisible to everyone else until commit, and visible to this transaction's
+     * own reads (read-your-writes) only when those reads also carry the
+     * `transactionId`. {@link rollbackTransaction} discards the staged writes.
+     * `commitTransaction` may reject with a conflict (HTTP 409) if a record this
+     * transaction read or wrote was changed by another committed transaction —
+     * retry the transaction in that case.
+     *
      * @param isolationLevel - Transaction isolation level (default: "ReadCommitted")
      * @returns Transaction ID
      */
@@ -580,10 +614,23 @@ export declare class EkoDBClient {
      */
     commitTransaction(transactionId: string): Promise<void>;
     /**
-     * Rollback a transaction
+     * Rollback a transaction (discards all staged writes; nothing was applied).
      * @param transactionId - The transaction ID to rollback
      */
     rollbackTransaction(transactionId: string): Promise<void>;
+    /**
+     * Create a savepoint within a transaction. A later
+     * {@link rollbackToSavepoint} discards everything staged after it.
+     */
+    createSavepoint(transactionId: string, name: string): Promise<void>;
+    /**
+     * Roll the transaction back to a savepoint, discarding writes staged after it.
+     */
+    rollbackToSavepoint(transactionId: string, name: string): Promise<void>;
+    /**
+     * Release (forget) a savepoint. Staged work is unaffected.
+     */
+    releaseSavepoint(transactionId: string, name: string): Promise<void>;
     /**
      * Insert or update a record (upsert operation)
      *
@@ -672,6 +719,10 @@ export declare class EkoDBClient {
      * List all collections
      */
     listCollections(): Promise<string[]>;
+    /**
+     * List collections, excluding internal chat/system collections.
+     */
+    listUserCollections(): Promise<string[]>;
     /**
      * Delete a collection
      */
@@ -844,6 +895,17 @@ export declare class EkoDBClient {
      * Unblocks ekoDB's tool loop so it can feed the result to the LLM.
      */
     submitChatToolResult(chatId: string, callId: string, success: boolean, result?: any, error?: string): Promise<void>;
+    /**
+     * Send a client tool keepalive (liveness ping) for an in-flight SSE chat stream.
+     *
+     * This is NOT a result: it does not unblock the tool loop or feed anything to the
+     * LLM. It simply resets the server's per-tool wait deadline (governed by
+     * `client_tool_timeout_secs`, default 60s) so that slow user confirmations or
+     * long-running client tools don't get the turn timed out before
+     * {@link submitChatToolResult} arrives. Send it periodically while a client tool
+     * is still working. See ekoDB#530.
+     */
+    submitChatToolKeepalive(chatId: string, callId: string): Promise<void>;
     /**
      * Send a message in an existing chat session via SSE streaming.
      *
@@ -1335,6 +1397,13 @@ export declare class WebSocketClient {
     private ws;
     private dispatcherRunning;
     private schemaCache;
+    /**
+     * Per-connection wire format, set by negotiateFormat() on every (re)connect:
+     * true once the server has Welcomed msgpack, so frames are sent/received as
+     * binary msgpack; false (JSON text) otherwise, including against an older
+     * server that never Welcomes. Keeps the transport fully back-compatible.
+     */
+    private binary;
     private autoReconnect;
     private reconnectInitialDelayMs;
     private reconnectMaxDelayMs;
@@ -1373,6 +1442,21 @@ export declare class WebSocketClient {
      */
     private ensureConnected;
     private openSocket;
+    /**
+     * Additive capability handshake: offer msgpack and, if the server Welcomes
+     * it, switch this connection to binary msgpack frames; otherwise stay on JSON
+     * text. The Welcome (a text frame) is read with a one-shot listener and a
+     * timeout so an older server that never answers — or answers with an Error —
+     * simply leaves the connection on JSON. Best-effort and never throws: JSON
+     * always works.
+     */
+    private negotiateFormat;
+    /**
+     * Send a request object on the active socket using the negotiated format:
+     * binary msgpack when the server Welcomed it, JSON text otherwise. The single
+     * write point so every request honors the negotiated transport.
+     */
+    private sendFrame;
     private spawnDispatcher;
     /**
      * Reject in-flight requests and tear down the dead socket. If the close was
@@ -1419,6 +1503,11 @@ export declare class WebSocketClient {
      * Send a tool result back to the server during a chat stream.
      */
     sendToolResult(chatId: string, callId: string, success: boolean, result?: any, error?: string): Promise<void>;
+    /**
+     * Cancel an in-flight streaming chat. Fire-and-forget: tells the server to
+     * stop generating tokens for the given chat.
+     */
+    cancelChat(chatId: string): Promise<void>;
     /**
      * Stateless raw LLM completion via WebSocket.
      *